Graphify: private revision-bound local graph lifecycle

[jeffhuber]

Part of #902.

Problem

If #876 adopts Graphify, Code Mower needs a safe lifecycle that cannot index an active checkout or confuse a stale graph with current source.

Scope

Add an optional exact Graphify pin, immutable tracked-file materialization, scrubbed environment/network posture, private 0700 state, atomic build manifest/artifact, and build/refresh/status/remove plus doctor commands. No hooks, watcher, hosted service, semantic extraction, or default dependency.

Dependencies

• Context: evaluate official Graphify as a local repository provider for v1.4.1 #876

Acceptance criteria

• Work starts only if Context: evaluate official Graphify as a local repository provider for v1.4.1 #876 records adopt.
• Every artifact binds full commit/tree SHA, provider version/options, build time, tracked census/digest, graph digest/bytes, and completeness.
• Untracked/private files cannot enter the graph.
• Refresh is explicit and atomically publishes a new immutable generation.
• Stale, corrupt, oversized, partial, and permission-invalid artifacts fail closed.

Code Mower delivery

Produce exactly one independently reviewable PR for this issue. Record the named builder, keep one writer on the branch, run focused tests and applicable full checks, obtain an independent Code Mower review against the exact current head, resolve every P0/P1/P2 finding, and pass normal CI plus code-mower/gate. Update the parent epic with PR/head, review, validation, outcome, and safe metadata-only upload evidence. Do not put credentials, source, diffs, prompts, transcripts, private context, task/message prose, or raw provider output in cloud data.

[jeffhuber]

Claude lane: delivered

PR: #926
Head: 3cff55a47b75be83ab00ef82b10ad67f9f499945
Labels: builder:claude, needs-codex-audit
Closing reference: the PR body closes this issue.

What shipped

src/code_mower/context_graph_lifecycle.py and src/code_mower/context_graph_command.py, plus code-mower context-graph build | refresh | status | remove | doctor, tests/test_context_graph_lifecycle.py, and docs/context-graph-lifecycle.md.

Against the acceptance criteria:

• Context: evaluate official Graphify as a local repository provider for v1.4.1 #876 records adopt — docs/graphify-evaluation.md records adopt-with-conditions (merged as context: adopt Graphify as an optional bounded local provider and prove the graph contract offline #924), so the gate is open.
• Artifact binding — BuildManifest binds full commit and tree, the exact pin with wheel digest and options, build time, tracked census count/bytes/digest, graph digest/bytes, completeness, skipped-path count, and the provider's indexed-file claim. Validated on every read.
• Untracked/private files cannot enter — the census comes from the commit's tree, never the working tree or index, and the blobs are materialized into a fresh 0700 directory as 0600 files. Symlinks and gitlinks are skipped and recorded as skipped.
• Refresh is explicit and atomic — build refuses when a usable generation already binds the revision; refresh publishes a new immutable generation. Two atomic renames: the generation becomes visible whole, then current names it.
• Fail closed — graph_status resolves to exactly one of absent/stale/corrupt/oversized/partial/invalid/current, and only current is usable. No fallback to an older generation. The privacy check runs on every read, so state loosened after the fact is refused.

Environment scrubbing is in the scope line rather than the criteria: the indexer inherits PATH, TMPDIR, LANG, LC_ALL, TZ and nothing else, with every proxy emptied and HOME/XDG redirected into the build's own scratch area. Git runs with system, global and local configuration disarmed.

No dependency, indexer, hook, watcher, hosted service, or default indexing step is added. The provider seam is an injected callable.

Tests run

None on this lane. Python execution is not permitted in this session — /usr/bin/python3 -c "print(1)" is refused before it runs, so no interpreter, venv, pytest, or ruff invocation was possible. I did not loop on it.

tests/test_context_graph_lifecycle.py is written to run offline against a real throwaway Git repository with an injected indexer, but it is unexecuted here. CI is its first execution, and CI plus the Codex audit are the only validation evidence for this PR — not my description of it.

What remains

1. CI (package_matrix 3.12/3.13/3.14, code-mower/gate) must go green; I will not be here to watch it.
2. Codex audit against head 3cff55a, and a fix round for any P0/P1/P2.
3. Update epic Epic: Graphify local repository context for v1.4.1 #902 with PR/head, review, validation, and outcome once the audit lands.

Adoption conditions 4 and 6 from the evaluation (symbol-first bounded queries; gating delivery on meets_gate()) belong to the retrieval adapter and are deliberately out of scope here.

[jeffhuber]

Head updated: fe08a2b (was 3cff55a).

The first CI run surfaced exactly one failure across 2929 tests — test_cli_command_registry_is_single_source_of_truth, which pins the exact CLI handler tuple so a new command has to be declared rather than appear by accident. context-graph is now declared. Every test in tests/test_context_graph_lifecycle.py passed on 3.12, 3.13 and 3.14 in that run; that was their first execution, since Python could not run on this lane.

needs-codex-audit re-applied against fe08a2b. Remaining: CI green on the new head, the Codex audit and any P0/P1/P2 fix round, and the epic #902 update.