A Midway Model: What Surgical Context Really Means

CodeGraph’s graph model, indexing pipeline, and explore surface describe one chain rather than three separate features. This checkpoint connects them so a reader can judge a graph-backed answer by four questions: what relationship is shown, how was it produced, is the source current, and what still needs validation. The result is a practical trust model for surgical context—not a promise that a retrieval response is already a correct program.

A graph answer is a chain of evidence

Start with source on disk. Extraction turns recognizable syntax into nodes and raw relationships. Storage keeps those facts, file conditions, and unresolved references in a reusable local graph. Resolution adds project-level connections where imports, names, inheritance, framework conventions, or bounded synthesis provide enough evidence. Retrieval then chooses a connected slice of that graph and returns source with the relationships that make the slice meaningful.

Each step can strengthen the answer, but each can also narrow or distort it. Extraction may miss a construct or capture an incomplete range. Resolution may face ambiguous names or an indirect dispatch it cannot safely connect. Retrieval may find the correct file but allocate too little of its relevant body, or omit a necessary file altogether. The agent’s explanation is therefore not simply “what the repository says.” It is what survives a chain of representations and selections.

flowchart LR S["Source on disk"] --> G["Graph fact: nodes and edges"] G --> P["Provenance and boundary"] G --> R["Retrieved source and relationships"] P --> A["Agent interpretation"] R --> A S --> F["Freshness signal"] F --> A A --> D["Direct read or narrower query"] A --> V["Compiler and tests"]

The graph fact is not the same as the retrieved context. The database may contain a relationship that the current response does not show because the allocator gave priority to another file or because a hard output limit was reached. Conversely, a response may contain source that is relevant to the question but not central to the path the agent is trying to explain. Surgical context is successful when the retrieved slice preserves the relationship needed for the decision, not merely when it contains related text.

Provenance is the link between a graph fact and a reasonable level of confidence. A direct call extracted from source and a synthesized callback connection can both appear in a flow, but they are not equivalent evidence. A route reference created from a recognized framework pattern has a different basis again. The reader does not need to reject the inferred connection; they need to know that it is inferred, where it was wired, and what consequence follows if the pattern is not the one the application actually uses.

Freshness is another link in the chain. A graph can be internally consistent and still lag behind the working tree. If a file has changed since indexing, the source returned from the database may no longer match the source the agent is about to edit. CodeGraph’s design treats a pending or stale file as a reason to read that file directly, not as a reason to pretend the graph is current.