feat(mcp): expose index freshness and relationship provenance

Signed-off-by: Vladimir Venegas Velásquez <vvenegasv@gmail.com>

Author: vvenegasv

README.md

@@ -382,6 +382,17 @@ codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.result
 | `delete_project` | Remove a project and all its graph data. |
 | `index_status` | Check indexing status of a project. |
 
+`index_status` includes an additive `evidence` object. `evidence.index_snapshot`
+reports the timestamp and Git HEAD captured when the last successful graph
+snapshot was finalized, the current HEAD, tracked working-tree state, and a
+`freshness` value: `current` means the indexed HEAD equals current HEAD and
+tracked files are clean; `head_changed` means a later checkout/commit changed
+HEAD; `working_tree_changed` means HEAD matches but tracked files are modified;
+`unknown` means Git or comparison data is unavailable. Untracked files are not
+compared. `evidence.coverage` reports discovered/indexed/excluded/failed file
+counters when the stored index contains them; older indexes may report
+`unknown` rather than guessing.
+
 ### Querying
 
 | Tool | Description |
@@ -393,6 +404,14 @@ codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.result
 | `get_graph_schema` | Node/edge counts, relationship patterns, property definitions per label. Run this first. |
 | `get_code_snippet` | Read source code for a function by qualified name. |
 | `get_architecture` | Codebase overview: languages, packages, routes, hotspots, clusters, ADR. |
+
+`trace_path`/`trace_call_path` preserve their existing `callers`/`callees`
+arrays and add `edge_evidence` for traversed relations when stored edge
+properties contain provenance. Relation `confidence` is source-resolution
+confidence from the indexer, not a probability of runtime correctness and not
+BM25/semantic search relevance. Dynamic behavior such as reflection,
+dependency injection, framework wiring, generated code, configuration, HTTP,
+async messaging, and cross-repo links may remain inferred or unavailable.
 | `search_code` | Grep-like text search within indexed project files. |
 | `manage_adr` | CRUD for Architecture Decision Records. |
 | `ingest_traces` | Ingest runtime traces to validate HTTP_CALLS edges. |

internal/cbm/sqlite_writer.c

@@ -788,7 +788,7 @@ static uint8_t *build_token_vec_record(const CBMDumpTokenVec *tv, int *out_len)
     return data;
 }
 
-// Build a projects table record: (name, indexed_at, root_path)
+// Build a projects table record.
 static uint8_t *build_project_record(const char *name, const char *indexed_at,
                                      const char *root_path, int *out_len) {
     RecordBuilder r;
@@ -797,6 +797,13 @@ static uint8_t *build_project_record(const char *name, const char *indexed_at,
     rec_add_text(&r, name);
     rec_add_text(&r, indexed_at);
     rec_add_text(&r, root_path);
+    /* indexed_git_head: unavailable in the direct writer path */
+    rec_add_null(&r);
+    /* files_discovered, files_indexed, files_excluded, files_failed */
+    rec_add_int(&r, 0);
+    rec_add_int(&r, 0);
+    rec_add_int(&r, 0);
+    rec_add_int(&r, 0);
 
     uint8_t *data = rec_finalize(&r, out_len);
     rec_free(&r);
@@ -2113,7 +2120,10 @@ static int write_db_after_nodes(write_db_ctx_t *w, uint32_t nodes_root) {
     MasterEntry master[] = {
         {"table", "projects", "projects", projects_root,
          "CREATE TABLE projects (\n\t\tname TEXT PRIMARY KEY,\n\t\tindexed_at TEXT NOT "
-         "NULL,\n\t\troot_path TEXT NOT NULL\n\t)"},
+         "NULL,\n\t\troot_path TEXT NOT NULL,\n\t\tindexed_git_head TEXT,\n\t\tfiles_discovered "
+         "INTEGER NOT NULL DEFAULT 0,\n\t\tfiles_indexed INTEGER NOT NULL DEFAULT 0,\n\t\t"
+         "files_excluded INTEGER NOT NULL DEFAULT 0,\n\t\tfiles_failed INTEGER NOT NULL DEFAULT "
+         "0\n\t)"},
         {"index", "sqlite_autoindex_projects_1", "projects", autoindex_projects_root, NULL},
         {"table", "file_hashes", "file_hashes", file_hashes_root,
          "CREATE TABLE file_hashes (\n\t\tproject TEXT NOT NULL REFERENCES projects(name) ON "

src/git/git_context.c

@@ -266,6 +266,42 @@ int cbm_git_context_resolve(const char *path, cbm_git_context_t *out) {
     return 0;
 }
 
+int cbm_git_tracked_dirty(const char *path, bool *out_dirty) {
+    if (!out_dirty) {
+        return CBM_NOT_FOUND;
+    }
+    *out_dirty = false;
+
+    if (!path || !git_validate_repo_path(path)) {
+        return CBM_NOT_FOUND;
+    }
+
+    char cmd[GIT_CMD_MAX];
+#ifdef _WIN32
+    const char *null_dev = "NUL";
+#else
+    const char *null_dev = "/dev/null";
+#endif
+    int n = snprintf(cmd, sizeof(cmd), "git -C \"%s\" status --porcelain --untracked-files=no 2>%s",
+                     path, null_dev);
+    if (n < 0 || n >= (int)sizeof(cmd)) {
+        return CBM_NOT_FOUND;
+    }
+
+    FILE *fp = cbm_popen(cmd, "r");
+    if (!fp) {
+        return CBM_NOT_FOUND;
+    }
+    char buf[GIT_OUTPUT_MAX];
+    bool has_output = fgets(buf, sizeof(buf), fp) != NULL;
+    int rc = cbm_pclose(fp);
+    if (rc != 0) {
+        return CBM_NOT_FOUND;
+    }
+    *out_dirty = has_output;
+    return 0;
+}
+
 char *cbm_git_context_branch_qn(const char *project_name, const cbm_git_context_t *ctx) {
     const char *project = project_name && project_name[0] ? project_name : "project";
     const char *slug = "working-tree";

src/git/git_context.h

@@ -21,6 +21,9 @@ typedef struct {
 
 int cbm_git_context_resolve(const char *path, cbm_git_context_t *out);
 void cbm_git_context_free(cbm_git_context_t *ctx);
+/* Returns 0 when tracked working-tree dirtiness was determined, non-zero when
+ * unavailable. Untracked files are intentionally not compared. */
+int cbm_git_tracked_dirty(const char *path, bool *out_dirty);
 char *cbm_git_context_branch_qn(const char *project_name, const cbm_git_context_t *ctx);
 int cbm_git_context_props_json(const cbm_git_context_t *ctx, char *buf, int buf_size);
 

src/mcp/mcp.c

@@ -896,6 +896,85 @@ static void add_git_context_json(yyjson_mut_doc *doc, yyjson_mut_val *obj, const
     cbm_git_context_free(&ctx);
 }
 
+static void add_index_evidence_json(yyjson_mut_doc *doc, yyjson_mut_val *root,
+                                    const cbm_project_t *proj) {
+    yyjson_mut_val *evidence = yyjson_mut_obj(doc);
+    yyjson_mut_val *snap = yyjson_mut_obj(doc);
+    const char *indexed_head = (proj && proj->indexed_git_head && proj->indexed_git_head[0])
+                                   ? proj->indexed_git_head
+                                   : NULL;
+    cbm_git_context_t ctx = {0};
+    int git_rc = cbm_git_context_resolve(proj ? proj->root_path : NULL, &ctx);
+    bool dirty = false;
+    int dirty_rc = (proj && git_rc == 0 && ctx.is_git)
+                       ? cbm_git_tracked_dirty(proj->root_path, &dirty)
+                       : CBM_NOT_FOUND;
+
+    add_git_context_string(doc, snap, "indexed_at", proj ? proj->indexed_at : NULL);
+    add_git_context_string(doc, snap, "indexed_git_head", indexed_head);
+    add_git_context_string(
+        doc, snap, "current_git_head",
+        (git_rc == 0 && ctx.is_git && ctx.head_sha && ctx.head_sha[0]) ? ctx.head_sha : NULL);
+    const char *repo_state = "unavailable";
+    if (git_rc == 0 && ctx.root_exists && !ctx.is_git) {
+        repo_state = "not_git";
+    } else if (git_rc == 0 && ctx.is_git && dirty_rc == 0) {
+        repo_state = dirty ? "dirty" : "clean";
+    }
+    yyjson_mut_obj_add_str(doc, snap, "repository_state", repo_state);
+    if (indexed_head && git_rc == 0 && ctx.is_git && ctx.head_sha && ctx.head_sha[0]) {
+        yyjson_mut_obj_add_bool(doc, snap, "snapshot_matches_current_head",
+                                strcmp(indexed_head, ctx.head_sha) == 0);
+    } else {
+        yyjson_mut_obj_add_null(doc, snap, "snapshot_matches_current_head");
+    }
+    if (indexed_head && git_rc == 0 && ctx.is_git && ctx.head_sha && ctx.head_sha[0] &&
+        dirty_rc == 0) {
+        yyjson_mut_obj_add_bool(doc, snap, "snapshot_matches_working_tree",
+                                strcmp(indexed_head, ctx.head_sha) == 0 && !dirty);
+    } else {
+        yyjson_mut_obj_add_null(doc, snap, "snapshot_matches_working_tree");
+    }
+    const char *freshness = "unknown";
+    if (indexed_head && git_rc == 0 && ctx.is_git && ctx.head_sha && ctx.head_sha[0] &&
+        dirty_rc == 0) {
+        if (strcmp(indexed_head, ctx.head_sha) != 0) {
+            freshness = "head_changed";
+        } else {
+            freshness = dirty ? "working_tree_changed" : "current";
+        }
+    } else if (git_rc == 0 && ctx.root_exists && !ctx.is_git) {
+        freshness = "unknown";
+    }
+    yyjson_mut_obj_add_str(doc, snap, "freshness", freshness);
+    yyjson_mut_obj_add_val(doc, evidence, "index_snapshot", snap);
+
+    yyjson_mut_val *cov = yyjson_mut_obj(doc);
+    int discovered = proj ? proj->files_discovered : 0;
+    int indexed = proj ? proj->files_indexed : 0;
+    int excluded = proj ? proj->files_excluded : 0;
+    int failed = proj ? proj->files_failed : 0;
+    yyjson_mut_obj_add_int(doc, cov, "files_discovered", discovered);
+    yyjson_mut_obj_add_int(doc, cov, "files_indexed", indexed);
+    yyjson_mut_obj_add_int(doc, cov, "files_excluded", excluded);
+    yyjson_mut_obj_add_int(doc, cov, "files_failed", failed);
+    yyjson_mut_obj_add_str(doc, cov, "coverage_status",
+                           failed > 0 || excluded > 0                ? "partial"
+                           : discovered > 0 && indexed == discovered ? "complete"
+                                                                     : "unknown");
+    yyjson_mut_obj_add_val(doc, evidence, "coverage", cov);
+    yyjson_mut_val *limits = yyjson_mut_arr(doc);
+    yyjson_mut_val *lim = yyjson_mut_obj(doc);
+    yyjson_mut_obj_add_str(doc, lim, "code", "UNTRACKED_FILES_NOT_COMPARED");
+    yyjson_mut_obj_add_str(doc, lim, "message",
+                           "Working-tree freshness compares current HEAD and tracked "
+                           "modifications; untracked files are not compared.");
+    yyjson_mut_arr_add_val(limits, lim);
+    yyjson_mut_obj_add_val(doc, evidence, "limitations", limits);
+    yyjson_mut_obj_add_val(doc, root, "evidence", evidence);
+    cbm_git_context_free(&ctx);
+}
+
 /* Build a helpful error listing available projects. Caller must free() result. */
 static char *build_project_list_error(const char *reason) {
     char dir_path[CBM_SZ_1K];
@@ -1781,9 +1860,8 @@ static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
             yyjson_mut_obj_add_strcpy(doc, root, "root_path",
                                       proj_info.root_path ? proj_info.root_path : "");
             add_git_context_json(doc, root, proj_info.root_path);
-            safe_str_free(&proj_info.name);
-            safe_str_free(&proj_info.indexed_at);
-            safe_str_free(&proj_info.root_path);
+            add_index_evidence_json(doc, root, &proj_info);
+            cbm_project_free_fields(&proj_info);
         }
         if (nodes == 0) {
             yyjson_mut_obj_add_str(
@@ -2349,6 +2427,79 @@ static int pick_resolved_node(const cbm_node_t *nodes, int count, bool *ambiguou
     return best;
 }
 
+static const char *edge_evidence_status(const char *strategy, double confidence, int candidates) {
+    if (!strategy || !strategy[0]) {
+        return "unavailable";
+    }
+    if (candidates > 1) {
+        return "ambiguous";
+    }
+    if (strstr(strategy, "heur") || strstr(strategy, "fuzzy") || confidence < 0.8) {
+        return "inferred";
+    }
+    return "verified";
+}
+
+static const char *edge_resolution_strategy(const char *strategy) {
+    if (!strategy || !strategy[0]) {
+        return "unknown";
+    }
+    if (strstr(strategy, "lsp")) {
+        return "hybrid_lsp";
+    }
+    if (strstr(strategy, "import") || strstr(strategy, "same_module") ||
+        strstr(strategy, "receiver")) {
+        return "direct_ast";
+    }
+    if (strstr(strategy, "fuzzy") || strstr(strategy, "heur")) {
+        return "heuristic";
+    }
+    return strategy;
+}
+
+static yyjson_mut_val *trace_edges_to_json_array(yyjson_mut_doc *doc, cbm_traverse_result_t *tr) {
+    yyjson_mut_val *arr = yyjson_mut_arr(doc);
+    for (int i = 0; i < tr->edge_count; i++) {
+        yyjson_mut_val *item = yyjson_mut_obj(doc);
+        yyjson_mut_obj_add_str(doc, item, "from",
+                               tr->edges[i].from_name ? tr->edges[i].from_name : "");
+        yyjson_mut_obj_add_str(doc, item, "to", tr->edges[i].to_name ? tr->edges[i].to_name : "");
+        yyjson_mut_obj_add_str(doc, item, "type", tr->edges[i].type ? tr->edges[i].type : "");
+        yyjson_mut_val *edge = yyjson_mut_obj(doc);
+        const char *props = tr->edges[i].properties_json;
+        yyjson_doc *pdoc = props ? yyjson_read(props, strlen(props), 0) : NULL;
+        yyjson_val *proot = pdoc ? yyjson_doc_get_root(pdoc) : NULL;
+        yyjson_val *v = proot ? yyjson_obj_get(proot, "strategy") : NULL;
+        const char *strategy = yyjson_is_str(v) ? yyjson_get_str(v) : NULL;
+        v = proot ? yyjson_obj_get(proot, "confidence") : NULL;
+        bool has_conf = yyjson_is_num(v);
+        double conf = has_conf ? yyjson_get_num(v) : 0.0;
+        v = proot ? yyjson_obj_get(proot, "candidates") : NULL;
+        int candidates = yyjson_is_int(v) ? (int)yyjson_get_int(v) : 0;
+        yyjson_mut_obj_add_str(doc, edge, "resolution_strategy",
+                               edge_resolution_strategy(strategy));
+        if (has_conf) {
+            yyjson_mut_obj_add_real(doc, edge, "confidence", conf);
+        } else {
+            yyjson_mut_obj_add_null(doc, edge, "confidence");
+        }
+        if (candidates > 0) {
+            yyjson_mut_obj_add_int(doc, edge, "candidate_count", candidates);
+        } else {
+            yyjson_mut_obj_add_null(doc, edge, "candidate_count");
+        }
+        yyjson_mut_obj_add_null(doc, edge, "source_location");
+        yyjson_mut_obj_add_str(doc, edge, "evidence_status",
+                               edge_evidence_status(strategy, conf, candidates));
+        yyjson_mut_obj_add_val(doc, item, "edge", edge);
+        yyjson_mut_arr_add_val(arr, item);
+        if (pdoc) {
+            yyjson_doc_free(pdoc);
+        }
+    }
+    return arr;
+}
+
 static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
     char *func_name = cbm_mcp_get_string_arg(args, "function_name");
     char *project = cbm_mcp_get_string_arg(args, "project");
@@ -2486,6 +2637,16 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
         yyjson_mut_obj_add_val(doc, root, "callers",
                                bfs_to_json_array(doc, &tr_in, risk_labels, include_tests));
     }
+    yyjson_mut_val *edge_evidence = yyjson_mut_obj(doc);
+    if (do_outbound) {
+        yyjson_mut_obj_add_val(doc, edge_evidence, "outbound",
+                               trace_edges_to_json_array(doc, &tr_out));
+    }
+    if (do_inbound) {
+        yyjson_mut_obj_add_val(doc, edge_evidence, "inbound",
+                               trace_edges_to_json_array(doc, &tr_in));
+    }
+    yyjson_mut_obj_add_val(doc, root, "edge_evidence", edge_evidence);
 
     /* Serialize BEFORE freeing traversal results (yyjson borrows strings) */
     char *json = yy_doc_to_str(doc);

src/pipeline/pipeline.c

@@ -876,6 +876,8 @@ static int dump_and_persist_hashes(cbm_pipeline_t *p, const cbm_file_info_t *fil
                                            stat_mtime_ns(&fst), fst.st_size);
             }
         }
+        (void)cbm_store_update_project_coverage(hash_store, p->project_name, file_count, file_count,
+                                                p->excluded_count, 0);
 
         /* FTS5 backfill: populate nodes_fts with camelCase-split names.
          * Contentless FTS5 requires the special 'delete-all' command instead of