shared_external_attachment_pattern_documented

[briansrls]

Auto-opened by session-dashboard for session fierce-ant-517.
Pushing to session/fierce-ant-517 advances this PR.

Worker attestation

Before flipping this PR to ready for review, confirm each item:

• Title describes the change (not the session id or branch).
• PR body summarises what and why (replace the TODO below).
• Tests run: name the command (e.g. npm test, cargo test) and the result.
• If this closes a work item, the body contains a Closes #N directive.
• No commits on this branch are surprises (no fork/cherry-pick I did not make).
• No secrets / credentials / large binaries staged.

Summary

TODO: replace this paragraph with one or two sentences naming the change and its motivation. Reviewers read this first.

Test plan

• TODO: list the commands that ran (or "no tests changed; relied on CI") and the outcome.

[briansrls]

Director conformance read — would-approve.

Read against r3-program-plan §1.8 promoter discipline + timing-lens design + the Lookup::Miss dissolution work absorbed at the cost-lens layer.

Conformance citations:

1. Gate [R2] Wildcard resource semantics: normalize at construction, enforce … #55 promotion DECLARED → CONSUMER_LANDED with grounded evidence chain: design doc + typed substrate (timing_lens.dag) + branded provenance nominals (types.dag) + bootstrap ratchet test (timing_lens_substrate_carrier_test.rs) covering inv. 1-4 + §2.6. Per-arm citation. Audit-trail-friendly.

2. Naming-discipline tightening: Output variant rename Missing → Unobserved in r3-structure.md aligns with Lookup::Miss dissolution discipline. Distinguishes "no evidence yet on this observation surface" (Unobserved) from "lookup returned Miss for this key in this table" (Lookup::Miss, which Brian's directive is removing entirely from the substrate). Avoids witness/bootstrap collisions where both arms could fire on the same node and silently conflate.

3. Cross-doc consistency: parallel rename in description (also r3-structure.md) keeps the demonstration reference aligned with the substrate variant name.

4. Cross-doc anchor: ROADMAP.md mention upgraded from naked text to design-doc citation + §2 anchor + dag substrate pointer. Reduces drift risk between the roadmap-narrative and the actual substrate.

5. No INVARIANTS violations: docs-only, no Rust source touched. The Unobserved naming preserves fail-closed semantics — the original framing said fail-closed enforcement on "non-observed states"; the variant rename keeps that contract explicit at the label level.

6. Bridge framing preserved: the "promotion to generic ExternalDataAnchor<Subject, Source> deferred to second concrete consumer" stance remains intact. Honest mid-state (CONSUMER_LANDED for the timing-lens-specific anchor; second-consumer-driven generalization deferred per Substrate Mgr design stance).

No INVARIANTS violations found. Diff 6+/5- across 3 docs files. Comment fires for on-record visibility.

— sent from zesty-bear-812

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-thinking
• Commit: 119a556d · Trigger: manual
• Comparison: main @ 32d02dc7 ... session/fierce-ant-517 @ 119a556d
• Conversation: View conversation

---

1. Story of the diff

This PR is a documentation/ledger receipt for R3 §1.8 gate #55, not an implementation change. It upgrades the “shared external attachment” concept from a declared planning item into a documented, consumer-landed pattern: ROADMAP.md:75-76 now points the workflow-as-data trigger at WorkflowObservationAnchor / Shared External Attachment and names the timing-lens design plus typed substrate location; docs/r3-program-plan.md:281 marks gate #55 CONSUMER_LANDED with the concrete pattern, carriers, provenance nominals, and bootstrap ratchet; docs/r3-structure.md:170 then folds that same receipt into the R3 lane narrative while preserving the deferral of the generic ExternalDataAnchor<Subject, Source> until a second concrete consumer appears. The adjacent timing-lens language is also tightened from Missing to Unobserved at docs/r3-structure.md:169 and docs/r3-structure.md:174, which makes the report-state vocabulary match the “missing evidence” meaning without colliding with other witness/bootstrap uses.

2. Invariant categories

1. LAYER MODEL (substrate vs implementation). Compliant — this diff touches substrate planning/receipts, not live substrate definitions; the load-bearing substrate references are documentation pointers to already-named carriers (WorkflowObservationAnchor, TimingObservationEntry) at docs/r3-program-plan.md:281, and no new Dag shape or implementation type is introduced in the diff.
2. INVARIANTS.md + modeling-discipline.md. Compliant — Boundary Discipline / single authority is handled by making the R3 gate row the ledger and having docs/r3-structure.md:170 point back to docs/r3-program-plan.md §1.8 row 55, instead of creating an independent second description. Progress-is-dissolution is also preserved: docs/r3-structure.md:170 explicitly keeps generic ExternalDataAnchor<Subject, Source> promotion deferred until the second concrete consumer, rather than turning this pattern into premature generic substrate. This matches the reference principles that facts need one authority and scaffolds need bounded dissolution/trigger discipline. chatgpt-review-9bfb8fe6-154a-4c…
3. CODING.md. N/A — diff is documentation-only; no Rust functions, helpers, methods, error/result shapes, or module structure are changed.
4. TESTING.md. Compliant — no new behavior is introduced, but the receipt line names the existing bootstrap ratchet, timing_lens_substrate_carrier_test.rs, as validating gate [R2] Wildcard resource semantics: normalize at construction, enforce … #55 invariants 1–4 and §2.6 wiring at docs/r3-program-plan.md:281. For a documentation promotion, pointing at the existing ratchet is the right level; I do not see a diff-cited reason to require a new test in this PR.
5. LOCKED DESIGN DECISIONS. Compliant — the diff does not alter Pure Bootstrap / zero-floor direction or any locked substrate shape. The closest locked-design concern is avoiding premature generic substrate; docs/r3-structure.md:170 explicitly preserves the design stance that promotion to ExternalDataAnchor<Subject, Source> waits for a second concrete consumer.
6. TRACKED vs UNTRACKED DEBT. Compliant — the only deferred shape is tracked and bounded: docs/r3-structure.md:170 names the deferred generic carrier, names the dissolution trigger (“second concrete consumer”), and identifies the likely consumer (ProofReceipt). I do not see a new TODO, scaffold, temporary file, or unbounded bridge in the diff.

2.5. Top-down PM intent review

Compliant — the PR strengthens, rather than dilutes, the workflow-as-data / recursive-flex plan. The highest-level intent is that external observations used by lenses become typed, single-authority substrate facts rather than ad hoc attachments; the diff now makes that path explicit in the roadmap trigger (ROADMAP.md:75-76), marks the R3 gate as consumer-landed with typed carriers and ratchet evidence (docs/r3-program-plan.md:281), and keeps the R3 structure narrative honest about both the current concrete pattern and the later generic-carrier promotion (docs/r3-structure.md:170). I do not see a must-have target made optional, a dissolution goal made permanent, or a hand-authored implementation path added.

3. Verdict

APPROVE — This is a clean receipt/ledger PR. The changed lines align the roadmap, R3 program plan, and R3 structure narrative around the same shared external attachment pattern, while preserving the second-consumer trigger for generic substrate promotion.