From 2b9d1727ad7ad976a78a5b04d66c5620b7b30a98 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 03:51:02 -0400 Subject: [PATCH 01/52] WIP: R3 Substrate --- ...3-378-http-path-helper-fail-open-worker.md | 87 ++++++++++++++ ...425-stale-invariants-prose-sweep-worker.md | 108 +++++++++++++++++ ...r3-426-sfp-subdoc-design-call-surfacing.md | 91 ++++++++++++++ ...integration-rs-scan-char-literal-worker.md | 111 ++++++++++++++++++ 4 files changed, 397 insertions(+) create mode 100644 docs/briefs/r3-378-http-path-helper-fail-open-worker.md create mode 100644 docs/briefs/r3-425-stale-invariants-prose-sweep-worker.md create mode 100644 docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md create mode 100644 docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md diff --git a/docs/briefs/r3-378-http-path-helper-fail-open-worker.md b/docs/briefs/r3-378-http-path-helper-fail-open-worker.md new file mode 100644 index 00000000000..f341c874854 --- /dev/null +++ b/docs/briefs/r3-378-http-path-helper-fail-open-worker.md @@ -0,0 +1,87 @@ +--- +status: draft (wait-window; awaits R3 host restoration before dispatch) +authority parent: R3 Substrate Manager (#1739) +roadmap row: ROADMAP.md "http_path.dag `None => ""` fabrications" (P1 — fabrication / fail-open boundaries) +--- + +# R3 :378 — `parse_segment_tokens` fail-open helper fix + +## Context + +The top-level `parse_path_template` in `dsl/std/http_path.dag:37-69` +already returns the typed `PathTemplateParseResult` coproduct +(`Ok(ParsedPathTemplate)` | `MalformedPathSegment { segment, reason }`). +The descent into `parse_segment_tokens` does **not** propagate that +discipline: lines 95, 99, 107, 111 each match an `Option` from +`first` / `skip(1) |> first` and substitute `""` on `None`. Each `None` +arm is structurally unreachable when the surrounding length / split +checks are correct, but the substitution silently fabricates a +zero-length string if invariants ever drift, and is the exact pattern +the row names. + +The 2026-05-04 R3 wait-window audit verified all four sites against +HEAD; the parent-session #828 audit cited the entry-range only and +missed these. Row remains REAL, not partially-dissolved. + +## Slice + +1. Read the four `match … None => ""` sites in `parse_segment_tokens` + (`dsl/std/http_path.dag:88-112`) and confirm each surrounding guard + makes the `None` arm structurally unreachable. The + `count(before_and_rest) != 2` and `count(name_and_suffix) != 2` + guards already early-return `MalformedPathSegment`; under those + guards, `first` and `skip(1) |> first` are both `Some`. +2. Replace each `None => ""` with `None => MalformedPathSegment { + segment: seg, reason: "internal: " }`, threaded as a + typed early-return — same shape as the already-used coproduct + return at `:91` and `:103`. +3. Confirm `parse_segment_tokens`'s return type is the coproduct (it + already is — see the `MalformedPathSegment` early returns at `:91` + / `:103`). No signature change required. +4. Update / add the smallest cementing test: a programmatic feed of a + single-segment input that drives one `None` arm, asserting the + typed `MalformedPathSegment` propagates rather than producing + `[LiteralToken { text: "" }]`. + +## Acceptance + +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green. +- `cargo clippy --all-targets -- -D warnings` clean. +- ROADMAP row "http_path.dag `None => ""` fabrications" flips Open → + Retired with PR sha + reasons in the row. +- `docs/debt/r3-debt-paydown-ledger-2026-05-02.md` row 41 flips Open → + Retired with PR sha and the dissolution shape ("parser returns + typed coproduct on every internal `None` path"). + +## STOP-AND-ESCALATE + +- If any `None` arm turns out to be structurally reachable (the + upstream guard does not in fact prove it `Some`), STOP — that's an + invariant gap, not a fabrication fix; surface to R3 Substrate + Manager (#1739) before introducing any new diagnostic surface. +- If lifting the inner returns requires changing `parse_segment_tokens`'s + return type or the caller's match shape, STOP and surface — that's + a different scope than the row names. + +## Authority audit receipt + +1. **Substrate exists?** `PathTemplateParseResult` coproduct + + `MalformedPathSegment` already declared and consumed at top level + (`http_path.dag:37-69`); helper consumes the same shape at `:91` + and `:103`. No new substrate. +2. **Existing brief?** None for this row. Audit ledger references + only (`docs/debt/r3-debt-paydown-ledger-2026-05-02.md` row 41). +3. **Design-doc match?** No design-doc; ROADMAP row plus INVARIANTS.md + C-8 fail-closed are the authority. +4. **Citations live?** `dsl/std/http_path.dag:95,99,107,111` verified + at HEAD by the wait-window audit. +5. **Carrier dissolves the bridge?** Yes — `MalformedPathSegment` + already exists and is the typed failure shape the row's dissolution + sentence names. + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per parent +session #828 instruction. Ratification pending host restoration and +parent dispatch slot allocation. diff --git a/docs/briefs/r3-425-stale-invariants-prose-sweep-worker.md b/docs/briefs/r3-425-stale-invariants-prose-sweep-worker.md new file mode 100644 index 00000000000..9b25873a1e2 --- /dev/null +++ b/docs/briefs/r3-425-stale-invariants-prose-sweep-worker.md @@ -0,0 +1,108 @@ +--- +status: draft (wait-window; awaits R3 host restoration before dispatch) +authority parent: R3 Substrate Manager (#1739) +roadmap row: ROADMAP.md "Stale §-style and line-number cross-references to pre-rewrite `INVARIANTS.md` — PARTIAL (T-Receipts W1)" +--- + +# R3 :425 — broader stale `INVARIANTS.md` reference sweep + +## Context + +T-Receipts W1 closed the named set of files (design-db16-refined, +clone-elimination, lane2-compile-time-proofs, M1_DESIGN, SELF_HOSTING, +sg-4b-1-fix-declaration-lookup-cleanup, p0-bug-no-profile-sentinel), +flipping their pre-rewrite line-number / `§`-style references to +stable `INVARIANTS.md#` anchors. ROADMAP marks the row PARTIAL: +"Broader stale INVARIANTS prose outside that named set remains a +follow-up sweep." + +The wait-window scan (2026-05-05) found ~15 additional files using +`INVARIANTS.md §"…"` (header-quote refs) or `INVARIANTS.md:` +(line-number refs). Representative set: + +- `docs/emit-target-spec-gaps.md` +- `docs/design-substrate-external-primitives.md` +- `docs/design-lens-framework.md` +- `docs/substrate-reflection-design.md` +- `docs/thesis-validation-plan.md` +- `docs/thesis/doc-authority.md` +- `docs/r2-structure.md` +- `docs/briefs/complexity-v2-v3-comparison-receipt.md` +- `docs/briefs/r2-pb-canonical-lens-bridge-disposition.md` +- `docs/briefs/r3-pb-t-lensproducer-sub3-regen-lens-retirement.md` +- `docs/briefs/r3-pb-runtime-equivalence-corpus-seed-audit.md` +- `docs/briefs/r3-pb-t-fixedpoint-worker.md` +- `docs/briefs/r2-pb-runtime-evaluator-convergence-matrix.md` +- `docs/briefs/r3-pb-binshim-retirement-worker.md` +- `docs/briefs/t-ground-languagespec.md` +- `docs/briefs/file-preference-bridge-dissolution.md` +- `docs/design-tests-as-data-completeness.md` +- `docs/briefs/r2-release-manager.md` + +The fix is mechanical: each `§"
"` or `:` reference +becomes the stable anchor `INVARIANTS.md#` per the ID set the +W1 sweep established. + +## Slice + +1. Run a structured grep at HEAD to enumerate every remaining + `INVARIANTS.md §` / `INVARIANTS.md:` reference outside the + already-fixed W1 set. Snapshot the count in the PR body. +2. For each match, identify the target invariant ID by reading the + current `INVARIANTS.md` and locating the principle / procedure + the prose is citing. The mapping is local to the cited principle + name (`§P1` → `#p1-modeling-faithfulness` etc., per the W1 + convention). +3. Replace each reference with `INVARIANTS.md#` and a short + parenthetical principle name when the surrounding sentence reads + ambiguously without it. Do not paraphrase the cited principle. +4. Where a reference cannot be mapped (the cited header no longer + exists at HEAD; the prose was a stale claim from the pre-rewrite + surface), STOP that file and add it to the per-file table in the + PR body — do not fabricate a target ID. +5. Re-run the structured grep; assert zero matches outside any + intentional historical-receipt blocks (which keep their original + prose for provenance and are out of scope for this sweep). + +## Acceptance + +- Per-file count snapshotted in PR body (before / after / unmappable). +- Zero `INVARIANTS.md §"…"` and zero `INVARIANTS.md:` matches + outside the W1-fixed set and outside intentional historical-receipt + banners. +- ROADMAP row flips PARTIAL → Retired (or stays PARTIAL with a + narrowed residual if the unmappable set is non-empty; in that case + the row's residual sentence names exactly which files remain and + why). +- `cargo test --workspace --exclude v2-compiler-tests` green + (defensive — pure prose changes, but the doc-tree may be linked from + test fixtures). + +## STOP-AND-ESCALATE + +- If a citation cannot be mapped to a current `INVARIANTS.md` ID + because the cited principle has been retired or renamed: STOP for + that file. Surface the unmappable set to R3 Substrate Manager; + resolution may require a Director call on whether the prose itself + is stale. +- If the count exceeds ~30 unique sites or the mapping requires + judgement on more than ~5 sites, STOP — the row's "small mechanical + scope" framing has been violated and this needs to split. + +## Authority audit receipt + +1. **Substrate exists?** N/A — pure prose sweep; no carrier change. +2. **Existing brief?** None; T-Receipts W1 covered the named subset. + This is the residual. +3. **Design-doc match?** N/A. +4. **Citations live?** Worker re-runs the grep at HEAD before + authoring; the wait-window 2026-05-05 enumeration is illustrative, + not authoritative. +5. **Carrier dissolves the bridge?** N/A; mechanical reference + normalization, not a substrate dissolution. + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per parent +session #828 instruction. Ratification pending host restoration and +parent dispatch slot allocation. diff --git a/docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md b/docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md new file mode 100644 index 00000000000..edf1a63937d --- /dev/null +++ b/docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md @@ -0,0 +1,91 @@ +--- +status: design-call surfacing packet (NOT a worker brief) +authority parent: R3 Substrate Manager (#1739) +escalates to: Director (#828) +roadmap row: ROADMAP.md "`Strict Forward Progress` subdoc ↔ heading drift" +--- + +# R3 :426 — SFP subdoc design-call surfacing packet + +## Why this is not a worker brief + +The row's dissolution sentence offers two structurally different +shapes: + +- (A) **Rename** `docs/invariants/strict-forward-progress.md` to + reflect its actual bounded-execution content, **and** author a + new dissolution-progress subdoc under the SFP rule name; or +- (B) **Split** the existing subdoc into two — one for bounded + execution, one for dissolution progress — both retained under + appropriately distinct names. + +Either path is a single short PR. The choice between them is an +**SFP discipline shape question** (what does "Strict Forward +Progress" name in reviewer usage going forward? does the rule keep +its current name as the dissolution-progress invariant, or does the +name retire in favor of two co-equal subdocs?) — not a worker-tier +call. R3 Substrate Manager cannot ratify it without Director input. + +## Facts on the ground (verified at HEAD, 2026-05-05) + +- `docs/invariants/strict-forward-progress.md` exists; its content + is bounded-execution discipline. +- `INVARIANTS.md` P4 and P5 prose flag the drift explicitly as + future cleanup ("future cleanup post-#620"). +- Reviewer usage of the SFP rule name in recent PR review prose + (per parent #828's framing) carries the dissolution-progress + meaning, not the bounded-execution meaning the subdoc actually + holds. + +## Decision the Director needs to make + +Pick one: + +1. **Rename + author new** — `strict-forward-progress.md` becomes + `bounded-execution.md`; a fresh `strict-forward-progress.md` is + authored carrying the dissolution-progress meaning that matches + reviewer usage. Pro: keeps SFP name attached to the + load-bearing reviewer-usage meaning. Con: any cross-reference + to the old subdoc URL breaks; mechanical follow-up sweep. +2. **Split into two** — `strict-forward-progress.md` retains the + SFP name and the bounded-execution content; a new + `dissolution-progress.md` carries the dissolution-progress + meaning. Pro: no cross-reference churn; both subdocs retain + their existing prose. Con: SFP name continues to mean + "bounded execution" in subdoc but "dissolution progress" in + reviewer usage — the drift is not actually resolved, just + renamed-around. +3. **Split + rename** — both: `strict-forward-progress.md` + becomes `bounded-execution.md` *and* a new + `dissolution-progress.md` is authored. Pro: removes ambiguity + of the SFP name entirely (it retires as a subdoc title; both + meanings get distinct co-equal titles). Con: largest + cross-reference sweep; reviewer-usage prose adjusts too. + +Worker brief authoring requires the Director to ratify one of (1) / +(2) / (3) — the brief's Slice section, file moves, and +cross-reference sweep all branch on the choice. + +## What this packet provides + +- Concrete enumeration of the three options with cross-reference + cost framing. +- HEAD-verified fact baseline (subdoc content, INVARIANTS prose + flags, reviewer-usage drift). +- Authority chain: ROADMAP row → INVARIANTS P4/P5 future-cleanup + flags → reviewer usage post-#620. + +## Next step + +R3 Substrate Manager forwards this packet to Director (#828) when +the dispatch queue has Director attention. After ratification, +worker brief is authored picking up the ratified shape (`Slice` +section reflects the picked option's exact file moves and +cross-reference sweep scope). + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per parent +session #828 instruction. The parent flagged that this row needs +Director ratification before worker brief authoring can begin; +this packet captures the ratification call cleanly. diff --git a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md new file mode 100644 index 00000000000..ed13cffd16b --- /dev/null +++ b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md @@ -0,0 +1,111 @@ +--- +status: draft (wait-window; awaits R3 host restoration before dispatch) +authority parent: R3 Substrate Manager (#1739) +roadmap row: ROADMAP.md "`IntegrationRsScan` / `integration_rs_active_line_contains` … byte-constant workaround attractor" (P2 Boundary Discipline / T-Receipts) +--- + +# R3 :435 — `IntegrationRsScan` char-literal state + comment correction + +## Context + +`src/v3/compiler/tests/integration/common/mod.rs` carries an +`IntegrationRsScan` state machine with four states: `Code`, +`LineComment`, `BlockComment(depth)`, `String`. The scanner is +"deliberately narrow" and does not model Rust char literals. The doc +comment at `:320-326` warns that any test author touching the scan +path must avoid `b'\\'` / `b'"'` and substitute numeric byte +constants — and that hitting a raw / byte-string opener inside a +char literal will **panic** rather than silently false-green. + +Historical evidence: +- #686's text-slicing helper introduced `DAG_ESCAPE_BYTE` / + `DAG_QUOTE_BYTE` constants for exactly this reason. +- #705 deleted that helper; constants went with it. +- No surviving in-tree workaround instances today; the scanner + constraint itself remains and is a workaround attractor for the + next test author landing in this scan path. + +Dissolution alternatives named by the row: widen the scanner to +model Rust char literals, **or** replace the scan with a structural +reader that does not need to exclude char-literal syntax. + +## Slice (extension path) + +This brief picks the **scanner-extension** path because it is the +smaller scope; if the worker's pre-flight reveals scanner widening +is harder than a small structural reader (e.g., `syn`-based parse +of `tests/integration.rs`), STOP and surface for re-scoping. + +1. Add a fifth state `Char` to `IntegrationRsScan` in + `src/v3/compiler/tests/integration/common/mod.rs:138-200`. +2. Wire the `Code` → `Char` transition on a `'` byte that is not + immediately preceded by an identifier-continuation byte (lifetime + syntax `'a` is not a char literal). Concretely: a `'` is char- + literal opener iff the previous scanned byte is not in + `[A-Za-z0-9_]`. (This same check is what `rustc`'s lexer uses to + disambiguate; the byte-oriented scan can apply it directly.) +3. While in `Char`, consume bytes to the closing `'`, honoring `\` + as an escape (skip the next byte). Numeric / hex / unicode escapes + inside the `\…` form do not need byte-level decoding — only + escape-skip is required for closing-quote correctness. +4. Update the `Code`-state raw / byte-string opener probe so it does + not fire when the apparent opener is inside `Char`. (With state + #5 in place, this is automatic — the probe lives in `Code` only.) +5. Replace the doc-comment block at `:320-326` ("`Not handled:` … + char literals — none appear in today's `tests/integration.rs` + module list. … extend `IntegrationRsScan` **or** the scan will + **panic**") with: "Char literals are recognized via the `Char` + state; raw / byte-string openers cannot fire inside char literals." +6. Add a unit test in the same file (or its sibling test module) + that scans an `tests/integration.rs`-shaped fragment containing + `b'\\'` and `b'"'` inside a `#[test]` body and asserts: + (a) the scan does not panic; + (b) `integration_rs_active_line_contains` returns `false` for + needles that appear only inside char literals (and in + `String` / comment) — code-only positivity is preserved. + +## Acceptance + +- Scanner extends to five states; char-literal recognition matches + rustc's lifetime-vs-char disambiguation rule. +- Doc comment at `:320-326` reflects the post-extension behavior. +- Unit test for `b'\\'` / `b'"'` inputs lands and is green. +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green. +- `cargo clippy --all-targets -- -D warnings` clean. +- ROADMAP row flips Open → Retired with PR sha; ledger row 71 in + `docs/debt/r3-debt-paydown-ledger-2026-05-02.md` flips Open → + Retired with the dissolution shape ("scanner widened to char + literals; workaround attractor removed"). + +## STOP-AND-ESCALATE + +- If pre-flight reveals the lifetime-vs-char disambiguation needs + more context than a single previous-byte lookback (e.g., the + scanner sees a `'` after whitespace following an identifier), + STOP and surface — the structural-reader alternative may be + cheaper than a correct byte-level disambiguator. +- If extending the scanner triggers cascading test failures + elsewhere that consume `integration_rs_active_line_contains` with + expectations baked against the four-state behavior, STOP — that's + a different scope (consumer migration) than the row names. + +## Authority audit receipt + +1. **Substrate exists?** N/A — Rust test-harness code, not `.dag` + substrate. +2. **Existing brief?** None; row is owner-unassigned per ROADMAP. +3. **Design-doc match?** N/A. +4. **Citations live?** `mod.rs:138, 141, 320-326` verified via + wait-window grep at HEAD (2026-05-05). State enum at `:138`, + doc comment block at `:320-326`. +5. **Carrier dissolves the bridge?** Yes — adding `Char` state + removes the "byte-constant workaround attractor" the row names; + dissolution sentence in ROADMAP is "widen the scanner to model + Rust char literals." + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per parent +session #828 instruction. Ratification pending host restoration and +parent dispatch slot allocation. From e53a442cabd738139a31448f0853cd85a64f45b3 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 04:00:04 -0400 Subject: [PATCH 02/52] WIP: R3 Substrate --- ...r3-426-sfp-subdoc-design-call-surfacing.md | 91 -------- ...426-sfp-subdoc-rename-and-author-worker.md | 95 +++++++++ ...-s1-transform-dispatch-substrate-worker.md | 198 ++++++++++++++++++ 3 files changed, 293 insertions(+), 91 deletions(-) delete mode 100644 docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md create mode 100644 docs/briefs/r3-426-sfp-subdoc-rename-and-author-worker.md create mode 100644 docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md diff --git a/docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md b/docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md deleted file mode 100644 index edf1a63937d..00000000000 --- a/docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -status: design-call surfacing packet (NOT a worker brief) -authority parent: R3 Substrate Manager (#1739) -escalates to: Director (#828) -roadmap row: ROADMAP.md "`Strict Forward Progress` subdoc ↔ heading drift" ---- - -# R3 :426 — SFP subdoc design-call surfacing packet - -## Why this is not a worker brief - -The row's dissolution sentence offers two structurally different -shapes: - -- (A) **Rename** `docs/invariants/strict-forward-progress.md` to - reflect its actual bounded-execution content, **and** author a - new dissolution-progress subdoc under the SFP rule name; or -- (B) **Split** the existing subdoc into two — one for bounded - execution, one for dissolution progress — both retained under - appropriately distinct names. - -Either path is a single short PR. The choice between them is an -**SFP discipline shape question** (what does "Strict Forward -Progress" name in reviewer usage going forward? does the rule keep -its current name as the dissolution-progress invariant, or does the -name retire in favor of two co-equal subdocs?) — not a worker-tier -call. R3 Substrate Manager cannot ratify it without Director input. - -## Facts on the ground (verified at HEAD, 2026-05-05) - -- `docs/invariants/strict-forward-progress.md` exists; its content - is bounded-execution discipline. -- `INVARIANTS.md` P4 and P5 prose flag the drift explicitly as - future cleanup ("future cleanup post-#620"). -- Reviewer usage of the SFP rule name in recent PR review prose - (per parent #828's framing) carries the dissolution-progress - meaning, not the bounded-execution meaning the subdoc actually - holds. - -## Decision the Director needs to make - -Pick one: - -1. **Rename + author new** — `strict-forward-progress.md` becomes - `bounded-execution.md`; a fresh `strict-forward-progress.md` is - authored carrying the dissolution-progress meaning that matches - reviewer usage. Pro: keeps SFP name attached to the - load-bearing reviewer-usage meaning. Con: any cross-reference - to the old subdoc URL breaks; mechanical follow-up sweep. -2. **Split into two** — `strict-forward-progress.md` retains the - SFP name and the bounded-execution content; a new - `dissolution-progress.md` carries the dissolution-progress - meaning. Pro: no cross-reference churn; both subdocs retain - their existing prose. Con: SFP name continues to mean - "bounded execution" in subdoc but "dissolution progress" in - reviewer usage — the drift is not actually resolved, just - renamed-around. -3. **Split + rename** — both: `strict-forward-progress.md` - becomes `bounded-execution.md` *and* a new - `dissolution-progress.md` is authored. Pro: removes ambiguity - of the SFP name entirely (it retires as a subdoc title; both - meanings get distinct co-equal titles). Con: largest - cross-reference sweep; reviewer-usage prose adjusts too. - -Worker brief authoring requires the Director to ratify one of (1) / -(2) / (3) — the brief's Slice section, file moves, and -cross-reference sweep all branch on the choice. - -## What this packet provides - -- Concrete enumeration of the three options with cross-reference - cost framing. -- HEAD-verified fact baseline (subdoc content, INVARIANTS prose - flags, reviewer-usage drift). -- Authority chain: ROADMAP row → INVARIANTS P4/P5 future-cleanup - flags → reviewer usage post-#620. - -## Next step - -R3 Substrate Manager forwards this packet to Director (#828) when -the dispatch queue has Director attention. After ratification, -worker brief is authored picking up the ratified shape (`Slice` -section reflects the picked option's exact file moves and -cross-reference sweep scope). - -## Provenance - -Drafted during R3 host-block wait window (2026-05-05) per parent -session #828 instruction. The parent flagged that this row needs -Director ratification before worker brief authoring can begin; -this packet captures the ratification call cleanly. diff --git a/docs/briefs/r3-426-sfp-subdoc-rename-and-author-worker.md b/docs/briefs/r3-426-sfp-subdoc-rename-and-author-worker.md new file mode 100644 index 00000000000..615063c1ec8 --- /dev/null +++ b/docs/briefs/r3-426-sfp-subdoc-rename-and-author-worker.md @@ -0,0 +1,95 @@ +--- +status: draft (wait-window; awaits R3 host restoration before dispatch) +authority parent: R3 Substrate Manager (#1739) +ratification: Director (#828) ratified option (a) at #issuecomment-4377264483 (2026-05-05) +roadmap row: ROADMAP.md "`Strict Forward Progress` subdoc ↔ heading drift" +supersedes: docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md (surfacing packet now obsolete) +--- + +# R3 :426 — SFP subdoc rename + dissolution-progress subdoc author + +## Context + +`docs/invariants/strict-forward-progress.md` carries +**bounded-execution** content; reviewer usage of the name "Strict +Forward Progress" carries the **dissolution-progress** meaning +(see `INVARIANTS.md:314`). `INVARIANTS.md` flags the drift in three +places (`:253`, `:273`, `:315`) as "future cleanup." + +Director ratified option (a): **rename + author new**, preserving +the SFP name attached to the reviewer-usage meaning. + +## Slice + +1. `git mv docs/invariants/strict-forward-progress.md + docs/invariants/bounded-forward-execution.md`. Content unchanged. +2. Author a fresh `docs/invariants/strict-forward-progress.md` + carrying the dissolution-progress concept. Source the canonical + statement from `INVARIANTS.md:314` ("a change counts as progress + only if it reduces ad-hoc state, duplicate authority, or implicit + behavior; transitional scaffolds need explicit dissolution paths + and cannot become the new steady state"). Cross-link the + bounded-execution subdoc as a sibling concern, not a parent. +3. Update `INVARIANTS.md`: + - `:253` — rewrite the "Note on naming" block: drop the drift + caveat; redirect the bounded-execution pointer to + `bounded-forward-execution.md`; affirm SFP name now points at + the dissolution-progress subdoc. + - `:273` — rewrite the bounded-forward-execution bullet's + subdoc reference to point at `bounded-forward-execution.md`. + - `:315` — delete the "*Note:*" block (drift caveat) entirely; + SFP bullet's subdoc reference now points at the freshly + authored `strict-forward-progress.md`. +4. `rg "strict-forward-progress\.md"` across the tree; update any + reference whose intent was bounded-execution (subdoc content) + to `bounded-forward-execution.md`. References whose intent was + the SFP rule name (reviewer usage) stay pointed at + `strict-forward-progress.md` — they now resolve correctly. +5. ROADMAP row "`Strict Forward Progress` subdoc ↔ heading drift" + flips Open → Retired with PR sha and the dissolution sentence + ("rename + author new per Director sign-off + #issuecomment-4377264483"). + +## Acceptance + +- Two subdocs exist: `bounded-forward-execution.md` (renamed, + content unchanged) + freshly authored `strict-forward-progress.md` + (dissolution-progress). +- `INVARIANTS.md:253/273/315` updated; drift caveats removed. +- `rg "strict-forward-progress\.md"` shows no references with + bounded-execution intent. +- `cargo fmt --all --check` clean (no Rust changes; defensive). +- ROADMAP row Retired. + +## STOP-AND-ESCALATE + +- If the freshly authored `strict-forward-progress.md` reveals that + the dissolution-progress concept has substantive content not + captured anywhere in `INVARIANTS.md` P5, STOP — the rule is + under-documented and the worker brief assumed only a + reorganization, not new authority. Surface to R3 Substrate + Manager. +- If the cross-tree reference sweep at step 4 turns up references + whose intent is genuinely ambiguous (was the cite about subdoc + content or about the rule name?), STOP that reference and + surface; do not silently route either way. + +## Authority audit receipt + +1. **Substrate exists?** N/A — invariants documentation, not `.dag`. +2. **Existing brief?** None; supersedes the surfacing packet + `r3-426-sfp-subdoc-design-call-surfacing.md`. +3. **Design-doc match?** Director's ratification message at + `#issuecomment-4377264483` names option (a) with the exact + file moves used here. +4. **Citations live?** `INVARIANTS.md:253,273,314,315` verified at + HEAD (2026-05-05). +5. **Carrier dissolves the bridge?** N/A; pure documentation + reorganization, not substrate work. + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per parent +session #828 instruction; replaces the earlier surfacing packet +once Director ratified option (a). Ratification pending host +restoration and parent dispatch slot allocation. diff --git a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md new file mode 100644 index 00000000000..f7dd21063cb --- /dev/null +++ b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md @@ -0,0 +1,198 @@ +--- +status: draft (wait-window; awaits R3 host restoration AND E6-G0c merge before dispatch) +authority parent: R3 Substrate Manager (#1739) +input packet: R3 PB (neat-bear-351, #1742) at #issuecomment-4377461921 +hard precondition: E6-G0c merged (R3 Evaluator merry-gull-128 #1743 owns) +authority docs: + - docs/design-prereq-x-ho-field-call.md §Prereq-X1 / §L1.b (Director-approved 2026-04-30 #1130) + - docs/briefs/x1b-evaluator-impact-audit.md §3, §4 Slice S1, §5 +disambiguation: This is **Prereq-X1.b** (HO field-call / runtime-sourced callee dispatch), NOT TV2 retirement audit "Decision 2" (`kernel_algebra_profile`). Same-label collision; different track. +--- + +# R3 X1.b S1 — `TransformDispatch` substrate carrier + atomic `(target, inputs)` retirement + +## Context + +Today's `TransformNode` carries `target: TransformTarget` (3 variants: +`Callable | FieldProject | Operator`) plus a sibling +`inputs: Vec` whose meaning depends on the variant — pure +positional dependency for `Callable` / `FieldProject`, or operator +arguments for `Operator`. The runtime-sourced callee case (HO +field-call, parameter dispatch) cannot be expressed in this shape: +the callee must be sourced from a port, but `TransformTarget` has no +port-valued variant. The current shape also leaks parallel authority +— `target` is the routing fact; `inputs` is the dependency-walk +fact; reflected consumers walk `inputs` directly to derive +dependencies (per audit §1 evaluator consumer catalog). + +§Prereq-X1 / §L1.b prescribes collapsing both fields into a single +`TransformDispatch` sum carrying its own typed payloads, with +`input_ports()` as the single dependency-walk authority and +`ArrowPortRef` as a typed witness for port-valued callees. + +S1 is the **Substrate authority** slice: lands the carrier and +mechanical consumer updates. S2 (lowerer produces `Indirect`), +S3 (evaluator semantics for `Indirect` / `FieldCall`), and S4 +(emitter follow-up) are downstream slices in different ownership. + +## Slice + +Per `x1b-evaluator-impact-audit.md` §4 Slice S1; not duplicated here. +Worker MUST read that section before authoring code. Summary: + +1. Introduce `TransformDispatch` on `TransformNode` with variants + `Callable | FieldProject | FieldCall | Operator | Indirect`. + Module-private payload fields; public accessors only. +2. Add `ArrowPortRef(PortId)` (private constructor) and + `Dag::resolve_arrow_port(p: PortId) -> Result`. +3. Add typed builders: `Dag::push_callable_transform`, + `push_field_project_transform`, `push_field_call_transform`, + `push_indirect_transform`. Co-construct args-vs-target proofs + per design doc. +4. Add `TransformDispatch::input_ports() -> impl Iterator<&PortId>` + as the single dependency-walk authority. +5. Migrate `dsl/std/` reflection sum to mirror the new variants + so generated / lockstep substrate stays consistent. +6. **Atomic** mechanical update of all in-tree consumers per audit + §3 list 7–12 + §1 evaluator consumers: + `src/v3/compiler/src/dag.rs`, `dag/builder.rs`, `lower.rs`, + `infer.rs`, `emit.rs`, `emit/rust_target.rs`, + `emit/python_target.rs`, `regen_bootstrap_emit.rs`, generated + `lens_*_generated.rs`, `bootstrap_generated*.rs`, evaluator + `lib.rs` (`eval_transform_node`), `lens_apply.rs` + (eligibility / `eval_transform` / `reflect_transform_target`), + `dimension.rs`. All mechanical: + `t.inputs` → `t.dispatch.input_ports()`, + `&t.target` → `&t.dispatch`. +7. **No bridge**: `TransformNode.target` and `TransformNode.inputs` + retire in the **same commit** that introduces `TransformDispatch`. + Per `INVARIANTS.md` P2 (single-authority metadata) + + `feedback_parallel_representation_debt`, an unbounded + `(target, inputs) ∥ dispatch` bridge is disallowed; this brief + does **not** authorize a temporary bounded bridge. + +### Behavior preservation + +S1 produces **zero net behavior change** relative to its starting +point. Because S1 lands **after** G0c (hard precondition), starting +point includes G0c's evaluated `Callable` / `FieldProject` arms in +`eval_transform_node`. S1 preserves that evaluation verbatim through +the rename to `TransformDispatch::Callable` / `FieldProject`; it +must **not** revert those arms to fail-closed. The only +newly-fail-closed arms S1 adds are `FieldCall` and `Indirect`, +which remain fail-closed until S3. + +The lens-apply evaluator (`lens_apply.rs`) preserves its existing +`Callable` / `FieldProject` evaluation through the rename and gains +fail-closed arms for `FieldCall` and `Indirect`. + +### Pre-flight (mandatory before authoring code) + +- Read `docs/design-prereq-x-ho-field-call.md` §Prereq-X1 / §L1.b + in full; carry the dissolution-ledger 🟢🟡🔴 marks into the PR + body. +- Read `docs/briefs/x1b-evaluator-impact-audit.md` §1 (evaluator + consumer catalog), §3 (substrate-adjacent consumer catalog), §4 + Slice S1, §5 (STOP conditions). +- Update `src/v3/DOWNSTREAM_REQUIREMENTS.md` with the consumer + enumeration **before** S1 work starts, per + `feedback_enumerate_before_substrate`. +- Verify E6-G0c is merged on `main` (`git log --oneline main -- + src/v3/compiler/src/lib.rs` and confirm host + `eval_transform_node` `Callable` / `FieldProject` arms are + evaluated, not fail-closed). If unmerged, STOP — wait. + +## Acceptance + +- Atomic commit: `TransformDispatch` introduced, `target` + `inputs` + retired, all consumers updated, generated files regenerated. +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile diagnostic + ratchet (`v2_strict_compile_diagnostic_count -- --ignored`) + remains at 0 diagnostics. +- `cargo clippy --all-targets -- -D warnings` clean. +- `cargo fmt --all --check` clean. +- G0c-evaluated `Callable` / `FieldProject` arms in + `eval_transform_node` and `lens_apply.rs` preserve evaluation + (regression: existing E6 tests still green). +- `FieldCall` and `Indirect` arms fail closed with a typed error + (no fabrication, no panic). +- ROADMAP receives a new entry under the appropriate section noting + S1 landed; X1 dissolution ledger in + `design-prereq-x-ho-field-call.md` flips L1.b 🟡 → 🟢 (or per + whatever flip the design doc names). + +## STOP-AND-ESCALATE + +Per `x1b-evaluator-impact-audit.md` §5 STOP conditions: + +- **G0c not merged.** Wait. S1 cannot land first. +- **Substrate redesign in flight invalidating §X1.b shape** + (e.g., a `CalleeRef`-collapse re-scope). Audit names this as a + Director STOP branch — surface to Director #828; do **not** + silently re-shape the variants. +- **Regen / strict-compile ratchet red** at S1 start. Wait for + green; S1 touches generated files and must not land into an + unstable regen state. +- **Reflection mid-migration drift** between `dsl/std/` reflection + sum and Rust `TransformDispatch` after step 5. Surface; this is + a substrate-internal coherence break and S1 cannot proceed + without it being clean. +- **`Vec` cannot retire atomically** (some consumer's + rewrite turns out to require a bridge). Surface to R3 Substrate + Manager (#1739); the no-bridge rule is load-bearing per the + audit and this brief, and re-scoping requires Director input. + +## Sequencing post-S1 + +- **S2** (Lowerer authority): produces `TransformDispatch::Indirect` + / parameter field-call paths. Different worker. +- **S3** (Evaluator authority, post-G0c): evaluator semantics for + `Indirect` (and `FieldCall` composition where applicable). + Different worker. +- **S4** (Emitter / Lens-author authority): non-mechanical emitter + / lens-author follow-up. Independent of S2/S3. +- **E6-G1** (R3 Evaluator merry-gull-128 #1743): generic + `fold_lens` parametric runtime callee — downstream of the + **full X1.b chain**. S1 alone is necessary, not sufficient + (per `r3-pr-e6-lens-fold-readiness-audit.md`). + +## Authority audit receipt + +1. **Substrate exists?** No — `TransformDispatch` is the new + carrier this slice introduces; today's `TransformNode` carries + `target: TransformTarget` (`src/v3/compiler/src/dag.rs:1695-1712`) + + `inputs: Vec`. No existing carrier dissolves the HO + field-call gap. +2. **Existing brief?** This brief is the X1.b S1 worker dispatch. + Authority docs: design-prereq-x-ho-field-call.md (§Prereq-X1 / + §L1.b) is the design authority; x1b-evaluator-impact-audit.md + is the consumer catalog + slice split. No prior worker brief + for S1 itself. +3. **Design-doc match?** Verified: §Prereq-X1 / §L1.b prescribes + exactly the `TransformDispatch` sum, `ArrowPortRef`, + `resolve_arrow_port`, builders, and `input_ports()` listed + here. The audit's S1 spec at §4 matches the design-doc + recommendation 1:1. +4. **Citations live?** `src/v3/compiler/src/dag.rs:1695-1712` + (`TransformTarget` enum + `TransformNode` struct) verified at + HEAD via design-doc cite (worker re-verifies at S1 start since + line numbers may drift). +5. **Carrier dissolves the bridge?** Yes — `TransformDispatch` + collapses `target` and `inputs` into a single typed sum; + `input_ports()` is the single dependency-walk authority, + eliminating the parallel `target` (routing) ∥ `inputs` + (dependency) authority pair. The `Indirect` variant carries + `ArrowPortRef` to express runtime-sourced callees the current + shape cannot express. + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per parent +session #828 instruction (T-Numeric-Construction parallel-author +posture extended to X1.b after R3 PB delivered the input packet +at #1742 #issuecomment-4377461921). Ratification pending host +restoration AND E6-G0c merge from R3 Evaluator (merry-gull-128 +#1743). Two-precondition gate; this brief is throughput-prep, not +immediate dispatch. From b97d4279043ea556ffb423d7b3cbbd205e0e7181 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 04:03:10 -0400 Subject: [PATCH 03/52] WIP: R3 Substrate --- docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md index f7dd21063cb..c42f0d26496 100644 --- a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md +++ b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md @@ -1,7 +1,7 @@ --- status: draft (wait-window; awaits R3 host restoration AND E6-G0c merge before dispatch) authority parent: R3 Substrate Manager (#1739) -input packet: R3 PB (neat-bear-351, #1742) at #issuecomment-4377461921 +input packet: R3 PB (neat-bear-351, #1742) at #issuecomment-4377461513 hard precondition: E6-G0c merged (R3 Evaluator merry-gull-128 #1743 owns) authority docs: - docs/design-prereq-x-ho-field-call.md §Prereq-X1 / §L1.b (Director-approved 2026-04-30 #1130) @@ -192,7 +192,7 @@ Per `x1b-evaluator-impact-audit.md` §5 STOP conditions: Drafted during R3 host-block wait window (2026-05-05) per parent session #828 instruction (T-Numeric-Construction parallel-author posture extended to X1.b after R3 PB delivered the input packet -at #1742 #issuecomment-4377461921). Ratification pending host +at #1742 #issuecomment-4377461513). Ratification pending host restoration AND E6-G0c merge from R3 Evaluator (merry-gull-128 #1743). Two-precondition gate; this brief is throughput-prep, not immediate dispatch. From 78985daac61a00ca495a90a1f9319934fe6aec40 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 04:18:01 -0400 Subject: [PATCH 04/52] WIP: R3 Substrate --- ...3-378-http-path-helper-fail-open-worker.md | 17 +- ...integration-rs-scan-char-literal-worker.md | 147 ++++++++++--- ...ission-path-projection-substrate-worker.md | 174 ++++++++++++++++ .../r3-t-e-p-producer-broadening-worker.md | 193 ++++++++++++++++++ 4 files changed, 502 insertions(+), 29 deletions(-) create mode 100644 docs/briefs/r3-l6-emission-path-projection-substrate-worker.md create mode 100644 docs/briefs/r3-t-e-p-producer-broadening-worker.md diff --git a/docs/briefs/r3-378-http-path-helper-fail-open-worker.md b/docs/briefs/r3-378-http-path-helper-fail-open-worker.md index f341c874854..a7dcfacab9b 100644 --- a/docs/briefs/r3-378-http-path-helper-fail-open-worker.md +++ b/docs/briefs/r3-378-http-path-helper-fail-open-worker.md @@ -38,10 +38,19 @@ missed these. Row remains REAL, not partially-dissolved. 3. Confirm `parse_segment_tokens`'s return type is the coproduct (it already is — see the `MalformedPathSegment` early returns at `:91` / `:103`). No signature change required. -4. Update / add the smallest cementing test: a programmatic feed of a - single-segment input that drives one `None` arm, asserting the - typed `MalformedPathSegment` propagates rather than producing - `[LiteralToken { text: "" }]`. +4. Update / add the smallest cementing test exercising the + **reachable** `MalformedPathSegment` propagation path that the + inner `None` arms guard against: a single-segment input whose + shape (e.g., `{a}b{c}` — multiple opening braces, or `{ab` — + missing closing brace) drives the upstream `count(...) != 2` + guards' typed early-returns. Assert the propagation reaches + `parse_path_template`'s typed `MalformedPathTemplate` / + `PathTemplateParseResult` boundary, not `[LiteralToken { text: "" }]`. + The inner-arm replacements at step 2 are structural-unreachability + declarations, not runtime fallbacks; under §1's guard-invariant + confirmation no input can drive them, so the test exists to + pin the **reachable** guard discipline rather than the unreachable + replacement arm. ## Acceptance diff --git a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md index ed13cffd16b..0ff6e30c702 100644 --- a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md +++ b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md @@ -29,25 +29,93 @@ Dissolution alternatives named by the row: widen the scanner to model Rust char literals, **or** replace the scan with a structural reader that does not need to exclude char-literal syntax. -## Slice (extension path) - -This brief picks the **scanner-extension** path because it is the -smaller scope; if the worker's pre-flight reveals scanner widening -is harder than a small structural reader (e.g., `syn`-based parse -of `tests/integration.rs`), STOP and surface for re-scoping. +## Slice — two co-equal paths; worker picks at pre-flight + +The worker picks **one** of the two paths below at pre-flight, +based on which is more honest given the live state of +`tests/integration.rs` and workspace dependency surface. Both paths +are spec-backed and explicitly named in the row's dissolution +sentence; neither is a STOP-fallback to the other. + +### Path A — structural Rust reader (preferred when feasible) + +Replace the byte-oriented scanner with a structural Rust source +reader that already encodes Rust's lexical grammar: + +- **`rustc_lexer`** (rustc's own lexer crate; thin, no syntax-tree + construction): tokenize `tests/integration.rs` and walk the + token stream skipping `LineComment` / `BlockComment` / + `Literal { kind: Str | RawStr | Byte | ByteStr | RawByteStr | + Char | ByteChar }` tokens. `integration_rs_active_line_contains` + becomes a token-stream filter rather than a hand-coded state + machine. Lifetime-vs-char disambiguation is rustc-faithful by + construction (the crate IS rustc's authority). +- **`syn::parse_file`** (heavier; full AST): parse the file and + walk only `Item` / `ImplItem` text spans for the needle. AST + walk is structurally exact; cost is the AST allocation per scan. + +Worker pre-flight verifies which dependency is easier to add to +the workspace; if `rustc_lexer` is not already transitively +available and adding it requires a vendored fork, prefer `syn` +(more likely already in the workspace via proc-macro deps). + +Path A acceptance: `IntegrationRsScan` deleted entirely; +`integration_rs_active_line_contains` reimplemented as a +token-stream / AST-span filter. Doc comment block at `:320-326` +deleted (no longer applicable). Workaround attractor (the +constraint itself) is gone, not just narrowed. + +### Path B — scanner extension with rustc-lexer-faithful rule + +If Path A is blocked (workspace dependency policy, rustc_lexer +not available, syn too heavyweight for a test harness), extend +the existing byte-oriented scanner. The disambiguation rule MUST +mirror `rustc_lexer::Cursor::single_quoted_string` semantics, NOT +a naive byte heuristic. + +**Worker pre-flight obligation (Path B):** read +`rustc_lexer/src/lib.rs` `single_quoted_string` (or the live +equivalent in the rustc tree at the worker's pin) and reproduce +its disambiguation logic faithfully. Cite the upstream source +SHA in the PR body. Naive lookback heuristics (e.g., "previous +byte is not identifier-continuation") are explicitly rejected +per the BLOCKING finding on the prior brief revision — they +misclassify `&'a T` and `'label: loop` as char openers. + +Sketch of the lexer-faithful rule: 1. Add a fifth state `Char` to `IntegrationRsScan` in `src/v3/compiler/tests/integration/common/mod.rs:138-200`. -2. Wire the `Code` → `Char` transition on a `'` byte that is not - immediately preceded by an identifier-continuation byte (lifetime - syntax `'a` is not a char literal). Concretely: a `'` is char- - literal opener iff the previous scanned byte is not in - `[A-Za-z0-9_]`. (This same check is what `rustc`'s lexer uses to - disambiguate; the byte-oriented scan can apply it directly.) -3. While in `Char`, consume bytes to the closing `'`, honoring `\` - as an escape (skip the next byte). Numeric / hex / unicode escapes - inside the `\…` form do not need byte-level decoding — only - escape-skip is required for closing-quote correctness. +2. Wire the `Code` → `Char` transition via **bounded forward + lookahead**, NOT previous-byte lookback. A previous-byte rule + misclassifies `&'a T` (byte before `'` is `&`, not an identifier + byte) and `'label: loop { ... }` (byte before `'` is whitespace + or `{`) as char-literal openers — both are lifetimes / labels. + Concretely: when the scanner sees `'` in `Code`, peek forward + up to 16 bytes (the longest valid char-literal body + `'\u{10FFFF}'` is ~10 bytes between quotes; 16 is the + defensive ceiling) for a closing `'`, honoring `\` as an + escape (the byte after `\` is consumed as part of the escape + without acting as a closing quote). + - **Closing `'` found within the window** → enter `Char` + (consume from the opening `'` through the closing `'` + inclusive); resume `Code`. + - **No closing `'` within the window** → the opening `'` was + a lifetime / label start, not a char-literal opener; stay + in `Code`, advance past the `'` only, and let the + identifier-continuation bytes after it be scanned in `Code` + normally. + This is fail-closed by construction: lifetimes / labels do not + carry closing `'`, so they never enter `Char`; char literals + always carry closing `'` within the bounded window, so they + always enter `Char`. No false-`Char` on lifetime / label syntax. +3. The bounded-lookahead recognizer in step 2 already handles + `\`-escape skipping inside the `Char` body. The scanner enters + `Char` only after the closing `'` is confirmed reachable, so + the body is consumed in a single pass without state drift. + Numeric / hex / unicode escapes inside the body do not require + byte-level decoding — only escape-skip is required for + closing-quote correctness. 4. Update the `Code`-state raw / byte-string opener probe so it does not fire when the apparent opener is inside `Char`. (With state #5 in place, this is automatic — the probe lives in `Code` only.) @@ -66,10 +134,27 @@ of `tests/integration.rs`), STOP and surface for re-scoping. ## Acceptance -- Scanner extends to five states; char-literal recognition matches - rustc's lifetime-vs-char disambiguation rule. -- Doc comment at `:320-326` reflects the post-extension behavior. -- Unit test for `b'\\'` / `b'"'` inputs lands and is green. +Path A or Path B, whichever the worker selects at pre-flight, +must satisfy: + +- **Path A:** `IntegrationRsScan` deleted; + `integration_rs_active_line_contains` reimplemented as a + token-stream / AST-span filter. Doc comment at `:320-326` + removed (no longer applicable). PR body cites the upstream + crate (`rustc_lexer` SHA or `syn` version) used. +- **Path B:** Scanner extends to five states; disambiguation rule + cites `rustc_lexer::Cursor::single_quoted_string` (or live + equivalent) at the worker's pinned upstream SHA in the PR + body. No false-`Char` classification on lifetime / label + inputs. Doc comment at `:320-326` reflects the post-extension + behavior. +- **Both paths** — unit tests land covering: (a) `b'\\'` / `b'"'` + char-literal bodies (the original workaround-attractor pattern); + (b) `&'a T` lifetime in reference position stays code (Path A: + not classified as literal-skip; Path B: stays in `Code`); + (c) `'label: loop { ... }` label form stays code (same). + All green. The lifetime + label tests are the BLOCKING-finding + regression cases — not optional. - `cargo test --workspace --exclude v2-compiler-tests` green. - `cargo test -p v2-compiler-tests` green. - `cargo clippy --all-targets -- -D warnings` clean. @@ -80,11 +165,23 @@ of `tests/integration.rs`), STOP and surface for re-scoping. ## STOP-AND-ESCALATE -- If pre-flight reveals the lifetime-vs-char disambiguation needs - more context than a single previous-byte lookback (e.g., the - scanner sees a `'` after whitespace following an identifier), - STOP and surface — the structural-reader alternative may be - cheaper than a correct byte-level disambiguator. +- If a real-world `tests/integration.rs`-shaped fragment in the + worker's pre-flight contains a char-literal body legitimately + longer than the 16-byte lookahead window, STOP and surface — + either widen the window with explicit upper-bound justification + or escalate to the structural-reader alternative the row's + dissolution sentence names. +- If a closing `'` lookahead can be ambiguous against an unrelated + later `'` in pathological code (e.g., a lifetime followed soon + after by a char literal on the same line), STOP and verify + against an actual fragment from the integration scan path. The + bounded-lookahead rule is fail-closed for the lifetime case (no + closing `'` ⇒ stay `Code`), but a worker who finds an + adversarial counter-example must surface rather than band-aid. +- Add a unit test that exercises both `&'a T` (lifetime in + reference type) and `'label: loop { break 'label; }` (label + scope) and asserts both stay in `Code` (no false-`Char`); these + are the BLOCKING-finding regression tests, not optional. - If extending the scanner triggers cascading test failures elsewhere that consume `integration_rs_active_line_contains` with expectations baked against the four-state behavior, STOP — that's diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md new file mode 100644 index 00000000000..90822caa003 --- /dev/null +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -0,0 +1,174 @@ +--- +status: draft (wait-window; awaits R3 host restoration before dispatch) +authority parent: R3 Substrate Manager (#1739) +ratification: Director (#828) ratified Option 2 + sub-questions §4.A=(a) / §4.B=List / §4.C=(i) / §4.D=(b) at cross-Mgr relay #issuecomment-4377533390 (2026-05-05); originating recommendation surfaced at #828 #issuecomment-4377459345 +roadmap row: docs/briefs/r3-substrate-l6-per-row-projection-routing-decision.md (originating routing receipt; archived predecessor tidy-tern-769 #1288) +cross-mgr handoff: R3 Grounding (bold-ferret-748, #1745) — Grounding owns row-population follow-up + `coverage.rs` conversion +--- + +# R3 L6 — `EmissionPathProjection` substrate carrier slice + +## Context + +`src/v3/grounding_cross_target_meta/src/coverage.rs` projects L6 +`(FormAxis × BehaviorAxis × ShapeATarget)` coverage by per-target +`MethodTemplateContract` list non-emptiness — honest only while +all Phase 1 rows are homogeneous (`Cardinality × Transform × target`). +The walker carries an in-source TODO to land per-row projection +before any non-`Cardinality × Transform` row enters the lists. + +The routing-decision receipt at +`docs/briefs/r3-substrate-l6-per-row-projection-routing-decision.md` +selected Option 2 (sibling projection carrier keyed by +`MethodTemplateContractKey`) and STOPped pending Director sign-off +on §4.A–§4.D. R3 Substrate Mgr surfaced the (a)/List/(i)/(b) +recommendation at #828 #issuecomment-4377459345; Director ratified +that slate at the cross-Mgr relay routing carrier authoring back +to R3 Substrate. + +This brief lands the **carrier slice only**. Grounding owns the +follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). + +## Slice + +1. Author new file `src/v3/std/cross_target_coverage.dag` containing: + + ```dag + // Header note (mandatory): option (c) — generated mirror of + // v3_compiler::dag::TypeConnective and v3_compiler::dag::Behavior + // — is the correct dissolution target for the hand-declared + // FormAxis / BehaviorAxis below, once a substrate-Disj-mirroring + // generator exists. The (a) hand-declared form here is interim + // until that generator lands. Per Director ratification of §4.A + // at #issuecomment-4377533390. + + type ShapeATarget = Rust | Python | Go + + type FormAxis = ... // mirrors v3_compiler::dag::TypeConnective discriminants (worker + // re-reads the live enum at dispatch time and lists the variants + // 1:1; new connectives added here only via P1 procedure on the + // upstream Rust enum first) + + type BehaviorAxis = ... // mirrors v3_compiler::dag::Behavior discriminants (same rule) + + type MethodTemplateContractKey { + target: ShapeATarget + dag_method: MethodRef + } + + type EmissionCell { + connective: FormAxis + behavior: BehaviorAxis + } + + type EmissionPathProjection { + row_identity: MethodTemplateContractKey + cells: List + } + + data emission_path_projections: List = [] + ``` + + The `data` declaration ships **empty**. Grounding's follow-up + PR populates the 42 Phase 1 rows. + +2. Add a small ratchet asserting that: + - The five types and the `data` declaration exist with the + ratified field shapes (typed-substrate read, no string scan). + - When `emission_path_projections` is non-empty, its row count + equals the sum of `MethodTemplateContract` row counts across + `*_method_template_contracts` lists (row-count parity). + The parity assertion is structurally trivial while the list + is empty (vacuously true) and activates the load-bearing + check once Grounding populates. + +3. **No row population, no `coverage.rs` edits in this slice.** + Both are scoped to the Grounding follow-up per §4.D=(b). + +## Acceptance + +- `src/v3/std/cross_target_coverage.dag` lands with the five + types + the empty `data` declaration + the mandatory + option-(c) header note. +- Ratchet test exists and passes (vacuous parity at this slice; + carrier-shape gates structurally enforced). +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile + diagnostic ratchet at 0. +- `cargo clippy --all-targets -- -D warnings` clean. +- `cargo fmt --all --check` clean. +- `MethodTemplateContract` rows untouched (Option 2 honors C1 + orthogonality — zero changes to authoring carriers). +- After landing, R3 Substrate Mgr signals R3 Grounding + (bold-ferret-748, #1745) so they can dispatch row-population. + +## STOP-AND-ESCALATE + +- **`FormAxis` / `BehaviorAxis` variant set has drifted from + `v3_compiler::dag::TypeConnective` / `Behavior` since the routing + receipt was authored.** Worker re-reads the live Rust enums; if + variant names or counts have moved, STOP — that's a P1 + modeling-faithfulness event for the upstream enum, and the + hand-declared mirror cannot land into a divergent state. Surface + to R3 Substrate Manager (#1739). +- **`MethodRef` shape has drifted** in a way that makes the + proposed `MethodTemplateContractKey { target, dag_method: + MethodRef }` join ambiguous against current + `MethodTemplateContract` rows. STOP — the join is load-bearing + (1:1 row-identity match) and silent re-shaping breaks Option 2's + C2 (no string-name dispatch) guarantee. +- **A substrate-`Disj`-mirroring generator lands during this + slice's authoring** (the option-(c) dissolution target). STOP — + this slice's hand-declared form becomes immediately retire-able + via the generator; rather than landing the interim form, surface + for re-scoping toward generated mirrors. + +## Cross-Mgr handoff post-landing + +Once this slice lands, R3 Substrate Mgr signals R3 Grounding +(bold-ferret-748, #1745) per the routing receipt §4.D=(b) +hand-off. Grounding then dispatches: + +- Row-population PR (42 Phase 1 rows, all `Cardinality × Transform + × ` — single-element `cells` list per row). +- `coverage.rs` conversion from list-non-empty projection to per-row + union over `emission_path_projections`. +- The row-count parity ratchet activates load-bearing at that + point (no longer vacuous). + +## Authority audit receipt + +1. **Substrate exists?** No — `EmissionPathProjection` / + `EmissionCell` / `MethodTemplateContractKey` / + `cross_target_coverage.dag` do not exist at HEAD (verified by + the routing receipt's `rg`). `MethodTemplateContract` exists + in `src/v3/std/emit_model.dag`; this slice does not touch it. +2. **Existing brief?** The routing-decision receipt at + `docs/briefs/r3-substrate-l6-per-row-projection-routing-decision.md` + selected Option 2 and STOPped on §4.A–§4.D. This brief is the + post-ratification authoring dispatch; the routing receipt + remains the carrier-shape authority. +3. **Design-doc match?** The §4.A–§4.D recommendations in the + routing receipt align with my surfaced (a)/List/(i)/(b) slate + and Director's ratification of same. The carrier sketch in §1 + above mirrors the routing receipt §2 Option 2 sketch 1:1. +4. **Citations live?** Routing receipt verified at HEAD by + wait-window scan (2026-05-05). `coverage.rs` TODO + walker + shape verified at HEAD per the routing receipt's §1 + restatement. +5. **Carrier dissolves the bridge?** Yes — `EmissionPathProjection` + carries the per-row projection fact as a typed row-local field, + eliminating the list-non-empty proxy in `coverage.rs`. + `MethodTemplateContractKey { target, dag_method }` provides 1:1 + row-identity for the source-row join; no string-name dispatch. + The C1 orthogonality guarantee is honored (zero changes to + `MethodTemplateContract` authoring rows). + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per parent +session #828 instruction (parallel-author posture); routing +receipt authored by archived predecessor tidy-tern-769 (#1288); +Director ratification arrived via cross-Mgr relay +#issuecomment-4377533390. Ratification pending host restoration +and parent dispatch slot allocation. diff --git a/docs/briefs/r3-t-e-p-producer-broadening-worker.md b/docs/briefs/r3-t-e-p-producer-broadening-worker.md new file mode 100644 index 00000000000..0ab26406787 --- /dev/null +++ b/docs/briefs/r3-t-e-p-producer-broadening-worker.md @@ -0,0 +1,193 @@ +--- +status: draft (wait-window; parallel-author posture per Director #issuecomment-4377264483; non-Evaluator-gated lane carve-out per docs/r3-structure.md) +authority parent: R3 Substrate Manager (#1739) +ratification: Director ratified lane at gunbc#828 #issuecomment-4362742638 (2026-05-02); R3 critical-path locked +roadmap row: ROADMAP.md "Substrate carrier port program (scopes the substrate dissolution path half of the honesty pass)" — Lane E-P (acceptance: cost/complexity lenses consume the side table + v2-oracle-vs-v3 cementing) +authority docs: + - docs/r3-structure.md:37 (lane definition; M-L sized; Substrate Mgr ownership; foundational) + - docs/r3-structure.md:155-165 (table row + critical-path placement) + - docs/r3-structure.md:163 (critical path: T-E-P-Producer-Broadening → T-Lens-Behavioral-Parity → T-Lens-Application-Surface → T-Workflow-As-Data + T-Lens-Self-Application) + - docs/r3-structure.md:295,446 (non-Evaluator-gated; parallel-dispatchable) + - docs/design-cost-lens-sizevar-dimension-wiring.md §391, §463, §504 + - docs/design-complexity-lens-behavioral-completeness.md §272, §282, §342, §598, §673, §684 +gates: + - e_p_per_call_descent_evidence_full_coverage + - e_p_call_pattern_lookup_authoritative + - e_p_sub_value_relation_per_call_landed +--- + +# R3 T-E-P-Producer-Broadening — full `ExprCall.descent_evidence` parity at live call sites + +## Context + +Lane E-P landed a first slice as +`v3_compiler::dag::per_call_descent_evidence` +(`src/v3/compiler/src/dag.rs:1384`) covering recursive self-call + +arithmetic-descent only. Unproven edges fail closed to +`SubValueRelation::SubValueUnknown`; `TransformNode` stays +unwidened. The remainder of the per-call producer surface — full +parity with v2's `ExprCall.descent_evidence` +(`src/v2/00_core.dag:199`) — has not landed. + +Cost and complexity lens behavioral parity (T-Lens-Behavioral-Parity) +gates on this lane: the `v3-lens-capability-register.md` audit +classifies `cost.dag` as PROXY and `complexity.dag` as PROXY because +neither lens consumes the per-call side table at the granularity v2 +produces. Ratchet receipts in `dag.rs:1187` (`CallPattern` 🟡 +SCAFFOLD) and `dag.rs:1268` (`SubValueRelation` 🟡 SCAFFOLD) name +the dissolution shape: full producer coverage + lens consumption. + +T-E-P-Producer-Broadening is **foundational** per `r3-structure.md:37`: +critical-path upstream of the entire R3 lens chain. Non-Evaluator-gated +(parallel-dispatchable per `:295,446`); the worker can dispatch +during R3 wait windows independent of R2-Evaluator close. + +## Slice + +This is M-L sized per the lane row; deliver across one PR or a +small staged set of PRs as the consumer-cementing surface dictates. +Worker should align to the three named gates structurally. + +### Phase 1 — Producer surface broadening (gate `e_p_per_call_descent_evidence_full_coverage`) + +1. Catalog every live call site in v3 lowered Dags where v2's + `ExprCall.descent_evidence` populates a `SubValueRelation` other + than `SubValueUnknown`. Use v2 oracle traces over the + verification-corpus programs as the ground truth. +2. For each call-site class outside the current first-slice + coverage (recursive self-call + arithmetic descent), extend + `per_call_descent_evidence(dag: &Dag)` to populate the + corresponding `SubValueRelation` variants. Reference variants + live at `dag.rs:1275-1294` (full enum). +3. Where a call-site class needs a new `CallPattern` variant beyond + today's nine (`dag.rs:1195-1225`), the addition follows + substrate-fact-introduction procedure (`INVARIANTS.md#p1-modeling-faithfulness` + procedure) — a P1 receipt in the PR body, not silent variant growth. +4. Worker keeps `TransformNode` unwidened. The producer is a + side-table; widening the node to inline call-pattern facts is + out of scope and would re-violate the audit's "off-substrate + side-table" framing. + +### Phase 2 — `CallPattern` lookup authority (gate `e_p_call_pattern_lookup_authoritative`) + +1. The lowering function `lower_call_pattern` at `dag.rs:1318` is + the routing authority from `CallPattern` to `LoweringTarget`. + Confirm consumers (cost/complexity lens, induction.dag witness + construction) reach call-pattern facts through this routing, + not by re-scanning the Dag. +2. If any consumer re-scans (string-match on operator names, + arithmetic-shape detection in lens code, etc.), migrate to the + side-table lookup. Per `feedback_parallel_representation_debt`, + parallel call-pattern derivation paths are debt. +3. Cementing test: per-call-pattern v2-oracle equivalence on the + verification corpus programs (every `ExprCall` site produces + the same `CallPattern` classification under v2 and v3). + +### Phase 3 — `SubValueRelation` consumer wiring (gate `e_p_sub_value_relation_per_call_landed`) + +1. Wire `cost.dag` to consume the per-call descent-evidence side + table for `CostBound` derivation. Design-doc spec: + `docs/design-cost-lens-sizevar-dimension-wiring.md` §391 + (consumer wiring), §463 (lens-side projection), §504 (cementing + shape). +2. Wire `complexity.dag` to consume the same side table for + work/span/asymptotic-class derivation. Design-doc spec: + `docs/design-complexity-lens-behavioral-completeness.md` §272, + §282, §342, §598, §673, §684 (per-call-class behavioral + completeness obligations). +3. Per-lens v2-oracle cementing test: same source program, same + `CostBound` / asymptotic classification under v2 and v3 lens + execution. Per-lens test discipline lives under + T-Tests-As-Data-Completeness's `lens_cementing_test_discipline_complete` + gate; this lane lands the cementing tests for cost + complexity + specifically. + +## Acceptance + +- `e_p_per_call_descent_evidence_full_coverage`: every v2-classified + `ExprCall.descent_evidence` populates an equivalent + `CallDescentEvidence` row in v3; `SubValueUnknown` rate matches v2's + unproven-edge rate exactly (no v3 regressions, no v3 fabrications). +- `e_p_call_pattern_lookup_authoritative`: `lower_call_pattern` is + the only route from call site to `LoweringTarget`; no parallel + call-pattern derivation in lens or consumer code. +- `e_p_sub_value_relation_per_call_landed`: cost + complexity lens + consume the side table; per-lens v2-oracle cementing tests green. +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile diagnostic + ratchet at 0. +- `cargo clippy --all-targets -- -D warnings` clean. +- `cargo fmt --all --check` clean. +- ROADMAP "Substrate carrier port program" Lane E-P row updates from + Partial → Retired (or to a narrower residual if any per-call class + legitimately defers; the residual row names exactly which classes + and why). +- `docs/v3-lens-capability-register.md` re-classifies cost + + complexity lenses from PROXY to (at least) PARTIAL with named + remaining work, or to BEHAVIORALLY COMPLETE if this lane's + consumer wiring closes the register's named blockers. + +## STOP-AND-ESCALATE + +- **A new `CallPattern` variant requires modeling discipline review.** + Adding a variant beyond the current nine is a substrate-fact + introduction; STOP and follow `INVARIANTS.md` P1 procedure + (DAG-ancestor / coproduct-vs-coordinate / primitive-vs-lens-extensible). + Do not silently grow the enum. +- **A consumer's existing call-pattern derivation cannot migrate + cleanly to side-table lookup** (e.g., the consumer needs a + call-pattern fact for a site the producer cannot yet classify): + STOP — the producer side and consumer side are coupled and the + lane's structural completeness is at issue. Surface to R3 + Substrate Manager (#1739). +- **v2-oracle and v3 producer disagree on a verification-corpus + call site** at cementing time: the disagreement is the bug. + Track to root cause; do not bridge with a fail-open default. +- **R2-Evaluator landing changes the consumer surface mid-lane:** + R2-Evaluator is a parallel program (per `r3-structure.md:444-448` + carve-out, this lane operates outside the R2-Evaluator-gated + cluster). If R2-Evaluator's landing reshapes lens execution in a + way that invalidates Phase 3 consumer wiring, surface to Director + for re-sequencing rather than chasing the moving target. + +## Authority audit receipt + +1. **Substrate exists?** Partial. `per_call_descent_evidence` lives + at `dag.rs:1384`; `CallPattern` (9 variants, 🟡 SCAFFOLD) at + `:1195`; `SubValueRelation` (variants 🟡 SCAFFOLD) at `:1275`; + `lower_call_pattern` at `:1318`. This lane broadens producer + coverage and wires consumers; carrier types are already landed. + No new top-level carrier introduced (variant additions follow + P1 procedure if needed per Phase 1 step 3). +2. **Existing brief?** None for this lane specifically. The + originally-named E-P lane sits inside the substrate carrier + port program (ROADMAP row); T-E-P-Producer-Broadening is the + 2026-05-02 R3 expansion of that lane to full producer parity + + consumer wiring. +3. **Design-doc match?** `docs/design-cost-lens-sizevar-dimension-wiring.md` + §391/§463/§504 + `docs/design-complexity-lens-behavioral-completeness.md` + §272/§282/§342/§598/§673/§684 specify the consumer wiring + shape exactly. Worker re-reads each cited section before Phase 3 + authoring; if the design-doc recommendation has shifted post-cite + (commit drift), re-frame Phase 3 to match. +4. **Citations live?** `dag.rs:1187, 1195, 1268, 1275, 1296, 1318, + 1384` and `00_core.dag:199` verified at HEAD via wait-window + grep (2026-05-05). Worker re-verifies at dispatch time. +5. **Carrier dissolves the bridge?** Yes — the dissolution sentence + in the audit is "cost/complexity lenses consume the side table, + plus a v2-oracle-vs-v3 cementing test." Phase 1 produces the + side table to full parity; Phase 2 ensures the lookup is the + authoritative routing; Phase 3 wires the lens consumers. The + PROXY classification on cost/complexity lenses lifts as the + side-table consumption replaces today's reduced-shape derivation. + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per parent +session #828 instruction (parallel-author posture for non-Evaluator-gated +lanes); replaces the earlier "Decision 2 follow-on" framing per +Director correction at #issuecomment-4377501646 (2026-05-05). +The "Decision 2" label was Director-side context-loss; lane is +**standalone foundational substrate-completion work** per +`r3-structure.md:37`. Ratification pending host restoration and +parent dispatch slot allocation. From e1b78bfd8b91438cb444d232e16afd23b6dc21dd Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 04:48:19 -0400 Subject: [PATCH 05/52] WIP: R3 Substrate --- ...-s1-transform-dispatch-substrate-worker.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md index c42f0d26496..8603a9ca98a 100644 --- a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md +++ b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md @@ -162,9 +162,11 @@ Per `x1b-evaluator-impact-audit.md` §5 STOP conditions: 1. **Substrate exists?** No — `TransformDispatch` is the new carrier this slice introduces; today's `TransformNode` carries - `target: TransformTarget` (`src/v3/compiler/src/dag.rs:1695-1712`) - + `inputs: Vec`. No existing carrier dissolves the HO - field-call gap. + `target: TransformTarget` + `inputs: Vec`. Live anchors + at the time of this brief authoring (re-verify at dispatch): + `pub enum TransformTarget` at `src/v3/compiler/src/dag.rs:1874`; + `pub struct TransformNode` at `:1900`. No existing carrier + dissolves the HO field-call gap. 2. **Existing brief?** This brief is the X1.b S1 worker dispatch. Authority docs: design-prereq-x-ho-field-call.md (§Prereq-X1 / §L1.b) is the design authority; x1b-evaluator-impact-audit.md @@ -175,10 +177,15 @@ Per `x1b-evaluator-impact-audit.md` §5 STOP conditions: `resolve_arrow_port`, builders, and `input_ports()` listed here. The audit's S1 spec at §4 matches the design-doc recommendation 1:1. -4. **Citations live?** `src/v3/compiler/src/dag.rs:1695-1712` - (`TransformTarget` enum + `TransformNode` struct) verified at - HEAD via design-doc cite (worker re-verifies at S1 start since - line numbers may drift). +4. **Citations live?** `src/v3/compiler/src/dag.rs:1874` + (`pub enum TransformTarget`) and `:1900` (`pub struct + TransformNode`) verified at HEAD by direct grep on this brief's + authoring tree (post-cursor-review fix; the pre-fix range + `:1695-1712` was wrong — that's the `ordinal_param_label` / + `BindNode` side-table region). Worker re-verifies at S1 start + since line numbers will continue to drift; cite by symbol + (`pub enum TransformTarget` / `pub struct TransformNode`) + alongside the line number to make drift recoverable. 5. **Carrier dissolves the bridge?** Yes — `TransformDispatch` collapses `target` and `inputs` into a single typed sum; `input_ports()` is the single dependency-walk authority, From 215f08b59587cd4c61707b7183cf83b3b774780b Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 04:57:12 -0400 Subject: [PATCH 06/52] WIP: R3 Substrate --- ...oduct-1-openai-chat-message-full-worker.md | 162 ++++++++++++++++ ...thropic-tool-result-content-wire-worker.md | 173 ++++++++++++++++++ ...-anthropic-messages-200-residual-worker.md | 169 +++++++++++++++++ 3 files changed, 504 insertions(+) create mode 100644 docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md create mode 100644 docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md create mode 100644 docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md diff --git a/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md b/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md new file mode 100644 index 00000000000..07460344cf0 --- /dev/null +++ b/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md @@ -0,0 +1,162 @@ +--- +status: draft (wait-window; awaits R3 host restoration before dispatch; operator-bridge expected to ship to PR #1782) +authority parent: R3 Substrate Manager (#1739) +ratification: Director (#828) ratified slate (1) + (2) + (3a) at #issuecomment-4377776495 (2026-05-05) over candidates surfaced at #828 #issuecomment-4377521226 +roadmap row: ROADMAP.md "`openai_chat_message_full_coproduct`" (P1 / Grounding services) +sibling briefs: + - r3-coproduct-2-anthropic-tool-result-content-wire-worker.md + - r3-coproduct-3-anthropic-messages-200-residual-worker.md +--- + +# R3 Coproduct slice 1 — OpenAI chat message full coproduct + +## Context + +`dsl/extdeps/llm/openai.dag:97-100` declares the narrow modeled +shape `OpenAiChatMessage { role, content: String }` with +`OpenAiChatMessageRole = System | Developer | User | Assistant` +(`:94`). The structural-coverage-gap row at `:198` carries the +closure tag: + +``` +closure:openai_chat_message_full_coproduct|OpenAiChatMessage|missing:tool_role_with_tool_call_id|missing:function_role|missing:multimodal_content_array +``` + +Three named missing variants: + +1. **Tool role with `tool_call_id`** — Chat Completions tool + messages carry both a `role: "tool"` discriminator and a + `tool_call_id` field; today's narrow row cannot express either. +2. **Function role** — pre-tool-API function-call messages still + on the wire surface; not modeled. +3. **Multimodal content array** — `content` widens from string to + an array of typed parts (text / image / etc.); today's row + forces `content: String`. + +ROADMAP P1 names this row "`openai_chat_message_full_coproduct`" +under Grounding services. Adjacent `CoproductWireContract` +pattern: not yet declared on the OpenAI side +(`dsl/extdeps/llm/openai.dag` does not import +`std.serialization::CoproductWireContract`); the equivalent rows +on the Anthropic side live at `dsl/extdeps/llm/anthropic.dag:20-30`. + +## Slice + +1. Extend `OpenAiChatMessageRole` with `Tool` and `Function` + variants. The narrow text-message subset retains + `System | Developer | User | Assistant`; the full coproduct + adds the two missing wire roles. +2. Widen `OpenAiChatMessage` to a coproduct that expresses the + three missing variants: + + ```dag + type OpenAiChatMessageContent + = OpenAiChatMessageText { text: String } + | OpenAiChatMessageParts { parts: List } + + type OpenAiChatMessagePart + = OpenAiChatMessageTextPart { text: String } + | OpenAiChatMessageImageUrlPart { image_url: OpenAiChatMessageImageUrl } + // additive parts (audio, file, ...) gap-carried separately if not + // observed in current wire surface + + type OpenAiChatMessage + = OpenAiChatMessageUser { role: OpenAiChatMessageRole, content: OpenAiChatMessageContent } + | OpenAiChatMessageAssistant { role: OpenAiChatMessageRole, content: OpenAiChatMessageContent, tool_calls: List? } + | OpenAiChatMessageTool { role: OpenAiChatMessageRole, content: OpenAiChatMessageContent, tool_call_id: String } + | OpenAiChatMessageFunction { role: OpenAiChatMessageRole, content: OpenAiChatMessageContent, name: String } + ``` + + Concrete variant shapes are sketches; worker grounds against + the OpenAI Chat Completions API reference at brief authoring + time and preserves whatever discriminator structure rustc / + serde can ratify at the wire layer. +3. Author `openai_chat_message_wire_contract: CoproductWireContract` + in the same file, mirroring the Anthropic pattern at + `anthropic.dag:20-23` (internally-tagged-object on `role`, + case-stripped variant name). Add `import std.serialization { + CoproductWireContract, VariantEncoding }` if not already + present. +4. Wire ratchets in `src/v2/tests/src/pipeline.rs` (or the + current test surface — re-verify at dispatch) covering the + three new variants. The existing pattern is named + `openai_chat_message_role_wire_matches_llm_snake_contract` / + `openai_chat_message_row_json_matches_chat_completions_wire_tags` + (cited at `openai.dag:90-92`); new ratchets follow that shape. +5. Retire the closure tag at `openai.dag:198` once the structural + surface lands. The `structural_coverage_gap_openai_chat_message_full_api_surface` + row either deletes (full closure) or narrows to remaining + gap-carried subshapes (e.g., audio parts not on the modeled + wire surface). + +## Acceptance + +- `OpenAiChatMessage` expresses all three missing variants with + typed fields. +- `OpenAiChatMessageRole` includes `Tool` and `Function`. +- `openai_chat_message_wire_contract` exists and emits expected + serde attributes for the new variants. +- Wire ratchets land covering all variants; existing + text-message-row ratchets remain green. +- Closure tag at `openai.dag:198` retires (or narrows with named + residual sub-shapes). +- ROADMAP row "`openai_chat_message_full_coproduct`" flips Open → + Retired with PR sha and dissolution shape. +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile diagnostic + ratchet at 0. +- `cargo clippy --all-targets -- -D warnings` clean. + +## STOP-AND-ESCALATE + +- **OpenAI API discriminator structure has shifted** since the + closure tag was authored (e.g., new variants merged or + consolidated). Worker grounds against the live API reference; + if the closure-tag's three named missing variants are not the + full set on the wire today, surface to R3 Substrate Manager — + the row needs re-scoping, not silent expansion. +- **`CoproductWireContract` cannot express OpenAI's variant + discriminator** (e.g., the role tag and content shape jointly + determine the variant in a way the contract types don't + cover). STOP — this is a substrate-fact-introduction event for + `std.serialization` and routes through P1 procedure + (`INVARIANTS.md#p1-modeling-faithfulness`). +- **Existing text-message-only consumers break under the + coproduct widening.** Per the row's narrow-text-row receipt at + `openai.dag:90-92`, the narrow row is 🟢 TERMINAL for a + modeled subset; widening must preserve text-only callers' + read paths. If consumer breakage cannot be avoided, surface — + the slice may need to introduce the full coproduct in + parallel rather than in place. + +## Authority audit receipt + +1. **Substrate exists?** Partial. `OpenAiChatMessage` / + `OpenAiChatMessageRole` exist as a narrow text-only modeled + subset (`openai.dag:94, 97-100`); the closure-tag at `:198` + names exactly which variants the narrow row excludes. +2. **Existing brief?** None. The structural-coverage-gap row at + `:198` is the live tracking authority. +3. **Design-doc match?** No design-doc; OpenAI Chat Completions + API reference + the closure tag's variant enumeration are + the authority. +4. **Citations live?** `openai.dag:90-92, 94, 97-100, 198` verified + at HEAD via wait-window grep (2026-05-05). Worker re-verifies + at dispatch. Cite by symbol name (`OpenAiChatMessage`, + `OpenAiChatMessageRole`, `structural_coverage_gap_openai_chat_message_full_api_surface`) + alongside line number to make drift recoverable. +5. **Carrier dissolves the bridge?** Yes — the closure tag's + `closure:openai_chat_message_full_coproduct|...` shape names + the typed-coproduct dissolution exactly; this slice authors + that coproduct and the wire-contract row, retiring the closure + tag. + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per Director +ratification at #issuecomment-4377776495 of the slate (1) + (2) + +(3a) surfaced at #828 #issuecomment-4377521226. Honest disclosure +per Director's note: this slate is fresh-authoring per path (a), +not recovery of original "3 newly-routed coproduct slices" intent +(unrecoverable from session memory). Operator-bridge expected to +ship this brief to PR #1782 alongside the existing seven briefs. diff --git a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md new file mode 100644 index 00000000000..437e31e9fc7 --- /dev/null +++ b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md @@ -0,0 +1,173 @@ +--- +status: draft (wait-window; awaits R3 host restoration before dispatch; operator-bridge expected to ship to PR #1782) +authority parent: R3 Substrate Manager (#1739) +ratification: Director (#828) ratified slate (1) + (2) + (3a) at #issuecomment-4377776495 (2026-05-05) +roadmap row: ROADMAP.md "`anthropic_tool_result_full_content_surface`" (P1 / Grounding services) +sibling briefs: + - r3-coproduct-1-openai-chat-message-full-worker.md + - r3-coproduct-3-anthropic-messages-200-residual-worker.md +--- + +# R3 Coproduct slice 2 — Anthropic tool_result content wire shape + +## Context + +`dsl/extdeps/llm/anthropic.dag:204` carries +`structural_coverage_gap_anthropic_tool_result_content_wire_shape` +plus the closely-coupled +`structural_coverage_gap_anthropic_tool_result_additive_blocks` +at `:67`. The receipt at `:204` reads: + +``` +closure:rest_request_wire_serde_alignment|llm.Anthropic.Messages|AnthropicUserContentBlock.UserToolResultBlock.content|residue:tool_result_content_must_serialize_scalar_text_or_content_block_array|trigger:emitted serde for AnthropicToolResultContent serializes ToolResultText as scalar string and ToolResultBlocks as content block array +``` + +Today's `AnthropicToolResultContent` (`anthropic.dag:62-65`) reads: + +```dag +type AnthropicToolResultContent + = ToolResultText { text: String } + | ToolResultBlocks { blocks: List } +``` + +Two coupled gaps: + +1. **Wire-serialization shape (this row, `:204`)** — the wire + serializes `ToolResultText` as a scalar string but + `ToolResultBlocks` as a content-block array. The current + `CoproductWireContract` rows at `:20-30` cover the outer + request coproducts (`AnthropicChatMessage`, + `AnthropicUserContentBlock`, + `AnthropicAssistantContentBlock`); they don't cover the + scalar-vs-array dispatch on `tool_result.content`. +2. **Additive missing variants (subsumed row, `:67`)** — + `ToolResultBlocks.blocks` is `List` but the + closure tag names three missing variants: + `missing:document | missing:search_result | missing:tool_reference`. + +ROADMAP P1 names the broader row "`anthropic_tool_result_full_content_surface`" +under Grounding services. This slice retires both gaps in one +PR (Director-ratified subsumption per +#issuecomment-4377776495). + +Adjacent `CoproductWireContract` pattern: `anthropic.dag:20-30` +(three live wire contracts using `InternallyTaggedObject` with +`StripPrefixSuffixAndSnakeCase`). + +## Slice + +1. **Wire-shape sub-slice.** Author a `CoproductWireContract` for + `AnthropicToolResultContent` capturing the scalar-vs-array + dispatch. The existing pattern (`InternallyTaggedObject`) + does not fit because `ToolResultText` serializes as a bare + scalar, not a tagged object. This requires either: + - Extending `std.serialization::VariantEncoding` with a new + dispatch shape (e.g., `UntaggedScalarOrTagged` or similar + — naming open). This is a P1 substrate-fact-introduction + event; brief STOPs at this point and surfaces to R3 + Substrate Manager for procedure. + - OR using an existing `VariantEncoding` shape that already + covers this dispatch — worker greps `std/serialization.dag` + at dispatch for current variant set and confirms. + + **Sub-slice STOP**: if no existing `VariantEncoding` covers + the dispatch, the wire-shape sub-slice cannot land without a + prior P1 procedure on `std.serialization`. Surface; do not + silently invent a new `VariantEncoding` variant in this + brief's scope. + +2. **Additive-blocks sub-slice.** Extend `ContentBlock` (worker + greps for live declaration at dispatch — current + `AnthropicToolResultContent.ToolResultBlocks.blocks` + consumes it) with the three named missing variants: + `Document | SearchResult | ToolReference`. Concrete payload + shapes ground against the Anthropic Messages API reference; + the closure tag at `:67` names the missing variants but not + their payloads — worker authors payloads from the API spec. + +3. **Wire ratchets.** Wire-emission tests on the v2 Rust + emitter for `AnthropicToolResultContent` covering both + scalar-text and block-array shapes; per-variant emission + tests for the three new `ContentBlock` variants. Existing + pattern lives in `src/v2/tests/src/pipeline.rs` (re-verify + surface at dispatch). + +4. **Closure-tag retirement.** Both + `structural_coverage_gap_anthropic_tool_result_content_wire_shape` + (`:204`) and + `structural_coverage_gap_anthropic_tool_result_additive_blocks` + (`:67`) retire when the slice lands. The + `rest_request_wire_serde_alignment_receipt` at `:194-198` + gains a `paid:tool_result_content_scalar_or_block_array` + row (or equivalent named-paid row) reflecting closure. + +## Acceptance + +- `AnthropicToolResultContent` wire serialization is captured + by a `CoproductWireContract` row (or equivalent + substrate-fact-introduction-ratified shape) covering the + scalar-vs-array dispatch. +- `ContentBlock` includes `Document | SearchResult | ToolReference` + with typed payloads. +- Wire ratchets cover both shapes + the three new variants. +- Both closure tags at `:67` and `:204` retire. +- `rest_request_wire_serde_alignment_receipt` at `:194-198` gains + the named-paid receipt row. +- ROADMAP row "`anthropic_tool_result_full_content_surface`" + flips Open → Retired with PR sha and dissolution shape. +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile diagnostic + ratchet at 0. +- `cargo clippy --all-targets -- -D warnings` clean. + +## STOP-AND-ESCALATE + +- **No existing `VariantEncoding` covers scalar-vs-tagged-array + dispatch.** Surface — this is the named P1 substrate-fact- + introduction event and routes through procedure, not silent + variant-set growth. +- **Anthropic API has shifted on tool_result content shape** + since the closure tags were authored. Re-scope the slice; do + not bridge with stale variant lists. +- **`ContentBlock` is consumed by sites outside `tool_result`** + whose typed expectations are violated by the additive + variants. The wait-window grep verified `ContentBlock` is + shared (it appears in `AnthropicToolResultContent.ToolResultBlocks` + and likely elsewhere — worker enumerates consumers at + dispatch via `src/v3/DOWNSTREAM_REQUIREMENTS.md` per + `feedback_enumerate_before_substrate`). If consumer breakage + is unavoidable, surface to R3 Substrate Manager. +- **Sub-slice 1 + 2 cannot land atomically.** If wire-shape work + blocks on P1 procedure but additive-blocks work is independent, + Director may authorize splitting; surface for that decision — + do not unilaterally split the brief. + +## Authority audit receipt + +1. **Substrate exists?** Partial. `AnthropicToolResultContent` + exists with two variants (`anthropic.dag:62-65`); `ContentBlock` + exists (consumed at `:65`). Wire dispatch shape NOT captured; + three additive `ContentBlock` variants NOT modeled. +2. **Existing brief?** None for this row directly. Adjacent + `rest_request_wire_serde_alignment_receipt` at `:194-198` + tracks the broader REST-wire authority migration. +3. **Design-doc match?** No design-doc; Anthropic Messages API + reference + the closure tags' variant enumerations are the + authority. +4. **Citations live?** `anthropic.dag:20-30, 62-65, 67, 194-198, + 204` verified at HEAD via wait-window grep (2026-05-05). + Worker re-verifies at dispatch with symbol-grep alongside + line numbers. +5. **Carrier dissolves the bridge?** Yes — both closure tags + name the typed-structural dissolution exactly; sub-slice 1 + authors the wire-contract row (or surfaces the P1 event), + sub-slice 2 authors the additive `ContentBlock` variants, + together retiring both gap rows. + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per +Director ratification at #issuecomment-4377776495. Director's +ratification note explicitly subsumed the `:67` additive-blocks +row into this slice rather than splitting them; honoring that +shape. Operator-bridge expected to ship this brief to PR #1782. diff --git a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md new file mode 100644 index 00000000000..ad82c1b43f4 --- /dev/null +++ b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md @@ -0,0 +1,169 @@ +--- +status: draft (wait-window; awaits R3 host restoration before dispatch; operator-bridge expected to ship to PR #1782) +authority parent: R3 Substrate Manager (#1739) +ratification: Director (#828) ratified slate (1) + (2) + (3a) at #issuecomment-4377776495 (2026-05-05) +roadmap row: ROADMAP.md tracked-debt rows under "Tracked debts -- 2026-04 analyses" — `anthropic_messages_200_residual` (Grounding services / response-fidelity) +sibling briefs: + - r3-coproduct-1-openai-chat-message-full-worker.md + - r3-coproduct-2-anthropic-tool-result-content-wire-worker.md +--- + +# R3 Coproduct slice 3 — Anthropic Messages 200 residual + +## Context + +`dsl/extdeps/llm/anthropic.dag:188` carries +`structural_coverage_gap_anthropic_messages_200_residual` with +closure tag: + +``` +closure:anthropic_messages_200_residual|AnthropicMessages200Body|json_pending:container|AnthropicMessages200TextBlock|variant_pending:thinking|variant_pending:tool_use|variant_pending:redacted_thinking|variant_pending:web_search|variant_pending:server_tool_use|trigger:content block coproduct plus container-management response surface +``` + +Two coupled gaps: + +1. **`AnthropicMessages200Body.container: Json?`** — the response + body's `container` field is currently typed as opaque `Json?`, + delaying the typed surface for container-management response + data. Closure tag names this as `json_pending:container`. +2. **`AnthropicMessages200TextBlock` content-block coproduct** — + the modeled response carries a flat list of + `AnthropicMessages200TextBlock`; five additional content-block + variants are wire-present but not modeled: + `thinking | tool_use | redacted_thinking | web_search | + server_tool_use`. + +This row is response-side; pairs with sibling slice 2's +request-side tool_result coverage on the same Anthropic Messages +module surface (Director's "LLM-coherence" rationale at +ratification time). + +## Slice + +1. **Content-block coproduct sub-slice.** Replace + `AnthropicMessages200TextBlock` (or the carrier of which it + is a singleton variant) with a coproduct expressing the five + missing variants: + + ```dag + type AnthropicMessages200ContentBlock + = MessagesText { text: String } + | MessagesThinking { thinking: String, signature: String } // sketch + | MessagesToolUse { id: String, name: String, input: Json } // sketch + | MessagesRedactedThinking { data: String } // sketch + | MessagesWebSearch { ... } // sketch + | MessagesServerToolUse { ... } // sketch + ``` + + Concrete variant payloads ground against the Anthropic + Messages API reference at brief authoring time. The closure + tag names variants but not payloads; worker reads the API + spec for each. + +2. **Container typed surface sub-slice.** Replace `container: + Json?` with a typed coproduct expressing the modeled + container-management response shape. Pre-flight obligation: + read the Anthropic Messages API reference for what + `container` carries when present. If the API spec leaves + `container` open-ended (i.e., it really is opaque from the + client's standpoint), STOP — `Json?` may be correct and the + `json_pending:container` closure should narrow rather than + retire. + +3. **Wire-contract row.** Mirror the request-side pattern at + `anthropic.dag:20-30`: `anthropic_messages_200_content_block_wire_contract: + CoproductWireContract` with `InternallyTaggedObject` on `type` + and case-stripped variant naming. The existing + `rest_request_wire_serde_alignment_receipt` shape at `:194-198` + gains a `paid:messages_200_content_block_internally_tagged_object` + row (or equivalent). + +4. **Wire ratchets.** Per-variant 200-body deserialization tests + covering the five new content-block variants and the typed + container shape. Existing pattern is the + `openai_chat_message_role_wire_matches_llm_snake_contract` + shape; new ratchets follow that lockdown form for the + response side. + +5. **Closure-tag retirement.** The closure tag at `:188` + retires (full closure) or narrows (if `container` legitimately + stays `Json?` per sub-slice 2 STOP). On full closure, the row + deletes; on narrow, the closure tag rewrites to name only the + remaining gap-carried variants/fields. + +## Acceptance + +- `AnthropicMessages200ContentBlock` (or equivalent renaming) + expresses all five missing variants with typed payloads. +- `AnthropicMessages200Body.container` is typed (or the closure + tag narrows with explicit "stays opaque per API spec" residual). +- Wire-contract row authored; receipt row added at + `rest_request_wire_serde_alignment_receipt`. +- Wire ratchets cover all variants + container shape; existing + text-block ratchets remain green. +- Closure tag at `:188` retires or narrows with named residual. +- ROADMAP `anthropic_messages_200_residual` row updates per the + retirement / narrowing outcome. +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile diagnostic + ratchet at 0. +- `cargo clippy --all-targets -- -D warnings` clean. + +## STOP-AND-ESCALATE + +- **Anthropic API has shifted on response content-block variants** + since the closure tag was authored. Worker grounds against the + live API reference; if the closure-tag's five named missing + variants are not the full set on the wire today, surface — the + row needs re-scoping, not silent expansion. +- **`container` field is opaque by API design.** If the Anthropic + spec confirms `container` carries client-opaque data, narrow the + closure tag rather than fabricating a typed surface. + Substrate-fact-introduction discipline applies: a typed surface + must reflect the API's actual shape, not aspirational shape. +- **Existing text-only consumers of `AnthropicMessages200TextBlock` + break under the rename / coproduct widening.** Per slice 1's + STOP rule on OpenAI text-message consumers, surface if breakage + is unavoidable; the slice may need to introduce the full + coproduct in parallel rather than in place. +- **`thinking` / `tool_use` content variants overlap with + request-side carriers** (e.g., `AnthropicAssistantContentBlock` + already has `AssistantTextBlock` / `AssistantToolUseBlock` per + the wait-window scan of `:25-29`). If response-side and + request-side variants are in fact the same coproduct shape, + sharing the type may be honest; surface for the design call — + do not silently merge or duplicate. + +## Authority audit receipt + +1. **Substrate exists?** Partial. Modeled response carriers + exist (`AnthropicMessages200Body`, + `AnthropicMessages200TextBlock`); five content-block variants + not modeled; `container` typed as `Json?` placeholder. +2. **Existing brief?** None for this row directly. Adjacent rows: + `rest_request_wire_serde_alignment_receipt` (paid at `:194-198`), + sibling slice 2's `anthropic_tool_result_content_wire_shape` + (`:204`). +3. **Design-doc match?** No design-doc; Anthropic Messages API + reference + the closure tag's variant enumeration are the + authority. +4. **Citations live?** `anthropic.dag:188, 194-198` verified at + HEAD via wait-window grep (2026-05-05); worker re-verifies at + dispatch with symbol-grep alongside line numbers. +5. **Carrier dissolves the bridge?** Yes for the variant-set + sub-slice — closure tag's + `closure:anthropic_messages_200_residual|...variant_pending:...` + shape names the typed-coproduct dissolution exactly. Container + sub-slice may narrow rather than retire if the API spec + confirms client-opaque shape. + +## Provenance + +Drafted during R3 host-block wait window (2026-05-05) per +Director ratification at #issuecomment-4377776495. Selected over +candidate (3c) `github_pull_review_response_residual` for +LLM-thematic coherence with sibling slices 1 and 2. Honest +disclosure per Director's note: this slate is fresh-authoring +per path (a), not recovery of original "3 newly-routed coproduct +slices" intent. Operator-bridge expected to ship this brief to +PR #1782. From 6ec6ca500123d701b05eb2cdf16eee02b979c99f Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 05:19:44 -0400 Subject: [PATCH 07/52] WIP: R3 Substrate --- ...integration-rs-scan-char-literal-worker.md | 109 ++++++++++++------ ...thropic-tool-result-content-wire-worker.md | 109 ++++++++++++++---- ...-anthropic-messages-200-residual-worker.md | 97 ++++++++++++++-- 3 files changed, 247 insertions(+), 68 deletions(-) diff --git a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md index 0ff6e30c702..4aaaad97af5 100644 --- a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md +++ b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md @@ -74,48 +74,81 @@ mirror `rustc_lexer::Cursor::single_quoted_string` semantics, NOT a naive byte heuristic. **Worker pre-flight obligation (Path B):** read -`rustc_lexer/src/lib.rs` `single_quoted_string` (or the live -equivalent in the rustc tree at the worker's pin) and reproduce +`rustc_lexer/src/lib.rs` `Cursor::lifetime_or_char` (the actual +disambiguator entry point — NOT `single_quoted_string`, which is +the body-consumer that runs after disambiguation) and reproduce its disambiguation logic faithfully. Cite the upstream source SHA in the PR body. Naive lookback heuristics (e.g., "previous byte is not identifier-continuation") are explicitly rejected per the BLOCKING finding on the prior brief revision — they misclassify `&'a T` and `'label: loop` as char openers. +`lifetime_or_char` decides between lifetime and char-literal by +peeking the next two characters (after the opening `'`): +- if char1 is a non-identifier-start byte, OR +- if char1 is an identifier byte AND char2 is `'` (closing quote) + with char1 being a single-character literal, +- OR if the body matches `\'` (escape pattern + closing + quote within bounded window), +then it's a char literal; otherwise lifetime. + +Path B's byte-oriented scan reproduces these branches exactly, +not a quote-search approximation. + Sketch of the lexer-faithful rule: 1. Add a fifth state `Char` to `IntegrationRsScan` in `src/v3/compiler/tests/integration/common/mod.rs:138-200`. -2. Wire the `Code` → `Char` transition via **bounded forward - lookahead**, NOT previous-byte lookback. A previous-byte rule - misclassifies `&'a T` (byte before `'` is `&`, not an identifier - byte) and `'label: loop { ... }` (byte before `'` is whitespace - or `{`) as char-literal openers — both are lifetimes / labels. - Concretely: when the scanner sees `'` in `Code`, peek forward - up to 16 bytes (the longest valid char-literal body - `'\u{10FFFF}'` is ~10 bytes between quotes; 16 is the - defensive ceiling) for a closing `'`, honoring `\` as an - escape (the byte after `\` is consumed as part of the escape - without acting as a closing quote). - - **Closing `'` found within the window** → enter `Char` - (consume from the opening `'` through the closing `'` - inclusive); resume `Code`. - - **No closing `'` within the window** → the opening `'` was - a lifetime / label start, not a char-literal opener; stay - in `Code`, advance past the `'` only, and let the - identifier-continuation bytes after it be scanned in `Code` - normally. - This is fail-closed by construction: lifetimes / labels do not - carry closing `'`, so they never enter `Char`; char literals - always carry closing `'` within the bounded window, so they - always enter `Char`. No false-`Char` on lifetime / label syntax. -3. The bounded-lookahead recognizer in step 2 already handles - `\`-escape skipping inside the `Char` body. The scanner enters - `Char` only after the closing `'` is confirmed reachable, so - the body is consumed in a single pass without state drift. - Numeric / hex / unicode escapes inside the body do not require - byte-level decoding — only escape-skip is required for - closing-quote correctness. +2. Wire the `Code` → `Char` transition via **branch-based + disambiguation mirroring `Cursor::lifetime_or_char`**, NOT + bounded-quote-search. A quote-search rule (peek N bytes for + a closing `'`) silently misclassifies adjacent lifetimes: + in `<'a, 'b>` the second `'b` quote sits inside any + reasonable lookahead window from the first `'`, so a + quote-search rule classifies `a, '` as a `Char` body and + silently violates P3 fail-closed. The same trap fires for + `for<'a, 'b>`, `&'a 'b ()`, and label-then-char shapes when + the second token's `'` falls inside the window. The rule + below avoids the trap by branching on the FIRST byte after + `'`, never on a far-away closing quote. + - **Sees `'` at position p in `Code`.** Peek `char1` = byte + at p+1. + - **Branch 1: `char1` is `\` (escape).** Consume the escape + sequence per rustc rules (`\` or `\x..` / + `\u{...}`), then assert the following byte is `'`. If yes + → enter `Char` and emit the closed range `[p, close]`; + if no → malformed input (in `tests/integration.rs` this + is a syntax error and the scan can panic per existing + `IntegrationRsScan` discipline). + - **Branch 2: `char1` is an identifier-start byte + (`[A-Za-z_]`).** Peek `char2` = byte at p+2. + - If `char2 == '` → char literal (`'a'` shape). Enter + `Char` for the closed range `[p, p+2]`. + - **Otherwise → lifetime / label.** Stay in `Code`, + advance past `'` only. The identifier-continue bytes + after `'` resume normal `Code` scanning. Critically, + this branch fires regardless of what later bytes look + like — `'a, 'b>` correctly stays in `Code` because + `char2 = ','`, not `'`. The second `'b` is processed + independently when the scanner reaches it. + - **Branch 3: `char1` is any other byte (non-`\`, + non-identifier-start) — e.g., space, digit, punctuation, + non-ASCII.** Treat as a single-byte char-literal body: + assert byte at p+2 is `'`; if yes → `Char` for `[p, p+2]`; + if no → malformed (panic / surface). + The three branches together reproduce `lifetime_or_char`'s + decision exactly. **No window scan, no closing-quote search.** + Lifetimes followed by other lifetimes within any distance + stay in `Code` because Branch 2's `char2 != '` test fires + immediately, before the second `'` is ever inspected. +3. Within the closed `Char` range determined by step 2, no + further escape-skipping is needed — the range was already + chosen with escapes consumed. The body is structurally + bounded: at most 1 byte (Branch 2/3 simple-char) or the + `\` length (Branch 1). Numeric / hex / unicode + escapes inside the `\` form do not require byte- + level decoding for the scanner — only the escape-skip in + Branch 1 is required for closing-quote correctness. 4. Update the `Code`-state raw / byte-string opener probe so it does not fire when the apparent opener is inside `Char`. (With state #5 in place, this is automatic — the probe lives in `Code` only.) @@ -152,9 +185,15 @@ must satisfy: char-literal bodies (the original workaround-attractor pattern); (b) `&'a T` lifetime in reference position stays code (Path A: not classified as literal-skip; Path B: stays in `Code`); - (c) `'label: loop { ... }` label form stays code (same). - All green. The lifetime + label tests are the BLOCKING-finding - regression cases — not optional. + (c) `'label: loop { ... }` label form stays code (same); + (d) **adjacent lifetimes** `for<'a, 'b>` and `Fn() -> &'a 'b ()` + stay code — multiple consecutive `'` tokens never enter + `Char`; (e) **adjacent label-then-char** `'l: loop { let c = 'x'; + break 'l; }` correctly disambiguates the inner `'x'` as `Char` + while the outer `'l` lifetimes stay `Code`. Tests (a)-(e) are + the BLOCKING-finding regression cases — not optional. Path A + inherits rustc's disambiguation by construction; Path B's + byte-oriented scan must pass tests (a)-(e) explicitly. - `cargo test --workspace --exclude v2-compiler-tests` green. - `cargo test -p v2-compiler-tests` green. - `cargo clippy --all-targets -- -D warnings` clean. diff --git a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md index 437e31e9fc7..c0c10a19b19 100644 --- a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md +++ b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md @@ -2,7 +2,7 @@ status: draft (wait-window; awaits R3 host restoration before dispatch; operator-bridge expected to ship to PR #1782) authority parent: R3 Substrate Manager (#1739) ratification: Director (#828) ratified slate (1) + (2) + (3a) at #issuecomment-4377776495 (2026-05-05) -roadmap row: ROADMAP.md "`anthropic_tool_result_full_content_surface`" (P1 / Grounding services) +roadmap row: ROADMAP.md "LLM service flattening" (`:393`) — names `structural_coverage_gap_anthropic_tool_result_content_wire_shape` and `structural_coverage_gap_anthropic_tool_result_additive_blocks` as the live tracking rows. The previously-cited `anthropic_tool_result_full_content_surface` row is **RESOLVED 2026-05-03** (ROADMAP `:344`); this slice does NOT reopen it. Open work lives on the two named gap rows only. sibling briefs: - r3-coproduct-1-openai-chat-message-full-worker.md - r3-coproduct-3-anthropic-messages-200-residual-worker.md @@ -45,9 +45,15 @@ Two coupled gaps: closure tag names three missing variants: `missing:document | missing:search_result | missing:tool_reference`. -ROADMAP P1 names the broader row "`anthropic_tool_result_full_content_surface`" -under Grounding services. This slice retires both gaps in one -PR (Director-ratified subsumption per +The previously-tracked broader row +`anthropic_tool_result_full_content_surface` is **RESOLVED +2026-05-03** per ROADMAP `:344` — the receipt row was already +deleted; this slice does NOT reopen it. The two open gap rows +named above (`structural_coverage_gap_anthropic_tool_result_content_wire_shape` +at `:204` and `structural_coverage_gap_anthropic_tool_result_additive_blocks` +at `:67`) are tracked under ROADMAP `:393` "LLM service flattening" +as residue from the 2026-05-03 closure. This slice retires both +gap rows in one PR (Director-ratified subsumption per #issuecomment-4377776495). Adjacent `CoproductWireContract` pattern: `anthropic.dag:20-30` @@ -76,21 +82,53 @@ Adjacent `CoproductWireContract` pattern: `anthropic.dag:20-30` silently invent a new `VariantEncoding` variant in this brief's scope. -2. **Additive-blocks sub-slice.** Extend `ContentBlock` (worker - greps for live declaration at dispatch — current - `AnthropicToolResultContent.ToolResultBlocks.blocks` - consumes it) with the three named missing variants: - `Document | SearchResult | ToolReference`. Concrete payload - shapes ground against the Anthropic Messages API reference; - the closure tag at `:67` names the missing variants but not - their payloads — worker authors payloads from the API spec. +2. **Additive-blocks sub-slice.** `ContentBlock` lives at + `dsl/extdeps/llm/llm.dag:41` as a **shared LLM primitive** + (cross-provider — both Anthropic and OpenAI consume it). + Extending it directly with `Document | SearchResult | + ToolReference` would pollute the shared shape with + Anthropic-specific variants. Per `INVARIANTS.md` P2 (single + authority / boundary discipline) and the codex BLOCKING + finding on the prior brief revision (sha 215f08b5), the + correct shape is an **Anthropic-specific nested block + carrier** that wraps shared `ContentBlock` for the cross- + provider variants and adds the Anthropic-only variants: + + ```dag + // Anthropic-specific tool-result block; layered atop shared + // ContentBlock for cross-provider variants (text/image) and + // adds Anthropic-only nested block kinds. Lives in + // dsl/extdeps/llm/anthropic.dag, NOT dsl/extdeps/llm/llm.dag. + type AnthropicToolResultBlock + = AnthropicSharedBlock { block: ContentBlock } // delegates to shared primitive + | AnthropicDocumentBlock { ... } // Anthropic-only + | AnthropicSearchResultBlock { ... } // Anthropic-only + | AnthropicToolReferenceBlock { ... } // Anthropic-only + ``` + + Then `AnthropicToolResultContent.ToolResultBlocks` switches + from `blocks: List` to `blocks: + List`. Cross-provider variants + reach through the `AnthropicSharedBlock` delegate; the + shared primitive stays uncontaminated. Worker re-verifies + at dispatch that `ContentBlock` is in fact cross-provider + (the wait-window grep confirmed `dsl/extdeps/llm/llm.dag:41` + is the home and `src/v3/std/anthropic_schema.dag:59` is a + separate Anthropic-internal `ContentBlock`-named type — if + those have converged or diverged further, surface). + Concrete payload shapes for the Anthropic-only variants + ground against the Anthropic Messages API reference. 3. **Wire ratchets.** Wire-emission tests on the v2 Rust emitter for `AnthropicToolResultContent` covering both scalar-text and block-array shapes; per-variant emission - tests for the three new `ContentBlock` variants. Existing - pattern lives in `src/v2/tests/src/pipeline.rs` (re-verify - surface at dispatch). + tests for the four `AnthropicToolResultBlock` variants + (`AnthropicSharedBlock` delegate + `AnthropicDocumentBlock` + + `AnthropicSearchResultBlock` + `AnthropicToolReferenceBlock`). + Shared `dsl/extdeps/llm/llm.dag::ContentBlock` is **not** + re-tested here — it stays unchanged. Existing pattern lives + in `src/v2/tests/src/pipeline.rs` (re-verify surface at + dispatch). 4. **Closure-tag retirement.** Both `structural_coverage_gap_anthropic_tool_result_content_wire_shape` @@ -107,14 +145,26 @@ Adjacent `CoproductWireContract` pattern: `anthropic.dag:20-30` by a `CoproductWireContract` row (or equivalent substrate-fact-introduction-ratified shape) covering the scalar-vs-array dispatch. -- `ContentBlock` includes `Document | SearchResult | ToolReference` - with typed payloads. +- New `AnthropicToolResultBlock` carrier includes + `AnthropicSharedBlock` (delegating to shared `ContentBlock`) + + `AnthropicDocumentBlock` + `AnthropicSearchResultBlock` + + `AnthropicToolReferenceBlock` with typed payloads. Shared + `dsl/extdeps/llm/llm.dag` `ContentBlock` is **untouched**. + `AnthropicToolResultContent.ToolResultBlocks.blocks` switches + from `List` to `List`. - Wire ratchets cover both shapes + the three new variants. - Both closure tags at `:67` and `:204` retire. - `rest_request_wire_serde_alignment_receipt` at `:194-198` gains the named-paid receipt row. -- ROADMAP row "`anthropic_tool_result_full_content_surface`" - flips Open → Retired with PR sha and dissolution shape. +- The two `structural_coverage_gap_*` rows under + `dsl/extdeps/llm/anthropic.dag` (the closure-tag list + values at `:67` and `:204`) flip from open coverage gaps + to deleted (full closure) or narrowed (with named-residual + closure-tag rewrite). ROADMAP `:393` "LLM service + flattening" residue prose updates to reflect the closure; + the previously-tracked row at ROADMAP `:344` is NOT touched + (already RESOLVED 2026-05-03; this PR is residue cleanup, + not row resurrection). - `cargo test --workspace --exclude v2-compiler-tests` green. - `cargo test -p v2-compiler-tests` green; strict-compile diagnostic ratchet at 0. @@ -145,9 +195,15 @@ Adjacent `CoproductWireContract` pattern: `anthropic.dag:20-30` ## Authority audit receipt 1. **Substrate exists?** Partial. `AnthropicToolResultContent` - exists with two variants (`anthropic.dag:62-65`); `ContentBlock` - exists (consumed at `:65`). Wire dispatch shape NOT captured; - three additive `ContentBlock` variants NOT modeled. + exists with two variants (`anthropic.dag:62-65`); shared + `ContentBlock` (`dsl/extdeps/llm/llm.dag:41`) exists and is + consumed at `:65`. Wire dispatch shape NOT captured; + `AnthropicToolResultBlock` Anthropic-specific carrier and + its three Anthropic-only variants NOT modeled. Per extdeps + layering (provider-specific block types live in provider + modules, not the shared `llm.dag`), this slice authors a + new Anthropic carrier rather than extending the shared + primitive. 2. **Existing brief?** None for this row directly. Adjacent `rest_request_wire_serde_alignment_receipt` at `:194-198` tracks the broader REST-wire authority migration. @@ -161,8 +217,13 @@ Adjacent `CoproductWireContract` pattern: `anthropic.dag:20-30` 5. **Carrier dissolves the bridge?** Yes — both closure tags name the typed-structural dissolution exactly; sub-slice 1 authors the wire-contract row (or surfaces the P1 event), - sub-slice 2 authors the additive `ContentBlock` variants, - together retiring both gap rows. + sub-slice 2 authors the new Anthropic-specific + `AnthropicToolResultBlock` carrier (Anthropic-only variants + in `dsl/extdeps/llm/anthropic.dag`, NOT in shared + `llm.dag`), together retiring both gap rows. Extdeps + layering preserved — shared `ContentBlock` stays cross- + provider; Anthropic-specific block kinds live on the + Anthropic-side carrier. ## Provenance diff --git a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md index ad82c1b43f4..8118307060f 100644 --- a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md +++ b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md @@ -38,12 +38,31 @@ request-side tool_result coverage on the same Anthropic Messages module surface (Director's "LLM-coherence" rationale at ratification time). -## Slice +## Slice — per-token enumeration of the live closure row + +The closure row at `anthropic.dag:188` carries 7 discrete tokens +(re-verified at HEAD as of brief authoring; worker re-verifies at +dispatch since the row may narrow further before S1 starts). Each +token is a discrete acceptance item; the slice closes the row +either by retiring all 7 or by explicitly narrowing the remaining +residual to a named subset: + +| Token in closure | Sub-slice item | Closure shape | +|---|---|---| +| `json_pending:container` | (1) typed container | `AnthropicMessages200Body.container: Json?` → typed coproduct OR explicit "stays opaque per API spec" residual | +| `AnthropicMessages200TextBlock` (carrier) | (2) carrier rename | rename to `AnthropicMessages200ContentBlock` (or equivalent) reflecting it is now a coproduct, not a text-only single-variant | +| `variant_pending:thinking` | (3) `Thinking` variant | typed payload per Anthropic API: `{ thinking: String, signature: String }` (worker re-verifies at API spec) | +| `variant_pending:tool_use` | (4) `ToolUse` variant | typed payload per API: `{ id: String, name: String, input: Json }` (worker re-verifies) | +| `variant_pending:redacted_thinking` | (5) `RedactedThinking` variant | typed payload per API: `{ data: String }` (worker re-verifies) | +| `variant_pending:web_search` | (6) `WebSearch` variant | payload per API (worker re-reads the spec; closure tag does not enumerate fields) | +| `variant_pending:server_tool_use` | (7) `ServerToolUse` variant | payload per API (same — worker re-reads spec) | + +### Slice steps 1. **Content-block coproduct sub-slice.** Replace - `AnthropicMessages200TextBlock` (or the carrier of which it - is a singleton variant) with a coproduct expressing the five - missing variants: + `AnthropicMessages200TextBlock` (today's singleton-variant + carrier) with a coproduct expressing all five missing + variants from items (3)-(7) of the table above: ```dag type AnthropicMessages200ContentBlock @@ -85,11 +104,63 @@ ratification time). shape; new ratchets follow that lockdown form for the response side. -5. **Closure-tag retirement.** The closure tag at `:188` - retires (full closure) or narrows (if `container` legitimately - stays `Json?` per sub-slice 2 STOP). On full closure, the row - deletes; on narrow, the closure tag rewrites to name only the - remaining gap-carried variants/fields. +5. **Reachable-carrier audit (mandatory pre-retirement).** + Before retiring the closure tag, enumerate every carrier + reachable from `AnthropicMessages200Body`. The wait-window + scan identifies these (worker re-verifies at dispatch): + `AnthropicMessages200TextBlock` (current singleton — to be + widened per slice step 1); `AnthropicMessages200Citation` + (`anthropic.dag:141`, consumed via + `AnthropicMessages200TextBlock.citations`); + `AnthropicMessages200Usage` (`:154`, consumed via + `AnthropicMessages200Body.usage`); + `AnthropicStopReason` (`:168`, TERMINAL). + + For each reachable carrier, audit whether any of these + conditions hold; if any does, the **carrier is residue** + that the closure tag at `:188` does not currently + enumerate but which the slice's response-fidelity + obligation reaches: + - **Untyped string-or-json placeholder** for an enum-like + wire field (e.g., `AnthropicMessages200Usage.service_tier: + String?` at `:159` — Anthropic Messages API documents + `service_tier` as an enum-like field, so `String?` may + be untyped placeholder rather than honest residual). + - **Optional Json field** that the API spec encodes with + a typed shape. + - **An additive variant set whose closure isn't tracked + anywhere** (e.g., `AnthropicMessages200Citation` variant + completeness). + + Each such finding either lands in the slice (extending the + carrier with the typed shape / new variants) OR earns a + new explicit closure-tag entry (e.g., `data + structural_coverage_gap_anthropic_messages_200_usage_service_tier`) + that gets its own residue tracking. The worker MUST NOT + retire the parent closure tag at `:188` without resolving + every reachable-carrier residual either by inclusion or by + explicit re-tracking. + +6. **Closure-tag retirement / explicit narrowing.** The + closure tag at `:188` retires when **all 7 items in the + per-token table close AND every reachable-carrier residual + from step 5 is either modeled or explicitly re-tracked.** + If any single item legitimately cannot close (e.g., + `container` stays `Json?` per sub-slice 2 STOP; a + `variant_pending` shape the API spec doesn't yet name + stably; a reachable-carrier residual whose closure shape + needs separate Director sign-off), the closure tag does + NOT retire — instead, it **narrows** by rewriting the + closure string to enumerate only the remaining residual + tokens with explicit per-residual rationale + (`json_pending:container|reason:API spec leaves this field + opaque to clients`, etc.). Per + `feedback_corrections_must_grep_verify_source` the worker + never silently leaves an old token in the closure; each + remaining token earns explicit per-token rationale, and + any newly-discovered reachable-carrier residual gets its + own tracking row rather than being swept under the parent + closure's retirement. ## Acceptance @@ -116,6 +187,14 @@ ratification time). live API reference; if the closure-tag's five named missing variants are not the full set on the wire today, surface — the row needs re-scoping, not silent expansion. +- **Reachable-carrier residual cannot be resolved in this slice's + scope.** If step 5's audit surfaces a residual whose dissolution + shape is genuinely larger than this slice (e.g., the typed + `service_tier` coproduct's variant set requires Anthropic API + reference work the slice can't absorb cleanly), STOP — split + the residual to a new closure-tag entry with explicit re-tracking, + surface the split to R3 Substrate Manager, and narrow the parent + closure rather than retire it. - **`container` field is opaque by API design.** If the Anthropic spec confirms `container` carries client-opaque data, narrow the closure tag rather than fabricating a typed surface. From 259ea066fb82c3443181c8e587f9b4ce6db2a4bf Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 06:16:55 -0400 Subject: [PATCH 08/52] WIP: R3 Substrate --- ...integration-rs-scan-char-literal-worker.md | 39 +++++++------ ...oduct-1-openai-chat-message-full-worker.md | 40 +++++++++++-- ...thropic-tool-result-content-wire-worker.md | 57 +++++++++++++++---- ...-s1-transform-dispatch-substrate-worker.md | 38 ++++++++++++- 4 files changed, 137 insertions(+), 37 deletions(-) diff --git a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md index 4aaaad97af5..17155292dd0 100644 --- a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md +++ b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md @@ -176,11 +176,14 @@ must satisfy: removed (no longer applicable). PR body cites the upstream crate (`rustc_lexer` SHA or `syn` version) used. - **Path B:** Scanner extends to five states; disambiguation rule - cites `rustc_lexer::Cursor::single_quoted_string` (or live - equivalent) at the worker's pinned upstream SHA in the PR - body. No false-`Char` classification on lifetime / label - inputs. Doc comment at `:320-326` reflects the post-extension - behavior. + cites `rustc_lexer::Cursor::lifetime_or_char` (the actual + disambiguator entry point) at the worker's pinned upstream SHA + in the PR body, and reproduces its three-branch logic exactly + (escape branch / identifier-start `char2 == '` branch / + non-identifier-start single-byte branch). No false-`Char` + classification on lifetime / label inputs. No window-scan / no + closing-quote-search heuristics. Doc comment at `:320-326` + reflects the post-extension behavior. - **Both paths** — unit tests land covering: (a) `b'\\'` / `b'"'` char-literal bodies (the original workaround-attractor pattern); (b) `&'a T` lifetime in reference position stays code (Path A: @@ -204,19 +207,19 @@ must satisfy: ## STOP-AND-ESCALATE -- If a real-world `tests/integration.rs`-shaped fragment in the - worker's pre-flight contains a char-literal body legitimately - longer than the 16-byte lookahead window, STOP and surface — - either widen the window with explicit upper-bound justification - or escalate to the structural-reader alternative the row's - dissolution sentence names. -- If a closing `'` lookahead can be ambiguous against an unrelated - later `'` in pathological code (e.g., a lifetime followed soon - after by a char literal on the same line), STOP and verify - against an actual fragment from the integration scan path. The - bounded-lookahead rule is fail-closed for the lifetime case (no - closing `'` ⇒ stay `Code`), but a worker who finds an - adversarial counter-example must surface rather than band-aid. +- **Path B's `lifetime_or_char` reproduction diverges from rustc.** + If the worker's branch-by-branch reproduction does not match + `rustc_lexer::Cursor::lifetime_or_char`'s observable behavior on + the test corpus (a)-(e), STOP — Path B is not lexer-faithful and + must be either corrected or escalated to Path A. No + window-scan / closing-quote-search fallback is authorized. +- **A real `tests/integration.rs` fragment exhibits a char-literal + shape outside `lifetime_or_char`'s decision domain** (e.g., a + Rust feature-gate addition that creates a new lexical category + rustc itself doesn't yet ratify in stable). STOP and surface — + Path A's structural-reader path inherits any rustc lexer update + by construction, while Path B requires manual chase. A divergent + fragment is a Path-A-or-escalate signal, not a band-aid. - Add a unit test that exercises both `&'a T` (lifetime in reference type) and `'label: loop { break 'label; }` (label scope) and asserts both stay in `Code` (no false-`Char`); these diff --git a/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md b/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md index 07460344cf0..7e14cc1773e 100644 --- a/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md +++ b/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md @@ -47,7 +47,16 @@ on the Anthropic side live at `dsl/extdeps/llm/anthropic.dag:20-30`. `System | Developer | User | Assistant`; the full coproduct adds the two missing wire roles. 2. Widen `OpenAiChatMessage` to a coproduct that expresses the - three missing variants: + three missing variants. **Critical layering rule:** the role + discriminator is **variant-determined** — it must NOT live as + a free `role: OpenAiChatMessageRole` field on each variant + (which would make `OpenAiChatMessageTool { role: User, ... }` + structurally representable, an illegal-state-by-construction + violation per `feedback_state_space_vs_behavioral_invariants`). + Either drop the `role` field from the variant payloads + entirely (variant identity ⇒ role) and project it via an + accessor function, OR carry per-variant singleton role tags + keyed by the variant tag itself. ```dag type OpenAiChatMessageContent @@ -60,17 +69,36 @@ on the Anthropic side live at `dsl/extdeps/llm/anthropic.dag:20-30`. // additive parts (audio, file, ...) gap-carried separately if not // observed in current wire surface + // Variant identity determines role; role NOT carried as field. + // Wire serializer emits the role discriminator from variant tag + // via `CoproductWireContract` / role accessor. type OpenAiChatMessage - = OpenAiChatMessageUser { role: OpenAiChatMessageRole, content: OpenAiChatMessageContent } - | OpenAiChatMessageAssistant { role: OpenAiChatMessageRole, content: OpenAiChatMessageContent, tool_calls: List? } - | OpenAiChatMessageTool { role: OpenAiChatMessageRole, content: OpenAiChatMessageContent, tool_call_id: String } - | OpenAiChatMessageFunction { role: OpenAiChatMessageRole, content: OpenAiChatMessageContent, name: String } + = OpenAiChatMessageSystem { content: OpenAiChatMessageContent } + | OpenAiChatMessageDeveloper { content: OpenAiChatMessageContent } + | OpenAiChatMessageUser { content: OpenAiChatMessageContent } + | OpenAiChatMessageAssistant { content: OpenAiChatMessageContent, tool_calls: List? } + | OpenAiChatMessageTool { content: OpenAiChatMessageContent, tool_call_id: String } + | OpenAiChatMessageFunction { content: OpenAiChatMessageContent, name: String } + + // Role projection (variant tag ⇒ role) — accessor, not field. + fn role_of(message: OpenAiChatMessage) -> OpenAiChatMessageRole { + match message { + OpenAiChatMessageSystem { .. } => OpenAiChatMessageRole.System, + OpenAiChatMessageDeveloper { .. } => OpenAiChatMessageRole.Developer, + OpenAiChatMessageUser { .. } => OpenAiChatMessageRole.User, + OpenAiChatMessageAssistant { .. } => OpenAiChatMessageRole.Assistant, + OpenAiChatMessageTool { .. } => OpenAiChatMessageRole.Tool, + OpenAiChatMessageFunction { .. } => OpenAiChatMessageRole.Function, + } + } ``` Concrete variant shapes are sketches; worker grounds against the OpenAI Chat Completions API reference at brief authoring time and preserves whatever discriminator structure rustc / - serde can ratify at the wire layer. + serde can ratify at the wire layer. The variant-determined-role + rule is **not** negotiable — it's the load-bearing invariant + per the codex BLOCKING finding. 3. Author `openai_chat_message_wire_contract: CoproductWireContract` in the same file, mirroring the Anthropic pattern at `anthropic.dag:20-23` (internally-tagged-object on `role`, diff --git a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md index c0c10a19b19..1e8a9a635f6 100644 --- a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md +++ b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md @@ -94,17 +94,52 @@ Adjacent `CoproductWireContract` pattern: `anthropic.dag:20-30` carrier** that wraps shared `ContentBlock` for the cross- provider variants and adds the Anthropic-only variants: - ```dag - // Anthropic-specific tool-result block; layered atop shared - // ContentBlock for cross-provider variants (text/image) and - // adds Anthropic-only nested block kinds. Lives in - // dsl/extdeps/llm/anthropic.dag, NOT dsl/extdeps/llm/llm.dag. - type AnthropicToolResultBlock - = AnthropicSharedBlock { block: ContentBlock } // delegates to shared primitive - | AnthropicDocumentBlock { ... } // Anthropic-only - | AnthropicSearchResultBlock { ... } // Anthropic-only - | AnthropicToolReferenceBlock { ... } // Anthropic-only - ``` +There are two structural shapes here, both honoring the layering +boundary; the worker picks at pre-flight based on which has a +ratified wire-contract path: + +**Shape (A): Direct text/image variants reusing shared payload +facts (preferred when the shared `ContentBlock` payload types are +exposed for re-use).** The Anthropic-specific carrier mirrors +shared `ContentBlock`'s variant payloads inline rather than wrapping +the shared sum. On the wire, every variant is a flat tagged-object +with `type` discriminator — no wrapper layer to make transparent. + +```dag +type AnthropicToolResultBlock + = AnthropicTextBlock { text: String } + | AnthropicImageBlock { source: ImageSource } // ImageSource imported from shared + | AnthropicDocumentBlock { ... } // Anthropic-only + | AnthropicSearchResultBlock { ... } // Anthropic-only + | AnthropicToolReferenceBlock { ... } // Anthropic-only +``` + +**Shape (B): Wrapper-with-transparent-delegation (only valid if +`std.serialization::CoproductWireContract` ratifies a transparent +delegation encoding for the wrapper variant).** The wrapper variant +is `#[serde(transparent)]`-equivalent on the wire — it disappears +in serialization, exposing the inner `ContentBlock`'s tagged-object +shape directly: + +```dag +type AnthropicToolResultBlock + = AnthropicSharedBlock { block: ContentBlock } // wire-transparent delegate + | AnthropicDocumentBlock { ... } + | AnthropicSearchResultBlock { ... } + | AnthropicToolReferenceBlock { ... } +``` + +Shape (B) requires authoring a wire-contract row that names the +transparent-delegation encoding (e.g., a new `VariantEncoding` +shape `TransparentDelegate`). If `std.serialization` does NOT +already ratify such an encoding, this is a P1 substrate-fact- +introduction event and routes through procedure (same STOP as +sub-slice 1's wire-shape sub-slice). + +**Worker pre-flight obligation:** grep `std/serialization.dag` for +any existing transparent-delegation encoding. If found, Shape (B) +is viable; if not, **Shape (A) is mandatory** for this slice (no +silent invention of new `VariantEncoding` shapes). Then `AnthropicToolResultContent.ToolResultBlocks` switches from `blocks: List` to `blocks: diff --git a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md index 8603a9ca98a..da115391af6 100644 --- a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md +++ b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md @@ -35,10 +35,44 @@ mechanical consumer updates. S2 (lowerer produces `Indirect`), S3 (evaluator semantics for `Indirect` / `FieldCall`), and S4 (emitter follow-up) are downstream slices in different ownership. +## Audit authority — confirmed live at HEAD + +The load-bearing audit `docs/briefs/x1b-evaluator-impact-audit.md` +is in tree at HEAD (verified by wait-window scan). Worker MUST +read the audit's §1, §3, §4, §5 in full before authoring code; +key facts inlined below for self-containedness, but the audit +itself remains the authoritative source — if the inline summary +diverges from the audit at dispatch time, the audit wins: + +- **§1 Evaluator consumer catalog (inlined summary):** three + classes of consumers reading `TransformTarget` / `TransformNode.inputs` + directly — E1 host-Rust evaluator (`src/v3/compiler/src/lib.rs::eval_transform_node`); + E2 lens-apply evaluator (`src/v3/compiler/src/lens_apply.rs` + including `eval_transform` / `reflect_transform_target` / + eligibility check); E3 adjacent evaluators that walk + `inputs` only (`dimension.rs`). Worker re-greps these + paths at dispatch. +- **§3 Substrate-adjacent consumer catalog (inlined + summary):** `src/v3/compiler/src/dag.rs` (carrier home), + `dag/builder.rs`, `lower.rs`, `infer.rs`, `emit.rs`, + `emit/rust_target.rs`, `emit/python_target.rs`, + `regen_bootstrap_emit.rs`, generated `lens_*_generated.rs` / + `bootstrap_generated*.rs`. All mechanical updates per slice + step 6 below. +- **§5 STOP conditions (inlined verbatim):** (a) substrate + redesign in flight invalidating §X1.b shape (e.g., + CalleeRef-collapse re-scope); (b) regen / strict-compile + ratchet red at S1 start; (c) reflection mid-migration drift + between `dsl/std/` reflection sum and Rust `TransformDispatch`; + (d) `Vec` cannot retire atomically (some consumer's + rewrite needs a bridge); (e) G0c not merged. + ## Slice -Per `x1b-evaluator-impact-audit.md` §4 Slice S1; not duplicated here. -Worker MUST read that section before authoring code. Summary: +Per audit §4 Slice S1, with steps below mirroring the audit's +ordering. Worker reads the audit's §4 in full before authoring; +the inline summary here serves as a dispatch packet, not a +substitute for the audit. 1. Introduce `TransformDispatch` on `TransformNode` with variants `Callable | FieldProject | FieldCall | Operator | Indirect`. From 69d7a176831583accf8ae5c37c2747bab309f61b Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 07:20:08 -0400 Subject: [PATCH 09/52] WIP: R3 Substrate --- ...integration-rs-scan-char-literal-worker.md | 96 +++++++++++++++---- ...thropic-tool-result-content-wire-worker.md | 51 +++++++--- ...-anthropic-messages-200-residual-worker.md | 19 +++- 3 files changed, 134 insertions(+), 32 deletions(-) diff --git a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md index 17155292dd0..f5e1d4d0ad8 100644 --- a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md +++ b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md @@ -73,15 +73,32 @@ the existing byte-oriented scanner. The disambiguation rule MUST mirror `rustc_lexer::Cursor::single_quoted_string` semantics, NOT a naive byte heuristic. -**Worker pre-flight obligation (Path B):** read -`rustc_lexer/src/lib.rs` `Cursor::lifetime_or_char` (the actual -disambiguator entry point — NOT `single_quoted_string`, which is -the body-consumer that runs after disambiguation) and reproduce -its disambiguation logic faithfully. Cite the upstream source -SHA in the PR body. Naive lookback heuristics (e.g., "previous -byte is not identifier-continuation") are explicitly rejected -per the BLOCKING finding on the prior brief revision — they -misclassify `&'a T` and `'label: loop` as char openers. +**Worker pre-flight obligations (Path B):** + +1. **Read `rustc_lexer/src/lib.rs` `Cursor::lifetime_or_char`** + (the actual disambiguator entry point — NOT + `single_quoted_string`, which is the body-consumer that + runs after disambiguation) and reproduce its disambiguation + logic faithfully. Cite the upstream source SHA in the PR + body. Naive lookback heuristics (e.g., "previous byte is + not identifier-continuation") are explicitly rejected per + the BLOCKING finding on the prior brief revision — they + misclassify `&'a T` and `'label: loop` as char openers. + +2. **Non-ASCII pre-flight scan.** Before Path B can be + selected, scan `tests/integration.rs` and every file in + the integration scan path for non-ASCII bytes (high bit + set). If any non-ASCII byte appears in a position that + could be inside an identifier, lifetime, or char-literal + body — i.e., outside `String` / comment regions — Path B's + byte-oriented branch logic is **out of domain** and Path A + is mandatory. Path B's byte-keyed disambiguation is not + UTF-8-aware; rustc allows Unicode-identifier lifetimes + (`'αβ`) and Unicode-codepoint char literals (`'α'`), and + silent byte-level handling reintroduces the P3 fail-closed + hazard. Pre-flight must record the result in the PR body + ("non-ASCII pre-flight scan: non-ASCII bytes + found in scan path; Path B selected / Path A required"). `lifetime_or_char` decides between lifetime and char-literal by peeking the next two characters (after the opening `'`): @@ -131,11 +148,32 @@ Sketch of the lexer-faithful rule: like — `'a, 'b>` correctly stays in `Code` because `char2 = ','`, not `'`. The second `'b` is processed independently when the scanner reaches it. - - **Branch 3: `char1` is any other byte (non-`\`, - non-identifier-start) — e.g., space, digit, punctuation, - non-ASCII.** Treat as a single-byte char-literal body: - assert byte at p+2 is `'`; if yes → `Char` for `[p, p+2]`; - if no → malformed (panic / surface). + - **Branch 3: `char1` is any other ASCII byte (non-`\`, + non-identifier-start) — e.g., space, digit, punctuation.** + Treat as a single-byte char-literal body: assert byte at + p+2 is `'`; if yes → `Char` for `[p, p+2]`; if no → + malformed (panic / surface). + - **Branch 4: `char1` is non-ASCII (high bit set, i.e., + start of a UTF-8 multi-byte codepoint).** Path B's byte- + oriented scan is **NOT lexer-faithful for Unicode**: + rustc allows Unicode-identifier lifetimes (`'αβ`) AND + Unicode-codepoint char literals (`'α'`), and Branch 3's + byte-counting consumed-bytes-then-look-for-`'` rule is + wrong for both — it treats the first UTF-8 byte as a + single-byte body, then checks the second UTF-8 byte + (which is part of the same codepoint) for a closing `'` + and fails. Path B must NOT silently take this branch; + instead, it MUST surface the non-ASCII byte as an + **out-of-domain signal** and either (a) escalate to + Path A for the file, or (b) the worker decodes the UTF-8 + codepoint and dispatches into Branch 1/2/3 keyed on + codepoint properties (Unicode-identifier-start, etc.). + Option (b) is a substantial extension to byte-oriented + scanning and turns Path B into a partial Unicode lexer; + prefer (a) when the integration scan path actually + contains non-ASCII identifiers (which is uncommon in + `tests/integration.rs` today, but **Path B must verify + this at pre-flight rather than assume it**). The three branches together reproduce `lifetime_or_char`'s decision exactly. **No window scan, no closing-quote search.** Lifetimes followed by other lifetimes within any distance @@ -194,9 +232,25 @@ must satisfy: `Char`; (e) **adjacent label-then-char** `'l: loop { let c = 'x'; break 'l; }` correctly disambiguates the inner `'x'` as `Char` while the outer `'l` lifetimes stay `Code`. Tests (a)-(e) are - the BLOCKING-finding regression cases — not optional. Path A - inherits rustc's disambiguation by construction; Path B's - byte-oriented scan must pass tests (a)-(e) explicitly. + the BLOCKING-finding regression cases — not optional. +- **Unicode regression cases** — (f) Unicode char literal `'α'` + (4 bytes: `'` + 2-byte UTF-8 `α` + `'`) recognized as `Char`; + Path A inherits this from rustc by construction; Path B's + pre-flight obligation (2) MUST escalate to Path A on detection + of the non-ASCII byte. (g) Unicode lifetime `'αβ` (mid-fragment, + e.g., `&'αβ T` where `αβ` is a Unicode XID-continue identifier) + stays in `Code`; same — Path A handles it, Path B must escalate. + (h) **Path B pre-flight escalation receipt** — the pre-flight + scan correctly reports the non-ASCII count and selects Path A + for any fragment containing tests (f)/(g) shapes. Test (h) is + the lockdown for the BLOCKING finding on Branch 4 / non-ASCII + out-of-domain. + + Path A inherits rustc's disambiguation by construction + (including Unicode); Path B's byte-oriented scan must pass + tests (a)-(e) explicitly **on ASCII-only fragments**, and must + pass (f)/(g)/(h) by escalating to Path A — Path B never directly + handles Unicode in this slice. - `cargo test --workspace --exclude v2-compiler-tests` green. - `cargo test -p v2-compiler-tests` green. - `cargo clippy --all-targets -- -D warnings` clean. @@ -213,6 +267,14 @@ must satisfy: the test corpus (a)-(e), STOP — Path B is not lexer-faithful and must be either corrected or escalated to Path A. No window-scan / closing-quote-search fallback is authorized. +- **Non-ASCII byte appears in scan path.** If pre-flight obligation + (2) finds any non-ASCII byte outside `String`/comment regions + in the integration scan path, Path B is **out of domain** — + byte-oriented scan cannot honestly dispatch on Unicode codepoints + (multi-byte UTF-8 sequences would be miscounted as single-byte + char-literal bodies, reintroducing the P3 fail-closed hazard). + Path A is mandatory in that case; do not silently extend Branch 3 + to non-ASCII bytes. - **A real `tests/integration.rs` fragment exhibits a char-literal shape outside `lifetime_or_char`'s decision domain** (e.g., a Rust feature-gate addition that creates a new lexical category diff --git a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md index 1e8a9a635f6..02c7d1ca74e 100644 --- a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md +++ b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md @@ -157,13 +157,23 @@ silent invention of new `VariantEncoding` shapes). 3. **Wire ratchets.** Wire-emission tests on the v2 Rust emitter for `AnthropicToolResultContent` covering both scalar-text and block-array shapes; per-variant emission - tests for the four `AnthropicToolResultBlock` variants - (`AnthropicSharedBlock` delegate + `AnthropicDocumentBlock` - + `AnthropicSearchResultBlock` + `AnthropicToolReferenceBlock`). + tests for every variant of `AnthropicToolResultBlock` as + defined by the picked Shape: + - **Shape (A) variants:** `AnthropicTextBlock` + + `AnthropicImageBlock` + `AnthropicDocumentBlock` + + `AnthropicSearchResultBlock` + `AnthropicToolReferenceBlock`. + Each emits as a flat tagged-object on the wire. + - **Shape (B) variants:** `AnthropicSharedBlock` (transparent + delegate to shared `ContentBlock`) + `AnthropicDocumentBlock` + + `AnthropicSearchResultBlock` + `AnthropicToolReferenceBlock`. + The transparent-delegate variant tests must verify the + wire serialization makes `AnthropicSharedBlock` invisible + (i.e., the wrapped `ContentBlock`'s tagged-object shape + reaches the wire without nesting). Shared `dsl/extdeps/llm/llm.dag::ContentBlock` is **not** - re-tested here — it stays unchanged. Existing pattern lives - in `src/v2/tests/src/pipeline.rs` (re-verify surface at - dispatch). + re-tested here under either shape — it stays unchanged. + Existing pattern lives in `src/v2/tests/src/pipeline.rs` + (re-verify surface at dispatch). 4. **Closure-tag retirement.** Both `structural_coverage_gap_anthropic_tool_result_content_wire_shape` @@ -180,13 +190,28 @@ silent invention of new `VariantEncoding` shapes). by a `CoproductWireContract` row (or equivalent substrate-fact-introduction-ratified shape) covering the scalar-vs-array dispatch. -- New `AnthropicToolResultBlock` carrier includes - `AnthropicSharedBlock` (delegating to shared `ContentBlock`) - + `AnthropicDocumentBlock` + `AnthropicSearchResultBlock` + - `AnthropicToolReferenceBlock` with typed payloads. Shared - `dsl/extdeps/llm/llm.dag` `ContentBlock` is **untouched**. - `AnthropicToolResultContent.ToolResultBlocks.blocks` switches - from `List` to `List`. +- New `AnthropicToolResultBlock` carrier exists in + `dsl/extdeps/llm/anthropic.dag` (NOT in shared `llm.dag`). + Variant set depends on the Shape selected at pre-flight: + - **Shape (A) (mandatory if no transparent-delegation + encoding exists in `std/serialization.dag`):** five + direct variants — `AnthropicTextBlock`, `AnthropicImageBlock`, + `AnthropicDocumentBlock`, `AnthropicSearchResultBlock`, + `AnthropicToolReferenceBlock`. No `AnthropicSharedBlock` + wrapper. Each variant flat-tagged-object on the wire. + - **Shape (B) (only valid when `std/serialization.dag` ratifies + a transparent-delegation `VariantEncoding`):** four variants + — `AnthropicSharedBlock` (transparent delegate to shared + `ContentBlock`) + `AnthropicDocumentBlock` + + `AnthropicSearchResultBlock` + `AnthropicToolReferenceBlock`. + The wrapper variant must serialize transparently — wire + output for an Anthropic text block emits + `{"type":"text","text":"..."}` with NO `AnthropicSharedBlock` + nesting layer. + Shared `dsl/extdeps/llm/llm.dag` `ContentBlock` is **untouched** + under either shape. `AnthropicToolResultContent.ToolResultBlocks.blocks` + switches from `List` to + `List`. - Wire ratchets cover both shapes + the three new variants. - Both closure tags at `:67` and `:204` retire. - `rest_request_wire_serde_alignment_receipt` at `:194-198` gains diff --git a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md index 8118307060f..c7aa64fdad5 100644 --- a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md +++ b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md @@ -40,12 +40,27 @@ ratification time). ## Slice — per-token enumeration of the live closure row +**Important**: this 7-token table enumerates **only the +`structural_coverage_gap_anthropic_messages_200_residual` closure +tag's named tokens at `anthropic.dag:188`**. It does **not** +enumerate the broader response-fidelity reachable-carrier surface +(`AnthropicMessages200Citation` variant completeness; +`AnthropicMessages200Usage.service_tier: String?` / +`cache_creation_input_tokens` / `cache_read_input_tokens` typed +shape; etc.). Those reachable residuals are tracked by the +**Reachable-carrier audit** at §5 below and MUST be resolved +(by inclusion or by explicit re-tracking) before the parent +closure tag at `:188` retires. This table covers what's named +**in** the closure tag; §5 covers what's **reachable from** the +response-fidelity surface but not yet named. + The closure row at `anthropic.dag:188` carries 7 discrete tokens (re-verified at HEAD as of brief authoring; worker re-verifies at dispatch since the row may narrow further before S1 starts). Each token is a discrete acceptance item; the slice closes the row -either by retiring all 7 or by explicitly narrowing the remaining -residual to a named subset: +either by retiring all 7 (AND completing §5's reachable-carrier +audit) or by explicitly narrowing the remaining residual to a +named subset: | Token in closure | Sub-slice item | Closure shape | |---|---|---| From ebb2df18dcf37601f23e08195e1161c132b7a3d1 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 08:11:42 -0400 Subject: [PATCH 10/52] WIP: R3 Substrate --- ...ission-path-projection-substrate-worker.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md index 90822caa003..787bb64fbd4 100644 --- a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -33,6 +33,37 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). 1. Author new file `src/v3/std/cross_target_coverage.dag` containing: + Each new coproduct / sum declaration MUST carry a 🟢/🟡/🔴 + classification annotation per `docs/modeling-discipline.md` + Practice 4 (Step 4 of the type-introduction checklist; + `INVARIANTS.md#p1-modeling-faithfulness` worked example). + The classifications below are pre-determined; worker copies + them verbatim into the live source: + + - `ShapeATarget` → **🟢 TERMINAL** — closed set of three target + languages (Rust / Python / Go). Adding a target is a + substrate-scope event (new emitter, new method-template + contracts), not a row-level addition; the 🟢 mark reflects + that any new variant requires a P1 substrate-fact-introduction + procedure on this declaration directly, not silent extension. + - `FormAxis` → **🟡 SCAFFOLD** — hand-declared mirror of + `v3_compiler::dag::TypeConnective`. Named dissolution trigger: + option (c) substrate-`Disj`-mirroring generator (per Director + ratification of §4.A at #issuecomment-4377533390). Generator + landing retires this hand-declared form. + - `BehaviorAxis` → **🟡 SCAFFOLD** — hand-declared mirror of + `v3_compiler::dag::Behavior`. Same dissolution trigger as + `FormAxis`. + + `MethodTemplateContractKey`, `EmissionCell`, and + `EmissionPathProjection` are records (not coproducts) and do + not require 🟢/🟡/🔴 marks per Practice 4 — the marks attach + to sum-typed declarations whose variant set is the modeling + choice. Worker re-verifies this against + `docs/modeling-discipline.md` Practice 4 at dispatch time; if + the discipline has been extended to require marks on records + too, worker adds matching annotations. + ```dag // Header note (mandatory): option (c) — generated mirror of // v3_compiler::dag::TypeConnective and v3_compiler::dag::Behavior @@ -42,13 +73,23 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). // until that generator lands. Per Director ratification of §4.A // at #issuecomment-4377533390. + /// 🟢 TERMINAL — closed set of v3 target languages. New target + /// addition routes through P1 substrate-fact-introduction + /// procedure on this declaration; row-level addition is not + /// authorized. type ShapeATarget = Rust | Python | Go + /// 🟡 SCAFFOLD — hand-declared mirror of + /// v3_compiler::dag::TypeConnective. Dissolution trigger: + /// substrate-Disj-mirroring generator (option (c)). type FormAxis = ... // mirrors v3_compiler::dag::TypeConnective discriminants (worker // re-reads the live enum at dispatch time and lists the variants // 1:1; new connectives added here only via P1 procedure on the // upstream Rust enum first) + /// 🟡 SCAFFOLD — hand-declared mirror of + /// v3_compiler::dag::Behavior. Dissolution trigger: + /// substrate-Disj-mirroring generator (option (c)). type BehaviorAxis = ... // mirrors v3_compiler::dag::Behavior discriminants (same rule) type MethodTemplateContractKey { From e685b4bdaeae2e62f8b97be82efc6f4ad450eaa3 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 08:16:30 -0400 Subject: [PATCH 11/52] WIP: R3 Substrate --- ...ission-path-projection-substrate-worker.md | 14 +++++- ...-s1-transform-dispatch-substrate-worker.md | 49 +++++++++++++++++++ 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md index 787bb64fbd4..4dca4abb300 100644 --- a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -131,8 +131,20 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). - `src/v3/std/cross_target_coverage.dag` lands with the five types + the empty `data` declaration + the mandatory option-(c) header note. +- **Practice 4 classification receipts on the live declaration + (mandatory).** Each new sum-typed declaration carries an + inline 🟢/🟡/🔴 doc comment per `docs/modeling-discipline.md` + Practice 4 Step 4: `ShapeATarget` → 🟢 TERMINAL; + `FormAxis` → 🟡 SCAFFOLD with named dissolution trigger + (option (c) substrate-`Disj`-mirroring generator); + `BehaviorAxis` → 🟡 SCAFFOLD with same dissolution trigger. + The marks must be present on the `.dag` source in + `cross_target_coverage.dag` itself, not only in the brief or + PR body. The ratchet test (next bullet) verifies the marks + are present. - Ratchet test exists and passes (vacuous parity at this slice; - carrier-shape gates structurally enforced). + carrier-shape gates structurally enforced; **classification + marks present on each new sum-typed declaration**). - `cargo test --workspace --exclude v2-compiler-tests` green. - `cargo test -p v2-compiler-tests` green; strict-compile diagnostic ratchet at 0. diff --git a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md index da115391af6..ef2c2f8398a 100644 --- a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md +++ b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md @@ -77,6 +77,43 @@ substitute for the audit. 1. Introduce `TransformDispatch` on `TransformNode` with variants `Callable | FieldProject | FieldCall | Operator | Indirect`. Module-private payload fields; public accessors only. + + **Practice 4 dissolution-ledger marks (mandatory on the live + declaration).** Per `docs/modeling-discipline.md` Practice 4 + (Step 4 of the type-introduction checklist), each variant of + the new `TransformDispatch` enum MUST carry its 🟢/🟡/🔴 mark + as a doc comment on the variant itself, copying the per-variant + ledger from `design-prereq-x-ho-field-call.md` §Prereq-X1 + (verified live at HEAD `:440-488`). Worker transcribes verbatim: + + - 🟡 `Operator { op: OperatorCall }` — future-dissolve. + Tracking gate: `std/{int,bool,float}/` declares operator- + algebra witness functions + parser desugars operator tokens + to `Call(FunctionRef)` at parse time, collapsing `Operator` + into the unified `Call { callee: CalleeRef = Decl(...) }` + shape. + - 🟢 `FieldProject` — keep. Pure value-access fact preserved + from current `TransformTarget::FieldProject`; no dispatch. + Distinct state family from `FieldCall`. + - 🟡 `Callable` — future-dissolve. Tracking gate: emitter + splits callee-rendering from dispatch match + (`lens_*_emitter_split` shape). Future: `Call { callee: + CalleeRef, args }` with `CalleeRef = Decl(DeclarationId) | + Field { ... } | Port(ArrowPortRef)`. + - 🟡 `FieldCall` — future-dissolve. Same tracking gate as + `Callable`. Future shape: `Call { callee: CalleeRef::Field + { label, child, carrier }, args }`. + - 🟡 `Indirect` — future-dissolve. Same tracking gate as + `Callable`. Future shape: `Call { callee: CalleeRef::Port( + ArrowPortRef), args }`. + + **No 🔴 (dissolve-now) variants** — the design's no-malformed- + state invariants (Facts Flow Forward, illegal-states- + unrepresentable, args-bound-to-target) all hold under the 🟡 + set above; verbatim from the design-doc ledger entry at + `:484-488`. The PR body MUST also carry the dissolution-ledger + summary per the audit's PR-body discipline; the per-variant + doc comments are the in-source receipt that satisfies Practice 4. 2. Add `ArrowPortRef(PortId)` (private constructor) and `Dag::resolve_arrow_port(p: PortId) -> Result`. @@ -141,6 +178,18 @@ fail-closed arms for `FieldCall` and `Indirect`. - Atomic commit: `TransformDispatch` introduced, `target` + `inputs` retired, all consumers updated, generated files regenerated. +- **Practice 4 classification receipts on the live declarations + (mandatory; both Rust and `.dag` sides).** Each variant of the + Rust `TransformDispatch` enum at `src/v3/compiler/src/dag.rs` + carries an inline 🟢/🟡/🔴 doc comment matching the design + ledger at `design-prereq-x-ho-field-call.md:440-488` (verbatim: + 🟡 `Operator`, 🟢 `FieldProject`, 🟡 `Callable`, 🟡 `FieldCall`, + 🟡 `Indirect`; no 🔴). The reflected `dsl/std/` mirror sum + variants carry the same marks (kept in sync per slice §1's + Migrate-reflection-sum step). The marks must be present on + the source in both files, not only in the design doc, brief, + or PR body — per `docs/modeling-discipline.md` Practice 4 + Step 4 the in-source receipt is the load-bearing artifact. - `cargo test --workspace --exclude v2-compiler-tests` green. - `cargo test -p v2-compiler-tests` green; strict-compile diagnostic ratchet (`v2_strict_compile_diagnostic_count -- --ignored`) From 84aebd9094b4f3917ebe4d82f2ebb325db471e4b Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 09:06:50 -0400 Subject: [PATCH 12/52] WIP: R3 Substrate --- ...t-2-anthropic-tool-result-content-wire-worker.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md index 02c7d1ca74e..1a5dcb747b2 100644 --- a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md +++ b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md @@ -143,10 +143,15 @@ silent invention of new `VariantEncoding` shapes). Then `AnthropicToolResultContent.ToolResultBlocks` switches from `blocks: List` to `blocks: - List`. Cross-provider variants - reach through the `AnthropicSharedBlock` delegate; the - shared primitive stays uncontaminated. Worker re-verifies - at dispatch that `ContentBlock` is in fact cross-provider + List` under either Shape. Under + **Shape (A)** the shared primitive stays uncontaminated + because text/image variants are mirrored inline as + `AnthropicTextBlock` / `AnthropicImageBlock` payload- + reusing variants. Under **Shape (B)** cross-provider + variants reach through the `AnthropicSharedBlock` delegate + (only valid when a transparent-delegation encoding is + ratified). Worker re-verifies at dispatch that + `ContentBlock` is in fact cross-provider (the wait-window grep confirmed `dsl/extdeps/llm/llm.dag:41` is the home and `src/v3/std/anthropic_schema.dag:59` is a separate Anthropic-internal `ContentBlock`-named type — if From 38e2c6430e53042640afb066ec84b042098d66aa Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 10:07:10 -0400 Subject: [PATCH 13/52] WIP: R3 Substrate --- ...integration-rs-scan-char-literal-worker.md | 54 ++++++++++----- ...-anthropic-messages-200-residual-worker.md | 67 ++++++++++--------- 2 files changed, 75 insertions(+), 46 deletions(-) diff --git a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md index f5e1d4d0ad8..5edf3b68033 100644 --- a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md +++ b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md @@ -40,19 +40,40 @@ sentence; neither is a STOP-fallback to the other. ### Path A — structural Rust reader (preferred when feasible) Replace the byte-oriented scanner with a structural Rust source -reader that already encodes Rust's lexical grammar: - -- **`rustc_lexer`** (rustc's own lexer crate; thin, no syntax-tree - construction): tokenize `tests/integration.rs` and walk the - token stream skipping `LineComment` / `BlockComment` / - `Literal { kind: Str | RawStr | Byte | ByteStr | RawByteStr | - Char | ByteChar }` tokens. `integration_rs_active_line_contains` - becomes a token-stream filter rather than a hand-coded state - machine. Lifetime-vs-char disambiguation is rustc-faithful by - construction (the crate IS rustc's authority). -- **`syn::parse_file`** (heavier; full AST): parse the file and - walk only `Item` / `ImplItem` text spans for the needle. AST - walk is structurally exact; cost is the AST allocation per scan. +reader that operates at the **token or typed-AST level** — never +at the source-text-span level (which is what `IntegrationRsScan` +does today and what the row's dissolution sentence names as the +attractor to remove). Two sub-options, both structural: + +- **`rustc_lexer` (token-level filter):** tokenize + `tests/integration.rs` once; the resulting token stream has + per-token `TokenKind` discriminators. Walk the stream and + filter to tokens whose kind is in the **Code-token set** + (`Ident` / `OpenBrace` / `CloseBrace` / `Pound` / `Semi` / + whitespace / etc.) — skip every token whose kind is in the + **Skip set** (`LineComment` / `BlockComment` / `Literal { + kind: Str | RawStr | Byte | ByteStr | RawByteStr | Char | + ByteChar }`). `integration_rs_active_line_contains` becomes + "does any Code-set token's text equal the needle on the + same line as the matched-attribute token?" — a filter over + typed token kinds, NOT a source-text-span scan. + Lifetime-vs-char disambiguation is rustc-faithful by + construction. + +- **`syn` typed-AST visitor:** parse the file once via + `syn::parse_file`; walk the AST with a `syn::visit::Visit` + implementation. The visitor extracts **typed facts** from + the AST nodes — e.g., `syn::Item::Mod`'s `ident` for `mod + foo;` declarations, `syn::Attribute::path`'s `Ident`s for + `#[path]` attributes — and produces a `Vec` (or + similar) of structured matches. `integration_rs_active_line_contains` + becomes a check against those typed facts, NOT a substring + scan of source spans. The visitor MUST NOT call + `.span().source_text()` or any equivalent source-span-fetch + API; if it does, the implementation has slipped back into + the very pattern this slice retires. **Acceptance for the + syn path includes a grep that no source-span-fetch is called + in the visitor.** Worker pre-flight verifies which dependency is easier to add to the workspace; if `rustc_lexer` is not already transitively @@ -61,9 +82,10 @@ available and adding it requires a vendored fork, prefer `syn` Path A acceptance: `IntegrationRsScan` deleted entirely; `integration_rs_active_line_contains` reimplemented as a -token-stream / AST-span filter. Doc comment block at `:320-326` -deleted (no longer applicable). Workaround attractor (the -constraint itself) is gone, not just narrowed. +typed-token or typed-AST filter (NOT a source-span scan). Doc +comment block at `:320-326` deleted (no longer applicable). +Workaround attractor (source-span scanning over Rust syntax) is +gone, not just narrowed. ### Path B — scanner extension with rustc-lexer-faithful rule diff --git a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md index c7aa64fdad5..cd40ead1f0a 100644 --- a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md +++ b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md @@ -38,39 +38,46 @@ request-side tool_result coverage on the same Anthropic Messages module surface (Director's "LLM-coherence" rationale at ratification time). -## Slice — per-token enumeration of the live closure row +## Slice — response-fidelity items, first-class enumeration -**Important**: this 7-token table enumerates **only the -`structural_coverage_gap_anthropic_messages_200_residual` closure -tag's named tokens at `anthropic.dag:188`**. It does **not** -enumerate the broader response-fidelity reachable-carrier surface -(`AnthropicMessages200Citation` variant completeness; -`AnthropicMessages200Usage.service_tier: String?` / -`cache_creation_input_tokens` / `cache_read_input_tokens` typed -shape; etc.). Those reachable residuals are tracked by the -**Reachable-carrier audit** at §5 below and MUST be resolved -(by inclusion or by explicit re-tracking) before the parent -closure tag at `:188` retires. This table covers what's named -**in** the closure tag; §5 covers what's **reachable from** the -response-fidelity surface but not yet named. +**Authoritative scope**: every item below is a first-class +acceptance item of this slice. Items (1)-(7) are tokens that +appear literally in +`structural_coverage_gap_anthropic_messages_200_residual`'s +closure tag at `anthropic.dag:188-189` (live HEAD verbatim; +re-verified at brief authoring). Items (8)-(11) are +reachable-carrier residuals on the response-fidelity surface +that the closure tag does NOT name today — but which the slice +treats as first-class items per the codex BLOCKING (sha +84aebd90) routing the slice scope at the response-fidelity +surface, not at the closure-tag surface alone. Worker re- +verifies all items at dispatch (the closure row may narrow, +or new reachable-carrier residuals may surface). -The closure row at `anthropic.dag:188` carries 7 discrete tokens -(re-verified at HEAD as of brief authoring; worker re-verifies at -dispatch since the row may narrow further before S1 starts). Each -token is a discrete acceptance item; the slice closes the row -either by retiring all 7 (AND completing §5's reachable-carrier -audit) or by explicitly narrowing the remaining residual to a -named subset: +The slice closes the row when **all 11 items** close, or +explicitly narrows the closure tag with per-residual rationale +(see §6). Reachable-carrier residuals may also earn their own +new `structural_coverage_gap_*` rows if the dissolution shape +warrants separate tracking. -| Token in closure | Sub-slice item | Closure shape | -|---|---|---| -| `json_pending:container` | (1) typed container | `AnthropicMessages200Body.container: Json?` → typed coproduct OR explicit "stays opaque per API spec" residual | -| `AnthropicMessages200TextBlock` (carrier) | (2) carrier rename | rename to `AnthropicMessages200ContentBlock` (or equivalent) reflecting it is now a coproduct, not a text-only single-variant | -| `variant_pending:thinking` | (3) `Thinking` variant | typed payload per Anthropic API: `{ thinking: String, signature: String }` (worker re-verifies at API spec) | -| `variant_pending:tool_use` | (4) `ToolUse` variant | typed payload per API: `{ id: String, name: String, input: Json }` (worker re-verifies) | -| `variant_pending:redacted_thinking` | (5) `RedactedThinking` variant | typed payload per API: `{ data: String }` (worker re-verifies) | -| `variant_pending:web_search` | (6) `WebSearch` variant | payload per API (worker re-reads the spec; closure tag does not enumerate fields) | -| `variant_pending:server_tool_use` | (7) `ServerToolUse` variant | payload per API (same — worker re-reads spec) | +| # | Source | Sub-slice item | Closure shape | +|---|---|---|---| +| 1 | closure-tag (live `:189`) | typed container | `AnthropicMessages200Body.container: Json?` → typed coproduct OR explicit "stays opaque per API spec" residual | +| 2 | closure-tag (live `:189`) | carrier rename | `AnthropicMessages200TextBlock` rename to `AnthropicMessages200ContentBlock` (or equivalent) reflecting it is now a coproduct, not a text-only single-variant | +| 3 | closure-tag (live `:189`) | `Thinking` variant | typed payload per Anthropic API: `{ thinking: String, signature: String }` (worker re-verifies) | +| 4 | closure-tag (live `:189`) | `ToolUse` variant | typed payload per API: `{ id: String, name: String, input: Json }` (worker re-verifies) | +| 5 | closure-tag (live `:189`) | `RedactedThinking` variant | typed payload per API: `{ data: String }` (worker re-verifies) | +| 6 | closure-tag (live `:189`) | `WebSearch` variant | payload per API (worker re-reads spec) | +| 7 | closure-tag (live `:189`) | `ServerToolUse` variant | payload per API (worker re-reads spec) | +| 8 | reachable carrier (`anthropic.dag:141`) | `AnthropicMessages200Citation` completeness | audit variant set against API spec; if incomplete, extend OR re-track in a new closure row | +| 9 | reachable carrier (`anthropic.dag:159`) | `AnthropicMessages200Usage.service_tier` | `String?` placeholder → typed coproduct (e.g., `Standard | Priority | Batch` per API spec) OR explicit "stays opaque" residual; honest vs aspirational shape per API | +| 10| reachable carrier (`anthropic.dag:157-158`)| `AnthropicMessages200Usage.cache_*` fields | `cache_creation_input_tokens` / `cache_read_input_tokens` are typed `Int?` today; audit completeness vs API and confirm honest vs additive-fields-pending | +| 11| reachable surface (general) | other reachable carrier from `AnthropicMessages200Body` | enumerate at dispatch: any field that is `Json?` / `String?` for an enum-like API field, or any nested type whose variant set has not been audited against the API | + +Items (1)-(7) are taken **verbatim** from the live closure-tag +string at `anthropic.dag:189`; items (8)-(11) are the +reachable-carrier audit elevated to first-class scope per the +codex BLOCKING (sha 84aebd90) finding 2. ### Slice steps From be174453d77a6b0eadd38fcefac0971c8989ab6f Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 11:13:10 -0400 Subject: [PATCH 14/52] WIP: R3 Substrate --- ...integration-rs-scan-char-literal-worker.md | 79 ++++++++++++------- 1 file changed, 50 insertions(+), 29 deletions(-) diff --git a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md index 5edf3b68033..cdea0b3b057 100644 --- a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md +++ b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md @@ -39,41 +39,62 @@ sentence; neither is a STOP-fallback to the other. ### Path A — structural Rust reader (preferred when feasible) -Replace the byte-oriented scanner with a structural Rust source -reader that operates at the **token or typed-AST level** — never -at the source-text-span level (which is what `IntegrationRsScan` -does today and what the row's dissolution sentence names as the -attractor to remove). Two sub-options, both structural: - -- **`rustc_lexer` (token-level filter):** tokenize - `tests/integration.rs` once; the resulting token stream has - per-token `TokenKind` discriminators. Walk the stream and - filter to tokens whose kind is in the **Code-token set** - (`Ident` / `OpenBrace` / `CloseBrace` / `Pound` / `Semi` / - whitespace / etc.) — skip every token whose kind is in the - **Skip set** (`LineComment` / `BlockComment` / `Literal { - kind: Str | RawStr | Byte | ByteStr | RawByteStr | Char | - ByteChar }`). `integration_rs_active_line_contains` becomes - "does any Code-set token's text equal the needle on the - same line as the matched-attribute token?" — a filter over - typed token kinds, NOT a source-text-span scan. - Lifetime-vs-char disambiguation is rustc-faithful by - construction. +**Structural binding fact preserved.** The current +`integration_rs_active_line_contains` is a generic substring +helper, but its load-bearing consumer is +`integration_rs_cementing_path_attr_binds_mod_stem` at +`src/v3/compiler/tests/integration/common/mod.rs:301` — the +structural fact being verified is "`#[path = "integration/cementing/.rs"]` +attribute is immediately followed by `mod ;` declaration." +Path A's typed extractor MUST preserve this binding fact, not +merely report code-token visibility. Concretely: the +replacement must produce typed `(path_attr_literal, mod_ident)` +pairs (or equivalent typed binding-fact representation) so +`integration_rs_cementing_path_attr_binds_mod_stem` can be +re-implemented as a typed predicate over the binding pairs, +not a substring search through filtered tokens. Replace the +byte-oriented scanner with a structural Rust source reader +that operates at the **token or typed-AST level** — never at +the source-text-span level (which is what `IntegrationRsScan` +does today and what the row's dissolution sentence names as +the attractor to remove). Two sub-options, both structural +and both producing the typed binding pairs: + +- **`rustc_lexer` (token-level structural extractor):** + tokenize `tests/integration.rs` once; the resulting token + stream has per-token `TokenKind` discriminators. Walk the + stream with a small state machine that recognizes the + `#[path = ""]` ... `mod ;` pattern in + Code-set tokens (`Pound` / `OpenBracket` / `Ident("path")` / + `Eq` / `Literal { kind: Str }` / `CloseBracket` / `Ident("mod")` / + `Ident()` / `Semi`), skipping `LineComment` / + `BlockComment` / non-string `Literal` tokens. The state + machine emits the same typed binding pairs `(path_attr_literal, + mod_ident)` as the `syn` path. `integration_rs_cementing_path_attr_binds_mod_stem` + is reimplemented as a typed predicate over the binding-pair + list. Lifetime-vs-char disambiguation is rustc-faithful by + construction (the crate IS rustc's authority). - **`syn` typed-AST visitor:** parse the file once via `syn::parse_file`; walk the AST with a `syn::visit::Visit` - implementation. The visitor extracts **typed facts** from - the AST nodes — e.g., `syn::Item::Mod`'s `ident` for `mod - foo;` declarations, `syn::Attribute::path`'s `Ident`s for - `#[path]` attributes — and produces a `Vec` (or - similar) of structured matches. `integration_rs_active_line_contains` - becomes a check against those typed facts, NOT a substring - scan of source spans. The visitor MUST NOT call + implementation. For each `syn::ItemMod`, the visitor + inspects the preceding `#[path = "..."]` attribute (if any) + and emits a typed binding pair `(path_attr_literal: LitStr, + mod_ident: Ident)` capturing the structural fact + "`#[path = LIT]` binds to `mod IDENT`". `integration_rs_cementing_path_attr_binds_mod_stem` + reduces to a typed predicate "is there a binding pair whose + `path_attr_literal` matches the expected + `integration/cementing/.rs` shape AND whose `mod_ident` + matches ``?" The visitor MUST NOT call `.span().source_text()` or any equivalent source-span-fetch API; if it does, the implementation has slipped back into the very pattern this slice retires. **Acceptance for the - syn path includes a grep that no source-span-fetch is called - in the visitor.** + syn path includes (a) a grep that no source-span-fetch is + called in the visitor, AND (b) a regression test asserting + `integration_rs_cementing_path_attr_binds_mod_stem` returns + `true` for the live binding pairs in `tests/integration.rs` + and `false` when either the attribute or the mod decl is + commented out / mismatched.** Worker pre-flight verifies which dependency is easier to add to the workspace; if `rustc_lexer` is not already transitively From bfa3c79898e4912f079845ca2cfcfed1bfc88da0 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 12:13:15 -0400 Subject: [PATCH 15/52] WIP: R3 Substrate --- ...oduct-1-openai-chat-message-full-worker.md | 15 +++++++- ...thropic-tool-result-content-wire-worker.md | 11 ++++++ ...-anthropic-messages-200-residual-worker.md | 34 ++++++++++++------- 3 files changed, 47 insertions(+), 13 deletions(-) diff --git a/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md b/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md index 7e14cc1773e..38854bffa3a 100644 --- a/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md +++ b/docs/briefs/r3-coproduct-1-openai-chat-message-full-worker.md @@ -120,8 +120,21 @@ on the Anthropic side live at `dsl/extdeps/llm/anthropic.dag:20-30`. ## Acceptance - `OpenAiChatMessage` expresses all three missing variants with - typed fields. + typed fields (variant-determined role per the load-bearing + invariant; no `role` field on payloads). - `OpenAiChatMessageRole` includes `Tool` and `Function`. +- **Practice 4 classification receipts on the live declarations + (mandatory).** Per `docs/modeling-discipline.md` Practice 4 + Step 4, every new sum-typed declaration carries an inline + 🟢/🟡/🔴 doc comment. For this slice: `OpenAiChatMessage` + (the widened coproduct) and the new `OpenAiChatMessageContent` + / `OpenAiChatMessagePart` sums all carry classification marks + with named dissolution triggers where 🟡 (e.g., gap-carried + additive parts like audio / file → tracking gate to update on + next API spec extension). The widened `OpenAiChatMessageRole` + also gains a Practice 4 mark if its variant set isn't already + TERMINAL. Marks must be present on the `.dag` source in + `openai.dag` itself, not only in the brief or PR body. - `openai_chat_message_wire_contract` exists and emits expected serde attributes for the new variants. - Wire ratchets land covering all variants; existing diff --git a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md index 1a5dcb747b2..803ebe540f1 100644 --- a/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md +++ b/docs/briefs/r3-coproduct-2-anthropic-tool-result-content-wire-worker.md @@ -195,6 +195,17 @@ silent invention of new `VariantEncoding` shapes). by a `CoproductWireContract` row (or equivalent substrate-fact-introduction-ratified shape) covering the scalar-vs-array dispatch. +- **Practice 4 classification receipts on the live declarations + (mandatory).** Per `docs/modeling-discipline.md` Practice 4 + Step 4, the new `AnthropicToolResultBlock` sum carries an + inline 🟢/🟡/🔴 doc comment with named dissolution trigger + (🟡 SCAFFOLD if more block kinds are gap-carried beyond the + three Anthropic-only variants; 🟢 TERMINAL if the variant set + is closed against current API spec). The existing + `AnthropicToolResultContent` sum's mark is updated if its + variant set changes. Marks must be present on the `.dag` + source in `anthropic.dag` itself, not only in the brief or + PR body. - New `AnthropicToolResultBlock` carrier exists in `dsl/extdeps/llm/anthropic.dag` (NOT in shared `llm.dag`). Variant set depends on the Shape selected at pre-flight: diff --git a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md index cd40ead1f0a..8330cbcdf90 100644 --- a/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md +++ b/docs/briefs/r3-coproduct-3-anthropic-messages-200-residual-worker.md @@ -60,19 +60,19 @@ explicitly narrows the closure tag with per-residual rationale new `structural_coverage_gap_*` rows if the dissolution shape warrants separate tracking. -| # | Source | Sub-slice item | Closure shape | +| # | Live carrier state at HEAD | Action | Closure shape | |---|---|---|---| -| 1 | closure-tag (live `:189`) | typed container | `AnthropicMessages200Body.container: Json?` → typed coproduct OR explicit "stays opaque per API spec" residual | -| 2 | closure-tag (live `:189`) | carrier rename | `AnthropicMessages200TextBlock` rename to `AnthropicMessages200ContentBlock` (or equivalent) reflecting it is now a coproduct, not a text-only single-variant | -| 3 | closure-tag (live `:189`) | `Thinking` variant | typed payload per Anthropic API: `{ thinking: String, signature: String }` (worker re-verifies) | -| 4 | closure-tag (live `:189`) | `ToolUse` variant | typed payload per API: `{ id: String, name: String, input: Json }` (worker re-verifies) | -| 5 | closure-tag (live `:189`) | `RedactedThinking` variant | typed payload per API: `{ data: String }` (worker re-verifies) | -| 6 | closure-tag (live `:189`) | `WebSearch` variant | payload per API (worker re-reads spec) | -| 7 | closure-tag (live `:189`) | `ServerToolUse` variant | payload per API (worker re-reads spec) | -| 8 | reachable carrier (`anthropic.dag:141`) | `AnthropicMessages200Citation` completeness | audit variant set against API spec; if incomplete, extend OR re-track in a new closure row | -| 9 | reachable carrier (`anthropic.dag:159`) | `AnthropicMessages200Usage.service_tier` | `String?` placeholder → typed coproduct (e.g., `Standard | Priority | Batch` per API spec) OR explicit "stays opaque" residual; honest vs aspirational shape per API | -| 10| reachable carrier (`anthropic.dag:157-158`)| `AnthropicMessages200Usage.cache_*` fields | `cache_creation_input_tokens` / `cache_read_input_tokens` are typed `Int?` today; audit completeness vs API and confirm honest vs additive-fields-pending | -| 11| reachable surface (general) | other reachable carrier from `AnthropicMessages200Body` | enumerate at dispatch: any field that is `Json?` / `String?` for an enum-like API field, or any nested type whose variant set has not been audited against the API | +| 1 | **field exists**: `AnthropicMessages200Body.container: Json?` at `anthropic.dag:185` | **modify field type** | `Json?` → typed coproduct OR explicit "stays opaque per API spec" residual | +| 2 | **type exists as record**: `AnthropicMessages200TextBlock` at `:148-152` (`{ type: String, text: String, citations: ... }`) | **rename + reshape from record to coproduct** | Rename to `AnthropicMessages200ContentBlock` (or equivalent) and reshape from a single-variant record to a typed sum spanning the variants below. Existing `text` / `citations` payload becomes the `Text` variant of the new sum. | +| 3 | **variant does NOT exist** in any modeled type today; closure tag names it as gap-pending | **add new variant** to the renamed sum from item (2) | `Thinking` variant: typed payload per Anthropic API: `{ thinking: String, signature: String }` (worker re-verifies) | +| 4 | **variant does NOT exist**; closure tag names it | **add new variant** | `ToolUse` variant: typed payload per API: `{ id: String, name: String, input: Json }` (worker re-verifies) | +| 5 | **variant does NOT exist**; closure tag names it | **add new variant** | `RedactedThinking` variant: typed payload per API: `{ data: String }` (worker re-verifies) | +| 6 | **variant does NOT exist**; closure tag names it | **add new variant** | `WebSearch` variant: payload per API (worker re-reads spec) | +| 7 | **variant does NOT exist**; closure tag names it | **add new variant** | `ServerToolUse` variant: payload per API (worker re-reads spec) | +| 8 | **type exists**: `AnthropicMessages200Citation` at `:141`; consumed via the `Text` variant's `citations` field (post-rename) | **audit variant set; possibly extend or re-track** | If the existing variant set is incomplete vs API spec, extend OR re-track in a new closure row | +| 9 | **field exists**: `AnthropicMessages200Usage.service_tier: String?` at `:159` | **modify field type** OR **explicit re-track** | `String?` placeholder → typed coproduct (e.g., `Standard \| Priority \| Batch` per API spec) OR explicit "stays opaque" residual; honest vs aspirational shape per API | +| 10| **fields exist**: `AnthropicMessages200Usage.cache_creation_input_tokens: Int?` + `cache_read_input_tokens: Int?` at `:157-158` | **audit completeness; no immediate change unless API mismatch** | Confirm honest vs additive-fields-pending against API; flag if shape diverges | +| 11| **dispatch-time enumeration**: any other reachable carrier from `AnthropicMessages200Body` not covered by items 1-10 | **enumerate, then add field/variant OR re-track** | Any field that is `Json?` / `String?` for an enum-like API field, or any nested type whose variant set has not been audited against the API | Items (1)-(7) are taken **verbatim** from the live closure-tag string at `anthropic.dag:189`; items (8)-(11) are the @@ -188,6 +188,16 @@ codex BLOCKING (sha 84aebd90) finding 2. - `AnthropicMessages200ContentBlock` (or equivalent renaming) expresses all five missing variants with typed payloads. +- **Practice 4 classification receipts on the live declarations + (mandatory).** Per `docs/modeling-discipline.md` Practice 4 + Step 4, the renamed `AnthropicMessages200ContentBlock` sum + carries an inline 🟢/🟡/🔴 doc comment with named dissolution + trigger. The new `service_tier` typed coproduct (if added per + item (9)) carries a mark. Existing sums whose variant set + changes (e.g., `AnthropicMessages200Citation` per item (8)) + have their existing marks updated. Marks must be present on + the `.dag` source in `anthropic.dag` itself, not only in the + brief or PR body. - `AnthropicMessages200Body.container` is typed (or the closure tag narrows with explicit "stays opaque per API spec" residual). - Wire-contract row authored; receipt row added at From adc5ed181fcf93e86af3f7e1c2f874fe6a65a912 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 5 May 2026 13:13:20 -0400 Subject: [PATCH 16/52] WIP: R3 Substrate --- .../r3-t-e-p-producer-broadening-worker.md | 63 ++++++++++++++----- 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/docs/briefs/r3-t-e-p-producer-broadening-worker.md b/docs/briefs/r3-t-e-p-producer-broadening-worker.md index 0ab26406787..5dc5a34a82f 100644 --- a/docs/briefs/r3-t-e-p-producer-broadening-worker.md +++ b/docs/briefs/r3-t-e-p-producer-broadening-worker.md @@ -60,7 +60,7 @@ Worker should align to the three named gates structurally. corresponding `SubValueRelation` variants. Reference variants live at `dag.rs:1275-1294` (full enum). 3. Where a call-site class needs a new `CallPattern` variant beyond - today's nine (`dag.rs:1195-1225`), the addition follows + today's eight (`dag.rs:1195-1225`), the addition follows substrate-fact-introduction procedure (`INVARIANTS.md#p1-modeling-faithfulness` procedure) — a P1 receipt in the PR body, not silent variant growth. 4. Worker keeps `TransformNode` unwidened. The producer is a @@ -70,18 +70,45 @@ Worker should align to the three named gates structurally. ### Phase 2 — `CallPattern` lookup authority (gate `e_p_call_pattern_lookup_authoritative`) -1. The lowering function `lower_call_pattern` at `dag.rs:1318` is - the routing authority from `CallPattern` to `LoweringTarget`. - Confirm consumers (cost/complexity lens, induction.dag witness - construction) reach call-pattern facts through this routing, - not by re-scanning the Dag. -2. If any consumer re-scans (string-match on operator names, - arithmetic-shape detection in lens code, etc.), migrate to the - side-table lookup. Per `feedback_parallel_representation_debt`, - parallel call-pattern derivation paths are debt. -3. Cementing test: per-call-pattern v2-oracle equivalence on the - verification corpus programs (every `ExprCall` site produces - the same `CallPattern` classification under v2 and v3). +1. **Authoritative lens-facing surface.** The L-7 single-authority + substrate query for the cost + complexity lenses is + `per_call_pattern_at(d: Dag, call_site: NodeId) -> CallPattern?`, + exposed from `std.computation` per + `docs/design-cost-lens-sizevar-dimension-wiring.md` §3.2 + §8.4 + and `docs/design-complexity-lens-behavioral-completeness.md` + §278 (Director-ratified — single-authority per `INVARIANTS.md` + P2 / L-7). The query wraps the side-table + `v3_compiler::dag::per_call_descent_evidence` and returns + `Option` (`None` for non-recursive call sites, + `Some(pattern)` for recursive ones). The internal lowering + helper `lower_call_pattern` at `dag.rs:1318` routes from + `CallPattern` to `LoweringTarget` for compiler-internal use, + but it is **not** the lens-facing query surface — the lens + path is `per_call_pattern_at` per the design docs. +2. **Land the typed query surface** if it doesn't already exist + on `std.computation`. Worker greps at dispatch — if landed, + use it; if not landed, this Phase covers landing it + (gated on Phase 1 broadening). Co-owned with the cost-lens + producer-consumption gate + (`per_call_pattern_query_surface_landed` per + `design-cost-lens-sizevar-dimension-wiring.md` §493 step 3). +3. **Confirm consumers route through `per_call_pattern_at`.** + Cost lens (`src/v3/lenses/cost.dag`) and complexity lens + (`src/v3/lenses/complexity.dag`) reach call-pattern facts + through `per_call_pattern_at`, NOT by re-scanning the Dag, + NOT through `lower_call_pattern` (which is compiler-internal). + `induction.dag` witness construction and any other consumers + route through the same query. +4. **Migrate any parallel paths.** If any consumer re-scans + (string-match on operator names, arithmetic-shape detection + in lens code, etc.) or reads `per_call_descent_evidence` + storage directly, migrate to `per_call_pattern_at`. Per + `feedback_parallel_representation_debt`, parallel + call-pattern derivation paths are debt. +5. **Cementing test.** Per-call-pattern v2-oracle equivalence on + the verification corpus programs (every `ExprCall` site + produces the same `CallPattern` classification under v2 and + v3 via `per_call_pattern_at`). ### Phase 3 — `SubValueRelation` consumer wiring (gate `e_p_sub_value_relation_per_call_landed`) @@ -130,10 +157,14 @@ Worker should align to the three named gates structurally. ## STOP-AND-ESCALATE - **A new `CallPattern` variant requires modeling discipline review.** - Adding a variant beyond the current nine is a substrate-fact + Adding a variant beyond the current eight is a substrate-fact introduction; STOP and follow `INVARIANTS.md` P1 procedure (DAG-ancestor / coproduct-vs-coordinate / primitive-vs-lens-extensible). - Do not silently grow the enum. + The new variant ALSO inherits the existing `CallPattern` 🟡 + SCAFFOLD classification at `dag.rs:1187` per Practice 4 (Step 4), + with the same dissolution trigger as `SizeBound`. Do not silently + grow the enum past current count without P1 receipt AND + Practice-4 classification confirmation in the PR body. - **A consumer's existing call-pattern derivation cannot migrate cleanly to side-table lookup** (e.g., the consumer needs a call-pattern fact for a site the producer cannot yet classify): @@ -153,7 +184,7 @@ Worker should align to the three named gates structurally. ## Authority audit receipt 1. **Substrate exists?** Partial. `per_call_descent_evidence` lives - at `dag.rs:1384`; `CallPattern` (9 variants, 🟡 SCAFFOLD) at + at `dag.rs:1384`; `CallPattern` (8 variants, 🟡 SCAFFOLD) at `:1195`; `SubValueRelation` (variants 🟡 SCAFFOLD) at `:1275`; `lower_call_pattern` at `:1318`. This lane broadens producer coverage and wires consumers; carrier types are already landed. From e875116f8f298a617d9bdd941eb710e5ef4629dd Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 02:59:28 +0000 Subject: [PATCH 17/52] fix(briefs): retire INVARIANTS.md line-number cites in r3-426 brief MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per codex review on PR #1782 (sha c2512cde): the new briefs introduced fresh `INVARIANTS.md:` citations — the same stale-line-anchor shape the :425 sweep brief itself names as needing dissolution. Replaces four line-number references in r3-426-sfp-subdoc-rename-and-author-worker.md (lines 16, 28, 58, 85) with prose-anchored locators citing the section anchor + bullet text. The other PB-lane briefs codex flagged (r3-pb-runtime-equivalence- corpus-seed-audit.md, r3-pb-t-fixedpoint-worker.md) belong to neat-bear-351's lane and are not in this PR's scope; will route separately. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...426-sfp-subdoc-rename-and-author-worker.md | 55 ++++++++++++------- 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/docs/briefs/r3-426-sfp-subdoc-rename-and-author-worker.md b/docs/briefs/r3-426-sfp-subdoc-rename-and-author-worker.md index 615063c1ec8..3bbcb5611c4 100644 --- a/docs/briefs/r3-426-sfp-subdoc-rename-and-author-worker.md +++ b/docs/briefs/r3-426-sfp-subdoc-rename-and-author-worker.md @@ -13,8 +13,13 @@ supersedes: docs/briefs/r3-426-sfp-subdoc-design-call-surfacing.md (surfacing pa `docs/invariants/strict-forward-progress.md` carries **bounded-execution** content; reviewer usage of the name "Strict Forward Progress" carries the **dissolution-progress** meaning -(see `INVARIANTS.md:314`). `INVARIANTS.md` flags the drift in three -places (`:253`, `:273`, `:315`) as "future cleanup." +(see the **Strict Forward Progress** bullet under +`INVARIANTS.md#p5-progress-is-dissolution` Related rules). +`INVARIANTS.md` flags the drift in three places — the +`> Note on naming.` blockquote and the **Bounded forward execution** +bullet under `INVARIANTS.md#p4-decidability` Related rules, plus +the `*Note:*` sub-bullet beneath the SFP bullet under +`INVARIANTS.md#p5-progress-is-dissolution` — as "future cleanup." Director ratified option (a): **rename + author new**, preserving the SFP name attached to the reviewer-usage meaning. @@ -25,21 +30,25 @@ the SFP name attached to the reviewer-usage meaning. docs/invariants/bounded-forward-execution.md`. Content unchanged. 2. Author a fresh `docs/invariants/strict-forward-progress.md` carrying the dissolution-progress concept. Source the canonical - statement from `INVARIANTS.md:314` ("a change counts as progress - only if it reduces ad-hoc state, duplicate authority, or implicit - behavior; transitional scaffolds need explicit dissolution paths - and cannot become the new steady state"). Cross-link the - bounded-execution subdoc as a sibling concern, not a parent. + statement from the **Strict Forward Progress** bullet under + `INVARIANTS.md#p5-progress-is-dissolution` Related rules + ("a change counts as progress only if it reduces ad-hoc state, + duplicate authority, or implicit behavior; transitional + scaffolds need explicit dissolution paths and cannot become the + new steady state"). Cross-link the bounded-execution subdoc as + a sibling concern, not a parent. 3. Update `INVARIANTS.md`: - - `:253` — rewrite the "Note on naming" block: drop the drift - caveat; redirect the bounded-execution pointer to - `bounded-forward-execution.md`; affirm SFP name now points at - the dissolution-progress subdoc. - - `:273` — rewrite the bounded-forward-execution bullet's - subdoc reference to point at `bounded-forward-execution.md`. - - `:315` — delete the "*Note:*" block (drift caveat) entirely; - SFP bullet's subdoc reference now points at the freshly - authored `strict-forward-progress.md`. + - **`> Note on naming.` blockquote under `#p4-decidability` + Related rules** — rewrite: drop the drift caveat; redirect + the bounded-execution pointer to `bounded-forward-execution.md`; + affirm SFP name now points at the dissolution-progress subdoc. + - **`**Bounded forward execution**` bullet under `#p4-decidability` + Related rules** — rewrite the subdoc reference to point at + `bounded-forward-execution.md`. + - **`*Note:*` sub-bullet beneath the SFP bullet under + `#p5-progress-is-dissolution`** — delete entirely (drift + caveat); SFP bullet's subdoc reference now points at the + freshly authored `strict-forward-progress.md`. 4. `rg "strict-forward-progress\.md"` across the tree; update any reference whose intent was bounded-execution (subdoc content) to `bounded-forward-execution.md`. References whose intent was @@ -55,7 +64,10 @@ the SFP name attached to the reviewer-usage meaning. - Two subdocs exist: `bounded-forward-execution.md` (renamed, content unchanged) + freshly authored `strict-forward-progress.md` (dissolution-progress). -- `INVARIANTS.md:253/273/315` updated; drift caveats removed. +- The three drift sites in `INVARIANTS.md` (the `> Note on naming.` + blockquote and **Bounded forward execution** bullet under + `#p4-decidability`, plus the `*Note:*` sub-bullet under + `#p5-progress-is-dissolution`) updated; drift caveats removed. - `rg "strict-forward-progress\.md"` shows no references with bounded-execution intent. - `cargo fmt --all --check` clean (no Rust changes; defensive). @@ -82,8 +94,13 @@ the SFP name attached to the reviewer-usage meaning. 3. **Design-doc match?** Director's ratification message at `#issuecomment-4377264483` names option (a) with the exact file moves used here. -4. **Citations live?** `INVARIANTS.md:253,273,314,315` verified at - HEAD (2026-05-05). +4. **Citations live?** Four prose sites in `INVARIANTS.md` verified + at HEAD (2026-05-05): `> Note on naming.` blockquote and + **Bounded forward execution** bullet under `#p4-decidability` + Related rules; **Strict Forward Progress** bullet and its + `*Note:*` sub-bullet under `#p5-progress-is-dissolution` + Related rules. Worker re-locates by prose excerpt at dispatch + (anchors stable; line numbers drift). 5. **Carrier dissolves the bridge?** N/A; pure documentation reorganization, not substrate work. From 2072b9861d1a7f45355249dfb5fb892581bdad89 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 03:00:51 +0000 Subject: [PATCH 18/52] fix(briefs): correct L6 type count + r3-435 dual-path retirement receipt Per openai-pro review on PR #1782 (sha c2512cde): 1. L6 brief said acceptance ratchet asserts "five types" exist but declares six (ShapeATarget, FormAxis, BehaviorAxis, MethodTemplateContractKey, EmissionCell, EmissionPathProjection). Updated both occurrences to enumerate all six explicitly. 2. r3-435 brief authorized both Path A (typed-AST reader, deletes IntegrationRsScan) and Path B (scanner widening with Char state), but retirement receipt language only covered Path B. Updated ROADMAP/ledger retirement and authority-audit step 5 to cover both authorized dissolution paths. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...integration-rs-scan-char-literal-worker.md | 21 +++++++++++++------ ...ission-path-projection-substrate-worker.md | 4 ++-- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md index cdea0b3b057..f5d7d0ee3ee 100644 --- a/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md +++ b/docs/briefs/r3-435-integration-rs-scan-char-literal-worker.md @@ -299,8 +299,11 @@ must satisfy: - `cargo clippy --all-targets -- -D warnings` clean. - ROADMAP row flips Open → Retired with PR sha; ledger row 71 in `docs/debt/r3-debt-paydown-ledger-2026-05-02.md` flips Open → - Retired with the dissolution shape ("scanner widened to char - literals; workaround attractor removed"). + Retired with the dissolution shape that matches the path taken: + Path A — "`IntegrationRsScan` retired; replaced by typed-AST + `(LitStr, Ident)` extraction; workaround attractor dissolved"; + Path B — "scanner widened to char literals (Branch 3 byte-state + handling); workaround attractor removed". ## STOP-AND-ESCALATE @@ -343,10 +346,16 @@ must satisfy: 4. **Citations live?** `mod.rs:138, 141, 320-326` verified via wait-window grep at HEAD (2026-05-05). State enum at `:138`, doc comment block at `:320-326`. -5. **Carrier dissolves the bridge?** Yes — adding `Char` state - removes the "byte-constant workaround attractor" the row names; - dissolution sentence in ROADMAP is "widen the scanner to model - Rust char literals." +5. **Carrier dissolves the bridge?** Yes — both authorized paths + dissolve the "byte-constant workaround attractor" the row + names: Path A by retiring `IntegrationRsScan` entirely in favor + of typed-AST `(path_attr_literal: LitStr, mod_ident: Ident)` + extraction; Path B by widening the existing scanner with a + `Char` state. ROADMAP's existing dissolution sentence ("widen + the scanner to model Rust char literals") covers Path B + verbatim and Path A in spirit (typed reader subsumes char- + literal modeling); the retirement receipt names the path + taken. ## Provenance diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md index 4dca4abb300..5a19ebef6b7 100644 --- a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -114,7 +114,7 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). PR populates the 42 Phase 1 rows. 2. Add a small ratchet asserting that: - - The five types and the `data` declaration exist with the + - The six types (`ShapeATarget`, `FormAxis`, `BehaviorAxis`, `MethodTemplateContractKey`, `EmissionCell`, `EmissionPathProjection`) and the `data` declaration exist with the ratified field shapes (typed-substrate read, no string scan). - When `emission_path_projections` is non-empty, its row count equals the sum of `MethodTemplateContract` row counts across @@ -129,7 +129,7 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). ## Acceptance - `src/v3/std/cross_target_coverage.dag` lands with the five - types + the empty `data` declaration + the mandatory + types (`ShapeATarget`, `FormAxis`, `BehaviorAxis`, `MethodTemplateContractKey`, `EmissionCell`, `EmissionPathProjection`) + the empty `data` declaration + the mandatory option-(c) header note. - **Practice 4 classification receipts on the live declaration (mandatory).** Each new sum-typed declaration carries an From 6282a070435140b0eeff03c33eee4f5c8e970524 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 03:13:34 +0000 Subject: [PATCH 19/52] fix(briefs): L6 second 'five types' site + T-E-P lookup-gate authority MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per cursor review on PR #1782 (sha 2072b986): 1. L6 brief acceptance bullet at :131 still said "five types" while the parenthetical and the Slice step at :117 said six. The prior fix only caught one of two sites; corrected the second. 2. T-E-P brief `e_p_call_pattern_lookup_authoritative` acceptance named only `lower_call_pattern` as "the only route from call site to LoweringTarget" — but Phase 2 explicitly requires lenses route through `per_call_pattern_at` (the L-7 single- authority lookup), NOT `lower_call_pattern` (compiler-internal). Acceptance text rewritten to name `per_call_pattern_at` as the consumer-facing gate and clarify `lower_call_pattern`'s internal-only scope. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../r3-l6-emission-path-projection-substrate-worker.md | 2 +- docs/briefs/r3-t-e-p-producer-broadening-worker.md | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md index 5a19ebef6b7..c0202edbe1d 100644 --- a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -128,7 +128,7 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). ## Acceptance -- `src/v3/std/cross_target_coverage.dag` lands with the five +- `src/v3/std/cross_target_coverage.dag` lands with the six types (`ShapeATarget`, `FormAxis`, `BehaviorAxis`, `MethodTemplateContractKey`, `EmissionCell`, `EmissionPathProjection`) + the empty `data` declaration + the mandatory option-(c) header note. - **Practice 4 classification receipts on the live declaration diff --git a/docs/briefs/r3-t-e-p-producer-broadening-worker.md b/docs/briefs/r3-t-e-p-producer-broadening-worker.md index 5dc5a34a82f..76dabf9d81f 100644 --- a/docs/briefs/r3-t-e-p-producer-broadening-worker.md +++ b/docs/briefs/r3-t-e-p-producer-broadening-worker.md @@ -135,9 +135,13 @@ Worker should align to the three named gates structurally. `ExprCall.descent_evidence` populates an equivalent `CallDescentEvidence` row in v3; `SubValueUnknown` rate matches v2's unproven-edge rate exactly (no v3 regressions, no v3 fabrications). -- `e_p_call_pattern_lookup_authoritative`: `lower_call_pattern` is - the only route from call site to `LoweringTarget`; no parallel - call-pattern derivation in lens or consumer code. +- `e_p_call_pattern_lookup_authoritative`: `per_call_pattern_at` + is the only route from call site to `CallPattern` for lenses + and external consumers (the L-7 single-authority lookup gate); + the compiler-internal helper `lower_call_pattern` (`dag.rs:1318`) + routes call-site → `LoweringTarget` only inside lowering itself + and is **not** a consumer-facing entry point. No parallel call- + pattern derivation in lens or consumer code. - `e_p_sub_value_relation_per_call_landed`: cost + complexity lens consume the side table; per-lens v2-oracle cementing tests green. - `cargo test --workspace --exclude v2-compiler-tests` green. From d924594237187e03414e0487662c05c0664b9512 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 03:23:18 +0000 Subject: [PATCH 20/52] fix(briefs): strengthen L6 ratchet from count-parity to per-row bijection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per openai-pro REQUEST_CHANGES on PR #1782 (sha 2072b986): the L6 acceptance ratchet asserted only row-count parity between emission_path_projections and the union of MethodTemplateContract rows. Count parity permits duplicate projection keys and missing source rows — the bridge from list-non-empty proxy to per-row projection would not be mechanically proven. The whole point of introducing MethodTemplateContractKey { target, dag_method } is to provide 1:1 row identity. Rewrites the ratchet to assert per-row bijection: every MethodTemplateContract source row has exactly one matching EmissionPathProjection row by key; every projection key resolves to exactly one source row; duplicate projection keys fail closed. (The other openai-pro BLOCKING finding — T-E-P e_p_call_pattern_lookup_authoritative naming the wrong authority — was already fixed at 6282a0704; the review citation was against the pre-fix sha 2072b986.) Co-Authored-By: Claude Opus 4.7 (1M context) --- ...ission-path-projection-substrate-worker.md | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md index c0202edbe1d..e751b069406 100644 --- a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -116,12 +116,21 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). 2. Add a small ratchet asserting that: - The six types (`ShapeATarget`, `FormAxis`, `BehaviorAxis`, `MethodTemplateContractKey`, `EmissionCell`, `EmissionPathProjection`) and the `data` declaration exist with the ratified field shapes (typed-substrate read, no string scan). - - When `emission_path_projections` is non-empty, its row count - equals the sum of `MethodTemplateContract` row counts across - `*_method_template_contracts` lists (row-count parity). - The parity assertion is structurally trivial while the list - is empty (vacuously true) and activates the load-bearing - check once Grounding populates. + - **Per-row key bijection** (the load-bearing modeled fact — + count-parity alone is insufficient because it permits + duplicate projection keys + missing source rows): every + `MethodTemplateContract` row across the union of + `*_method_template_contracts` lists has exactly one + `EmissionPathProjection` row whose `key: + MethodTemplateContractKey { target, dag_method }` matches + the source row's `(target, dag_method)`; every projection + key resolves to exactly one source row; duplicate projection + keys fail closed (ratchet asserts uniqueness on the + projection key set + bijective coverage of the source key + set). Bijection is structurally trivial while + `emission_path_projections` is empty (vacuously true on the + empty source set) and activates the load-bearing check once + Grounding populates. 3. **No row population, no `coverage.rs` edits in this slice.** Both are scoped to the Grounding follow-up per §4.D=(b). From 946d3316bd0948dc22948d0c2157226db0c1877c Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 03:38:35 +0000 Subject: [PATCH 21/52] fix(briefs): split L6 ratchet into slice-active vs deferred-activation gates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per BLOCKING inline review on PR #1782 at d92459423: the prior bijection ratchet was unsatisfiable as authored. The *_method_template_contracts lists at HEAD (rust/python/go) are non-empty; shipping emission_path_projections: [] alongside a strict bijection requirement means the bijection cannot pass when the slice lands — source rows would be uncovered. Prior text incorrectly said "vacuously true on the empty source set" — the SOURCE set isn't empty, only the projection set is. Splits the ratchet into two gate categories: - Slice-active gates: types/data shape exist + empty-state predicate (emission_path_projections == []). - Deferred-activation gate: per-row key bijection, authored as a test scaffold by this slice but #[ignore]'d (or feature-gated on len > 0) until Grounding's follow-up populates rows. On activation, asserts the bijection over the populated set. This honors P1 doc faithfulness: the slice's acceptance contract is satisfiable as authored, and the bijection becomes the load-bearing gate the row-population PR satisfies. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...ission-path-projection-substrate-worker.md | 46 ++++++++++++------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md index e751b069406..b14ca96daed 100644 --- a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -114,23 +114,37 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). PR populates the 42 Phase 1 rows. 2. Add a small ratchet asserting that: - - The six types (`ShapeATarget`, `FormAxis`, `BehaviorAxis`, `MethodTemplateContractKey`, `EmissionCell`, `EmissionPathProjection`) and the `data` declaration exist with the - ratified field shapes (typed-substrate read, no string scan). - - **Per-row key bijection** (the load-bearing modeled fact — - count-parity alone is insufficient because it permits - duplicate projection keys + missing source rows): every - `MethodTemplateContract` row across the union of - `*_method_template_contracts` lists has exactly one - `EmissionPathProjection` row whose `key: - MethodTemplateContractKey { target, dag_method }` matches - the source row's `(target, dag_method)`; every projection - key resolves to exactly one source row; duplicate projection - keys fail closed (ratchet asserts uniqueness on the + - **(Slice-active gate)** The six types (`ShapeATarget`, + `FormAxis`, `BehaviorAxis`, `MethodTemplateContractKey`, + `EmissionCell`, `EmissionPathProjection`) and the `data` + declaration exist with the ratified field shapes (typed- + substrate read, no string scan). + - **(Slice-active gate)** `emission_path_projections == []` + (the empty-state predicate). The slice ships with the data + declaration empty by design; populated rows are scoped to + Grounding's follow-up per §4.D=(b). The empty-state + assertion is the slice's load-bearing claim that no row + drift sneaks in via this PR. + - **(Deferred-activation gate, asserted by Grounding's + follow-up PR — NOT this slice)** Per-row key bijection + between `emission_path_projections` and the union of + `*_method_template_contracts` rows. The `*_method_template_ + contracts` lists at HEAD (`rust_method_template_contracts`, + `python_method_template_contracts`, + `go_method_template_contracts`) are non-empty, so a strict + bijection cannot pass while this slice ships + `emission_path_projections: []` — that's why the bijection + check belongs in Grounding's row-population PR, not here. + Test scaffold authored by this slice but **`#[ignore]`'d** + (or feature-gated on `emission_path_projections.len() > 0`) + until Grounding lands; on activation the test asserts: + every `MethodTemplateContract` row has exactly one + matching `EmissionPathProjection` row by + `MethodTemplateContractKey { target, dag_method }`; every + projection key resolves to exactly one source row; + duplicate projection keys fail closed (uniqueness on the projection key set + bijective coverage of the source key - set). Bijection is structurally trivial while - `emission_path_projections` is empty (vacuously true on the - empty source set) and activates the load-bearing check once - Grounding populates. + set). 3. **No row population, no `coverage.rs` edits in this slice.** Both are scoped to the Grounding follow-up per §4.D=(b). From b913e2f4e128707e19a11f32232e9a447a33934a Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 04:48:40 +0000 Subject: [PATCH 22/52] fix(briefs): require L6 bootstrap enrollment to honor P2 facts-flow-forward MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per BLOCKING inline review on PR #1782 at L6:34: the slice authored src/v3/std/cross_target_coverage.dag but never required enrolling it in the bootstrap/load authority. Without enrollment the file is dead-letter on disk and EmissionPathProjection can be absent from the downstream Dag — silent P2 facts-flow-forward violation. Adds a new Slice step 2 requiring a cross_target_coverage field on BootstrapFixtures in src/v3/std/extdeps_bootstrap_fixtures.dag mirroring the *_method_template_contracts enrollment pattern, plus a loader-visibility ratchet. Renumbers subsequent Slice steps. Adds matching Acceptance bullet. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...ission-path-projection-substrate-worker.md | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md index b14ca96daed..6662a2aacb5 100644 --- a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -113,7 +113,21 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). The `data` declaration ships **empty**. Grounding's follow-up PR populates the 42 Phase 1 rows. -2. Add a small ratchet asserting that: +2. **Enroll the new file in the bootstrap/load authority** (P2 + facts-flow-forward — without this the file is dead-letter on + disk and `EmissionPathProjection` can be absent from the + downstream Dag). Add a `cross_target_coverage: BootstrapFixture` + field to the `BootstrapFixtures` record in + `src/v3/std/extdeps_bootstrap_fixtures.dag` with `virtual_path: + "src/v3/std/cross_target_coverage.dag"`, mirroring the + `*_method_template_contracts` enrollment pattern at the same + file. Verify at HEAD that the enrolled fixture is reachable + from compile-time loader — a ratchet asserting the loader sees + the new module by name (analogous to the loader-coverage check + covering `rust_method_template_contracts` etc.) lands as part + of step 3. + +3. Add a small ratchet asserting that: - **(Slice-active gate)** The six types (`ShapeATarget`, `FormAxis`, `BehaviorAxis`, `MethodTemplateContractKey`, `EmissionCell`, `EmissionPathProjection`) and the `data` @@ -146,7 +160,7 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). projection key set + bijective coverage of the source key set). -3. **No row population, no `coverage.rs` edits in this slice.** +4. **No row population, no `coverage.rs` edits in this slice.** Both are scoped to the Grounding follow-up per §4.D=(b). ## Acceptance @@ -154,6 +168,13 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). - `src/v3/std/cross_target_coverage.dag` lands with the six types (`ShapeATarget`, `FormAxis`, `BehaviorAxis`, `MethodTemplateContractKey`, `EmissionCell`, `EmissionPathProjection`) + the empty `data` declaration + the mandatory option-(c) header note. +- **Bootstrap enrollment**: the new file is registered in + `src/v3/std/extdeps_bootstrap_fixtures.dag` with a + `cross_target_coverage` field on `BootstrapFixtures` whose + `virtual_path` points at `src/v3/std/cross_target_coverage.dag` + (matching the `*_method_template_contracts` enrollment pattern). + Loader-visibility ratchet asserts the module name resolves + through bootstrap. - **Practice 4 classification receipts on the live declaration (mandatory).** Each new sum-typed declaration carries an inline 🟢/🟡/🔴 doc comment per `docs/modeling-discipline.md` From f2666e4c33930299937ec4e5d2a5e32b5c7ece17 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 01:08:45 -0400 Subject: [PATCH 23/52] WIP: R3 Substrate --- ...1-q-class-2-chain-break-gap-test-canvas.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/briefs/r3-substrate-s1-q-class-2-chain-break-gap-test-canvas.md diff --git a/docs/briefs/r3-substrate-s1-q-class-2-chain-break-gap-test-canvas.md b/docs/briefs/r3-substrate-s1-q-class-2-chain-break-gap-test-canvas.md new file mode 100644 index 00000000000..1e768e96d15 --- /dev/null +++ b/docs/briefs/r3-substrate-s1-q-class-2-chain-break-gap-test-canvas.md @@ -0,0 +1,147 @@ +--- +status: draft (Mgr-tier canvas; ENGAGE-NOW per Director disposition 2026-05-06 at gunbc#828 #issuecomment-4384615320) +authority parent: R3 Substrate Manager (#1739) +ratification: Director disposition 2026-05-06 directs Substrate Mgr to surface gap-test candidate per option (a) +roadmap row: docs/r3-program-plan.md §10.3 Q-Class-2-Chain-Break + §1.8 ledger row #61 +authority docs: + - docs/r3-program-plan.md:75 (§4.2 Class 2 chain-break) + - docs/r3-program-plan.md:258 (ledger row #61 — DECLARED, RED until Q-LBP-R3-Closeability resolves) + - docs/r3-program-plan.md:366-368 (two resolution paths (a)/(b)) + - docs/r3-program-plan.md:974 (Q-Class-2-Chain-Break disposition) + - docs/audit/r3-debt-sweep-2026-05-06.md §3 (YELLOW chain rule) + - docs/r3-structure.md:174 (gap-test definition) + - docs/r3-design-schedule-2026-05-06.md §1 S1 +gates: + - substrate_gap_function_valued_data_closed (#61) +--- + +# R3 Substrate S1 — Q-Class-2-Chain-Break gap-test surface canvas + +## Purpose + +Surface a candidate option-(a) gap-test for `substrate_gap_function_valued_data_closed` +(Class 2, ledger row #61) that **traces to GREEN within finite chain +without requiring T-Lens-Behavioral-Parity COMPLETE**. Per Director +disposition 2026-05-06 (gunbc#828 #issuecomment-4384615320): engage now; +recommend option (a) re-pick. If (a) structurally infeasible, escalate +(b) Q-LBP-R3-Closeability scope-calibration as load-bearing. + +This is a **Mgr-tier canvas**, not a worker brief. Output is a +recommended gap-test shape + traceability argument to GREEN; worker +dispatch (if any) follows Director ratification of the candidate. + +## Class 2 statement (per `r3-structure.md:174`) + +> `substrate_gap_function_valued_data_closed` — `Lens` instance +> with function-typed payload executes through evaluator and produces +> `DimensionReport` without Rust mediation. Closes via +> T-Lens-Application-Surface + T-E-P-Producer-Broadening. + +The original chain — T-Lens-Application-Surface ← T-Lens-Behavioral-Parity +← Q-Lens-Behavioral-Parity-R3-Closeability (RED) — does not terminate +at GREEN within finite steps; per Refinement 3 YELLOW chain rule +(`r3-debt-sweep-2026-05-06.md` §3) Class 2 inherits RED. + +## Candidate surface (option-(a) re-pick) + +**Recommendation**: narrow the gap-test from "function-typed payload +in arbitrary `Lens` instance" to "function-typed `data` declaration +consumed by an evaluator-executable representative". The narrowed test +exercises the substrate fact (function-valued data is first-class) +without requiring any specific lens to reach BEHAVIORALLY COMPLETE. + +### Proposed gap-test shape + +Authored as a `.dag` representative under `dsl/tests/` or similar: + +1. **Function-valued data declaration** — top-level `data f: Int -> Int = ...` + form using existing `func`/`Arrow` substrate (already landed; see + `src/v3/std/types.dag` Arrow + `v3_compiler::dag::Callable`). +2. **Evaluator consumption** — `eval_*` path that takes the function-valued + data as input, applies it to a representative argument, and produces + a `Value` result. Target: existing E6-G0d constructor runtime + execution path (Evaluator E1, dispatched 2026-05-06 to valiant-carp-10 + per #1767 #issuecomment-4385079490) extended to `Callable` payloads + referenced through `data` rather than constructed inline. +3. **No Rust mediation predicate** — assertion that the evaluator's + handling of the function-valued payload routes through `eval_call` + / `eval_lens_apply` (or equivalent) using only substrate-facts + produced by T-E-P-Producer-Broadening (descent-evidence side-table). + +### Traceability to GREEN + +- **Prerequisite 1**: T-E-P-Producer-Broadening Phase 1 (descent-evidence + full coverage) — independently dispatchable, foundational, no LBP + prereq. Already scheduled (S10). +- **Prerequisite 2**: Evaluator E6-G0d (constructor + `Callable` + runtime execution) — DISPATCHED 2026-05-06; valiant-carp-10 owner. +- **No T-LBP dependency**: the gap-test does NOT assert "complexity + lens reaches BEHAVIORALLY COMPLETE on this input". It asserts only + "evaluator executes function-valued data path". Lens behavior is + out of scope. + +Both prerequisites are EVAL-3-side or substrate-side — no chain through +Q-LBP-R3-Closeability. **Trace to GREEN is finite**: T-E-P Phase 1 ++ E6-G0d → gap-test executes → green. + +## Ratification surface + +This canvas is the Substrate-Mgr-side surface for Director ratification of: + +- **Q1**: Is the narrowed gap-test (function-valued `data` + evaluator + consumption, lens-behavior out of scope) acceptable as a Class 2 + closure under §1.8 row #61? +- **Q2**: If yes, ledger row #61 reframes from CHAIN-BREAK / RED → + DECLARED / YELLOW (gated only on T-E-P + E6-G0d, both in flight). + Substrate Mgr authors a worker brief on the gap-test representative + for dispatch post-prerequisite. +- **Q3**: If no (i.e., Class 2 must demonstrate via `Lens` shape + specifically), then option (b) — Q-LBP-R3-Closeability scope- + calibration becomes load-bearing. This canvas hands off to S2 + (T-LBP scope-calibration canvas). + +## STOP-AND-ESCALATE + +- **Director rules option-(a) infeasible**: hand off to S2 immediately; + Class 2 closure becomes LBP-cascade-gated. Not a Substrate-side + problem to solve. +- **T-E-P-Producer-Broadening Phase 1 produces no surface usable by + function-valued data path**: the prerequisite chain itself has a + gap; surface to Director as a substrate-extension question (does + function-valued data require additional descent-evidence variants + beyond current 8 `CallPattern`?). New variant addition follows P1 + procedure per `INVARIANTS.md#p1-modeling-faithfulness`. +- **E6-G0d worker-brief surface drifts** (e.g., Evaluator scope narrows + to non-`Callable` constructors only): Class 2 closure must wait for + separate `Callable`-runtime work; gap-test deferred until that + surface lands. Coordinate with Evaluator Mgr (#1743). + +## Authority audit receipt + +1. **Substrate exists?** Function-valued `data` substrate exists: + `Arrow` (in `src/v3/std/types.dag` + `dag.rs`), `Callable` + (`dag.rs` evaluator path), `data` declarations (lowerer evaluates + to `Value` at lower time per memory note "Data declaration wiring + 2026-02-25"). No new top-level carrier required for the gap-test; + re-uses landed surfaces. +2. **Existing brief?** None. `r3-pr-e6-g0d-constructor-runtime-execution-worker.md` + is the upstream Evaluator brief; this canvas is the Substrate-side + gap-test specification that consumes E6-G0d's runtime extension. +3. **Design-doc match?** `r3-program-plan.md` §10.3 Q-Class-2-Chain-Break + names option (a) re-pick + option (b) LBP escalation. Director + disposition 2026-05-06 selects (a). Canvas surfaces (a) candidate. +4. **Citations live?** `r3-program-plan.md:75, 258, 366-368, 974` and + `r3-structure.md:174` verified at HEAD 2026-05-06. +5. **Carrier dissolves the bridge?** Gap-test is structural + demonstration, not a carrier. The "bridge" being dissolved is the + YELLOW chain-rule violation in §1.8 row #61: re-picking the + gap-test removes the invalid YELLOW status by replacing the + non-finite chain with a finite one. + +## Provenance + +Drafted 2026-05-06 per Director disposition (gunbc#828 +#issuecomment-4384615320) directing Substrate Mgr to surface option-(a) +candidate. Dispatched as part of R3 design schedule (PR #1810 §1 S1). +Awaits Director Q1/Q2/Q3 ratification before worker brief authoring +proceeds. From 2614217e4fc8d4cef16865008d91ae41eee7b888 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 01:13:23 -0400 Subject: [PATCH 24/52] WIP: R3 Substrate --- ...trate-s2-t-lbp-scope-calibration-canvas.md | 224 ++++++++++++++++++ ...te-s3-machine-constraint-carrier-worker.md | 208 ++++++++++++++++ ...pproximate-field-float-migration-worker.md | 215 +++++++++++++++++ ...strate-s9-t-numeric-construction-worker.md | 214 +++++++++++++++++ 4 files changed, 861 insertions(+) create mode 100644 docs/briefs/r3-substrate-s2-t-lbp-scope-calibration-canvas.md create mode 100644 docs/briefs/r3-substrate-s3-machine-constraint-carrier-worker.md create mode 100644 docs/briefs/r3-substrate-s8-approximate-field-float-migration-worker.md create mode 100644 docs/briefs/r3-substrate-s9-t-numeric-construction-worker.md diff --git a/docs/briefs/r3-substrate-s2-t-lbp-scope-calibration-canvas.md b/docs/briefs/r3-substrate-s2-t-lbp-scope-calibration-canvas.md new file mode 100644 index 00000000000..2ee1c3dcc4b --- /dev/null +++ b/docs/briefs/r3-substrate-s2-t-lbp-scope-calibration-canvas.md @@ -0,0 +1,224 @@ +--- +status: draft (Mgr-tier canvas; ENGAGE-NOW per Director disposition 2026-05-06) +authority parent: R3 Substrate Manager (#1739) + Verification Manager (#1740) cross-program +ratification: Director needs Substrate canvas detail before engaging Q-Lens-Behavioral-Parity-R3-Closeability (E3 RED) +roadmap row: docs/r3-program-plan.md §10 Q-LBP-R3-Closeability + §1.8 ledger rows #79-#83 (T-LBP), #61 (Class 2), #88-#95 (T-LAS), #54 (timing-lens), #57-#59 (T-LSA) +authority docs: + - docs/r3-structure.md:38 (T-LBP lane definition; L-XL sized; cross-program Substrate+Verification) + - docs/r3-structure.md:140-145 (T-LBP gate IDs) + - docs/r3-structure.md:209 (lane row + 4 sub-slices) + - docs/v3-lens-capability-register.md (PROXY/STUB/PARTIAL classifications) + - docs/r3-program-plan.md §10 Q-LBP-R3-Closeability + - docs/r3-design-schedule-2026-05-06.md §1 S2 +gates: + - complexity_lens_behaviorally_complete (#79) + - cost_lens_behaviorally_complete (#80) + - parallelism_lens_behaviorally_complete (#81) + - effect_enumeration_lens_behaviorally_complete (#82) + - lens_capability_register_zero_proxy_zero_stub (#83) +--- + +# R3 Substrate S2 — T-Lens-Behavioral-Parity scope-calibration canvas + +## Purpose + +Director needs Substrate-side canvas detail before engaging +Q-Lens-Behavioral-Parity-R3-Closeability (currently E3 RED — no +executable close path identified). Per `r3-structure.md:209` T-LBP +has 4 sub-slices. This canvas surfaces, for each lens, the specific +substrate / runtime / consumer blockers that gate +"PROXY/STUB/PARTIAL → BEHAVIORALLY COMPLETE", and names option +(a) / (b) / (c) shapes consistent with Substrate Mgr E3 RED: + +- **(a) accept**: T-LBP scope unchanged; Director ratifies finite + close-path within R3 horizon for all 4 lenses. +- **(b) reframe**: narrow R3 T-LBP scope to 1-2 lenses; remaining + lenses carve to R4 with substrate-gap routing. +- **(c) carve to R4**: T-LBP fully out of R3; cascading lanes + (T-LAS / T-WAD / T-LSA / Class 2) re-routed or carved. + +This canvas is **Mgr-tier scope-calibration input**, not a worker +brief. Output → Director ratifies (a/b/c) shape → cascading dispatch +work follows. + +## Per-lens blocker matrix + +Per `docs/v3-lens-capability-register.md` audit (Substrate Mgr surface +of register status; worker re-verifies at HEAD before ratification). + +### Lens 1 — `complexity` (currently PROXY) + +Sub-slice scope (per `r3-structure.md:209`): symbolic CostExpr full +algebra (Sum/Mul/Log/Const) consumed by lens; work/span dimension +split; asymptotic classification; cementing test against frozen +v2-oracle snapshot. + +| Sub-slice | Blocker | Substrate dependency | Status | +|---|---|---|---| +| 1a — symbolic CostExpr algebra consumed | Lens reads `per_call_descent_evidence` side-table at full coverage | T-E-P-Producer-Broadening Phase 1 | foundational; in flight (S10) | +| 1b — work/span split | Lens emits `Dimension` + `Dimension` separately rather than scalar cost | substrate `Dimension` projection — landed | landed | +| 1c — asymptotic classification | Lens computes asymptotic class from symbolic algebra | depends on 1a + classification fold | gated on 1a | +| 1d — cementing test (frozen v2-oracle) | Frozen snapshot captured pre-v2-retirement; cementing-test consumes frozen receipt | T-Tests-As-Data-Completeness consumer pattern; frozen snapshot infrastructure | T-V2-Retirement coordination | + +**Close-path option-(a) feasibility**: feasible IF T-E-P Phase 1 +lands + cementing-test pattern lands. No substrate-extension required. +Critical-path: longest among 4 lenses but not blocked by missing +substrate. + +### Lens 2 — `cost` (currently PROXY) + +Sub-slice scope: same producer foundation as complexity; `SizeVar` +value semantics; `Dimension` wiring; cementing test. + +| Sub-slice | Blocker | Substrate dependency | Status | +|---|---|---|---| +| 2a — `SizeVar` value semantics | `SizeVar` substrate landed; lens evaluates against runtime values | landed (per `design-cost-lens-sizevar-dimension-wiring.md`) | landed | +| 2b — `Dimension` wiring | Lens output projects `Dimension` | landed (Dimension projection) | landed | +| 2c — producer consumption | same as 1a — `per_call_descent_evidence` full coverage | T-E-P Phase 1 | gated on T-E-P | +| 2d — cementing test | same as 1d | same | T-V2-Retirement coordination | + +**Close-path option-(a) feasibility**: feasible; mirrors complexity +critical-path. Both lenses share the producer dependency; closing +T-E-P Phase 1 unblocks both simultaneously. + +### Lens 3 — `parallelism` (currently STUB) + +Sub-slice scope: Stage 2e parallelism walk port from +`src/v3/compiler/src/workflow_parallelism.rs` to `.dag`; rewire via +`lane2_workflow_at` / `std.effects` (idempotency closure template). + +| Sub-slice | Blocker | Substrate dependency | Status | +|---|---|---|---| +| 3a — Stage 2e walk ported to `.dag` | Workflow-parallelism walker needs `.dag` representation | substrate: `lane2_workflow_at` query + `std.effects` idempotency template | partial (effects substrate landed; walker port pending) | +| 3b — rewire via `lane2_workflow_at` | Lens consumes the new query | depends on 3a | gated on 3a | +| 3c — cementing test | frozen v2-oracle parallelism trace | same as 1d | T-V2-Retirement coordination | + +**Close-path option-(a) feasibility**: feasible; substrate exists, +work is port + rewire. Independent from T-E-P critical-path. Sized +M (smaller than complexity/cost). + +### Lens 4 — `effect_enumeration` (currently PARTIAL) + +Sub-slice scope: resource-threading migration; ambient metadata +removal; caller-side effect-set pinning; full `OperationEffect` +retirement. + +| Sub-slice | Blocker | Substrate dependency | Status | +|---|---|---|---| +| 4a — resource-threading migration | Effects route through resource handles (not ambient metadata) | substrate: existing resource carrier (Read/Write/Exclusive); migration target | substrate landed | +| 4b — ambient metadata removal | `OperationEffect` carrier no longer needed for caller-side enumeration | substrate cleanup; coordinate with T-V2-Retirement | gated on 4a | +| 4c — caller-side effect-set pinning | Lens reads pinned effect-set from caller, not callee ambient | substrate: caller-side pinning carrier | NOT LANDED — substrate gap | +| 4d — full `OperationEffect` retirement | Tier-2 retirement of legacy carrier | depends on 4a-4c | gated on 4a-4c | + +**Close-path option-(a) feasibility**: BLOCKED on 4c — caller-side +effect-set pinning carrier is not landed. This is a **substrate +extension required for option-(a) feasibility**. If 4c is not +authored within R3 horizon, lens 4 cannot reach BEHAVIORALLY +COMPLETE. + +## Option (a/b/c) shape recommendations + +### Option (a) — accept full T-LBP scope + +**Feasibility per blocker matrix**: feasible for lenses 1, 2, 3. +**BLOCKED for lens 4** on substrate gap 4c (caller-side effect-set +pinning carrier). + +**Required for (a)**: Substrate Mgr authors brief for 4c carrier; +worker dispatched in R3. Adds approximately 1 worker-slot +equivalent to R3 critical path (lens 4 is currently PARTIAL, not +STUB; partial-to-COMPLETE work plus 4c carrier authoring). + +**Cost**: ~M-L worker effort; 4c carrier introduction is substrate- +fact-introduction event (P1 procedure required). + +### Option (b) — reframe T-LBP to 1-2 lenses for R3 + +**Recommended subset**: complexity + cost (lenses 1 + 2). Both share +the T-E-P producer dependency; closing them simultaneously is the +critical-path fastest path. Both have frozen-v2-oracle cementing +test pattern available. + +**Carve-to-R4**: parallelism (lens 3) + effect_enumeration (lens 4). +Class 2 gap-test (S1 candidate) does NOT require parallelism or +effect_enumeration COMPLETE — re-uses complexity/cost lens +infrastructure for the function-valued data path. Class 2 closure +remains feasible under (b). + +**Cost**: ~M worker effort reduction; parallelism + effect_enumeration +substrate-gaps (4c) carry to R4 with documented routing. + +**Cascade impact**: T-LAS (lens application surface) gates on +"lenses COMPLETE". Under (b), T-LAS demonstrations narrow to +complexity-contract-compile-error + CRDT cost basis (both consume +complexity / cost). memory-peak cost basis is cost-lens-driven (still +in scope). opt-in cross-iteration parallelism demonstration (T-LAS +gate `opt_in_iteration_parallelism_via_lens_application_demonstrated`) +becomes problematic — needs parallelism lens. Carve to R4 alongside +parallelism lens. + +T-Lens-Self-Application demonstration uses **timing** lens (T-WAD's +new lens shape, not in T-LBP scope). T-LSA still feasible under (b). + +### Option (c) — T-LBP fully out of R3 + +**Cascade impact**: massive. T-LAS, T-WAD, T-LSA all carry to R4 or +later. R3 critical-path collapses. Recursive-flex thesis claim +(`r3-structure.md:42`) un-cashes for R3. + +**Recommendation against (c)** unless Director judges that R3 close +horizon is fundamentally incompatible with any T-LBP work. + +## Ratification surface + +- **Q1**: Is option (a) acceptable given the 4c substrate gap? If + yes, Substrate Mgr authors 4c carrier brief immediately + dispatch + to worker pool. +- **Q2**: Is option (b) acceptable scope-narrow? If yes, Substrate + Mgr documents R4 carve-out routing for lenses 3 + 4; cascade + recipients (T-LAS, T-WAD, T-LSA Mgrs) consume the narrowed scope. +- **Q3**: If neither (a) nor (b), surface Director-requested option + shape; this canvas iterates. + +## STOP-AND-ESCALATE + +- **Lens capability register drift**: this canvas is anchored to + register status as of 2026-05-06. If register is updated mid- + canvas, blocker matrix may shift. Worker re-verifies register + at HEAD before ratification proceeds. +- **T-E-P-Producer-Broadening reveals additional producer surface + required for lens 1/2 BEHAVIORALLY COMPLETE**: the canvas + assumes T-E-P Phase 1 is sufficient producer surface. If + Phase 1 lands and complexity/cost lenses still cannot reach + COMPLETE, re-canvas; option-(a) feasibility for lenses 1/2 + shifts. +- **Class 2 gap-test (S1) requires lens-behavioral-parity COMPLETE + for representative**: S1 canvas argues otherwise (function-valued + data path is evaluator-side, not lens-behavior-dependent). If + Director rules S1 narrowing infeasible, T-LBP becomes load-bearing + for Class 2 — option (b) carve-out narrows further (cannot + exclude complexity/cost without breaking S1). + +## Authority audit receipt + +1. **Substrate exists?** Per-lens substrate inventoried in blocker + matrix; 4c is the only confirmed substrate gap. Lenses 1-3 + substrate is landed; work is consumer-wiring + cementing tests. +2. **Existing brief?** None for T-LBP scope-calibration. T-LBP + itself was authored 2026-05-02 per `r3-structure.md` expansion; + this canvas is the scope-calibration response to E3 RED. +3. **Design-doc match?** `v3-lens-capability-register.md` is the + anchor. Worker re-reads at dispatch. +4. **Citations live?** Verified at HEAD 2026-05-06: `r3-structure.md:38, 140-145, 209` + and design schedule §1 S2. +5. **Carrier dissolves the bridge?** N/A — canvas is scope-calibration + not carrier landing. The "bridge" is the YELLOW chain rule + violation in Q-LBP-R3-Closeability + Class 2 cascade. (a/b/c) + recommendation provides Director with shape options to dissolve. + +## Provenance + +Drafted 2026-05-06 per R3 design schedule §1 S2 (PR #1810). Director +ratifies (a/b/c) shape; cascade dispatch to T-LAS / T-WAD / T-LSA +Mgrs follows. Coordinate with Verification Mgr (#1740) for +cross-program V3 sub-slice ownership. diff --git a/docs/briefs/r3-substrate-s3-machine-constraint-carrier-worker.md b/docs/briefs/r3-substrate-s3-machine-constraint-carrier-worker.md new file mode 100644 index 00000000000..5b2d50d3f61 --- /dev/null +++ b/docs/briefs/r3-substrate-s3-machine-constraint-carrier-worker.md @@ -0,0 +1,208 @@ +--- +status: draft (worker brief; ENGAGE-NOW per Brian directive 2026-05-06) +authority parent: R3 Substrate Manager (#1739) +ratification: Brian directive 2026-05-06 (chat) — algebra × machine-constraints interaction modeling; concrete types as products of independent axes +roadmap row: docs/r3-program-plan.md §4.1 Class 1 (parser/grammar surface) + §1.8 ledger row #60 +authority docs: + - docs/r3-program-plan.md:428 (Class 1 modeling target — independent constraint models) + - docs/r3-program-plan.md:60 (substrate_gap_parser_grammar_closed) + - docs/r3-design-schedule-2026-05-06.md §1 S3 + - docs/audit/r3-debt-sweep-2026-05-06.md (Class 1 5-criteria Pass) +gates: + - substrate_gap_parser_grammar_closed (#60) +worker pin: valiant-ant-72 (per S7 brief partition; valiant-ant-72 reserved for S3 implementation post-design ratification) +--- + +# R3 Substrate S3 — `MachineConstraint` carrier worker brief + +## Context + +Per Brian directive 2026-05-06 (chat): concrete types like `i64` +emerge as products of independent constraint axes — algebra +(`Int = AbelianGroup`) × machine constraint (`MachineWidth<64>`) +— **NOT primary substrate entities**. The current substrate treats +some concrete primitives (e.g., `Int<32>`, `Float<64>`) as primary +declarations; modeling target reframes them as projections of +algebra × machine-constraint products. + +Class 1 (`substrate_gap_parser_grammar_closed`, ledger row #60) closes +when: +1. Substrate carriers for machine constraints exist as independent axes. +2. Parser handles generic interaction syntax (e.g., `Int @ Width<32>` + or equivalent — bikeshed in design phase). +3. ≥ 3 algebra × constraint pairs emit to target primitives + (Rust `i32` / `i64` / `u64` minimum). +4. Target primitives are NOT primary substrate entities — they + are emitted from the interaction. +5. v2-oracle parity on the same source program produces equivalent + target-language output. + +This brief lands the **substrate carrier slice**: `MachineConstraint` ++ `MachineWidth` + interaction-lookup substrate. Companion lanes +land parser-grammar (separate downstream PR after carrier ratification) ++ emitter wiring (Grounding Mgr coordination — cross-program at brief +landing). + +## Slice + +### Phase 1 — Carrier shape (gate scaffolding for #60) + +1. **Author `dsl/std/machine_constraints.dag`** introducing: + + Each new coproduct / sum declaration MUST carry a 🟢/🟡/🔴 + classification annotation per `docs/modeling-discipline.md` + Practice 4 (Step 4 of the type-introduction checklist; + `INVARIANTS.md#p1-modeling-faithfulness` worked example). + + - `MachineWidth` — phantom-parameter carrier; `bits: Nat`. + **🟢 PRIMITIVE** — width values are Nat-valued; the carrier + names "this width matters for emission" with the value carried + in the phantom parameter. No variant enumeration; new widths + are not new variants but new instances. + - `MachineConstraint` — top-level machine-axis carrier with + phantom `C`. Subsumes `MachineWidth` and any future + machine-side axis (RegisterClass / EndianMode / Alignment). + **🟢 PRIMITIVE** — the carrier names the axis class; specific + instantiations (`MachineConstraint>`, + `MachineConstraint>`) project values onto + the axis. + + Co-author the **Q-MachineConstraint-Axis-Enumeration** note + surfacing further axes for Director ratification: + - `RegisterClass` (e.g., int / float / vector register class) + - `EndianMode` (`Little` | `Big`) + - `Alignment` (Nat-valued phantom) + + Phase-1 scope lands `MachineWidth` + `MachineConstraint` only. + Additional axes are surfaced for Director scope decision before + Phase-2 expansion. + +2. **Interaction-lookup substrate**. Add an `AlgebraMachineProduct` + record carrier: + + ``` + data AlgebraMachineProduct = { + algebra: AlgebraRef, + machine: MachineConstraintRef, + emits_to: TargetPrimitiveRef, + } + ``` + + This is the **interaction substrate** — concrete-type emission + reads this table to find `Int × MachineWidth<32> → i32` mappings. + Co-located with Grounding Mgr's emit-shim consumption (cross-lane). + +3. **Annotation classifications** for new declarations follow + Practice 4. Worker authors P1 receipts in PR body for each + substrate-fact introduction. + +### Phase 2 — Parser-grammar surface (separate downstream PR) + +This brief does NOT land parser changes. Per "carrier slice only" +discipline, parser-grammar work is sequenced after Director +ratification of carrier shape. A follow-up brief (Substrate +S3-Phase-2) lands grammar production + AST nodes for the interaction +syntax (bikeshed: `Int @ Width<32>` vs `Int with MachineWidth<32>` +vs operator-form). + +### Phase 3 — Emit-shim consumption (Grounding Mgr coordination) + +Cross-program. Grounding Mgr (#1745) consumes +`AlgebraMachineProduct` table to emit Rust target primitives. Brief +G2 (`r3-structure.md` Lane T-Ground-Rust) is the consumer. + +### Phase 4 — ≥3 algebra × constraint pairs landed (Pass criterion 3) + +Demonstrate Class 1 closure with three concrete instantiations: + +1. `Int × MachineWidth<32> → Rust i32` +2. `Int × MachineWidth<64> → Rust i64` +3. `UInt × MachineWidth<64> → Rust u64` + +These exercise the substrate but **target-primitive emission lives +in Grounding Mgr lane**, not this brief. This brief produces the +substrate; Grounding consumes. Coordinate Phase-3/4 hand-off receipts. + +## Acceptance + +- `dsl/std/machine_constraints.dag` lands with `MachineWidth` + + `MachineConstraint` + `AlgebraMachineProduct` (records / phantom + carriers; no parser surface). +- Practice 4 classification receipts in PR body for each new + declaration. +- Q-MachineConstraint-Axis-Enumeration surfaced as a §note in PR + body for Director ratification of further axes (RegisterClass / + EndianMode / Alignment). +- Grounding Mgr cross-lane handoff documented (G2 brief consumes + `AlgebraMachineProduct` substrate). +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile diagnostic + ratchet at 0. +- `cargo clippy --all-targets -- -D warnings` clean. +- `cargo fmt --all --check` clean. +- ROADMAP "Class 1 (parser/grammar surface)" row updates to reflect + carrier-slice landed (remaining: parser surface + emit consumption). +- §1.8 row #60 status moves DECLARED → CONSUMER_LANDED upon Phases + 1+3 coordination; PASSING upon Phase 4 demonstration. + +## STOP-AND-ESCALATE + +- **Director rules `MachineConstraint` axis enumeration is + not the right shape**: STOP. Re-canvas. Brian directive surfaces + algebra × machine-constraint as the modeling target; if Director + identifies a third axis (e.g., compile-target-OS conditioning), + carrier shape may need to expand beyond `MachineWidth` / + `RegisterClass` / `EndianMode` / `Alignment`. +- **Concrete primitive (`Int<32>`, `Float<64>`, etc.) is currently + primary substrate entity**: per Brian directive, target-primitive + is NOT primary. If existing substrate has primary `Int` / + `Float` declarations consumed at lower or emit time, those + consumers must migrate to read `AlgebraMachineProduct` interaction + table — sequenced **after** carrier slice lands. STOP if migration + scope is non-trivial; surface to Substrate Mgr (#1739) for + scope decision (carve to S9 T-Numeric-Construction). +- **Parser-grammar interaction syntax lands during Phase-1 worker + scope creep**: STOP — brief is carrier slice only. Parser work + is Phase-2 sequenced after Director carrier-shape ratification. +- **`AlgebraMachineProduct` interaction-lookup table grows beyond + 3 entries during Phase-1**: STOP — Phase-1 is substrate carrier + only; populating the table is Grounding Mgr (Phase-3) work. +- **Substrate-fact-introduction P1 procedure flags + `MachineConstraint` axis as DAG-ancestor of an existing + declaration**: STOP — re-frame as consumer migration not new + carrier. Per `INVARIANTS.md#p1-modeling-faithfulness` DFS the + concept DAG before introducing. + +## Authority audit receipt + +1. **Substrate exists?** Per memory + grep at draft time: + `dsl/std/` lacks `MachineConstraint`, `MachineWidth`, or + `AlgebraMachineProduct` declarations. `Int` / `Float` exist as + concrete carriers; this brief reframes them as projections of + algebra × machine-constraint product. Worker re-greps at dispatch. +2. **Existing brief?** None for machine-constraint axis. S9 + (T-Numeric-Construction) is the algebra-side companion — it + lands `Int = AbelianGroup` shape; this brief lands the + machine-side shape. Brief co-references S9; the two briefs + are independent axes (Substrate Mgr partition response 2026-05-06). +3. **Design-doc match?** Brian directive 2026-05-06 (chat) is the + primary authority. No design-doc precedent; this brief IS the + design surface. Director ratification of carrier shape required + before parser-grammar Phase-2 dispatch. +4. **Citations live?** `r3-program-plan.md:428, 60` and design + schedule §1 S3 verified at HEAD 2026-05-06. +5. **Carrier dissolves the bridge?** Yes — `substrate_gap_parser_grammar_closed` + #60 5-criteria Pass requires (a) substrate carriers + [this brief: Phase 1] + (b) parser handles generic interaction + syntax [Phase 2] + (c) ≥3 emission pairs [Phase 3+4 + cross-program] + (d) target primitives NOT primary substrate + entities [structural property of carrier shape] + (e) v2-oracle + parity. This brief covers (a) and structurally enables (d). + +## Provenance + +Drafted 2026-05-06 per Brian directive (chat) + R3 design schedule +§1 S3 (PR #1810). Substrate Mgr authors carrier-slice scope; worker +pin = valiant-ant-72 per S3 implementation reservation +(Substrate Mgr partition response 2026-05-06). Dispatched as +foundational substrate work; gates Class 1 closure. diff --git a/docs/briefs/r3-substrate-s8-approximate-field-float-migration-worker.md b/docs/briefs/r3-substrate-s8-approximate-field-float-migration-worker.md new file mode 100644 index 00000000000..8b9e026a352 --- /dev/null +++ b/docs/briefs/r3-substrate-s8-approximate-field-float-migration-worker.md @@ -0,0 +1,215 @@ +--- +status: draft (worker brief; ENGAGE-NOW parallel with S3 per Substrate Mgr partition response 2026-05-06 at gunbc#846 #issuecomment-4385074769) +authority parent: R3 Substrate Manager (#1739) +ratification: parallel-author authorized per Substrate canvas B2 + Grounding G2 + Substrate Mgr partition; `MachineConstraint` and `ApproximateField` are independent axes (machine width vs algebra approximation) +roadmap row: T-Numeric-Construction (Lane B2) + §1.8 ledger rows #17-#24 +authority docs: + - docs/r3-design-schedule-2026-05-06.md §1 S8 + - Substrate canvas B2 (post at gunbc#846 #issuecomment-4385074769) — partition response naming S8 parallel with S3 + - docs/r3-structure.md (T-Numeric-Construction lane row) +gates: + - one or more of §1.8 ledger rows #17-#24 (T-Numeric-Construction 8 gates) — specifically the float-row gates +--- + +# R3 Substrate S8 — `ApproximateField` Float migration worker brief + +## Context + +Float32/Float64 currently model as `Field` / `Field` +(or equivalent concrete carrier). Per Substrate canvas B2 + Grounding +G2 audit: the modeling is wrong on two axes — + +1. **Algebra**: floats do not satisfy `Field` axioms (associativity + fails under rounding; identity fails for `+0.0` vs `-0.0`; + distributivity fails). They satisfy a weaker structure — + `ApproximateField` — which is the substrate target. +2. **Width independence**: `Word32` / `Word64` is the wrong axis. + Per S3 (`MachineConstraint` carrier), machine width is an + independent axis from algebra. Float32 = `ApproximateField` × + `MachineWidth<32>`; Float64 = `ApproximateField` × + `MachineWidth<64>`. The base carrier `F` is the algebraic field + being approximated (`Real` for IEEE-754 floats; potentially + `Rational` or `Complex` for other approximation regimes). + +This brief is **parallel with S3** per Substrate Mgr partition +response 2026-05-06 — they're independent axes. Brief cross-references +S3 carriers; consumer work synthesizes both axes at the +`AlgebraMachineProduct` interaction-lookup substrate. + +## Slice + +### Phase 1 — `ApproximateField` carrier landing + +1. **Author `ApproximateField` declaration** in + `dsl/std/algebraic_structures.dag` (or co-located with `Field` / + `Ring` / `Group` if such file exists; worker greps for canonical + location at dispatch). + + Practice 4 classification: **🟡 SCAFFOLD** — the axiom-set + relaxation from `Field` is hand-modeled until property-based + tests (T-Tests-As-Data-Completeness `ForAll` quantifier substrate) + land that derive `ApproximateField` from named relaxation rules + (associativity-up-to-rounding etc.). Named dissolution trigger: + `forall_exists_quantifier_substrate_landed` (§1.8 ledger row). + + Surface **Q-ApproximateField-Axiom-Set** for Director ratification: + - Which axioms relax (associativity / identity / distributivity)? + - Which retain (commutativity / closure)? + - Are rounding-mode parameters part of the carrier or a separate axis? + +2. **Author `Real` base-carrier** if not landed: + + ``` + data Real // 🟢 PRIMITIVE — algebraic real numbers; structural fact + ``` + + The `F` parameter on `ApproximateField` is the field being + approximated. `Real` is the canonical instance for IEEE-754 + floats; `Rational` is a possible alternative (rational + approximation / fixed-point). Phase-1 lands `Real` only; + `Rational` if needed for Phase-3 emission demonstration. + +### Phase 2 — Float consumer migration + +1. **Catalog existing `Field` / `Field` references** + at HEAD via grep across `dsl/std/`, `src/v3/std/`, `src/v3/compiler/`, + `src/v3/grounding_*`. Worker re-greps at dispatch; existing memory + notes record `Field` shape but state may have drifted. + +2. **Migrate each consumer** from `Field` / + `Field` → `ApproximateField` × `MachineWidth` + product. Consumers fall into two classes: + - **Algebra-only consumers** (e.g., type inference, lens + analysis): consume `ApproximateField`; do not need + machine width. + - **Emission consumers** (e.g., Grounding Rust target): consume + the product `ApproximateField × MachineWidth` via + `AlgebraMachineProduct` interaction-lookup (S3 carrier). + +3. **Cross-reference S3** at the interaction-lookup table: + + ``` + AlgebraMachineProduct { + algebra: ApproximateField, + machine: MachineWidth<32>, + emits_to: Rust f32, + } + AlgebraMachineProduct { + algebra: ApproximateField, + machine: MachineWidth<64>, + emits_to: Rust f64, + } + ``` + + These are **demonstration entries** for Class 1 Pass criterion + (≥3 algebra × constraint pairs); float entries are ON TOP of + S3's int entries (Int × Width<32> → i32, etc.). Combined float + + int demonstrations close Phase-3 of S3. + +### Phase 3 — Real / base-carrier convention documentation + +1. **`docs/modeling-discipline.md` patch** documenting the + "approximation regime" pattern: `ApproximateField` × machine + axis × rounding-mode (if separate) compose to the concrete + primitive. Establishes pattern for future `ApproximateRing`, + `ApproximateGroup` extensions. + +2. **Q-ApproximateField-Rounding-Mode** — surface for Director + ratification: is rounding mode part of `ApproximateField` + (parametrized) or a separate `RoundingMode` axis (composing + like `MachineConstraint`)? Recommendation: separate axis, + following the "independent axes" thesis from Brian directive + (algebra / machine / rounding all independent). + +## Acceptance + +- `ApproximateField` declaration landed with Practice 4 SCAFFOLD + classification receipt + named dissolution trigger. +- `Real` base-carrier landed (PRIMITIVE) if not already present. +- `Field` / `Field` consumer migration complete; + zero remaining references in non-test, non-archive `.dag` / + `.rs` source. +- `AlgebraMachineProduct` interaction entries for Float32 / Float64 + added (cross-references S3 substrate; coordinate timing — + S3 must land carriers Phase-1 first). +- Q-ApproximateField-Axiom-Set + Q-ApproximateField-Rounding-Mode + surfaced in PR body for Director ratification. +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile diagnostic + ratchet at 0. +- `cargo clippy --all-targets -- -D warnings` clean. +- `cargo fmt --all --check` clean. +- §1.8 ledger float-row gates advance from DECLARED → CONSUMER_LANDED. +- ROADMAP T-Numeric-Construction Float row updates from PARTIAL → + Retired-with-residual (residual: rounding-mode axis pending + Q-ApproximateField-Rounding-Mode resolution if Director carries + to follow-up). + +## STOP-AND-ESCALATE + +- **`Field` / `Field` consumers in v2 compiler + paths** that block migration cleanly: the lane intersects + T-V2-Retirement (PB Mgr P3). STOP; coordinate cross-program + with PB Mgr (#1742) on sequencing. Float migration may need + to wait for v2 retirement of consumer paths, or v2 retirement + may need to consume migrated paths first. +- **Property-based test substrate (`ForAll` quantifier) lands + during this brief's wait window**: dissolution trigger fires + for SCAFFOLD classification; revisit `ApproximateField` + classification (🟡 → 🟢 if axiom set fully derived). Coordinate + with Verification Mgr (V4 T-Tests-As-Data-Completeness). +- **S3 `MachineConstraint` shape lands differently than + this brief assumes** (e.g., `MachineWidth` carrier + renamed or restructured): re-frame Phase-2 consumer migration + to match S3 ratified shape. Brief assumes `MachineWidth` + + `AlgebraMachineProduct` table per S3 Phase-1; if S3 shifts, + this brief shifts. +- **Director ratifies `ApproximateField` is not the right + algebra-side shape** (e.g., prefers `IEEE754Float` or + `BoundedField`): STOP. Re-canvas; carrier authoring + follows ratification. +- **Rounding mode emerges as load-bearing for ≥1 emission + consumer** (e.g., complexity lens needs rounding-mode-aware + cost model): Q-ApproximateField-Rounding-Mode becomes + blocking; surface to Director immediately, do not bridge + with default rounding mode. +- **`Real` carrier conflicts with existing declaration** at + HEAD: re-use existing carrier; re-frame Phase-1 step 2 as + consumer migration not landing. + +## Authority audit receipt + +1. **Substrate exists?** Per memory + draft-time grep: + `Field` / `Field` references exist (memory + notes "Word*" usage). `ApproximateField` does NOT exist + in `dsl/std/`. `Real` carrier may or may not exist — + worker greps at dispatch. No new top-level carrier conflict + anticipated. +2. **Existing brief?** None for `ApproximateField` migration. + T-Numeric-Construction lane covers Float migration as part + of broader scope (S9); this brief is the focused float-migration + slice. Brief co-references S9 (T-Numeric-Construction full + 13-type scope); S8 is the float-specific carrier landing. +3. **Design-doc match?** No design-doc precedent specifically + for `ApproximateField`. Substrate canvas B2 + Grounding + G2 audit are the originating authority. Worker re-reads + audit notes at dispatch. +4. **Citations live?** Substrate Mgr partition response cited + at gunbc#846 #issuecomment-4385074769 — verified at HEAD + 2026-05-06. +5. **Carrier dissolves the bridge?** Yes — `Field` is + a substrate-modeling fault (Field axioms fail for floats; + width is wrong axis). `ApproximateField` × `MachineWidth` + product correctly models the algebra-machine factoring. + Migration retires the faulty carrier and lands the correct + one. Cementing test (Phase 3 PR documentation) anchors the + pattern. + +## Provenance + +Drafted 2026-05-06 per R3 design schedule §1 S8 (PR #1810) + +Substrate Mgr partition response 2026-05-06 (gunbc#846 +#issuecomment-4385074769) authorizing parallel-author with S3. +Cross-references S3 (`MachineConstraint`) carrier brief — +both briefs are Mgr-tier design now; cross-reference at +brief-landing. diff --git a/docs/briefs/r3-substrate-s9-t-numeric-construction-worker.md b/docs/briefs/r3-substrate-s9-t-numeric-construction-worker.md new file mode 100644 index 00000000000..0c489b579b9 --- /dev/null +++ b/docs/briefs/r3-substrate-s9-t-numeric-construction-worker.md @@ -0,0 +1,214 @@ +--- +status: draft (Mgr-tier worker brief; ENGAGE-NOW parallel-author authorized per Substrate canvas B2 ratified) +authority parent: R3 Substrate Manager (#1739) +ratification: B2 ratified per Substrate Mgr canvas + Director ratification of T-Numeric-Construction lane scope +roadmap row: T-Numeric-Construction (REFRAMED 2026-05-01 from T-Int128) + §1.8 ledger rows #17-#24 +authority docs: + - docs/r3-design-schedule-2026-05-06.md §1 S9 + - docs/r3-structure.md (T-Numeric-Construction lane row + 8 gates) + - Substrate canvas B2 (parallel-author authorization) + - docs/r3-program-plan.md §1.8 rows #17-#24 +gates: + - 8 T-Numeric-Construction gates (§1.8 rows #17-#24) including: + - int_construction_landed + - uint_construction_landed + - float_construction_landed (paired with S8) + - char_refinement_landed (Int-inherited) + - epoch_ms_refinement_landed (Int-inherited) + - duration_refinement_landed (Int-inherited) + - http_status_refinement_landed (Int-inherited) + - port_refinement_landed (Int-inherited) + - cross-references: numeric_construction_demonstration (#67 — folded into Acceptance) +--- + +# R3 Substrate S9 — T-Numeric-Construction Mgr-tier worker brief + +## Context + +T-Numeric-Construction (REFRAMED 2026-05-01 from prior T-Int128 lane) +covers the full numeric-primitive construction surface: 13 in-scope +types + Slice 2 Nat-alignment migration. Per B2 canvas + Substrate +Mgr partition response 2026-05-06, this brief authorizes parallel +authoring NOW (foundational; no Evaluator gating). + +**Scope inventory (13 types)**: +- **Direct** (3): `Int`, `UInt`, `Float` +- **Int-inherited refinements** (10): `Char`, `EpochMs`, `Duration`, + `Milliseconds`, `Seconds`, `RetryCount`, `HttpStatus`, `Port`, + `PositiveInt`, `NonNegativeInt` + +**Cross-references**: +- **S3** `MachineConstraint` — machine-axis carriers; Int / + UInt / Float concrete primitives emit via `AlgebraMachineProduct`. +- **S8** `ApproximateField` — Float-specific algebra carrier. + S8 owns Float migration; this brief covers Int / UInt + 10 + refinements. + +## Slice + +This is **L** sized — multi-PR delivery. Worker stages into 4 +phases below; Substrate Mgr ratifies phase-by-phase. + +### Phase 1 — Int / UInt direct construction (gates #17 / #18) + +1. **`Int = AbelianGroup` algebra carrier**. Author or verify + `Int` declaration as projection of algebraic structure + (`AbelianGroup`) + machine axis (`MachineConstraint`). + Practice 4 classification: 🟢 PRIMITIVE if algebra-only; + 🟡 SCAFFOLD if machine-axis composition is hand-modeled. +2. **`UInt = Monoid` algebra carrier**. Companion to `Int`; + non-negative monoid structure. +3. **Concrete emission entries** in `AlgebraMachineProduct` + (cross-program with Grounding Mgr): + - `Int × MachineWidth<32> → Rust i32` + - `Int × MachineWidth<64> → Rust i64` + - `Int × MachineWidth<128> → Rust i128` + - `UInt × MachineWidth<32> → Rust u32` + - `UInt × MachineWidth<64> → Rust u64` + + Phase-1 lands the substrate; emission consumer landing is + Grounding Mgr G2 (T-Ground-Rust). + +### Phase 2 — Float construction (gate #19; coordinate with S8) + +This phase is **owned by S8** — `ApproximateField` migration ++ `Real` base-carrier + `Float = ApproximateField × MachineWidth`. +This brief references S8 closure rather than re-doing the work. +Worker confirms S8 has landed before declaring Phase 2 complete. + +### Phase 3 — Int-inherited refinements (gates #20-#24) + +Refinements are SECONDARY-PARAMETER projections of `Int`. Per +modeling-discipline P1: refinement = predicate over base type, not +new substrate fact. Each refinement lands as: + +``` +data Char = Refined +data EpochMs = Refined +data Duration = Refined +data Milliseconds = Refined +data Seconds = Refined +data RetryCount = Refined +data HttpStatus = Refined +data Port = Refined +data PositiveInt = Refined +data NonNegativeInt = Refined +``` + +(Exact `Refined` shape depends on landed +`TypeExpr::Refined` substrate — annotation elimination Wave 1 +landed the AST per memory note 2026-02-26.) + +Practice 4 classification: each refinement is 🟢 PRIMITIVE +(structural refinement of base type; no new sum-type variants). + +### Phase 4 — Slice 2 Nat-alignment migration + +Per B2 canvas + roadmap: existing `Nat` references in substrate +need migration to canonical Nat-via-PeanoNat or Nat-via-Refined +shape. Worker: + +1. Greps existing `Nat` references at dispatch. +2. Catalogs which use Nat as algebra-axis-carrier (correct usage) + vs which use Nat as concrete primitive (drift; should migrate + to `UInt × MachineWidth` product). +3. Migrates concrete-primitive uses to product form. Algebra-axis + uses are preserved (`AbelianGroup` etc.). + +## Acceptance + +- 13 in-scope types landed per Phase mapping (3 direct + 10 + refinements; Phase 2 = S8 cross-coordination). +- Slice 2 Nat-alignment migration complete; no concrete-primitive + Nat references in non-test source outside algebra-axis usage. +- Practice 4 classification receipts for each new declaration. +- Cross-program receipts with Grounding Mgr (#1745) for emission + consumer entries in `AlgebraMachineProduct`. +- §1.8 gates #17-#24 advance DECLARED → CONSUMER_LANDED phase by + phase. +- §1.8 gate #67 (`numeric_construction_demonstration`) folded into + Acceptance per Substrate Mgr partition response 2026-05-06: the + end-to-end `Int<32>` + `Real<64>` round-trip demonstration is an + Acceptance bullet on this brief, not a separate dispatch. + Demonstration runs via E6-G0d evaluator + Grounding Rust emission. +- `cargo test --workspace --exclude v2-compiler-tests` green. +- `cargo test -p v2-compiler-tests` green; strict-compile diagnostic + ratchet at 0. +- `cargo clippy --all-targets -- -D warnings` clean. +- `cargo fmt --all --check` clean. +- ROADMAP T-Numeric-Construction row updates Partial → Retired + upon all 4 phases landing; residual rows for any deferred + refinement (e.g., if Refined<...> substrate lacks predicate + expressivity for a specific refinement, that one defers). + +## STOP-AND-ESCALATE + +- **`MachineConstraint` (S3) does not land before Phase-1 + emission entries**: this brief depends on S3 substrate for + `AlgebraMachineProduct` interaction table. Phase-1 algebra + carriers can land independently; emission entries STOP until + S3 lands. Coordinate sequencing with Substrate Mgr (#1739). +- **`ApproximateField` (S8) doesn't land before Phase-2 + Float demonstration**: Phase 2 is S8-owned. STOP if S8 work + blocks; Phase 2 reopens upon S8 landing. +- **Refined substrate not expressive enough** + for a specific refinement (e.g., `EpochMs` predicate + "milliseconds-since-epoch" cannot be expressed as a closed + predicate over `Int`): re-frame as algebra-axis (i.e., + `EpochMs` is a separate algebra, not a refinement). STOP; + surface to Substrate Mgr. +- **v2-refinement-syntax-blocker reopens** (per + `r3-structure.md` T-Numeric-Construction internal cascade + on T-V2-Retirement): coordinate with PB Mgr (#1742) on + v2 retirement sequencing. T-Numeric-Construction has named + T-V2-Retirement-landing-first dependency for path-(a) + v2-refinement-syntax-blocker resolution. +- **Practice 4 classification flags a refinement as + hand-declared mirror of compiler-internal type**: STOP. + Per modeling-discipline P1, hand-declared mirrors require + named dissolution trigger. Author the dissolution trigger + before landing the SCAFFOLD-marked carrier. +- **`Char` refinement requires unicode-codepoint validity + predicate that exceeds Refined<...> substrate**: defer + to a `Char`-specific carrier (e.g., + `data Char = UnicodeCodepoint`) following P1 procedure. + +## Authority audit receipt + +1. **Substrate exists?** Algebra carriers (`Group`, `AbelianGroup`, + `Monoid`) likely exist in `dsl/std/algebraic_structures.dag` + (worker re-greps at dispatch). `Int` / `UInt` may exist as + concrete primitives needing migration; `Refined` + substrate landed per annotation-elimination Wave 1 (memory note + 2026-02-26). The 10 Int-inherited refinements may have partial + landed surfaces (e.g., `HttpStatus`, `Port` may exist in HTTP + domain modules); worker greps + reframes as migration where + applicable. +2. **Existing brief?** S3 (`MachineConstraint`) and S8 + (`ApproximateField` Float migration) are companion briefs. + This brief is the broader T-Numeric-Construction parent; + S3 + S8 cover specific axes. Brief explicitly references + both; sequencing handoffs documented in STOP-AND-ESCALATE. +3. **Design-doc match?** No design-doc specifically for + T-Numeric-Construction; lane reframe (2026-05-01 from + T-Int128) is the originating authority. Substrate Mgr canvas + B2 + roadmap row are the design surface. +4. **Citations live?** `r3-design-schedule-2026-05-06.md §1 S9` + verified at HEAD 2026-05-06. +5. **Carrier dissolves the bridge?** Yes — current substrate + models `Int` / `UInt` / `Float` as primary primitives + (carrier-modeling fault per Brian directive). This brief + reframes them as products of algebra × machine axes. + Refinements consume `Refined` substrate + consistently. Cementing demonstration is gate #67 + (numeric_construction_demonstration), folded into Acceptance. + +## Provenance + +Drafted 2026-05-06 per R3 design schedule §1 S9 (PR #1810) + +Substrate Mgr canvas B2 ratified for parallel authoring. +Coordinates with S3 + S8 cross-axis briefs. Worker pin TBD +(idle pool: loyal-wolf-828 reserved for S7 PR-F; valiant-ant-72 +reserved for S3 implementation; smart-ram-167 reserved for S11 +Slice C). T-Numeric-Construction worker pin assignment surfaces +post-S3/S8 dispatch as idle pool refreshes. From 9db003d403ecaea9273f057a52e80d9ce6a60166 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 05:19:37 +0000 Subject: [PATCH 25/52] docs(briefs): normalize Practice 4 citation in S3 brief per codex review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex review on PR #1782 (sha 2614217e) flagged stale citation "Practice 4 (Step 4 of the type-introduction checklist)" in S3 brief — no such checklist step exists in the pinned rubric. Live rule per docs/modeling-discipline.md:131-134 is the "What to check" checkpoint-comment requirement under Practice 4 (coproduct dissolution). Updated the S3 reference to cite that line directly and drop the stale "Step 4 of type-introduction checklist" wording. S2/S8/S9 already use bare "Practice 4" without the stale steps wording. S1 (committed earlier today) does not contain the stale phrase. S6 (pre-existing brief flagged by reviewer as carrying the same pattern) is out of this branch's scope; flag for separate paydown. --- .../r3-substrate-s3-machine-constraint-carrier-worker.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/briefs/r3-substrate-s3-machine-constraint-carrier-worker.md b/docs/briefs/r3-substrate-s3-machine-constraint-carrier-worker.md index 5b2d50d3f61..cbebd95e834 100644 --- a/docs/briefs/r3-substrate-s3-machine-constraint-carrier-worker.md +++ b/docs/briefs/r3-substrate-s3-machine-constraint-carrier-worker.md @@ -50,9 +50,11 @@ landing). 1. **Author `dsl/std/machine_constraints.dag`** introducing: Each new coproduct / sum declaration MUST carry a 🟢/🟡/🔴 - classification annotation per `docs/modeling-discipline.md` - Practice 4 (Step 4 of the type-introduction checklist; - `INVARIANTS.md#p1-modeling-faithfulness` worked example). + checkpoint-comment classification per `docs/modeling-discipline.md` + Practice 4 (coproduct dissolution; the "What to check" rule at + `docs/modeling-discipline.md:131` — checkpoint comment naming + classification, ledger entry if GREEN, named trigger if YELLOW). + Implements `INVARIANTS.md#p1-modeling-faithfulness`. - `MachineWidth` — phantom-parameter carrier; `bits: Nat`. **🟢 PRIMITIVE** — width values are Nat-valued; the carrier From 2dc92f34fab7e47f8ad9a3bc53640e131ed22949 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 05:21:32 +0000 Subject: [PATCH 26/52] docs(briefs): sweep stale Practice 4 citations corpus-wide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex review on PR #1782 flagged the stale "Step 4 of the type-introduction checklist" wording — no such checklist exists in docs/modeling-discipline.md. The live rule is the "What to check" checkpoint-comment requirement under Practice 4 (coproduct dissolution) at docs/modeling-discipline.md:131. Sweep across docs/ found 2 additional briefs carrying the stale phrasing (S3 fixed previously at 9db003d40): - docs/briefs/r3-l6-emission-path-projection-substrate-worker.md - docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md Both updated to cite the live rule directly. Verified zero remaining "type-introduction checklist" or "Step 4 of the" references in docs/ tree. --- .../r3-l6-emission-path-projection-substrate-worker.md | 8 +++++--- .../r3-x1b-s1-transform-dispatch-substrate-worker.md | 3 ++- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md index 6662a2aacb5..10da1472a1c 100644 --- a/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md +++ b/docs/briefs/r3-l6-emission-path-projection-substrate-worker.md @@ -34,9 +34,11 @@ follow-up row-population PR + `coverage.rs` conversion (per §4.D=(b)). 1. Author new file `src/v3/std/cross_target_coverage.dag` containing: Each new coproduct / sum declaration MUST carry a 🟢/🟡/🔴 - classification annotation per `docs/modeling-discipline.md` - Practice 4 (Step 4 of the type-introduction checklist; - `INVARIANTS.md#p1-modeling-faithfulness` worked example). + checkpoint-comment classification per `docs/modeling-discipline.md` + Practice 4 (coproduct dissolution; the "What to check" rule at + `docs/modeling-discipline.md:131` — checkpoint comment naming + classification, ledger entry if GREEN, named trigger if YELLOW). + Implements `INVARIANTS.md#p1-modeling-faithfulness`. The classifications below are pre-determined; worker copies them verbatim into the live source: diff --git a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md index ef2c2f8398a..e038a2a1f5d 100644 --- a/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md +++ b/docs/briefs/r3-x1b-s1-transform-dispatch-substrate-worker.md @@ -80,7 +80,8 @@ substitute for the audit. **Practice 4 dissolution-ledger marks (mandatory on the live declaration).** Per `docs/modeling-discipline.md` Practice 4 - (Step 4 of the type-introduction checklist), each variant of + (coproduct dissolution; "What to check" rule at + `docs/modeling-discipline.md:131`), each variant of the new `TransformDispatch` enum MUST carry its 🟢/🟡/🔴 mark as a doc comment on the variant itself, copying the per-variant ledger from `design-prereq-x-ho-field-call.md` §Prereq-X1 From 0ecd4818148452afc16ad2c8249297426bb129f7 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 05:23:22 +0000 Subject: [PATCH 27/52] docs(briefs): add Practice 4 citation discipline note to authoring checklist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per parent inbox status flag at gunbc#828 #issuecomment-4385346221: add a Citation discipline section to brief-authoring-checklist.md naming the correct shape — Practice 4 (coproduct dissolution) + "What to check" rule at docs/modeling-discipline.md:131 — and calling out the stale "Step 4 of the type-introduction checklist" phrasing as a failure mode. References the corpus sweep at 2dc92f34f. Prevents future briefs that copy old templates from re-introducing the stale citation pattern. --- docs/briefs/brief-authoring-checklist.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/briefs/brief-authoring-checklist.md b/docs/briefs/brief-authoring-checklist.md index 44882444633..f1d7a937876 100644 --- a/docs/briefs/brief-authoring-checklist.md +++ b/docs/briefs/brief-authoring-checklist.md @@ -74,6 +74,26 @@ Before authoring any of the brief sections above, answer **all five** in writing **Examples from #836:** - B4.2 fold_step_formal: brief assumed bridge skips on step-formal binding. Worker pre-flight audit revealed bridge actually skips on accumulator/element type eligibility. Carrier addressed wrong question. Brief reframed. +## Citation discipline — Practice 4 / modeling-discipline references + +**Cite the live rule, not a fabricated checklist step.** When a +brief requires the worker to mark new coproduct / sum declarations +with a 🟢/🟡/🔴 classification, cite **Practice 4 (coproduct +dissolution)** and the **"What to check" rule at +`docs/modeling-discipline.md:131`** (checkpoint comment naming +classification, ledger entry if GREEN, named trigger if YELLOW). + +Do **not** cite "Step 4 of the type-introduction checklist" — there +is no such checklist in `docs/modeling-discipline.md`. The doc lists +4 dissolution patterns (set-membership / closed-set-tag / algebraic +form / dimensional) and the checkpoint-comment rule is the +"What to check" stanza at line 131, not a fifth step. + +**Failure mode**: codex review on PR #1782 (2026-05-06) flagged the +stale wording across multiple briefs; corpus sweep landed at +`2dc92f34f`. Future briefs that copy old templates should normalize +the citation before landing. + ## Audit receipt format The PR body that lands the brief must include a short audit receipt: From 811de219fa03da4c8f87c0c148ad122ebee6e78a Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Wed, 6 May 2026 05:29:54 +0000 Subject: [PATCH 28/52] =?UTF-8?q?docs(r3):=20cascade=20work=20post-Directo?= =?UTF-8?q?r=20ratification=20=E2=80=94=20S1=20worker,=20R4=20routing,=20U?= =?UTF-8?q?nit/Quantity=20canvas?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per Director ratification at gunbc#828 inbox response 2026-05-06 (zesty-bear-812): 1. S1 Q1+Q2 RATIFIED → author S1 gap-test representative worker brief (`r3-substrate-s1-gap-test-representative-worker.md`). Dispatchable on T-E-P Phase 1 + E6-G0d landing; closes ledger row #61. 2. S2 Q2 RATIFIED (option-(b) T-LBP narrowing) + S3 + S8 deferrals → R4 carve-out routing ledger (`docs/r4-carve-out-routing.md`). Captures C1 (parallelism lens), C2 (effect_enum lens), C3 (register narrowing), C4 (deferred MachineConstraint axes), C5 (rounding-mode product extension), C6 (Unit/Quantity). Cascade messages to Verification / Grounding / Debt-Paydown Mgrs. 3. S9 Phase-3 dimensional refinement boundary → Unit/Quantity carrier canvas (`r3-substrate-s9-unit-quantity-carrier-canvas.md`). Surfaces Q-Unit-1..5 for Director ratification: carrier name, 2-axis vs 3-axis Phase-1, Duration/Seconds collapse, Refined composition order, Practice 4 classification. Updates §1.8 ledger receipts for carved items; R3 closure receipts treat carved items as explicitly-deferred (not drift). --- ...trate-s1-gap-test-representative-worker.md | 190 +++++++++++++ ...bstrate-s9-unit-quantity-carrier-canvas.md | 255 ++++++++++++++++++ docs/r4-carve-out-routing.md | 171 ++++++++++++ 3 files changed, 616 insertions(+) create mode 100644 docs/briefs/r3-substrate-s1-gap-test-representative-worker.md create mode 100644 docs/briefs/r3-substrate-s9-unit-quantity-carrier-canvas.md create mode 100644 docs/r4-carve-out-routing.md diff --git a/docs/briefs/r3-substrate-s1-gap-test-representative-worker.md b/docs/briefs/r3-substrate-s1-gap-test-representative-worker.md new file mode 100644 index 00000000000..402efc99fac --- /dev/null +++ b/docs/briefs/r3-substrate-s1-gap-test-representative-worker.md @@ -0,0 +1,190 @@ +--- +status: draft (worker brief; dispatch-blocked on T-E-P Phase 1 landing + E6-G0d landing per S1 canvas trace-to-GREEN) +authority parent: R3 Substrate Manager (#1739) +ratification: Director ratified S1 Q1+Q2 at gunbc#828 inbox response 2026-05-06 (zesty-bear-812; "Narrowed gap-test (function-valued data + evaluator consumption; lens-behavior out of scope) is correct as Class 2 closure"); ledger row #61 reframes RED → DECLARED YELLOW +roadmap row: docs/r3-program-plan.md §1.8 ledger row #61 (substrate_gap_function_valued_data_closed) +authority docs: + - docs/briefs/r3-substrate-s1-q-class-2-chain-break-gap-test-canvas.md (canvas this brief consumes) + - docs/r3-program-plan.md §10.3 Q-Class-2-Chain-Break (Director disposition + ratification record) + - docs/r3-structure.md:174 (Class 2 gap-test definition) + - docs/briefs/r3-pr-e6-g0d-constructor-runtime-execution-worker.md (Evaluator E1 prerequisite) + - docs/briefs/r3-t-e-p-producer-broadening-worker.md (T-E-P Phase 1 prerequisite) +gates: + - substrate_gap_function_valued_data_closed (#61) +--- + +# R3 Substrate S1 — Class 2 gap-test representative worker brief + +## Context + +Director ratified the option-(a) narrowed gap-test surface from S1 +canvas: function-valued `data` declaration consumed by evaluator +(via E6-G0d / `Callable` runtime path) producing a `Value` result, +asserting "evaluator executes function-valued data path" without +requiring any specific lens to reach BEHAVIORALLY COMPLETE. + +This brief lands the **representative `.dag` test program + assertion +predicate** that closes ledger row #61. The substrate fact under +test is "function-valued data is first-class"; the test is +deliberately decoupled from lens-behavior axes. + +**Dispatch is gated** on two prerequisite landings: +1. **T-E-P-Producer-Broadening Phase 1** (`per_call_descent_evidence` + full coverage) — descent-evidence side-table is the substrate the + evaluator path may consume for the representative. +2. **Evaluator E6-G0d** (`Callable` runtime execution in + `eval_transform_node` / `eval_call`) — the runtime path the test + exercises. Currently DISPATCHED to valiant-carp-10 via #1767. + +Worker confirms both prerequisites at HEAD before proceeding. + +## Slice + +### Phase 1 — Representative `.dag` source + +1. Author `dsl/tests/r3/class_2_function_valued_data.dag` (or under + the canonical `.dag` test fixture root; worker greps for the + project's representative-test convention at dispatch). + +2. Test program shape: + + ``` + // Function-valued data — the substrate fact under test. + data add_one: Int -> Int = fn(x: Int) -> Int { x + 1 } + + // Consume function-valued data via apply. + func test_function_valued_data() -> Int { + add_one(41) + } + ``` + + Exact syntax aligns to current DSL grammar (worker greps existing + `func` + `data` + `Arrow` test fixtures for canonical authoring). + The decisive structural property: `add_one` is declared as + **top-level `data` with `Arrow` type and function body**, NOT + as a `func` declaration. This is what makes it function-valued + data rather than a callable-by-name function. + +3. Expected runtime behavior: `test_function_valued_data()` evaluates + to `42` (`Int`-valued). + +### Phase 2 — Evaluator-path assertion + +The closure predicate for ledger row #61 is "evaluator executes +function-valued data path producing `Value` without Rust mediation." +The assertion has two arms: + +1. **Positive arm — runtime evaluation produces correct result.** + Run the representative through E6-G0d evaluator path; assert + output `Value` equals `Value::Int(42)`. + +2. **Routing arm — evaluator dispatches through `eval_call` / + `eval_lens_apply` (or equivalent) using only descent-evidence + substrate facts.** Assert no Rust-side fallback is invoked + (e.g., no `unimplemented!` / `todo!` / Rust-mediated identity + passthrough). The "no Rust mediation" predicate is structural: + the runtime path traces through DSL-substrate-defined operations + only. + +Worker authors the assertion in the project's canonical test harness +(likely `cargo test -p gunbc-codegen` or `cargo test -p v2-compiler-tests` +depending on where Class-2 representative tests slot; greps at +dispatch). + +### Phase 3 — Cementing test discipline + +Per `r3-structure.md` Class 2 closure definition: gap-test must +demonstrate the substrate fact under named conditions. Cementing +discipline requires: + +1. Test runs deterministically — no timing/network/random + dependencies. The representative is closed-form integer arithmetic. +2. Test is idempotent — reruns produce same result. +3. Test is in `cargo test --workspace` default invocation (not + `--ignored`); CI runs it on every push. + +If test infrastructure currently routes Class 2 representatives +through a separate harness (e.g., `cargo test -p v2-compiler-tests`), +worker preserves that routing — do NOT reframe test infrastructure +as part of this slice. + +## Acceptance + +- `dsl/tests/r3/class_2_function_valued_data.dag` (or canonical + equivalent path) lands with the representative program. +- Evaluator-path assertion lands in canonical test harness; positive + + routing arms both pass. +- `cargo test --workspace --exclude v2-compiler-tests` green; + representative test included in default invocation. +- §1.8 ledger row #61 status moves DECLARED YELLOW → CONSUMER_LANDED + (representative + assertion landed) → PASSING (both arms green + + cementing discipline verified). +- ROADMAP / structure receipt: Class 2 substrate-gap closes per the + narrowed gap-test surface; no T-LBP load-bearing for Class 2. +- `cargo clippy --all-targets -- -D warnings` clean. +- `cargo fmt --all --check` clean. + +## STOP-AND-ESCALATE + +- **T-E-P Phase 1 lands but `per_call_descent_evidence` does not + produce the substrate-fact the evaluator path consumes for + function-valued data**: the prerequisite chain has a gap. + STOP — surface to Substrate Mgr (#1739). Phase 1 may need + additional `CallPattern` / `SubValueRelation` variants (P1 + procedure for substrate-fact introduction). +- **E6-G0d landing produces `Callable` runtime path but routes + through a Rust-mediated fallback** (e.g., Rust-side identity + passthrough for function-valued data because DSL-side + dispatch is incomplete): routing arm fails. STOP — coordinate + with Evaluator Mgr (#1743) on E6-G0d completion scope. The + routing arm is load-bearing; do not weaken it to "as long as + result is correct". +- **Representative test passes positive arm but routing arm + fails because evaluator dispatches through a `lower_*` / + bridge function**: the bridge is the substrate gap the test + is supposed to surface. STOP — do not bridge the bridge. + Coordinate with Substrate Mgr (#1739) + Evaluator Mgr (#1743) + on the dispatch-path bridge as a substrate finding. +- **Test must be marked `#[ignore]` or routed to a separate + harness to pass**: STOP — Class 2 closure requires green-by- + default. If test is fundamentally not-green-by-default, the + closure predicate is not satisfied. Surface as a finding, + do not declare row #61 PASSING. +- **DSL grammar rejects the `data add_one: Int -> Int = fn(...)` + shape**: the substrate fact under test is "function-valued data + is first-class". If grammar does not support the shape, the + substrate gap is upstream of evaluator-side. STOP — coordinate + with Substrate Mgr; this becomes a parser-grammar finding + (Class 1 cross-pollination). + +## Authority audit receipt + +1. **Substrate exists?** `Arrow` type + `Callable` runtime substrate + exist (per memory notes + per existing `func` / lambda fixtures); + worker re-greps `dsl/std/types.dag` + `src/v3/compiler/src/dag.rs` + at dispatch to confirm. Top-level `data X: Arrow = fn(...)` shape + may or may not be exercised by existing fixtures — worker + confirms representative-shape-novelty vs precedent at dispatch. +2. **Existing brief?** S1 canvas (`r3-substrate-s1-q-class-2-chain-break-gap-test-canvas.md`) + is the upstream design canvas; this brief is the worker dispatch + per Director Q1+Q2 ratification. No competing brief. +3. **Design-doc match?** Director ratification at gunbc#828 inbox + response 2026-05-06 anchors the Q1 narrowing decision; this brief + structurally matches the ratified scope (lens-behavior out of scope). +4. **Citations live?** S1 canvas references verified at HEAD 2026-05-06. + E6-G0d brief #1784 / T-E-P brief + `r3-t-e-p-producer-broadening-worker.md` referenced for + prerequisite definitions; worker re-verifies at dispatch. +5. **Carrier dissolves the bridge?** N/A — this brief lands a + representative + assertion, not a substrate carrier. The "bridge" + under test is "function-valued data path executes through evaluator + without Rust mediation"; the test surfaces the bridge if any + currently exists, allowing closure or escalation per + STOP-AND-ESCALATE. + +## Provenance + +Drafted 2026-05-06 per Director Q1+Q2 ratification of S1 canvas +(gunbc#828 inbox response 2026-05-06; zesty-bear-812). Dispatch +gated on T-E-P Phase 1 + E6-G0d both landing. Worker pin TBD; +representative test authoring is small (~M sized, likely 1 PR). diff --git a/docs/briefs/r3-substrate-s9-unit-quantity-carrier-canvas.md b/docs/briefs/r3-substrate-s9-unit-quantity-carrier-canvas.md new file mode 100644 index 00000000000..a8347065a00 --- /dev/null +++ b/docs/briefs/r3-substrate-s9-unit-quantity-carrier-canvas.md @@ -0,0 +1,255 @@ +--- +status: draft (Mgr-tier canvas; surfaces design question for Director ratification per S9 Phase-3 boundary feedback) +authority parent: R3 Substrate Manager (#1739) +ratification: Director feedback on S9 at gunbc#828 inbox response 2026-05-06 (zesty-bear-812) — "several Phase-3 refinements are likely dimensional/unit-of-measure, not value-restriction predicates ... the right shape is likely a Unit axis" +roadmap row: cross-references docs/briefs/r3-substrate-s9-t-numeric-construction-worker.md Phase-3 +authority docs: + - docs/briefs/r3-substrate-s9-t-numeric-construction-worker.md (parent S9 brief) + - feedback_reason_not_label (the discipline this canvas applies) + - INVARIANTS.md#p1-modeling-faithfulness (substrate-fact-introduction procedure) + - docs/r4-carve-out-routing.md C6 (R4 routing if Unit/Quantity defers) +gates: cross-references §1.8 ledger rows #20-#23 (refinements that may reframe) +--- + +# R3 Substrate S9 Phase-3 — Unit/Quantity carrier canvas + +## Purpose + +Director feedback on S9 (gunbc#828 inbox response 2026-05-06) flagged +that several Phase-3 refinements are not value-restriction predicates +but **dimensional / unit-of-measure** semantics: + +- `Duration` — carries time-quantity +- `Milliseconds` — carries time-quantity at milli-scale +- `Seconds` — carries time-quantity at unit-scale +- `EpochMs` — carries time-instant at milli-scale (different + conceptual axis: instant vs duration) + +Forcing these through `Refined` is a +`feedback_reason_not_label` violation: the predicate name is the +label, not the reason. The reason for `Milliseconds` is "this +carries time-unit semantics at milli scale", not "this Int satisfies +some Boolean predicate P". + +This canvas surfaces the design question for Director ratification. +**Output**: a ratified `Unit` (or equivalent) +carrier shape; S9 Phase-3 reframes from `Refined` for +the dimensional refinements; remaining 6 refinements (`Char`, +`HttpStatus`, `Port`, `RetryCount`, `PositiveInt`, `NonNegativeInt`) +proceed under `Refined` shape unchanged. + +## Candidate carrier shape + +### Sketch — 2-axis `Quantity` × `Scale` + +``` +data Quantity = Time | Length | Mass | Memory | Information + | DataRate | Frequency | Count | Currency + +data Scale = + | Atto // 10^-18 + | Femto // 10^-15 + | Pico // 10^-12 + | Nano // 10^-9 + | Micro // 10^-6 + | Milli // 10^-3 + | Unit // 10^0 + | Kilo // 10^3 + | Mega // 10^6 + | Giga // 10^9 + | Tera // 10^12 + | Peta // 10^15 + | Exa // 10^18 + +data Unit = Phantom // 🟢 PRIMITIVE — Q: Quantity, S: Scale +``` + +Phase-3 dimensional refinements emit as products: + +``` +Duration ≡ Quantity