Keeping the Map Honest as Code Changes

CodeGraph’s value depends on more than finding the right relationship once; the relationship must still describe the working tree when an agent acts on it. This chapter follows the index through an edit, a pending state, incremental sync, reconnect catch-up, and failure recovery. The practical judgment is when to trust automatic freshness, when to read a file directly, and when a rebuild is safer than another query.

From edit to pending state

A file watcher is the first part of the freshness contract, not the whole contract. CodeGraph watches the project using native operating-system events, filters those events to relevant source paths, and debounces bursts of changes before starting a sync. The debounce matters because an editor, formatter, or build step can touch several files in quick succession. Treating every event as a separate indexing run would create work while the files are still changing.

The normal lifecycle begins with a graph that represents the current baseline. A source file is created, modified, or deleted. The watcher records the path as pending and waits for a quiet window. It then asks incremental sync to compare the working tree with the stored file records, re-extract changed files, update their nodes and edges, and run the resolution work needed to bring the graph back into line.

The pending state is not hidden from the agent. If a tool response would use a file that has changed since the last completed sync, CodeGraph can prepend a staleness banner naming that file and telling the agent to read it directly for accurate content. Pending files that are not relevant to the current response can be reported separately rather than interrupting an otherwise fresh result. This is a small but important design choice: the system does not make the agent wait for every edit, and it does not silently serve an old body as though it were current.

The ownership boundary is clear. The watcher owns the observation that a path changed. The indexer owns reconciling that path with the stored file record. The MCP response owns telling the agent whether the file it is about to rely on has crossed those boundaries yet. No single component can make the graph fresh by assertion alone. The source event must be delivered, the sync must complete, and the response must account for edits that arrived during the transition.

This also explains why the pending banner is per file rather than a single project-wide warning. An edit to a file unrelated to the current flow should not force every query into a direct-read fallback. An edit to a file whose source is being returned should. The signal follows the dependency between the response and the changed path, which is exactly the granularity needed for surgical context.