Add stable machine-facing indexing view and semantic refresh classification

[devin-ai-integration]

Problem or motivation

Refresh is purely hash-driven: if the source hash matches, the snapshot is reused; otherwise full rebuild. This conflates four different change types into one "something changed" signal. Structure drift in authoring surfaces (heading structure, table layout, relation blocks) causes parser drift even when semantics haven't changed. snapshotNeedsRebuild() in runtime.ts only checks for missing description/metadata fields — it does not classify the nature of the change.

Proposed solution

1. Declared machine-facing indexing view

Create a stable semantic spine artifact (e.g., indexing-view.json) containing the machine-facing contract: pattern IDs with canonical title/status/type/normativity/part/cluster, alias set with successor/deprecation pointers, anchor map, explicit relation edges, route-bearing metadata, and snapshot edition identity. On refresh, diff this view first before deciding whether a full rebuild is needed.

2. Classify source changes into four families

Change family	Description	Indexer action
Viewing change	Same semantic spine, different wording/order/examples	Mostly ignore — rebuild artifacts but expect identical indexing view
Slot/base explicitness change	Implicit metadata made explicit	Strengthen constructor signature, no semantic change
Editioned semantic change	Meaning actually changed	Mint new edition, retarget references explicitly
Described-entity retargeting	Object of talk changed	Not a refresh — treat as a retargeting event

3. Refresh sentinels

Post-rebuild checks: ID continuity, alias coverage, anchor continuity, route closure, no dangling references, no hidden semantic owner changes. Report in build-audit.json.

Affected area

src/runtime/ (compiler & query engine)

Alternatives considered

Keeping hash-only refresh is simpler but does not protect against editorial drift — a whitespace-only rewrite triggers a full rebuild, while a silent semantic change gets the same treatment as a typo fix.

Additional context

• Current refresh logic: src/runtime/runtime.ts lines 62–115
• Current compatibility check: snapshotNeedsRebuild() lines 313+

FPF grounding:

• G.11 (Telemetry-Driven Refresh & Decay Orchestrator, Stable): Directly governs refresh triggers, decay detection, and edition-aware reruns. The proposed four-family change classification implements G.11's concern of knowing what kind of change triggers refresh.
• B.3.4 (Evidence Decay & Epistemic Debt, Stable): Hash-only refresh creates epistemic debt (B.3.4:2) — it cannot distinguish a cosmetic edit from a semantic change, so trust in the compiled index silently decays. The proposed sentinels implement B.3.4's freshness model.
• A.6.3 (U.EpistemicViewing, Stable): The indexing view is a describedEntity-preserving projection (a "view") of the compiled state — this is exactly what A.6.3 defines. The view adds no new semantics; it projects existing compiled artifacts into a stable machine-facing contract.

Note: Previous version cited A.6.S (SignatureEngineeringPair) and E.20 (Draft). A.6.S is about boundary signature engineering, not internal indexing views — replaced with A.6.3 (EpistemicViewing). E.20 is Draft status and its scope (mechanism introduction) doesn't match — removed.

Measurable impact

Metric	Before	After (target)	How to measure
Stable indexing view artifact exists	No	Yes (indexing-view.json emitted)	ls .runtime/fpf-index/indexing-view.json
Change families classified in build audit	0	4 (viewing, slot/base, editioned, retargeting)	grep -c 'change_family' .runtime/fpf-index/build-audit.json
Refresh sentinel checks in build audit	0	≥5 (ID continuity, alias coverage, anchor continuity, route closure, dangling refs)	`grep -Ec 'sentinel
Unnecessary full rebuilds on whitespace-only edits	triggers rebuild	no rebuild (hash match on indexing view)	Edit whitespace in FPF-spec.md, run bun run cli -- refresh, check build-audit.json for rebuilt: false

[venikman]

Take on the premise

Partially agree — the problem is real; the proposed solution is over-scoped for current user value.

The core observation is correct: hash-only refresh cannot distinguish a whitespace edit from a semantic rename, and B.3.4 (evidence decay / epistemic debt) is the right frame for that gap. A spec-authoring team evolving FPF-spec.md would genuinely benefit from knowing "this rebuild was cosmetic" vs "this rebuild retargeted an entity."

But — who consumes the classification?

No MCP tool user (Codex or otherwise) ever sees changeFamily or sentinels. These are operator/spec-author concerns. The proposal adds:

• a new serialized artifact (indexing-view.json)
• four change-family classifications
• five refresh sentinels
• classification fields in BuildAudit

…to serve a diagnostic need that today has zero identified downstream consumer. That's a lot of machinery for optionality.

Concrete counter-proposals to sharpen scope:

1. Ship it as expert-only output first. Emit indexing-view.json, skip the classification inference, let spec-authors eyeball diffs. If a real operator workflow emerges that needs the four families, formalize them then.
2. Or defer until you have a user. Right now refresh() works fine for the MCP public surface. Adding classification now is building a mechanism in search of a problem — the opposite of E.20's admission criteria, ironically.

PR #29 implements the full scope. I flagged the changeFamily type drift, the described_entity_retargeting over-broadness, and missing unit tests. Even if you proceed with the full design, address those before merge.

Problem is real but premature — recommend shipping as expert-only view artifact first, defer classification until a user asks for it.

[devin-ai-integration]

Merger plan update

Status: PR #29 — nearly merge-ready, fixing two confirmed bugs

Incorporating venikman's feedback from this issue:

1. "Ship as expert-only view artifact first, defer classification" — The classification machinery is already implemented, tested, and only surfaces in BuildAudit (not in any public MCP tool response). Stripping it would require more rework than keeping it. Plan: merge as-is, since the classification is effectively expert-only output already. If a future consumer never materializes, the code is inert.

2. Two confirmed bugs found during review (Codex comments):

   • P1 (real logic bug): inferChangeFamily() returns entity_addition when addedIds > 0 even if existing entities also changed (changedIds > 0), masking semantic/slot changes as benign additions. Fix: gate on changedIds.length === 0.
   • P2 (migration gap): On first source-changing rebuild after upgrading from older artifacts (no indexing-view.json yet), loadIndexingView() returns undefined even though a compatible existingSnapshot could derive the previous view. refreshClassification is silently dropped. Fix: fall back to buildIndexingView(existingSnapshot) when the file is missing but a compatible snapshot exists.

3. Merge order: PR feat: add stable indexing view and semantic refresh classification #29 is next after the fixes above. CI verification + merge request to follow.