Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/*
* store.h — Opaque SQLite graph store for code knowledge graphs.
*
* All functions are prefixed cbm_store_*. The store handle is opaque —
* callers never touch SQLite internals directly.
*
* Thread safety: a single store handle must not be used concurrently.
* Use one store per thread or external synchronization.
*/
#ifndef CBM_STORE_H
#define CBM_STORE_H
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
/* ── Opaque handle ──────────────────────────────────────────────── */
typedef struct cbm_store cbm_store_t;
typedef struct cbm_store_read_scope cbm_store_read_scope_t;
/* ── Result codes ───────────────────────────────────────────────── */
#define CBM_STORE_OK 0
#define CBM_STORE_ERR (-1)
#define CBM_STORE_NOT_FOUND (-2)
/* Persisted index format. A bump routes every existing index through one full
* rebuild (pipeline.c, format_change_reindex) that keeps ADR/project metadata.
* 1 #1108: File-node QNs keep the file extension.
* 2 Kubernetes objects: one Resource per YAML document, QN
* <file>::<group>/<Kind>/<declared namespace or ->/<name>; a
* Dockerfile.<variant> keeps its suffix in its QNs.
* 3 Image identity invents no registry: a reference without a host is
* __image__<repository as written>, registry "unknown" -- no longer
* __image__docker.io/[library/]<repository>.
* 4 #1913: Go method QNs are receiver-qualified (pkg.Recv.method, generic
* receivers unwrapped); free functions stay pkg.func. */
#define CBM_INDEX_FORMAT_VERSION 4
#define CBM_STORE_CANCELLED (-3)
#define CBM_STORE_SCAN_LIMIT (-4)
#define CBM_STORE_CALLBACK_ERR (-5)
/* Read-scope cleanup could not restore the connection: close/discard it. */
#define CBM_STORE_SCOPE_DISCARD (-6)
#define CBM_STORE_FILE_OUTLINE_MAX_LIMIT 200
#define CBM_STORE_FILE_OUTLINE_MAX_LABELS 16
#define CBM_STORE_FILE_OUTLINE_MAX_TEXT_BYTES (256U * 1024U)
/* ── Data structures ────────────────────────────────────────────── */
typedef struct {
int64_t id;
const char *project;
const char *label; /* Function, Class, Method, Module, File, ... */
const char *name; /* short name */
const char *qualified_name; /* full dotted path */
const char *file_path; /* relative file path */
int start_line;
int end_line;
const char *properties_json; /* JSON string, NULL → "{}" */
} cbm_node_t;
/* Compact declaration row returned by the bounded file-outline query. */
typedef struct {
const char *name;
const char *label;
const char *qualified_name;
int start_line;
int end_line;
} cbm_file_outline_row_t;
/* Optional cancellation callback for bounded store queries. */
typedef bool (*cbm_store_cancel_fn)(void *context);
typedef struct {
int64_t id;
const char *project;
int64_t source_id;
int64_t target_id;
const char *type; /* CALLS, HTTP_CALLS, IMPORTS, ... */
const char *properties_json; /* JSON string, NULL → "{}" */
} cbm_edge_t;
typedef struct {
const char *name;
const char *indexed_at; /* ISO 8601 */
const char *root_path;
} cbm_project_t;
typedef struct {
const char *project;
const char *rel_path;
const char *sha256;
int64_t mtime_ns;
int64_t size;
} cbm_file_hash_t;
/* One file's persisted LSP surface: the serialized cross-file definition set
* (exactly what pass_lsp_cross registration consumes) plus the metadata the
* closure-repair incremental route needs to decide and bound its work. The
* store treats defs_json/ref_bloom as opaque; the codec lives with
* pass_lsp_cross, which is the only writer and reader of their contents. */
typedef struct {
const char *project;
const char *rel_path;
const char *surface_sha; /* sha256 hex of defs_json (the early-cutoff key) */
const char *defs_json; /* canonical JSON array of the file's LSP defs */
const void *ref_bloom; /* referenced-identifier bloom blob (may be NULL) */
int ref_bloom_len;
const char *config_ctx; /* governing-config context hash ("" = none) */
} cbm_lsp_surface_row_t;
/* The definition variants that lie in a file (graph_buffer.c "Definition
* variants"): one row per variant span in `file_path`, as the node it
* belongs to with start_line/end_line set to that span. Covers the file's
* own nodes (their other #if branches) and nodes whose file_path names
* another file that the file writes a variant of. */
int cbm_store_find_variant_spans_by_file(cbm_store_t *s, const char *project, const char *file_path,
cbm_node_t **out, int *count);
/* Find nodes overlapping a line range in a file (excludes Module/Package). */
int cbm_store_find_nodes_by_file_overlap(cbm_store_t *s, const char *project, const char *file_path,
int start_line, int end_line, cbm_node_t **out,
int *count);
/* Find nodes whose qualified_name ends with the given suffix (dot-boundary). */
int cbm_store_find_nodes_by_qn_suffix(cbm_store_t *s, const char *project, const char *suffix,
cbm_node_t **out, int *count);
/* Find callables whose signature-qualified QN (#2061) has `base` as its base
* QN (exact), or a base ending with "." + `base` (suffix_match). QNs without
* a callable identity suffix never match: this is the tier that lets a bare
* QN name every overload. */
int cbm_store_find_nodes_by_qn_base(cbm_store_t *s, const char *project, const char *base,
bool suffix_match, cbm_node_t **out, int *count);
/* Get CALLS degree of a node (inbound and outbound). */
void cbm_store_node_degree(cbm_store_t *s, int64_t node_id, int *in_deg, int *out_deg);
/* Get distinct canonical File-node paths, with a non-Folder node fallback for legacy/manual
* stores that have no File nodes. Caller frees each out[i] and out itself. */
int cbm_store_list_files(cbm_store_t *s, const char *project, char ***out, int *count);
/* Persisted index-format identity. Bump when a change alters the QN scheme
* or node identity of an already-written graph, so an old DB is routed
* through the full-reindex path instead of producing a mixed graph.
* 1 = File QNs keep the file extension (#769). */
int cbm_store_get_format_version(cbm_store_t *s, int *out);
int cbm_store_set_format_version(cbm_store_t *s, int version);
/* Get caller/callee names for a node (CALLS/HTTP_CALLS/ASYNC_CALLS edges).
* Returns 0 on success. Caller must free each out_callers[i]/out_callees[i]
* and the arrays themselves. */
int cbm_store_node_neighbor_names(cbm_store_t *s, int64_t node_id, int limit, char ***out_callers,
int *caller_count, char ***out_callees, int *callee_count);
/* Batch count in/out degree for multiple nodes.
* edge_type: filter by edge type (e.g. "CALLS"), or NULL/"" for all types.
* out_in[i] and out_out[i] receive the in/out degree for node_ids[i].
* Returns CBM_STORE_OK or CBM_STORE_ERR. */
int cbm_store_batch_count_degrees(cbm_store_t *s, const int64_t *node_ids, int id_count,
const char *edge_type, int *out_in, int *out_out);
/* Upsert file hashes in batch. */
int cbm_store_upsert_file_hash_batch(cbm_store_t *s, const cbm_file_hash_t *hashes, int count);
/* ── LSP surface rows (closure-repair incremental) ───────────────
* Upsert/get/delete are whole-row, keyed (project, rel_path). get returns
* heap rows released with cbm_store_free_lsp_surfaces. A project with no
* rows returns OK with *count == 0 — callers treat that as "no surface
* data" and route to a full rebuild, which is also the upgrade path for
* databases written before this table existed. */
int cbm_store_upsert_lsp_surface_batch(cbm_store_t *s, const cbm_lsp_surface_row_t *rows,
int count);
int cbm_store_get_lsp_surfaces(cbm_store_t *s, const char *project, cbm_lsp_surface_row_t **out,
int *count);
int cbm_store_delete_lsp_surfaces(cbm_store_t *s, const char *project);
void cbm_store_free_lsp_surfaces(cbm_lsp_surface_row_t *rows, int count);
/* Reverse-dependency lookup for closure-repair routing: the DISTINCT
* file_paths of nodes with at least one edge INTO a node of any file in
* target_files, excluding the target files themselves. This is "who consumed
* these files' definitions" as recorded by the previous generation — served
* by idx_edges_target + idx_nodes_file, so cost tracks the result size, not
* the graph size. out gets a malloc'd array of malloc'd strings; free with
* cbm_store_free_dependent_files. */
int cbm_store_get_dependent_files(cbm_store_t *s, const char *project,
const char *const *target_files, int target_count, char ***out,
int *out_count);
void cbm_store_free_dependent_files(char **files, int count);
/* Variant partners for closure-repair routing: the files that write another
* variant of a definition written in any of `files` (one node for a
* definition's platform files, header declaration and source definition, Go
* build-tagged files; a DEFINES edge from each file's File node). Excludes
* `files` themselves; served by idx_nodes_file + the edge source/target
* indexes. Free with cbm_store_free_dependent_files. */
int cbm_store_get_variant_partner_files(cbm_store_t *s, const char *project,
const char *const *files, int count, char ***out,
int *out_count);
/* Find edges whose properties contain a url_path matching the keyword. */
int cbm_store_find_edges_by_url_path(cbm_store_t *s, const char *project, const char *keyword,
cbm_edge_t **out, int *count);
/* Restore database from another store (backup API). */
int cbm_store_restore_from(cbm_store_t *dst, cbm_store_t *src);
/* Copy a transactionally-consistent snapshot, including committed WAL frames,
* from an existing DB into a same-directory staging path. */
int cbm_store_backup_path(const char *source_path, const char *staging_path);
/* Seal a staging DB into one self-contained main file before atomic publish.
* The store must have no concurrent users. */
int cbm_store_prepare_for_publish(cbm_store_t *s);
/* Checkpoint and detach sidecars from an existing destination immediately
* before replacement. Fails closed while another process prevents sealing. */
int cbm_store_prepare_path_for_replace(const char *path);
/* ── Search ─────────────────────────────────────────────────────── */
typedef struct {
const char *project;
const char *label; /* NULL = any label */
const char *name_pattern; /* regex on name, NULL = any */
const char *qn_pattern; /* regex on qualified_name, NULL = any */
const char *file_pattern; /* glob on file_path, NULL = any */
const char *relationship; /* edge type filter, NULL = any */
const char *direction; /* "inbound" / "outbound" / "any", NULL = any */
int min_degree; /* -1 = no filter (default), 0+ = minimum */
int max_degree; /* -1 = no filter (default), 0+ = maximum */
int limit; /* 0 = default (10) */
int offset;
bool exclude_entry_points;
bool include_connected;
const char *sort_by; /* "relevance" / "name" / "degree", NULL = relevance */
bool case_sensitive;
const char **exclude_labels; /* NULL-terminated array, or NULL */
const char *kind; /* a Resource's kind property ("Deployment"), NULL = any */
const char *namespace_name; /* the namespace of a Resource's obj_key, NULL = any */
} cbm_search_params_t;
typedef struct {
cbm_node_t node;
int in_degree;
int out_degree;
/* connected_names: allocated array of strings, count in connected_count */
const char **connected_names;
int connected_count;
} cbm_search_result_t;
typedef struct {
cbm_search_result_t *results;
int count;
int total; /* total before pagination */
} cbm_search_output_t;
/* ── Traversal ──────────────────────────────────────────────────── */
typedef struct {
cbm_node_t node;
int hop; /* BFS depth from root */
} cbm_node_hop_t;
typedef struct {
const char *from_name;
const char *to_name;
const char *type;
double confidence;
int64_t source_id; /* edge endpoints — let callers match an edge to a hop node */
int64_t target_id;
const char *properties_json; /* raw edge properties (carries CALLS arg expressions) */
} cbm_edge_info_t;
typedef struct {
cbm_node_t root;
cbm_node_hop_t *visited;
int visited_count;
cbm_edge_info_t *edges;
int edge_count;
/* True when trail expansion hit its recursive-row safety budget (or, for
* the plain BFS, the max_results ceiling); counts are lower bounds. */
bool truncated;
bool edges_truncated; /* optional edge-data ceiling reached; node counts stay exact */
} cbm_traverse_result_t;
/* ── Schema introspection ───────────────────────────────────────── */
typedef struct {
const char *label;
int count;
char **properties; /* distinct property keys for this label (base + JSON) */
int property_count;
} cbm_label_count_t;
typedef struct {
const char *type;
int count;
char **properties; /* distinct property keys for this edge type (base + JSON) */
int property_count;
} cbm_type_count_t;
typedef struct {
cbm_label_count_t *node_labels;
int node_label_count;
cbm_type_count_t *edge_types;
int edge_type_count;
/* relationship patterns like "(Function)-[CALLS]->(Function) [123x]" */
const char **rel_patterns;
int rel_pattern_count;
const char **sample_func_names;
int sample_func_count;
const char **sample_class_names;
int sample_class_count;
const char **sample_qns;
int sample_qn_count;
} cbm_schema_info_t;
/* ── Graph comparison ──────────────────────────────────────────── */
/* Stable graph identities deliberately exclude the project name. Strings are
* borrowed from the active SQLite row and remain valid only for the duration
* of the callback. */
typedef struct {
const char *qualified_name;
const char *label;
const char *file_path;
} cbm_graph_node_identity_t;
typedef struct {
cbm_graph_node_identity_t source;
cbm_graph_node_identity_t target;
const char *type;
const char *local_name_gen;
} cbm_graph_edge_identity_t;
typedef bool (*cbm_graph_compare_cancel_fn)(void *context);
typedef bool (*cbm_graph_compare_node_fn)(void *context, bool added,
const cbm_graph_node_identity_t *node);
typedef bool (*cbm_graph_compare_edge_fn)(void *context, bool added,
const cbm_graph_edge_identity_t *edge);
#define CBM_GRAPH_COMPARE_GENERATION_SIZE 128
#define CBM_GRAPH_COMPARE_INDEX_MODE_SIZE 32
typedef struct {
char generation[CBM_GRAPH_COMPARE_GENERATION_SIZE];
char index_mode[CBM_GRAPH_COMPARE_INDEX_MODE_SIZE];
int64_t node_count;
int64_t edge_count;
} cbm_graph_compare_project_t;
typedef struct {
cbm_graph_compare_project_t base;
cbm_graph_compare_project_t target;
uint64_t nodes_added_total;
uint64_t nodes_removed_total;
uint64_t edges_added_total;
uint64_t edges_removed_total;
} cbm_graph_compare_result_t;
/* Compare two independently-owned read-only stores using ordered streaming
* cursors. Both read transactions and both SQLite progress handlers are owned
* by this call and released on every exit. scan_limit applies independently to
* the combined node rows and combined edge rows across the two projects. */
int cbm_store_compare_graphs(cbm_store_t *base_store, const char *base_project,
cbm_store_t *target_store, const char *target_project,
uint64_t scan_limit, cbm_graph_compare_cancel_fn cancel,
cbm_graph_compare_node_fn on_node, cbm_graph_compare_edge_fn on_edge,
void *context, cbm_graph_compare_result_t *out);
#ifdef CBM_ENABLE_TEST_SEAMS
/* Deterministic one-shot comparison fault seams. Values count successful
* comparison binds/cancellation checks before the injected event; -1 disables
* the seam. */
void cbm_store_compare_test_fail_bind_after(int successful_binds);
void cbm_store_compare_test_cancel_after(int successful_checks);
void cbm_store_compare_test_cancel_from_progress(bool enabled);
#endif
/* ── Lifecycle ──────────────────────────────────────────────────── */
/* Open an in-memory database (for testing). */
cbm_store_t *cbm_store_open_memory(void);
/* Open a file-backed database at the given path. Creates if needed. */
cbm_store_t *cbm_store_open_path(const char *db_path);
/* Open an existing file-backed database read-write without CREATE. Intended
* for coordinated mutations where a missing/typo path must never materialize
* a ghost database. Returns NULL when the file does not exist. */
cbm_store_t *cbm_store_open_path_existing(const char *db_path);
/* Open an existing file-backed database for querying only. Opened READ-ONLY
* (no SQLITE_OPEN_CREATE, no write pragmas) so queries never mutate the DB and
* work on a read-only file / filesystem. Returns NULL if the file does not
* exist — never creates a new .db file. */
cbm_store_t *cbm_store_open_path_query(const char *db_path);
#ifdef CBM_ENABLE_TEST_SEAMS
/* Every following query open calls `hook(ctx)` inside its first-access
* section (after the first read, the process-wide lock still held) until the
* hook is cleared with NULL. Test builds only. */
void cbm_store_query_first_access_hook_for_testing(void (*hook)(void *ctx), void *ctx);
#endif
/* Validate and seal an existing DB for atomic replacement without creating or
* migrating its schema. Returns OK when sealed, NOT_FOUND when the bytes are
* definitely corrupt/incompatible and should be quarantined, or ERR when the
* file is busy/unavailable and must be left in place. */
int cbm_store_seal_existing_path_for_replace(const char *db_path);
/* On-disk path of a file-backed store, or NULL for an in-memory (:memory:)
* store. The returned pointer is owned by the store. */
const char *cbm_store_db_path(const cbm_store_t *s);
/* Check database integrity. Returns true if the DB passes basic sanity checks
* (projects table has correct types, no corruption indicators).
* Returns false if corruption is detected — caller should delete and re-index. */
bool cbm_store_check_integrity(cbm_store_t *s);
/* True when the edges table carries the #768 local_name_gen discriminator —
* the schema a read-write open (cbm_store_open_path_existing) requires. A
* pre-#768 store still serves read-only queries but refuses every write open
* until it is reindexed. Read-only: safe on a store opened for query. */
bool cbm_store_edges_schema_current(cbm_store_t *s);
/* Shallow check + PRAGMA quick_check — catches page-level corruption.
* O(db size); use on rare paths (artifact import), not hot opens. */
bool cbm_store_check_integrity_deep(cbm_store_t *s);
/* Outcome of a quarantine-grade integrity check. Used to decide whether a DB
* that failed the cheap open-time check should be quarantined (renamed to
* .corrupt and rebuilt) or left alone. See cbm_store_check_integrity_verdict. */
typedef enum {
CBM_INTEGRITY_OK = 0, /* DB is healthy */
CBM_INTEGRITY_CORRUPT = 1, /* DB is structurally damaged — safe to quarantine */
CBM_INTEGRITY_TRANSIENT = 2, /* SQL/busy/IO error — NOT corruption, do NOT quarantine */
} cbm_integrity_verdict_t;
/* Full integrity verdict for the quarantine decision path.
*
* The plain cbm_store_check_integrity() returns a single bool and cannot
* distinguish "the projects table has 99 rows" (real corruption) from
* "sqlite3_prepare_v2 returned SQLITE_BUSY because another instance held the
* writer lock" (a transient lock contention, #1206). Quarantining on the latter
* is what makes concurrent MCP instances destroy each other's healthy DBs.
*
* This function runs the shallow check, then PRAGMA quick_check, and classifies
* the failure mode so the caller can quarantine ONLY on confirmed corruption.
* O(db size); use only on the recovery/quarantine path, not hot opens. */
cbm_integrity_verdict_t cbm_store_check_integrity_verdict(cbm_store_t *s);
/* Open database for a named project in the default cache dir. */
cbm_store_t *cbm_store_open(const char *project);
/* Close the store and free all resources. NULL-safe. */
void cbm_store_close(cbm_store_t *s);
/* Get the underlying sqlite3 handle (for testing only). */
struct sqlite3 *cbm_store_get_db(cbm_store_t *s);
/* The digest of a project's graph CONTENT (store_content_digest.c): rows keyed
* by what they say, never by row id, database identity, generation or mtime.
* Two graphs of the same tree, built incrementally or in full, are equal
* exactly when their content digests are. out: 32 raw SHA-256 bytes. */
int cbm_store_graph_content_digest(cbm_store_t *s, const char *project, unsigned char out[32]);
/* The part of the content test selection reads: node identity, every edge by
* endpoints and type without properties, except the corpus-statistical
* SIMILAR_TO / SEMANTICALLY_RELATED; file hashes; index coverage. */
int cbm_store_graph_topology_digest(cbm_store_t *s, const char *project, unsigned char out[32]);
/* Get the last error message (static string, valid until next call). */
const char *cbm_store_error(cbm_store_t *s);
/* ── Transaction ────────────────────────────────────────────────── */
/* Begin a transaction. Returns CBM_STORE_OK on success. */
int cbm_store_begin(cbm_store_t *s);
/* Commit the current transaction. */
int cbm_store_commit(cbm_store_t *s);
/* Rollback the current transaction. */
int cbm_store_rollback(cbm_store_t *s);
/* Read batch: run the reads that follow in one deferred read transaction,
* renewed every 100 ms so a writer is never held back longer, instead of one
* lock round trip per statement. Begin returns false (and does nothing) when
* a transaction is already open. For read-only work only; end it before any
* write, transaction or read scope on the same store. Close ends it. */
bool cbm_store_read_batch_begin(cbm_store_t *s);
void cbm_store_read_batch_end(cbm_store_t *s);
/* Test seam: make an open read batch due for renewal at its next statement. */
void cbm_store_read_batch_expire_for_test(cbm_store_t *s);
/* Stable request read scope. Borrows an exclusively owned, single-thread
* store and callback context. Refuses a transaction, busy statement or owned
* progress handler; idle cached statements are allowed. Saves query_only and
* busy_timeout, sets ON/0, begins DEFERRED and pins main.nodes before returning.
* The cancellation callback is a pure predicate: no SQLite/store/scope/walk
* calls. Do not replace connection handlers, transactions or close the store
* during the borrow. Close walks first, then the scope, then the store.
*
* Open clears *out. Any cleanup/restoration failure, including failed open,
* returns SCOPE_DISCARD: the caller MUST discard this connection. */
int cbm_store_read_scope_open(cbm_store_t *s, cbm_store_cancel_fn cancel, void *context,
cbm_store_read_scope_t **out);
/* First cancellation/error is sticky. Check also rejects a lost transaction. */
int cbm_store_read_scope_check(cbm_store_read_scope_t *scope);
/* Consumer failure: accepts ERR or CANCELLED; other values latch ERR. */
int cbm_store_read_scope_fail(cbm_store_read_scope_t *scope, int status);
/* Borrowed store binding, not a health check or certification. */
cbm_store_t *cbm_store_read_scope_store(const cbm_store_read_scope_t *scope);
/* Disables its handler before cleanup. Returns latched status unless cleanup
* fails (SCOPE_DISCARD). NULL is OK. Frees scope on every non-NULL call. */
int cbm_store_read_scope_close(cbm_store_read_scope_t *scope);
/* ── Bulk write optimization ────────────────────────────────────── */
/* Tune pragmas for bulk write throughput (synchronous=OFF, 64 MiB cache).
* WAL journal mode is preserved throughout for crash safety. */
int cbm_store_begin_bulk(cbm_store_t *s);
/* Restore normal pragmas (synchronous=NORMAL, the 64 MiB read-write cache)
* after bulk writes. */
int cbm_store_end_bulk(cbm_store_t *s);
/* Drop user indexes for faster bulk inserts. */
int cbm_store_drop_indexes(cbm_store_t *s);
/* Recreate user indexes after bulk inserts. */
int cbm_store_create_indexes(cbm_store_t *s);
/* ── WAL / Checkpoint ───────────────────────────────────────────── */
/* Force WAL checkpoint + PRAGMA optimize. */
int cbm_store_checkpoint(cbm_store_t *s);
/* #1083: the WAL size limit (journal_size_limit) applied to this write
* connection, in bytes; -1 = unlimited (SQLite default / pre-fix). */
int64_t cbm_store_journal_size_limit(cbm_store_t *s);
/* Advance the pagination-cursor generation atomically. Seeds a genuinely
* legacy database with a fresh per-file uid, preserves that uid thereafter,
* and increments its canonical uint64 mutation counter. Safe inside an
* existing transaction (implemented with a nested savepoint); malformed or
* partial metadata fails closed without committing a partial advance. */
int cbm_store_generation_advance(cbm_store_t *s);
/* Opaque store generation for pagination-cursor staleness detection:
* "u<16-lower-hex-db_uid>g<canonical-uint64-mutation_gen>". Returns "legacy"
* only when store_meta is genuinely absent; malformed or missing metadata is
* an error. */
int cbm_store_generation(cbm_store_t *s, char *buf, size_t bufsz);
/* Per-store feature metadata in store_meta (key/value text). Keys are
* namespaced by the owning feature, e.g. "cross_repo_last_run:<project>".
* get: CBM_STORE_OK with *out owned by the caller (release with
* cbm_free(CBM_MEM_CLASS_STORE, *out)), or
* CBM_STORE_NOT_FOUND when the key -- or store_meta itself -- is absent.
* Read-only: safe on a store opened for query.
* put: upserts the key; seeds store_meta through the generation path when a
* legacy store lacks it. Atomic (savepoint); needs a read-write store. */
int cbm_store_meta_get(cbm_store_t *s, const char *key, char **out);
int cbm_store_meta_put(cbm_store_t *s, const char *key, const char *value);
/* Seal a fully-written staging database before atomic publication.
* Raises synchronous to FULL, requires an exclusive TRUNCATE checkpoint to
* complete, then leaves the database in verified DELETE journal mode so the
* main file is self-contained (no required -wal/-shm sidecars). This is a
* fail-closed operation: SQLITE_BUSY and an unconfirmed mode transition are
* errors. The caller must own the staging database exclusively. */
int cbm_store_seal_for_atomic_publish(cbm_store_t *s);
/* Resolve the mmap_size pragma value applied to on-disk stores from the
* CBM_SQLITE_MMAP_SIZE environment variable. Defaults to 67108864 (64 MB)
* when the variable is unset, malformed, or partially numeric. Negative
* values clamp to 0 (which disables mmap and reverts to read()/pread()
* I/O — recoverable SQLITE_IOERR instead of SIGBUS when concurrent
* processes truncate the DB file under live mappings). Exposed for
* testability. */
int64_t cbm_store_resolve_mmap_size(void);
/* ── Dump / Restore ─────────────────────────────────────────────── */
/* Dump in-memory database to a file. */
int cbm_store_dump_to_file(cbm_store_t *s, const char *dest_path);
/* ── Project CRUD ───────────────────────────────────────────────── */
int cbm_store_upsert_project(cbm_store_t *s, const char *name, const char *root_path);
int cbm_store_get_project(cbm_store_t *s, const char *name, cbm_project_t *out);
int cbm_store_list_projects(cbm_store_t *s, cbm_project_t **out, int *count);
int cbm_store_delete_project(cbm_store_t *s, const char *name);
/* ── Node CRUD ──────────────────────────────────────────────────── */
/* Upsert a single node. Returns node ID (>0) or CBM_STORE_ERR. */
int64_t cbm_store_upsert_node(cbm_store_t *s, const cbm_node_t *n);
/* Upsert nodes in batch. out_ids must have room for count entries. */
int cbm_store_upsert_node_batch(cbm_store_t *s, const cbm_node_t *nodes, int count,
int64_t *out_ids);
/* Find node by primary key. Returns CBM_STORE_OK or CBM_STORE_NOT_FOUND. */
int cbm_store_find_node_by_id(cbm_store_t *s, int64_t id, cbm_node_t *out);
/* Find node by project + qualified_name. */
int cbm_store_find_node_by_qn(cbm_store_t *s, const char *project, const char *qn, cbm_node_t *out);
/* Find node by qualified_name only (no project filter — QNs are globally unique). */
int cbm_store_find_node_by_qn_any(cbm_store_t *s, const char *qn, cbm_node_t *out);
/* Find all nodes in a project. Returns allocated array, caller frees. */
int cbm_store_find_nodes(cbm_store_t *s, const char *project, cbm_node_t **out, int *count);
/* Find nodes by name (exact match). Returns allocated array, caller frees. */
int cbm_store_find_nodes_by_name(cbm_store_t *s, const char *project, const char *name,
cbm_node_t **out, int *count);
/* Find nodes by name across all projects. Returns allocated array, caller frees. */
int cbm_store_find_nodes_by_name_any(cbm_store_t *s, const char *name, cbm_node_t **out,
int *count);
/* Find nodes by label. */
int cbm_store_find_nodes_by_label(cbm_store_t *s, const char *project, const char *label,
cbm_node_t **out, int *count);
/* Find nodes by file path. */
int cbm_store_find_nodes_by_file(cbm_store_t *s, const char *project, const char *file_path,
cbm_node_t **out, int *count);
/* Streamed node scan: the rows of cbm_store_find_nodes (label NULL) or
* cbm_store_find_nodes_by_label, in the same order, a batch at a time. Pages
* are keyset queries along the eager query's index, and no read lock is held
* between calls. open returns NULL on error. next fills out[0..max) and sets
* *count; a count of 0 means the scan is exhausted. The caller frees each
* returned node with cbm_node_free_fields. A failed read returns
* CBM_STORE_ERR with no rows from that call and ends the scan;
* cbm_store_error() names the failure. paged is false when the eager query's
* plan is not the one the pages reproduce: the scan then hands out the eager
* scan's rows (same order, no memory saving). Close the scan before closing
* the store. */
typedef struct cbm_store_node_scan cbm_store_node_scan_t;
cbm_store_node_scan_t *cbm_store_node_scan_open(cbm_store_t *s, const char *project,
const char *label);
int cbm_store_node_scan_next(cbm_store_node_scan_t *scan, cbm_node_t *out, int max, int *count);
bool cbm_store_node_scan_paged(const cbm_store_node_scan_t *scan);
void cbm_store_node_scan_close(cbm_store_node_scan_t *scan);
#ifdef CBM_ENABLE_TEST_SEAMS
/* One-shot fault: after this many successful pages (of any scan), the next
* page fails like a SQLite step error; -1 disables the seam. */
void cbm_store_node_scan_test_fail_page_after(int successful_pages);
#endif
/* Return a stable, paginated outline for one exact repository-relative file.
* File/folder/container nodes are excluded. labels may be NULL when
* label_count is zero; otherwise labels are exact-match filters. The query is
* capped by CBM_STORE_FILE_OUTLINE_MAX_LIMIT and a fixed aggregate text-byte
* budget, and fails without partial rows when cancelled or over budget.
* total is the exact filtered count before pagination. */
int cbm_store_get_file_outline(cbm_store_t *s, const char *project, const char *file_path,
const char *const *labels, int label_count, int limit, int offset,
cbm_store_cancel_fn cancel, void *cancel_context,
cbm_file_outline_row_t **out, int *count, int *total);
void cbm_store_free_file_outline(cbm_file_outline_row_t *rows, int count);
/* Batch lookup: map qualified names → node IDs.
* qns[i] is resolved; out_ids[i] receives the ID or 0 if not found.
* Returns number of QNs actually found, or CBM_STORE_ERR. */
int cbm_store_find_node_ids_by_qns(cbm_store_t *s, const char *project, const char **qns,
int qn_count, int64_t *out_ids);
/* Count nodes in project. Returns count or CBM_STORE_ERR. */
int cbm_store_count_nodes(cbm_store_t *s, const char *project);
int cbm_store_count_nodes_scoped(cbm_store_t *s, const char *project, const char *path);
int cbm_store_count_edges_scoped(cbm_store_t *s, const char *project, const char *path);
/* True when path is a non-empty scope after normalization (issue #604). */
bool cbm_store_arch_path_scoped(const char *path);
/* When scoped, writes normalized directory prefix into norm_out. Returns false if unscoped. */
bool cbm_store_normalize_arch_path(const char *path, char *norm_out, size_t norm_sz);
/* True when architecture aspect `name` belongs to the "overview" subset:
* every aspect EXCEPT the large per-file listing (file_tree). Shared by both
* aspect gates — want_aspect (store.c) and aspect_wanted (mcp.c) — so the
* two sites cannot drift. */
bool cbm_store_arch_aspect_in_overview(const char *name);
/* Delete all nodes for a project (cascade deletes edges). */
int cbm_store_delete_nodes_by_project(cbm_store_t *s, const char *project);
/* Delete nodes by file path. */
int cbm_store_delete_nodes_by_file(cbm_store_t *s, const char *project, const char *file_path);
/* Delete nodes by label. */
int cbm_store_delete_nodes_by_label(cbm_store_t *s, const char *project, const char *label);
/* ── Edge CRUD ──────────────────────────────────────────────────── */
/* Insert or update edge. Returns edge ID (>0) or CBM_STORE_ERR. */
int64_t cbm_store_insert_edge(cbm_store_t *s, const cbm_edge_t *e);
/* Insert edges in batch. */
int cbm_store_insert_edge_batch(cbm_store_t *s, const cbm_edge_t *edges, int count);
/* Fetch all CALLS edges among Function/Method nodes for a project as parallel
* (source_id, target_id) arrays, released together with
* cbm_store_free_call_edges. For SCC / cycle analysis.
* Stops at max_edges and sets *truncated — never a silent cap. Returns
* CBM_STORE_OK (or _ERR); *count is the number returned. */
int cbm_store_fetch_call_edges(cbm_store_t *s, const char *project, int max_edges,
int64_t **out_src, int64_t **out_tgt, int *count, bool *truncated);
/* Free the (source_id, target_id) arrays returned by cbm_store_fetch_call_edges. */
void cbm_store_free_call_edges(int64_t *src, int64_t *tgt);
/* Find edges by source node. */
int cbm_store_find_edges_by_source(cbm_store_t *s, int64_t source_id, cbm_edge_t **out, int *count);
/* Find edges by target node. */
int cbm_store_find_edges_by_target(cbm_store_t *s, int64_t target_id, cbm_edge_t **out, int *count);
/* Find edges by source + type. */
int cbm_store_find_edges_by_source_type(cbm_store_t *s, int64_t source_id, const char *type,
cbm_edge_t **out, int *count);
/* Find edges by target + type. */
int cbm_store_find_edges_by_target_type(cbm_store_t *s, int64_t target_id, const char *type,
cbm_edge_t **out, int *count);
/* Find all edges of a type in project. */
int cbm_store_find_edges_by_type(cbm_store_t *s, const char *project, const char *type,
cbm_edge_t **out, int *count);
/* Count all edges in project. */
int cbm_store_count_edges(cbm_store_t *s, const char *project);
/* Count edges of given type. */
int cbm_store_count_edges_by_type(cbm_store_t *s, const char *project, const char *type);
/* Delete all edges for a project. */
int cbm_store_delete_edges_by_project(cbm_store_t *s, const char *project);
/* Delete edges by type. */
int cbm_store_delete_edges_by_type(cbm_store_t *s, const char *project, const char *type);
/* ── File hash CRUD ─────────────────────────────────────────────── */
int cbm_store_upsert_file_hash(cbm_store_t *s, const char *project, const char *rel_path,
const char *sha256, int64_t mtime_ns, int64_t size);
int cbm_store_get_file_hashes(cbm_store_t *s, const char *project, cbm_file_hash_t **out,
int *count);
/* Fetch one exact file-hash record. The returned strings are heap-owned and
* must be released with cbm_store_clear_file_hash(). */
int cbm_store_get_file_hash(cbm_store_t *s, const char *project, const char *rel_path,
cbm_file_hash_t *out);
/* Free heap-owned fields in one exact file-hash record and zero it. */
void cbm_store_clear_file_hash(cbm_file_hash_t *hash);
int cbm_store_delete_file_hash(cbm_store_t *s, const char *project, const char *rel_path);
int cbm_store_delete_file_hashes(cbm_store_t *s, const char *project);
/* ── Index coverage (#963) ──────────────────────────────────────── */
/* One best-effort coverage row: a file the indexer could not fully cover.
* kind "parse_partial" = indexed but the parse tree had ERROR/MISSING regions
* (detail = 1-based line ranges "12-40,88-90"); skip kinds "read"/"extract"/
* "oversized" = not indexed at all (detail = reason). "unresolved_calls" is
* indexed source whose invocation targets were not resolved (detail = JSON
* array of caller, leaf, source byte span, and reason). Stored in the separate
* index_coverage table — coverage is metadata ABOUT the graph, never mixed
* into the graph itself. */
typedef struct {
const char *rel_path;
const char *kind;
const char *detail;
} cbm_coverage_row_t;
/* Older generations lack precise caller attribution and resolver candidates,
* so their exact trace totals cannot be trusted until the project is reindexed. */
enum { CBM_UNRESOLVED_CALL_COVERAGE_VERSION = 5 };
/* Metadata describing how completely one index run recorded the best-effort
* coverage signal. `recording_status` is "complete", "truncated", or
* "unavailable"; it is deliberately separate from hash_records_complete.
* unresolved_calls_complete describes only unresolved invocation capture;
* false keeps CALLS totals conservative without voiding other coverage.
* Strings returned by cbm_store_coverage_meta_get are heap-owned. */
typedef struct {
const char *project;
const char *generation;
const char *index_mode;
const char *recorded_at;
const char *recording_status;
int ignored_files_stored;
int ignored_files_total;
int coverage_version;
bool hash_records_complete;
bool unresolved_calls_complete;
/* Git checkout identity frozen at the successful staged-generation
* boundary (BT-240), stored in the index_checkout table. NULL/"" when the
* run had no git context (non-git repo) or the DB predates that table.
* Owned by the row: meta_get allocates it, meta_clear frees it. */
const char *indexed_checkout_sha;
} cbm_coverage_meta_t;
/* Replace the project's coverage rows in one transaction, then prune rows for
* files absent from file_hashes (deleted from the repo). Call AFTER hashes
* were persisted for the run. */
int cbm_store_coverage_replace(cbm_store_t *s, const char *project, const cbm_coverage_row_t *rows,
int count);
/* Replace coverage rows and their run metadata atomically. Passing NULL meta
* clears any older metadata so it cannot be mistaken for the new row set. */
int cbm_store_coverage_replace_ex(cbm_store_t *s, const char *project,
const cbm_coverage_row_t *rows, int count,
const cbm_coverage_meta_t *meta);
/* Fetch all coverage rows (ordered by rel_path). Caller frees via
* cbm_store_free_coverage. */
int cbm_store_coverage_get(cbm_store_t *s, const char *project, cbm_coverage_row_t **out,
int *count);
/* Fetch coverage rows for one path. Exact rows are returned together with any
* not_indexed_dir ancestor that covers the path. */
int cbm_store_coverage_get_path(cbm_store_t *s, const char *project, const char *rel_path,
cbm_coverage_row_t **out, int *count);
/* Fetch coverage rows at/below a directory scope, plus a not_indexed_dir
* ancestor that covers the scope. Prefix matching is segment-boundary safe. */
int cbm_store_coverage_get_scope(cbm_store_t *s, const char *project, const char *scope,
cbm_coverage_row_t **out, int *count);
/* Fetch bounded unresolved invocation diagnostics for one exact caller file. */
int cbm_store_coverage_get_unresolved_path(cbm_store_t *s, const char *project,
const char *rel_path, cbm_coverage_row_t **out,
int *count);
/* Indexed candidate existence; truncated/malformed evidence also returns true
* because omitted candidates cannot prove an exact inbound total. */
int cbm_store_coverage_has_unresolved_candidate(cbm_store_t *s, const char *project,
const char *candidate, bool *out);
/* Fetch/free the metadata paired with the current coverage row set. */
int cbm_store_coverage_meta_get(cbm_store_t *s, const char *project, cbm_coverage_meta_t *out);
/* ── Observed runtime calls (ingest_traces) ──────────────────────────
* Separate from the graph tables and keyed by qualified name: node ids are
* reassigned on reindex, names survive. A "label" identifies one run
* (e.g. "pytest 2026-08-27"); counts accumulate per (pair, label). */
int cbm_store_observed_upsert_pair(cbm_store_t *s, const char *project, const char *caller_qn,
const char *callee_qn, const char *label, long long count);
int cbm_store_observed_upsert_path(cbm_store_t *s, const char *project, const char *path_json,
const char *label, long long count);
long long cbm_store_observed_pair_total(cbm_store_t *s, const char *project);
int cbm_store_observed_evict_oldest_label(cbm_store_t *s, const char *project,
char **evicted_label_out);
/* *count_out = 0 when never observed (absence is data, not an error);
* label/last_seen receive the NEWEST run's values. */
int cbm_store_observed_lookup(cbm_store_t *s, const char *project, const char *caller_qn,
const char *callee_qn, long long *count_out, char *label_buf,
size_t label_cap, char *last_seen_buf, size_t last_seen_cap);
void cbm_store_coverage_meta_clear(cbm_coverage_meta_t *meta);
/* Name of the derived miss-graph shadow project ("<project>::missed").
* cbm_store_coverage_replace materializes the coverage FAILURE rows as a file-
* structure graph (Project → Folder → File{kind, detail}) under this project
* name — queryable via the normal cypher path without touching the real
* project's graph. By-design not_indexed_* rows and unresolved_calls evidence
* stay out of it. */
void cbm_store_coverage_shadow_project(char *dst, size_t dstsz, const char *project);
void cbm_store_free_coverage(cbm_coverage_row_t *rows, int count);
/* ── Doc-link unresolved references ─────────────────────────────── */
/* One doc-comment reference that did not become a MENTIONS edge, stored in
* doc_link_unresolved (project, rel_path, line, syntax, raw, reason). The
* table is created at publish when missing, so databases written by older
* builds stay readable without an index-format change. `reason` is one of
* missing, ambiguous, external, test_only_target, not_indexed, graph_gap,
* unparseable, below_bar_tier (it resolved, but its link family does not
* ship); a row with rel_path "" and reason "error" records that the
* doc-link layer itself failed for the generation. Rows returned by the
* getters own their strings; rows and strings are memory-core blocks of
* CBM_MEM_CLASS_STORE, released only by cbm_store_free_doc_links. */
typedef struct {
const char *rel_path;
int line;
const char *syntax;
const char *raw;
const char *reason;
} cbm_doc_link_row_t;
/* Replace the project's rows in one transaction, creating the table first
* when it does not exist. */
int cbm_store_doc_links_replace(cbm_store_t *s, const char *project, const cbm_doc_link_row_t *rows,
int count);
/* All rows of the project ordered by (rel_path, line, raw). *table_present
* (optional) is false — with zero rows and CBM_STORE_OK — for a database that
* has no doc_link_unresolved table yet. */
int cbm_store_doc_links_get(cbm_store_t *s, const char *project, cbm_doc_link_row_t **out,
int *count, bool *table_present);
/* Row count per reason (ordered by reason; reasons owned by the result) and
* up to `sample_limit` rows ordered by (reason, rel_path, line). Same
* table_present contract as above. */
typedef struct {
const char *reason;
int count;
} cbm_doc_link_reason_count_t;
int cbm_store_doc_links_summary(cbm_store_t *s, const char *project,
cbm_doc_link_reason_count_t **reasons, int *reason_count,
cbm_doc_link_row_t **samples, int *sample_count, int sample_limit,
bool *table_present);
/* Diagnostic display budgets; the query copies three extra bytes per field
* so a formatter can inspect a complete UTF-8 scalar at the display boundary. */
enum {
CBM_DOC_LINK_PREVIEW_ROWS = 50,
CBM_DOC_LINK_PREVIEW_LONG_BYTES = 1024,
CBM_DOC_LINK_PREVIEW_SHORT_BYTES = 128,
CBM_DOC_LINK_PREVIEW_LOOKAHEAD = 3,
};
typedef struct {
const char *text;
size_t length; /* copied prefix bytes, excluding the added NUL */
uint64_t original_bytes;
} cbm_doc_link_preview_text_t;
typedef struct {
cbm_doc_link_preview_text_t rel_path;
int line;
cbm_doc_link_preview_text_t syntax;
cbm_doc_link_preview_text_t raw;
cbm_doc_link_preview_text_t reason;
} cbm_doc_link_preview_row_t;
/* Up to fifty rows ordered by original (reason, rel_path, line, raw), before
* empty-path marker filtering. Text is an explicit-length byte prefix and may
* contain NUL or invalid UTF-8. Missing-table semantics match the full getter.
* On failure, no rows are returned. All allocations belong to STORE. */
int cbm_store_doc_links_preview(cbm_store_t *s, const char *project,
cbm_doc_link_preview_row_t **out, int *count, bool *table_present);
void cbm_store_free_doc_link_previews(cbm_doc_link_preview_row_t *rows, int count);
#ifdef CBM_ENABLE_TEST_SEAMS
/* Sample-field copies only: exclude full getters, row arrays and reason keys.
* Byte counts include the trailing NUL. Requests include failed allocations;
* field_copies/copied_bytes count only successful copies. Reset leaves fault
* controls and their consumed flag unchanged. */
typedef struct {
uint64_t field_copies;
uint64_t copied_bytes;
uint64_t requested_bytes;
uint64_t max_request_bytes;
} cbm_doc_links_sample_test_stats_t;
void cbm_store_doc_links_test_sample_stats_reset(void);
void cbm_store_doc_links_test_sample_stats(cbm_doc_links_sample_test_stats_t *out);
/* One-shot field-copy allocation failure: 0 is next, 4 is fifth, -1 disables.
* Setting the control clears its consumed flag. */
void cbm_store_doc_links_test_fail_sample_alloc_after(int successful_copies);
bool cbm_store_doc_links_test_sample_alloc_failed(void);
#endif
void cbm_store_free_doc_links(cbm_doc_link_row_t *rows, int count);
void cbm_store_free_doc_link_reasons(cbm_doc_link_reason_count_t *reasons, int count);
/* ── Search ─────────────────────────────────────────────────────── */
int cbm_store_search(cbm_store_t *s, const cbm_search_params_t *params, cbm_search_output_t *out);
/* Free a search output's allocated memory. */
void cbm_store_search_free(cbm_search_output_t *out);
/* ── Traversal ──────────────────────────────────────────────────── */
int cbm_store_bfs(cbm_store_t *s, int64_t start_id, const char *direction, const char **edge_types,
int edge_type_count, int max_depth, int max_results, cbm_traverse_result_t *out);
/* Variable-length Cypher traversal with relationship-trail semantics. */
int cbm_store_bfs_trail(cbm_store_t *s, int64_t start_id, const char *direction,
const char **edge_types, int edge_type_count, int max_depth,
int max_results, cbm_traverse_result_t *out);
/* BFS with an explicit edge-data budget. max_edges=0 skips the secondary
* all-pairs edge lookup; max_edges>0 collects at most that many edges and
* raises out->edges_truncated on saturation. Node traversal is unchanged.
* This is intended for lean callers that need nodes but not edge properties. */
int cbm_store_bfs_with_edge_limit(cbm_store_t *s, int64_t start_id, const char *direction,
const char **edge_types, int edge_type_count, int max_depth,
int max_results, int max_edges, cbm_traverse_result_t *out);
/* Multi-source BFS from ALL seed ids at once (one CTE, temp-table anchored).
* Seeds are EXCLUDED from the result (impact semantics); MIN(hop) across the
* seed set; canonical (hop,id) order; *truncated set when the max_results
* memory-safety ceiling was hit (counting is otherwise uncapped). */
int cbm_store_bfs_multi(cbm_store_t *s, const int64_t *seed_ids, int seed_count,
const char *direction, const char **edge_types, int edge_type_count,
int max_depth, int max_results, cbm_traverse_result_t *out,
bool *truncated);
/* Free a traverse result's allocated memory. */
void cbm_store_traverse_free(cbm_traverse_result_t *out);
/* ── Impact analysis ────────────────────────────────────────────── */
typedef enum {
CBM_RISK_CRITICAL = 0,
CBM_RISK_HIGH = 1,
CBM_RISK_MEDIUM = 2,
CBM_RISK_LOW = 3,
} cbm_risk_level_t;
/* Map BFS hop depth to risk level. */
cbm_risk_level_t cbm_hop_to_risk(int hop);
/* String representation of risk level. */
const char *cbm_risk_label(cbm_risk_level_t level);
typedef struct {
int critical;
int high;
int medium;
int low;
int total;
bool has_cross_service;
} cbm_impact_summary_t;
/* Build impact summary from visited hops and edges. */
cbm_impact_summary_t cbm_build_impact_summary(const cbm_node_hop_t *hops, int hop_count,
const cbm_edge_info_t *edges, int edge_count);
/* Deduplicate BFS hops, keeping minimum hop per node ID.
* Returns allocated array and count via out params. Caller frees result. */
int cbm_deduplicate_hops(const cbm_node_hop_t *hops, int hop_count, cbm_node_hop_t **out,
int *out_count);
/* ── Schema ─────────────────────────────────────────────────────── */
int cbm_store_get_schema(cbm_store_t *s, const char *project, cbm_schema_info_t *out);
/* Like cbm_store_get_schema but skips per-label/per-type JSON property-key
* discovery (json_each scans over every row) — for callers that only need
* label/type counts, e.g. get_architecture. */
int cbm_store_get_schema_counts(cbm_store_t *s, const char *project, cbm_schema_info_t *out);
int cbm_store_get_schema_counts_scoped(cbm_store_t *s, const char *project, const char *path,
cbm_schema_info_t *out);
/* Free a schema info's allocated memory. */
void cbm_store_schema_free(cbm_schema_info_t *out);
/* ── Architecture ───────────────────────────────────────────────── */
typedef struct {
const char *language;
int file_count;
} cbm_language_count_t;
typedef struct {
const char *name;
int node_count;
int fan_in;
int fan_out;
} cbm_package_summary_t;
typedef struct {
const char *name;
const char *qualified_name;
const char *file;
} cbm_entry_point_t;
typedef struct {
const char *method;
const char *path;
const char *handler;
} cbm_route_info_t;
typedef struct {
const char *name;
const char *qualified_name;
int fan_in;
} cbm_hotspot_t;
typedef struct {
const char *from;
const char *to;
int call_count;
} cbm_cross_pkg_boundary_t;
typedef struct {
const char *from;
const char *to;
const char *type;
int count;
} cbm_service_link_t;
typedef struct {
const char *name;
const char *layer;
const char *reason;
} cbm_package_layer_t;
typedef struct {
int id;
const char *label;
int members;
double cohesion;
const char **top_nodes;
int top_node_count;
const char **packages;
int package_count;
const char **edge_types;
int edge_type_count;
} cbm_cluster_info_t;
typedef struct {
const char *path;
const char *type; /* "dir" or "file" */
int children;
} cbm_file_tree_entry_t;
typedef struct {
/* Pointers first to minimize padding */
cbm_language_count_t *languages;
cbm_package_summary_t *packages;
cbm_entry_point_t *entry_points;
cbm_route_info_t *routes;
cbm_hotspot_t *hotspots;
cbm_cross_pkg_boundary_t *boundaries;
cbm_service_link_t *services;
cbm_package_layer_t *layers;
cbm_cluster_info_t *clusters;
cbm_file_tree_entry_t *file_tree;
/* Counts after pointers */
int language_count;
int package_count;
int entry_point_count;
int route_count;
int hotspot_count;
int boundary_count;
int service_count;
int layer_count;
int cluster_count;
int file_tree_count;
} cbm_architecture_info_t;
int cbm_store_get_architecture(cbm_store_t *s, const char *project, const char *path,
const char **aspects, int aspect_count,
cbm_architecture_info_t *out);
void cbm_store_architecture_free(cbm_architecture_info_t *out);
/* ── ADR (Architecture Decision Record) ────────────────────────── */
#define CBM_ADR_MAX_LENGTH 8000
typedef struct {
const char *project;
const char *content;
const char *created_at;
const char *updated_at;
} cbm_adr_t;
int cbm_store_adr_store(cbm_store_t *s, const char *project, const char *content);
int cbm_store_adr_get(cbm_store_t *s, const char *project, cbm_adr_t *out);
/* Move any legacy ADR row from the graph DB's project_summaries into the
* per-project sidecar, once (guarded by a marker in the sidecar). Call before a
* rebuild deletes the old generation, and on artifact import. Returns
* CBM_STORE_ERR on failure so callers can preserve the old generation. */
int cbm_store_adr_migrate_once(cbm_store_t *s);
/* Restore ADRs from the graph DB's project_summaries into the per-project sidecar
* for any project the sidecar has no row for, without overwriting a local one and
* regardless of the migrated marker. Used on artifact import so a teammate who
* already indexed the project (marked sidecar, no ADR) still receives the shared
* ADR the artifact carries. Returns CBM_STORE_ERR on failure. */
int cbm_store_adr_restore_from_graph_if_absent(cbm_store_t *s);
int cbm_store_adr_delete(cbm_store_t *s, const char *project);
int cbm_store_adr_update_sections(cbm_store_t *s, const char *project, const char **keys,
const char **values, int count, cbm_adr_t *out);
void cbm_store_adr_free(cbm_adr_t *adr);
/* ── Doc -> code candidates (for the agent to verify) ───────────── */
/* One documentation section -> function candidate, with the calibrated
* probability that the section is about the function. Candidates, not links:
* never graph edges; a short ranked list per section for the agent to judge. */
typedef struct {
const char *section_qn;
const char *target_qn;
int rank;
double score;
double p;
const char *evidence; /* JSON: {"terms":n,"name_tokens":m} */
} cbm_doc_candidate_t;
/* Replace the project's candidates. The table is created here, at publish
* (not in the schema): a database written by an older build has none, and
* readers treat that as "no candidates". */
int cbm_store_doc_candidates_replace(cbm_store_t *s, const char *project,
const cbm_doc_candidate_t *rows, int count);
/* The candidates of one section (section_qn) or for one function (target_qn;
* pass the other NULL), highest p first, then score, at most limit. *out is
* allocated in CBM_MEM_CLASS_STORE (cbm_store_doc_candidates_free).
* CBM_STORE_NOT_FOUND: no table. */
int cbm_store_doc_candidates_get(cbm_store_t *s, const char *project, const char *section_qn,
const char *target_qn, int limit, cbm_doc_candidate_t **out,
int *count);
/* The candidates that point at a file as a whole: at its File node, or at a
* Folder node that holds it (a doc's home folder), highest p first, then
* score, at most limit. Allocation and CBM_STORE_NOT_FOUND as above. */
int cbm_store_doc_candidates_for_path(cbm_store_t *s, const char *project, const char *file_path,
int limit, cbm_doc_candidate_t **out, int *count);
void cbm_store_doc_candidates_free(cbm_doc_candidate_t *rows, int count);
/* ADR section parsing/rendering (pure functions, no store needed) */
enum { PROPS_MAX = 16 };
typedef struct {
char *keys[PROPS_MAX];
char *values[PROPS_MAX];
int count;
} cbm_adr_sections_t;
cbm_adr_sections_t cbm_adr_parse_sections(const char *content);
char *cbm_adr_render(const cbm_adr_sections_t *sections);
int cbm_adr_validate_content(const char *content, char *errbuf, int errbuf_size);
int cbm_adr_validate_section_keys(const char **keys, int count, char *errbuf, int errbuf_size);
void cbm_adr_sections_free(cbm_adr_sections_t *s);
/* ── ADR section headings (the splice model) ────────────────────
*
* A section write must not rebuild the document. cbm_adr_parse_sections() +
* cbm_adr_render() is a lossy model — it drops everything before the first
* heading, drops headings it does not recognise, and reorders what is left —
* so rebuilding from it silently rewrites text nobody asked to change. These
* functions locate a heading's byte span instead, so a write replaces that
* span and leaves every other byte of the document exactly as it was.
*
* A heading is a line of the form "## NAME" that is NOT inside a fenced code
* block. NAME is matched EXACTLY, including case: "## Purpose" and
* "## PURPOSE" are different sections, because folding them would silently
* merge two blocks the author chose to keep apart. The six canonical names
* are a convention (see ADR_EMPTY_HINT), not a privilege: any name that
* round-trips is a section, and none of them gets ordering priority. */
typedef struct {
const char *name; /* into the source buffer; NOT NUL-terminated */
int name_len;
size_t heading_start; /* offset of the first '#' of the heading line */
size_t body_start; /* offset just past the heading line's newline */
size_t body_end; /* offset of the next heading, or end of document */
} cbm_adr_heading_t;
/* Reports every heading in document order. Returns CBM_STORE_ERR without
* calling `cb` when the document has an unterminated code fence: its structure
* is ambiguous, and guessing could splice into a code sample. */
int cbm_adr_scan_headings(const char *content, void (*cb)(void *ctx, const cbm_adr_heading_t *h),
void *ctx);
/* CBM_STORE_ERR + message when the document cannot be spliced safely. */
int cbm_adr_check_structure(const char *content, char *errbuf, int errbuf_size);
/* Replaces the body of `name`, or appends the section when it is absent.
* Returns a new document (caller frees), or NULL on bad input, an unterminated
* fence, or OOM. Bytes outside the replaced span are preserved exactly, and
* splicing the same name and body twice is byte-identical to doing it once. */
char *cbm_adr_splice_section(const char *content, const char *name, const char *body);
/* Rejects names that could not round-trip through a "## NAME" heading. */
int cbm_adr_validate_section_name(const char *name, char *errbuf, int errbuf_size);
/* ── Search helpers (exposed for testing) ───────────────────────── */
/* Convert a glob pattern to SQL LIKE pattern. Caller must free result. */
char *cbm_glob_to_like(const char *pattern);
/* Extract literal substrings (>= 3 chars) from a regex pattern for LIKE pre-filtering.
* Bails on alternation (|). Returns count of hints written to out[].
* Each out[i] is malloc'd — caller must free each string. */
int cbm_extract_like_hints(const char *pattern, char **out, int max_out);
/* Literal prefix every match of an anchored POSIX ERE must begin with: the
* plain printable-ASCII run after a leading '^', minus its last character when
* a quantifier or escape follows it. Returns its length (written NUL-terminated
* to out); 0 when the pattern is not anchored, contains '|', or starts with an
* operator. Case is kept as written. */
int cbm_regex_anchored_prefix(const char *pattern, char *out, int out_sz);
/* Prepend (?i) to a regex pattern if not already present.
* Returns a static buffer — do NOT free. */
const char *cbm_ensure_case_insensitive(const char *pattern);
/* Strip leading (?i) from a regex pattern.
* Returns a static buffer — do NOT free. */
const char *cbm_strip_case_flag(const char *pattern);
/* ── Architecture helpers (exposed for testing) ────────────────── */
const char *cbm_qn_to_package(const char *qn);
const char *cbm_qn_to_top_package(const char *qn);
bool cbm_is_test_file_path(const char *fp);
int cbm_store_find_architecture_docs(cbm_store_t *s, const char *project, char ***out, int *count);
/* ── Community detection (Leiden) ──────────────────────────────── */
typedef struct {
int64_t src;
int64_t dst;
} cbm_louvain_edge_t;
typedef struct {
int64_t node_id;
int community;
} cbm_louvain_result_t;
/* Multi-level Leiden community detection (Traag, Waltman & van Eck 2019,
* arXiv:1810.08473): local moving + refinement + aggregation, repeated until
* the partition can no longer be coarsened. Refinement guarantees every
* reported community is internally connected. The resolution parameter
* controls granularity (higher -> more, smaller communities); 1.0 is standard.
* Allocates *out (length *out_count == node_count) in CBM_MEM_CLASS_OTHER;
* the caller releases it with cbm_leiden_free(*out). */
int cbm_leiden(const int64_t *nodes, int node_count, const cbm_louvain_edge_t *edges,
int edge_count, double resolution, cbm_louvain_result_t **out, int *out_count);
/* Convenience wrapper: cbm_leiden with resolution 1.0. */
int cbm_louvain(const int64_t *nodes, int node_count, const cbm_louvain_edge_t *edges,
int edge_count, cbm_louvain_result_t **out, int *out_count);
/* Free the result array returned by cbm_leiden / cbm_louvain. */
void cbm_leiden_free(cbm_louvain_result_t *result);
/* ── Memory management helpers ──────────────────────────────────── */
/* Free heap-allocated strings in a stack-allocated node (does NOT free the node itself). */
void cbm_node_free_fields(cbm_node_t *n);
/* Free heap-allocated strings in a stack-allocated project (does NOT free the project itself). */
void cbm_project_free_fields(cbm_project_t *p);
/* Free an array of nodes returned by find_nodes_by_* functions. */
void cbm_store_free_nodes(cbm_node_t *nodes, int count);
/* Free an array of edges returned by find_edges_by_* functions. */
void cbm_store_free_edges(cbm_edge_t *edges, int count);
/* Free an array of projects. */
void cbm_store_free_projects(cbm_project_t *projects, int count);
/* Free an array of file hashes. */
void cbm_store_free_file_hashes(cbm_file_hash_t *hashes, int count);
/* ── Vector search ───────────────────────────────────────────────── */
/* Result from vector similarity search. */
typedef struct {
int64_t node_id;
char *name;
char *qualified_name;
char *file_path;
char *label;
double score;
} cbm_vector_result_t;
/* Search for nodes similar to the given query keywords using stored RI vectors.
* Builds a merged query vector from the keywords, then does cosine scan via
* the cbm_cosine_i8 SQL function joined with the nodes table.
* Returns CBM_STORE_OK with results sorted by score DESC (possibly zero),
* CBM_STORE_NOT_FOUND when the store carries no node_vectors table (lean
* index — an empty universe, not a fault), or CBM_STORE_ERR when the scan
* itself failed; callers must not render CBM_STORE_ERR as zero matches.
* Caller must free with cbm_store_free_vector_results. */
int cbm_store_vector_search(cbm_store_t *s, const char *project, const char **keywords,
int keyword_count, int limit, cbm_vector_result_t **out,
int *out_count);
/* Free vector search results. */
void cbm_store_free_vector_results(cbm_vector_result_t *results, int count);
/* Count vectors for a project. */
int cbm_store_count_vectors(cbm_store_t *s, const char *project);
/* Execute an arbitrary SQL statement (pragmas, FTS5 maintenance, etc).
* Returns CBM_STORE_OK on success. */
int cbm_store_exec(cbm_store_t *s, const char *sql);
/* Populate nodes_fts from the `nodes` table — the single writer for the BM25
* index. Every backfill site routes through it so the column list is decided
* in exactly ONE place: a hand-written INSERT that names only the identifier
* columns silently leaves `body` NULL for every node it writes, which looks
* perfect after a full reindex and de-indexes prose on the warm path.
*
* project == NULL → wholesale rebuild: clears the index, then reindexes
* every node in the database.
* project != NULL → incremental: indexes only that project's nodes with
* id > after_id and leaves existing rows untouched.
*
* Returns CBM_STORE_OK on success; CBM_STORE_NOT_FOUND when nodes_fts cannot
* be written at all (FTS5 compiled out — the caller decides whether that is
* fatal); CBM_STORE_ERR on a genuine write failure. */
int cbm_store_fts_rebuild(cbm_store_t *s, const char *project, int64_t after_id);
#endif /* CBM_STORE_H */