Skip to content

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.

67.8 KB
Raw Blame
/*
 * 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 */