Keeping the Map Honest: Caches, Updates, and Data Boundaries

Graphify's graph is a derived view of a changing corpus, so its usefulness depends on more than how well it answers a query on the day it is built. This chapter follows the map through cache reuse, source changes, semantic refreshes, failures, and data exposure. The practical judgment is twofold: when can a previous result be trusted as a reusable representation of the same source, and when must the system re-extract or change its processing path?

A stale graph can be more misleading than no graph because it returns precise-looking relationships from an old state. A partial graph can be similarly dangerous if a missing node is interpreted as proof that the source does not contain it. Graphify's lifecycle mechanisms are designed to make reuse cheap while treating invalid, incomplete, or differently produced results as reasons to retry or refresh.

A cache is a claim about source state

Graphify fingerprints extracted files by content. When the content is unchanged, an AST result can be reused rather than regenerated. The obvious benefit is speed and cost: a large repository does not need to be parsed from scratch after every question or every small edit. The deeper benefit is repeatability. The graph can preserve a structural result whose input content is known to match the content that produced it.

That claim is narrower than “the graph is current.” A content hash says that the bytes of a file match a prior extraction key. It does not say that the file's surrounding imports, callers, documents, or deployment assumptions have not changed. It does not say that a semantic interpretation made under an older prompt or mode is still the result the operator wants. It does not repair a prior extraction that omitted a symbol. Cache reuse preserves a previous result; it does not upgrade the result's meaning.

The distinction between code and semantic material makes the lifecycle more visible. AST results occupy a structural cache path, while semantic results have separate namespaces for ordinary and deeper extraction modes. Semantic entries can also be associated with a fingerprint of the extraction prompt. If the prompt changes, replaying an older semantic result would mix extraction vintages while making the graph look uniform. Treating the change as a cache miss is more expensive, but it preserves the meaning of the stored result: the entry is reused only when it belongs to the extraction conditions the current run expects.

This separation also makes the cache a record of processing conditions rather than a single undifferentiated warehouse. A structural hit says that the same content can be represented by the existing AST result. A semantic hit says that the content and the semantic extraction conditions are compatible with the stored fragment. A deep-mode result is not silently substituted for a standard-mode result, and a result written under one prompt is not automatically treated as equivalent to a result written under another. The namespaces keep a change in interpretation from masquerading as a change-free reuse.

This is why a code update and a document update do not have the same refresh path.