docs: Scheduled deletions section + DB-17 reference-resolution provenance

[briansrls]

Summary

Two artifacts, landed together because they reference each other:

1. Scheduled deletions section in `src/v3/ROADMAP.md` — sibling to "Active deferrals." Every scaffold in live substrate lives here with trigger, blocker, and enforcement path. Three kinds of enforcement, with an explicit rule that grep is not one of them.
2. DB-17 reference-resolution provenance — splits `AtomPayload::ResolvedIdentifier` into `ResolvedByStructure` / `ResolvedByName` so lenses can structurally detect name-fallback bridges. Unblocks the scheduled deletion of `declaration_by_name` and NameKeyedReference bridges.

The framing these consume

Both artifacts express the thesis-level reframe from earlier tonight: the compiler IS the dependency analyzer. Every named scaffold gets a structural enforcement path, or the substrate amendment that unlocks one is filed as a DB. Grep over source is the anti-pattern — it's a heuristic that can't distinguish legitimate bootstrap from user-range drift.

Scheduled deletions table (initial population)

Category	Scaffolds
Lens-able today	`ArrowBody::Pending`, `ArrowBody::Unparsed`, `ValueBody::Unparsed`, `TransformTarget::Operator`
Needs DB-17	`declaration_by_name`, NameKeyedReference bridges
Compiler-source ratchet (temp; dissolves at self-hosting)	`Node.name` field, `encoding_meet` / `encoding_join`
TBD (recon pending)	`keyword_to_name`

DB-17 shape

```rust
// Before
pub enum AtomPayload {
ResolvedIdentifier(DeclarationId),
// ...
}

// After
pub enum AtomPayload {
ResolvedByStructure(DeclarationId),
ResolvedByName(DeclarationId),
// ...
}
```

Lowering call sites pick the variant based on resolution path. Consumers update to handle both variants. Lens queries for `ResolvedByName` reachable from user-range roots.

Dissolution of `ResolvedByName` itself is scheduled for when M2 module scoping lands; at that point every reference is structural and the variant becomes unreachable.

Relationship to other PRs

• `lens_structural_resolution.dag` (another session) — implements the lens that consumes DB-17. The lens starts with the `UnresolvedArrowBody` variant (lens-able today against the existing substrate); the `NameKeyedReference` variant waits on DB-17 landing.
• PR docs: ROADMAP is the single tracker — close issues, write deferrals here #500 (ROADMAP-as-tracker discipline) — this PR extends the tracker with the scheduled-deletions direction (mirror of the active-deferrals direction).
• PR docs: DB-14 R3 + E-9 invariant (external realization lives on Arrow.body) #497 (DB-14 R3 + E-9) — same pattern: bank the rule structurally, then consume it. DB-17 parallels E-9's move.

Test plan

• Reviewers confirm the three enforcement-path classification holds for all 9 scheduled scaffolds
• DB-17 schema shape is implementable against the real `AtomPayload` definition (cross-check at `src/v3/compiler/src/dag.rs`)
• Grep-is-not-an-enforcement-path rule is clear and distinguishes the doc-level banked-dissolutions ratchet (narrow exception) from system-level structural invariants

🤖 Generated with Claude Code

[briansrls]

ChatGPT Review

Principle audit.

1. Fail-closed. This is mostly in good shape. The new ROADMAP section explicitly rejects grep-as-enforcement and routes scaffolds toward lenses, DBs, or narrowly-bounded temporary ratchets, which is aligned with the thesis’s “lenses, not grep” direction. My one concern is that DB-17’s enforcement story is not fully closed yet: the doc says the future lens must distinguish bootstrap/std from user-range resolutions, but the substrate-visible boundary fact is still an open question in docs/design-reference-resolution-provenance.md:131-137. Until that is either folded into DB-17 or named as a sibling blocker in the scheduled-deletions row at src/v3/ROADMAP.md:532-533, the enforcement path is still partially behavioral. NON-BLOCKING.

2. Illegal states unrepresentable. Strong. The split from ResolvedIdentifier into ResolvedByStructure and ResolvedByName fixes a real overloaded-state problem: today one substrate shape hides two semantically different resolution paths, and the proposal makes that illegal conflation impossible at the type level (docs/design-reference-resolution-provenance.md:14-23, 43-56). This is exactly the kind of change the discipline doc wants.

3. Facts flow forward. Also strong. DB-17 is directly about carrying a fact that is currently dropped after lowering — resolution provenance — so a downstream lens can consume it structurally instead of reconstructing it from source heuristics (docs/design-reference-resolution-provenance.md:19-23, 74-92, 118-125). That is cleanly thesis-aligned.

4. Coproduct dissolution. Mostly satisfied. The new substrate growth is treated honestly as scaffolded, not terminal: ResolvedByName gets an explicit dissolution trigger at M2 module scoping (docs/design-reference-resolution-provenance.md:88-92, 156-162). My only comment is the new scheduled-deletions table undercuts its own standard with the keyword_to_name row, which still has TBD trigger/blocker/enforcement (src/v3/ROADMAP.md:536, 542, 554-557). In a section explicitly titled “scaffolds with named dissolution triggers,” that row is still under-classified. NON-BLOCKING.

5. Single-authority metadata. Good. The new ROADMAP section creates one canonical place for scaffold-deletion receipts, and DB-17 correctly rejects a provenance side table in favor of carrying the fact on the Atom itself (docs/design-reference-resolution-provenance.md:98-105; src/v3/ROADMAP.md:510-522). That is the right authority shape.

6. API-level enforcement. Mostly good because the variant split forces consumers to see the distinction. The only thing I would watch is the suggested resolved_id(payload) -> Option<DeclarationId> helper (docs/design-reference-resolution-provenance.md:60-70, 122). If that becomes the common API, the new distinction will collapse back into convention very quickly. Any provenance-erasing accessor should be obviously lossy and narrowly used, not the default convenience path. NON-BLOCKING.

Design question. Is DB-17 itself the full enforcement unlock, or is the real prerequisite “DB-17 plus a substrate-visible declaration-source/range fact”? Right now src/v3/ROADMAP.md reads as though DB-17 alone unblocks structural enforcement for declaration_by_name / NameKeyedReference, but the design doc itself says the lens may still need a sibling boundary fact (docs/design-reference-resolution-provenance.md:131-137). What’s at stake is whether the later implementation can stay structural, or whether it will feel pressure to smuggle the boundary back in through Rust-side user_start checks.

Verdict. APPROVE_WITH_COMMENTS. This is a useful docs round: the scheduled-deletions section makes scaffold debt auditable, and DB-17 is the right kind of upstream amendment rather than another grep rule. My comments are about tightening the receipts so the eventual implementation cannot quietly fall back to a Rust-side boundary heuristic, and about not leaving a TBD row inside a table that claims every scaffold has a named trigger.

LOOP HEALTH: converging — this round turns two recurring review themes (grep-as-enforcement and invisible name-fallback bridges) into explicit structural work items; keyword_to_name is the one row that still feels under-classified rather than fully tracked.

---

View conversation

[briansrls]

ChatGPT Review

Principle audit.

1. Fail-closed. Satisfied. This round keeps pushing enforcement away from grep/audit cadence and toward substrate-visible facts plus lenses. The new scheduled-deletions section explicitly constrains enforcement to structural lenses, DB-backed substrate amendments, or a temporary compiler-source ratchet, and DB-17 gives declaration_by_name a real structural path instead of a review convention (src/v3/ROADMAP.md:514-556; docs/design-reference-resolution-provenance.md:72-92, 166-170).

2. Illegal states unrepresentable. Satisfied. DB-17’s split from ResolvedIdentifier into ResolvedByStructure and ResolvedByName puts the important distinction in the type instead of hiding it in prose or a side table (docs/design-reference-resolution-provenance.md:29-56). That is exactly the right modeling move.

3. Facts flow forward. Satisfied. The whole point of DB-17 is to stop dropping resolution provenance after lowering and carry it into reflection/lens consumers as a first-class fact (docs/design-reference-resolution-provenance.md:14-23, 118-125). This is cleanly thesis-aligned.

4. Coproduct dissolution. Satisfied. ResolvedByName is treated honestly as a scaffold with a named dissolution trigger at M2 module scoping (docs/design-reference-resolution-provenance.md:88-92). And the added e0d566e follow-up does fix the earlier keyword_to_name problem: instead of leaving a fake TBD row in an authoritative table, it scopes that item out of the v3 ledger (src/v3/ROADMAP.md:526-541).

5. Single-authority metadata. One NON-BLOCKING concern. The new keyword_to_name note only really works if the scheduled-deletions section has one crisp scope authority, but right now it says three slightly different things: “every scaffold in the live substrate lives here” (src/v3/ROADMAP.md:510), compiler-source ratchets are also in scope (:522, 532-535), and the note says the list tracks “v3-scope scaffolds only” (:541). On top of that, the exclusion rationale cites src/v3/ROADMAP.md §“Sketch vs Oracle framing,” and I do not see that section anywhere in the current ROADMAP. I would tighten this to one explicit scope sentence and either point to the real supporting section or drop that citation.

6. API-level enforcement. Satisfied. The docs are moving the right way: DB-17 makes name fallback a substrate fact, the future lens consumes that fact, and the roadmap treats grep as a signal that a missing DB should be filed rather than as a gate (docs/design-reference-resolution-provenance.md:72-92; src/v3/ROADMAP.md:543-556). That is the right enforcement shape.

Design question. What is the exact authority boundary of the Scheduled Deletions ledger: only v3 substrate scaffolds, all v3-scoped scaffolds including temporary Rust ratchets, or something wider? The added keyword_to_name note makes a real scoping decision, but the section currently states that scope inconsistently. What is at stake is whether future exclusions are predictable and auditable, or whether “out of scope” becomes a prose carve-out decided case by case.

Verdict. APPROVE_WITH_COMMENTS. This is a better round than the previous one: DB-17 is a real structural unlock, and the keyword_to_name follow-up correctly removes the weak TBD row instead of pretending it is already classified. My only ask is to make the ledger’s scope explicit in one place and fix the dead internal citation so the exclusion rationale stands on its own.

LOOP HEALTH: converging — this round dissolves the earlier keyword_to_name tracking ambiguity and turns declaration_by_name into a named DB-backed path; the remaining gap is scope clarity in the new ledger, not new debt.

---

View conversation

[briansrls]

codex · gpt-5.4 · e0d566ea

⚠️ Review (blocking: 1, non-blocking: 0+/0-)

BLOCKING (1)

Root Cause

• docs/design-reference-resolution-provenance.md The docs key the scheduled deletion to the helper name instead of the actual bridge classes; split the tracker into ResolvedByName reference fallbacks versus the remaining compiler-internal declaration_by_name lookups, each with its own dissolution path.

ROADMAP — Verified

• keyword_to_name v2 scope: The cited src/v2/parser-design.md, src/v2/02_parse.dag, and src/v2/stage0/src/v2_compiler_parse.rs do show keyword_to_name surviving only as tok_keyword_to_name in v2, and I found no v3 equivalent.
• DB-17 schema grounding: src/v3/compiler/src/dag.rs and src/v3/std/substrate.dag both currently expose AtomPayload::ResolvedIdentifier, so the proposed split is grounded in the live substrate rather than stale thesis text.

⚠️ The scheduled-deletions tracker is useful, but the declaration_by_name row currently overclaims what DB-17 would actually dissolve.

[briansrls]

BLOCKING: This collapses two different debts into one: DB-17 would surface name-fallback AtomPayload edges, but it would not cover the other live declaration_by_name call sites (bootstrap caches and downstream name recovery), so "joint dissolution via one lens" misstates the single-authority/semantic-authority fix.

[briansrls]

codex · gpt-5.4 · e0d566ea

⚠️ Review (blocking: 1, non-blocking: 0+/0-)

BLOCKING (1)

Root Cause

• docs/design-reference-resolution-provenance.md The docs key the scheduled deletion to the helper name instead of the actual bridge classes; split the tracker into ResolvedByName reference fallbacks versus the remaining compiler-internal declaration_by_name lookups, each with its own dissolution path.

ROADMAP — Verified

• keyword_to_name v2 scope: The cited src/v2/parser-design.md, src/v2/02_parse.dag, and src/v2/stage0/src/v2_compiler_parse.rs do show keyword_to_name surviving only as tok_keyword_to_name in v2, and I found no v3 equivalent.
• DB-17 schema grounding: src/v3/compiler/src/dag.rs and src/v3/std/substrate.dag both currently expose AtomPayload::ResolvedIdentifier, so the proposed split is grounded in the live substrate rather than stale thesis text.

⚠️ The scheduled-deletions tracker is useful, but the declaration_by_name row currently overclaims what DB-17 would actually dissolve.

[briansrls]

Meta-Review (Loop Health)

According to a document from 2026-04-17, the loop is no longer earning another ordinary review round. It made one real move, then started polishing the accounting of that move instead of cashing it out structurally.

Loop summary.

Visible history shows 3 review rounds, 2 visible commit states, 1 codex review, and 2 browser reviews, over roughly 45 minutes from 15:31Z to 16:16Z on 2026-04-17. The second browser review explicitly references a follow-up commit (e0d566e), so there is clear evidence of at least one revise-and-rereview cycle, but not a long series of distinct implementation turns.

Forward progress evidence.

There was forward motion. The loop converted two previously hand-wavy review themes into explicit design artifacts: a scheduled-deletions ledger and DB-17’s proposed split of ResolvedIdentifier into ResolvedByStructure and ResolvedByName. Both browser reviews agree that this is the right modeling direction: move from grep/convention to substrate-visible facts and typed distinctions, which matches the discipline’s “facts flow forward,” coproduct-dissolution, and API-level-enforcement principles.

There is also one concrete response to review feedback: the earlier keyword_to_name ambiguity was not left as a fake tracked scaffold; it was scoped out of the v3 ledger in the follow-up round, and the second browser review explicitly calls that an improvement.

So this is not a dead loop. It did surface the class and start naming it correctly.

Debt accumulation evidence.

The problem is that the loop’s output is still mostly accounting, not authority. Principle 1 says consumers define correctness; without a consumer, 100% conformant prose is still substrate growth with no proof. This PR is docs-only: the visible progress is a proposed DB and a ledger, not a new test, lens, emitter path, interpreter path, or enforced invariant. The project’s own roadmap warns that it already has large areas of modeled structure with zero consumers, and that such modeling should be made load-bearing before adding more.

The recurring finding also did not fully graduate. Across the three visible rounds, reviewers keep circling the same class: name-fallback bridges, grep-as-enforcement, and unclear scaffold accounting. First it was “DB-17 may still need a sibling boundary fact”; then “ledger scope is inconsistent”; then codex escalated that the tracker is still keyed to the helper name instead of the actual bridge classes. That is the same disease moving one level sideways each round, not a new class being eliminated.

That matters because the project’s own rules are explicit: recurring adapter/bridge patterns are supposed to be stopped loudly, not normalized into tracked transitional prose. The “no short-term solutions” and “no bridges” invariants say a tracked bridge is still the wrong shape if it teaches downstream consumers the wrong authority boundary.

The codex blocker is the clearest debt signal: the ledger is still tracking the wrong unit of debt. If the deletion row is keyed to declaration_by_name as a helper instead of the actual bridge classes (ResolvedByName fallbacks vs remaining compiler-internal lookups), then the accounting surface is still slightly compensatory. That is exactly the kind of representation mistake that gets copied.

Cheating signal.

The implementer is not hiding compromises. That part is healthy. The scaffolds are named, the debt is being written down in a scheduled-deletions ledger, and the follow-up commit did respond directly to a review theme rather than pretending the first draft was already sufficient.

But the fixes are still drifting toward “good enough with accounting” rather than structural completion. This is not hidden cheating; it is documented triage. The issue is that the loop is now spending its marginal effort on making the accounting cleaner instead of either landing the structural consumer or promoting the recurring class into a stronger invariant/test. The browser reviews call the remaining issues “scope clarity” and “boundary fact,” while codex says the row still overclaims what DB-17 dissolves. That is a smell that the loop has moved from solving the problem to refining the description of the problem.

In this codebase’s own terms: the compromises are explicit, but they are still compromises. The loop is approaching the point where another pass buys cleaner prose, not a better substrate.

Meta-verdict

🔁 PAUSE_AND_REGROUP

The loop has made some forward progress, but it is now repeating at the wrong layer. Another ordinary review round will probably produce one more refinement of the ledger wording or the DB-17 scope note. That is not the highest-value next move.

What should happen next is one of these, not another prose pass:

• split the debt accounting by the actual bridge classes, exactly as codex requested, or
• graduate the recurring pattern into a stronger structural rule / invariant / lens boundary, so the next instance is blocked by construction instead of reviewed again.

Why this is not 📈 KEEP_ITERATING: because no new consumer was enabled and the recurring finding has not yet graduated.

Why this is not ⚖️ SHIP_WITH_DEBT: because the remaining blocker is about the unit of accounting itself, which is too foundational to normalize.

Why this is not 🔄 REVERT_AND_RETHINK: because the direction is right; the loop shape is wrong.

So the blunt read is: the review loop is starting to shift debt unless it stops being a prose loop and becomes a structural decision.

---

View conversation

[briansrls]

Addressed codex BLOCKING (commit fab812e) — split the conflated class

Codex was right: keying the scheduled deletion to the helper name `declaration_by_name` conflated three distinct debt classes. Investigated: the Rust helper at `dag.rs:1459` has ~83 call sites that split cleanly into:

1. Bootstrap `substrate_markers` caches (`dag.rs:1616+`). Looks up "Int"/"Bool"/"String"/"Value"/"Transform"/"Branch"/"Loop"/"Bind"/"Main"/"DeclarationRef"/"TypeRealization"/"OperatorRealization"/"BehaviorRealization" by name to populate marker fields. Compiler-internal cache.
2. Pipeline-authority wiring (`bootstrap.rs`, `pipeline_authority.rs`). Walks Dag by name for `PIPELINE_REALIZATION_META`, "parse", "PipelineStageBinding", "PipelineSnapshotKind". Bootstrap machinery.
3. Emitter algebra lookups (`emit_go.rs`, `emit_python.rs`). "OrderedRing" etc. at emission time. Emission-layer dispatch.
4. User-range lowering fallback. Structural walk can't resolve a user identifier → fall back to name lookup → produces an AtomPayload indistinguishable from structurally-resolved. This is DB-17's scope.

Fix in the scheduled-deletions table

• Old: one row conflating all four ("declaration_by_name" + "NameKeyedReference bridges" / "dissolves jointly via one lens").
• New: two rows.
  • User-range `ResolvedByName` AtomPayload (DB-17) — needs DB-17; lens walks AtomPayloads for the new variant.
  • Compiler-internal `declaration_by_name` call sites — compiler-source ratchet (temporary), dissolves at self-hosting for most sites, via specific substrate amendment for marker caches.

Fix in the DB-17 doc

• Title narrowed: "user-range AtomPayload scope."
• New §"What DB-17 does NOT cover" enumerates the three compiler-internal classes with separate dissolution paths.
• Implementation scope clarified: compiler-internal `declaration_by_name` call sites do NOT produce AtomPayload — they use the helper directly — so they're out of scope for this substrate change.
• Dissolution section: notes DB-17 dissolves only the user-range class; compiler-internal sites dissolve separately.

On the meta-review

Meta-review signaled "this loop is no longer earning rounds." Taking that seriously — this commit addresses the one remaining structural issue and is the final iteration. The split is the fact the reviewer was pushing for; the rest of the scheduled-deletions discipline stays as-landed. Ready for merge.

[briansrls]

ChatGPT review in progress... (view conversation)

Check back in ~30 minutes for the full review.