Skip to content

Commit 0aad606

Browse files
committed
Add truthful index freshness verdict to verbose status
Port upstream DeusData PR DeusData#1561 from the removed MCP server into the operations layer. `status --verbose` now emits a `freshness` object next to the unchanged `git` object: - indexed_generation, indexed_checkout_sha (recorded in coverage meta at the staged-generation boundary), checkout_sha (live HEAD) - status_available plus bounded tracked_changes / untracked_source samples (cap 16, truncated flag) from cbm_git_worktree_status - verdict current/stale/unknown, dominant reason, reasons[] (max 8), recommended_action The verdict is fail-closed: a missing recorded identity is unknown, a SHA mismatch or tracked changes are stale, and untracked sources, an unavailable git status or an unresolvable HEAD prevent "current". It is report-only and never triggers indexing; the default (non-verbose) status output is unchanged. The status tool schema description and docs/MEASURING_SAVINGS.md describe the new block. Integration tests (real git repos, real project DB in a private cache dir) cover current, mismatch, tracked, untracked-only, mixed, non-git, missing identity, sample-cap truncation and the verbose-only gate.
1 parent 42a2e2d commit 0aad606

4 files changed

Lines changed: 488 additions & 6 deletions

File tree

‎docs/MEASURING_SAVINGS.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -104,10 +104,12 @@ codebase-memory-cli status --project PROJECT_NAME --verbose
104104
```
105105

106106
Confirm that `root_path` is `GRAPH_REPO`, `git.head_sha` is `SHA`, and the Git
107-
context is detached. `index_status` describes the project root and its current
108-
filesystem Git context; it does **not** by itself prove that indexed records
109-
were produced from that revision. The immediately preceding successful fresh
110-
`index_repository` call is the freshness requirement.
107+
context is detached. The verbose `freshness` object compares the checkout SHA
108+
recorded when the index was written with the live HEAD and a bounded worktree
109+
status; `verdict` is `current`, `stale`, or `unknown` (report-only, it never
110+
indexes). Treat anything other than `current` as not proven. The immediately
111+
preceding successful fresh `index_repository` call remains the freshness
112+
requirement.
111113

112114
Finally, run one or more representative queries whose expected symbols you
113115
have verified directly at the recorded SHA:

‎src/operations/read.c‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@
3636
#define OP_DB_EXT_LEN 3U
3737
#define OP_COVERAGE_FILE_CAP 500
3838
#define OP_COVERAGE_SUMMARY_SAMPLES 5
39+
#define OP_STATUS_SAMPLE_MAX 16 /* per-class path samples in verbose freshness */
40+
#define OP_REASONS_MAX 8 /* freshness reasons array ceiling */
3941
#define OP_PROJECTS_MAX_LIMIT 500
4042

4143
static char *copy_string(const char *text);
@@ -542,6 +544,126 @@ static void add_status_coverage(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_s
542544
}
543545
}
544546

547+
/* Bounded worktree-status snapshot inside the freshness block. Fail-closed:
548+
* status_available is false whenever git status could not run clean, in which
549+
* case counts are zero and no samples are emitted -- a non-git root or missing
550+
* git is never presented as a clean worktree. Ignored paths are absent. */
551+
static void add_worktree_status_json(yyjson_mut_doc *doc, yyjson_mut_val *freshness,
552+
const cbm_worktree_status_t *st) {
553+
yyjson_mut_obj_add_bool(doc, freshness, "status_available", st->available);
554+
555+
yyjson_mut_val *tracked = yyjson_mut_obj(doc);
556+
yyjson_mut_obj_add_int(doc, tracked, "count", st->tracked_count);
557+
yyjson_mut_val *tpaths = yyjson_mut_arr(doc);
558+
for (int i = 0; i < st->tracked_sample_count; i++)
559+
yyjson_mut_arr_add_strcpy(doc, tpaths, st->tracked_paths[i]);
560+
yyjson_mut_obj_add_val(doc, tracked, "paths", tpaths);
561+
yyjson_mut_obj_add_bool(doc, tracked, "truncated", st->tracked_truncated);
562+
yyjson_mut_obj_add_val(doc, freshness, "tracked_changes", tracked);
563+
564+
yyjson_mut_val *untracked = yyjson_mut_obj(doc);
565+
yyjson_mut_obj_add_int(doc, untracked, "count", st->untracked_count);
566+
yyjson_mut_val *upaths = yyjson_mut_arr(doc);
567+
for (int i = 0; i < st->untracked_sample_count; i++)
568+
yyjson_mut_arr_add_strcpy(doc, upaths, st->untracked_paths[i]);
569+
yyjson_mut_obj_add_val(doc, untracked, "paths", upaths);
570+
yyjson_mut_obj_add_bool(doc, untracked, "truncated", st->untracked_truncated);
571+
yyjson_mut_obj_add_val(doc, freshness, "untracked_source", untracked);
572+
}
573+
574+
/* Fail-closed freshness verdict against the indexed-checkout identity recorded
575+
* with the DB at the staged-generation boundary:
576+
* - no indexed SHA -> unknown
577+
* - indexed SHA differs from live git HEAD -> stale
578+
* - tracked changes present -> stale
579+
* - untracked sources / status unavailable -> prevents current (unknown)
580+
* - equal SHA + status available + no changes -> current
581+
* Report-only: never triggers indexing. Verbose-only. */
582+
static void add_index_freshness_json(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_store_t *store,
583+
const char *project, const char *root_path,
584+
const char *indexed_generation) {
585+
yyjson_mut_val *freshness = yyjson_mut_obj(doc);
586+
yyjson_mut_obj_add_strcpy(doc, freshness, "indexed_generation",
587+
indexed_generation ? indexed_generation : "");
588+
589+
cbm_coverage_meta_t meta = {0};
590+
bool have_meta = store && cbm_store_coverage_meta_get(store, project, &meta) == CBM_STORE_OK;
591+
const char *indexed_sha = NULL;
592+
if (have_meta && meta.indexed_checkout_sha && meta.indexed_checkout_sha[0])
593+
indexed_sha = meta.indexed_checkout_sha;
594+
595+
cbm_git_context_t ctx = {0};
596+
(void)cbm_git_context_resolve(root_path, &ctx);
597+
const char *checkout_sha = ctx.head_sha && ctx.head_sha[0] ? ctx.head_sha : NULL;
598+
599+
cbm_worktree_status_t st = {0};
600+
int status_rc = cbm_git_worktree_status(root_path, OP_STATUS_SAMPLE_MAX, &st);
601+
bool status_available = status_rc == 0 && st.available;
602+
add_worktree_status_json(doc, freshness, &st);
603+
604+
if (indexed_sha)
605+
yyjson_mut_obj_add_strcpy(doc, freshness, "indexed_checkout_sha", indexed_sha);
606+
else
607+
yyjson_mut_obj_add_null(doc, freshness, "indexed_checkout_sha");
608+
if (checkout_sha)
609+
yyjson_mut_obj_add_strcpy(doc, freshness, "checkout_sha", checkout_sha);
610+
else
611+
yyjson_mut_obj_add_null(doc, freshness, "checkout_sha");
612+
613+
/* Stale reasons win; a missing indexed identity is unknown regardless of
614+
* live state. "reason" is the first (dominant) entry of "reasons". */
615+
bool sha_present = indexed_sha != NULL;
616+
bool live_present = checkout_sha != NULL;
617+
bool sha_mismatch = sha_present && live_present && strcmp(indexed_sha, checkout_sha) != 0;
618+
bool has_tracked = st.tracked_count > 0;
619+
bool has_untracked = st.untracked_count > 0;
620+
621+
const char *verdict;
622+
if (!sha_present)
623+
verdict = "unknown";
624+
else if (sha_mismatch || has_tracked)
625+
verdict = "stale";
626+
else if (!live_present || !status_available || has_untracked)
627+
verdict = "unknown";
628+
else
629+
verdict = "current";
630+
631+
const char *reasons[OP_REASONS_MAX];
632+
int n_reasons = 0;
633+
if (!sha_present)
634+
reasons[n_reasons++] = "indexed_checkout_unavailable";
635+
if (sha_mismatch)
636+
reasons[n_reasons++] = "indexed_checkout_mismatch";
637+
if (has_tracked)
638+
reasons[n_reasons++] = "tracked_changes_present";
639+
if (!status_available)
640+
reasons[n_reasons++] = "status_unavailable";
641+
if (has_untracked)
642+
reasons[n_reasons++] = "untracked_not_indexed";
643+
if (n_reasons == 0)
644+
reasons[n_reasons++] = "indexed_checkout_current";
645+
646+
const char *recommended_action = "reindex_to_record_indexed_checkout";
647+
if (strcmp(verdict, "current") == 0)
648+
recommended_action = "use_graph";
649+
else if (strcmp(verdict, "stale") == 0)
650+
recommended_action = "reindex_to_match_checkout";
651+
652+
yyjson_mut_obj_add_str(doc, freshness, "verdict", verdict);
653+
yyjson_mut_obj_add_str(doc, freshness, "reason", reasons[0]);
654+
yyjson_mut_val *reasons_val = yyjson_mut_arr(doc);
655+
for (int i = 0; i < n_reasons; i++)
656+
yyjson_mut_arr_add_str(doc, reasons_val, reasons[i]);
657+
yyjson_mut_obj_add_val(doc, freshness, "reasons", reasons_val);
658+
yyjson_mut_obj_add_str(doc, freshness, "recommended_action", recommended_action);
659+
yyjson_mut_obj_add_val(doc, root, "freshness", freshness);
660+
661+
if (have_meta)
662+
cbm_store_coverage_meta_clear(&meta);
663+
cbm_git_worktree_status_free(&st);
664+
cbm_git_context_free(&ctx);
665+
}
666+
545667
static cbm_operation_result_t execute_status(const char *args_json,
546668
const cbm_operation_runtime_t *runtime) {
547669
char *project = json_string_arg(args_json, "project");
@@ -638,6 +760,7 @@ static cbm_operation_result_t execute_status(const char *args_json,
638760
yyjson_mut_obj_add_val(doc, root, "git", git_obj);
639761
}
640762
cbm_git_context_free(&git);
763+
add_index_freshness_json(doc, root, store, project, root_path, info.indexed_at);
641764
}
642765
}
643766
add_status_coverage(doc, root, store, project, have_info ? info.indexed_at : NULL,

‎src/operations/tool_catalog.c‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -389,8 +389,9 @@ static const tool_def_t TOOLS[] = {
389389
"not, why.",
390390
"{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},"
391391
"\"verbose\":{\"type\":\"boolean\",\"default\":false,\"description\":\"Include the git "
392-
"context block (worktree/shadow path variants). Only needed when debugging where an index "
393-
"lives — omitted by default to keep the status lean.\"},"
392+
"context block (worktree/shadow path variants) and a report-only freshness verdict "
393+
"(current/stale/unknown against the indexed checkout and worktree status). Only needed "
394+
"when debugging where an index lives — omitted by default to keep the status lean.\"},"
394395
"\"diagnostics\":{\"type\":\"string\",\"enum\":[\"none\",\"summary\",\"full\"],"
395396
"\"default\":\"none\",\"description\":\"Coverage detail: none = counts only; summary = a few "
396397
"sample paths per class; full = up to 500 paths per class.\"}},\"required\":["

0 commit comments

Comments
 (0)