Deterministic change intelligence

What this is

Change intelligence is the code-mining layer that decides what a new revision means for an existing summary before spending another model call. It compares content and parsed-symbol information deterministically, classifies the result, and records freshness as state that a reader can see.

It is deliberately not a model deciding that a diff “looks harmless.” A comment-only or whitespace-only edit in a supported language can short-circuit re-mining; a changed symbol can produce a bounded delta package; an ambiguous or unsupported change goes to full re-mine rather than being labelled unchanged.

Why it exists

Code summaries are useful only while a reader can tell whether they still describe the code. Re-mining every file on every revision wastes cost and context. Ignoring a small change is worse: it lets a confident, stale summary look current. The useful middle ground is a deterministic decision with a conservative failure mode and a traceable reason.

The same posture applies beyond the changed file. A direct dependent may need attention when an exported symbol or module relationship changes, but unlimited fan-out would create noise and surprise cost. The first propagation pass is therefore bounded to one reverse-dependency hop.

How it works

On re-ingest, Sophia compares the old and new module representations. For supported languages it strips comments without touching string literals and normalizes whitespace before deciding that an edit has no semantic effect. When symbol bodies changed, the drift payload identifies those symbols; imports, top-level residue, malformed input, and unsupported-language uncertainty fail toward an opaque change and full re-mine.

A delta-capable lease carries a verified git range, the prior summary, and the touched-symbol evidence. A miner may submit a delta_patch only when its declared source hash matches the pending drift payload; otherwise the sink rejects that shortcut. Summaries remain readable while drift is pending, but their freshness state is returned with them instead of hidden by a query filter.

One-hop propagation marks affected downstream facts stale_pending_triage and can enqueue a re-mine. It does not recursively walk the whole graph. That bound keeps an implication visible without claiming that the system has proved every transitive consequence of a code change.

What your agent does with it

// Read the current code surface before acting on a summary:
const module = await sophia.getModuleSummary({ module_id: 'module-id' });
// → { summary_text, freshness_state, freshness_as_of_hash, summary_stale, ... }
// A stale or delta-patched state is evidence for the next action, not hidden metadata.