From 02edf043540ce0f665fdaa9ac6376d583a0cf57c Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 22:18:55 -0400 Subject: [PATCH 01/10] WIP: Grounding Manager --- docs/briefs/t-ground-engine-phase-1.md | 151 +++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/briefs/t-ground-engine-phase-1.md diff --git a/docs/briefs/t-ground-engine-phase-1.md b/docs/briefs/t-ground-engine-phase-1.md new file mode 100644 index 00000000000..ba7ef9fb86c --- /dev/null +++ b/docs/briefs/t-ground-engine-phase-1.md @@ -0,0 +1,151 @@ +# T-Ground-Engine — Phase 1 (Pilot-Scope Production Walker) + +**Status**: PROPOSAL — same formal gates as the parent program (R1 all-gates-green closure + R2 promotion of [`docs/r2-structure.md`](../r2-structure.md)). Pilot merge ([PR #765](https://github.com/gunb-ai/gunbc/pull/765), commit `2909f9e05`) is a necessary-not-sufficient signal. Director-discretionary dispatch is honored under the same posture the pilot dispatched under. + +**Lane**: T-Ground-Engine (M) per ROADMAP.md §"Post-R1 Grounding lanes". This brief covers **Phase 1 only** — the pilot-scope subset. Engine grows in subsequent phases as full-reference lanes land (cross-type coercion paths, container types, Python/Go targets). + +**Manager**: R2 Grounding Manager ([`docs/briefs/grounding-manager.md`](grounding-manager.md)). + +**Parent context**: pilot brief inheritance lives in [`PR #765`](https://github.com/gunb-ai/gunbc/pull/765) (merged commit `2909f9e05`). Read its merged state, not the original brief — the structural fix from the codex P2 adjudication landed and changes the inherited shape. + +--- + +## Orient before working + +1. **PR #765 — the pilot.** Read [`src/v3/grounding_pilot/src/lib.rs`](../../src/v3/grounding_pilot/src/lib.rs) end-to-end. **You are replacing this crate with the production walker.** The pilot's contract is your inheritance. +2. **[`dsl/extdeps/languages/rust/primitives.dag`](../../dsl/extdeps/languages/rust/primitives.dag).** The structural authority. Note: `RustPrimitive` is a **sum type** (`IntegerPrimitive | NonIntegerPrimitive`), partitioned so overflow-bearing state-space is structurally separated from non-overflow. State-space discipline is load-bearing — see "Inherited from pilot" below. +3. **[`dsl/std/integer.dag`](../../dsl/std/integer.dag), [`dsl/std/algebra.dag`](../../dsl/std/algebra.dag), [`dsl/std/bit.dag`](../../dsl/std/bit.dag).** The .dag-side authority for unfolding user types (`Int8`..`UInt64`, `Bool`, `Unit`) into `(algebra, carrier)` facts. The pilot's `dag_type_facts` function mirrors these — your job is to consume them directly. +4. **[`docs/thesis/target-grounding-proposal.md`](../thesis/target-grounding-proposal.md).** Minimum-satisfier discipline, fail-closed tie-breaking with structured diagnostics, the three-way L4 split. +5. **[`docs/single-emitter-design.md`](../single-emitter-design.md).** The architectural design Engine operationalizes: "the mapping should fall out from the algebra, not from a hand-maintained table." +6. **[`MODELING.md`](../../MODELING.md)** (especially M9: DFS the concept DAG) and **[`INVARIANTS.md`](../../INVARIANTS.md).** Same governing rules as pilot. +7. **Pilot receipt** (manager-authored, in flight at the time of dispatch — check `docs/briefs/grounding-pilot-receipt.md` or successor) — captures the four headline lessons Engine inherits. + +--- + +## Framing question this lane (Phase 1) answers + +Can the production walker consume `.dag` declarations directly via the v3 substrate, retain the pilot's parity guarantees (zero mismatches on Stratum A + canonical extension on Stratum B across the 10 pilot types), and inherit the pilot's fail-closed contract (`Ambiguous` + `NoInhabitant`) — **without** mirroring facts as Rust constants? + +A "yes" greenlights the pilot crate's deletion (T-Ground-Dissolve scope expansion already committed). A "no" routes the substrate gap to manager → Director. + +--- + +## Inherited from pilot (carry-forwards Engine must honor) + +These are not optional. The pilot established them empirically; Engine inherits them as design contracts. + +1. **Mirroring is forbidden.** The pilot's `dag_type_facts` and `RUST_PILOT_PRIMITIVES` mirror `.dag` facts as Rust constants. This was a pilot-scoped concession with explicit hand-sync risk flagged in three places. **Engine must consume the `.dag` declarations directly.** Eliminating mirroring is the load-bearing scope of this lane — without it, Engine is just "pilot at scale." +2. **State-space discipline.** `RustPrimitive`'s sum-type partition (`IntegerPrimitive | NonIntegerPrimitive`) makes illegal combinations (`bool: Some(TwoComplementWrap)`, `i64: None`) unrepresentable. Engine must preserve this — variant-aware walker handling, no widening to a flat record. Per the codex P2 adjudication on PR #765 ([`comment 4317414841`](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317414841)). +3. **Fail-closed by construction.** `GroundingError::{Ambiguous, NoInhabitant}` plus `pilot_primitives_have_unique_algebra_carrier_keys` and `missing_inhabitant_fails_closed` tests. Pilot deferred minimum-satisfier discipline to Engine; Engine ships it. Bare-vector candidates list is the floor; Engine produces a real diagnostic per the proposal's L4 surface. +4. **SG-0 ratchet untouched.** Pilot lived as a sibling crate (`src/v3/grounding_pilot/`) to avoid bumping the SG-0 hand-Rust ratchet on `src/v3/compiler/`. Engine inherits the same constraint — see the Phase 0 audit below for where Engine lives. + +--- + +## Phase 1 scope + +**Same routing surface as pilot — 10 Rust primitive types.** Engine-Phase-1 is not a scope expansion; it's a substrate-integration upgrade. + +### Phase 0 — substrate audit + design decision + +Before implementation, audit where Engine lives. Three options, ordered by project-thesis alignment: + +- **(a) `.dag`-defined walker** (e.g., `dsl/grounding/engine.dag`). Cleanest, no SG-0 ratchet issue, fully aligned with the project's "compiler operations are `.dag` programs" thesis. **Requires audit**: can the v3 substrate today model: + - Loading `rust_pilot_primitives: List` as a value to walk? + - Pattern-matching `RustPrimitive`'s sum variants to extract `algebra` and `carrier` fields (the variant-tagged algebra means matching has to dispatch on variant)? + - Filtering by structural equality on `(algebra, carrier)` — note algebra is variant-typed (`IntegerAlgebra` vs `NonIntegerAlgebra`), so equality is heterogeneous? + - Returning a `Result` (or the structural equivalent — sum type carrying the structured diagnostic)? + + If yes, this is the destination. + +- **(b) Sibling crate** (e.g., `src/v3/grounding_engine/`). Extends the pilot's pattern; fastest path; defers the `.dag`-walker question. Acceptable **only if** (a)'s substrate audit fails — flag the gap that blocks (a) so manager can coordinate substrate work with Director. + +- **(c) `src/v3/compiler/`.** **REJECTED** — SG-0 hand-Rust ratchet. Do not propose. + +The PR description must lead with the audit result and the resulting choice. **Do not skip the audit** — defaulting to (b) without auditing (a) is the missing-modeling pattern called out in `feedback_model_before_fixing.md`. + +Audit deliverable: write up findings in `docs/r2-grounding/engine-substrate-audit.md` (≤ 300 lines, create the directory if it doesn't exist). Conclude with (a) or (b), with substrate-gap flags if (b). + +If (b), the substrate gaps surfaced are escalation-class — flag to manager, do not invent workarounds. + +### Phase 1 — production walker + +Implement the walker per the audit's choice. Required behavior: + +- **Direct `.dag` consumption.** No Rust-constant mirror of `rust_pilot_primitives`, no Rust-constant mirror of std-side type-mappings. The pilot's `RustPrimitive` and `dag_type_facts` mirroring must not survive into Engine. +- **Variant-aware walker.** `RustPrimitive`'s `IntegerPrimitive | NonIntegerPrimitive` partition means routing must dispatch on variant to extract the algebra field. The variant tag is not itself a routing key — search across both variants and match on `(algebra, carrier)` agreement, where algebra equality is heterogeneous across the variant-typed enums (`IntegerAlgebra` vs `NonIntegerAlgebra`). +- **Inherit fail-closed contract.** `Ambiguous` and `NoInhabitant` with structured diagnostic naming candidates (when ambiguous). Pilot's bare-vector candidates list is the floor; Engine produces a real diagnostic per the proposal's L4 surface. +- **Minimum-satisfier selection.** Pilot deferred this; Engine ships it. For pilot scope every key has exactly one satisfier so this is never exercised — but the discipline must be in place for full-reference lanes (containers, cross-type coercion, etc.). + +### Phase 2 — parity tests + +Re-run the pilot's test suite against the production walker. All 10 routing-parity assertions must pass (Stratum A: `Int64→i64`, `Bool→bool`, `Unit→()`; Stratum B: signed widths to `i8`/`i16`/`i32`, unsigned widths to `u8`..`u64`). Plus: + +- **Mirroring-elimination assertion.** Structural test that verifies the walker reads from the `.dag` source — e.g., changing `primitives.dag` changes walker behavior without code edits. This is the load-bearing test for the mirroring-lesson carry-forward. +- **State-space-discipline assertion.** Variant-aware walker correctness: structural test that asserts `IntegerPrimitive`-only fields (`overflow`) are not accessed when routing through a `NonIntegerPrimitive` (or the structural equivalent in the chosen substrate). +- **Diagnostic-quality test.** The `Ambiguous` path produces a structured diagnostic naming all candidates, not a bare vector. + +### Phase 3 — pilot-crate retirement signal + +This PR **does not** delete `src/v3/grounding_pilot/` — that's T-Ground-Dissolve scope per the dissolution-expansion line in the pilot's PR body. But it does add a one-line deprecation note to the pilot crate's `lib.rs` header pointing at Engine, so future readers know the pilot's role transitioned to "historical reference." + +--- + +## Out of scope (do NOT do) + +- **Cross-type coercion paths** (UTF-8 String↔FreeMonoid, etc.) — these need full-reference scope; later Engine phase. +- **Container types** — block on cardinality-substrate. +- **Other targets** (Python, Go, dag) — separate full-reference lanes, blocked on substrate. +- **Emit-pipeline wiring.** Escalate to manager. Per program brief: emit-pipeline boundary closes in R1 T-Emit; any post-close amendment routes via Director. **Do not absorb emit-pipeline work into Engine-Phase-1.** +- **Removing the existing table-lookup call sites in emit** — T-Ground-Dissolve scope. +- **Touching `dsl/std/coercion.dag`** — T-Ground-Dissolve scope. +- **Deleting `src/v3/grounding_pilot/`** — T-Ground-Dissolve scope. This PR adds a deprecation note only. +- **Widening `RustPrimitive` back to a flat record** — locked structural decision per codex P2 adjudication on PR #765. + +--- + +## Hand-off discipline + +Escalate to manager (do **not** absorb in lane) if: + +- **Phase 0 audit concludes (b) is required** because the v3 substrate can't model the walker in `.dag`. This is a substrate-capability question manager routes to Director — substrate work may need to pre-empt or run in parallel with Engine implementation. +- **Phase 1 reveals a `.dag`-substrate gap not visible in the audit** (e.g., loading data-tables-as-values blows up at integration; pattern-matching variants of `RustPrimitive` works in the audit but not when integrated with the rest of the substrate). +- **Phase 2 reveals a parity divergence from pilot** — same escalation as pilot's brief: routing-parity failure routes to Director for proposal amendment. +- **Anything would require touching the emit pipeline.** +- **DSL-side type unfolding requires a new concept in `dsl/std/`** — escalate; concept additions to std should be reviewed at the std-authority level, not absorbed in Engine scope. + +Per `feedback_root_causes_over_quick_fixes.md`: no quick fixes. If Engine is blocked, escalate; do not patch. + +--- + +## Acceptance + +PR lands with: + +- `docs/r2-grounding/engine-substrate-audit.md` documenting the (a) vs (b) decision and any substrate-gap flags. +- Production walker in the chosen location, consuming `.dag` directly, no Rust-constant mirror. +- Variant-aware routing across `IntegerPrimitive | NonIntegerPrimitive`. +- 10/10 routing-parity tests passing against the production walker. +- Mirroring-elimination test (changes to `primitives.dag` change walker behavior without code edits). +- State-space-discipline test (variant-aware walker correctness). +- Diagnostic-quality test (`Ambiguous` produces structured diagnostic, not bare vector). +- One-line deprecation note in `src/v3/grounding_pilot/src/lib.rs` pointing at Engine. +- PR body covers: audit conclusion, design choice, substrate-gap flags (if any), parity confirmation, mirroring-elimination demonstration. +- `cargo test --workspace --exclude v2-compiler-tests`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt --all --check` all clean. +- Per `feedback_test_timeout_2s.md`, all tests sub-second. +- Per `TESTING.md`, hermetic, behavior-driven, unit-first. + +--- + +## What unblocks on merge + +- **Manager** updates working-state checklist; T-Ground-Dissolve checklist gains a confirmed entry to delete `src/v3/grounding_pilot/`. +- **T-Ground-Tests** dispatch becomes possible once Engine + at least one full-reference lane reaches parity. Engine alone is necessary-not-sufficient for Tests dispatch (Tests' L4 witness-based certification needs full-reference scope to assert against). +- **No automatic full-reference unblocking** — T-Ground-Rust / -Python / -Go still block on DB-11 closure (refinement substrate) and cardinality-substrate. Engine-Phase-1 merge does not change those gates. + +--- + +## Notes (informational, no action required) + +- Pilot's `selection_is_by_algebra_homomorphism_not_name` test is the assertion that future receipt readers should look at to understand what pilot proved. Engine should keep an equivalent test alive — the architectural claim under validation is unchanged. +- Pilot's `pilot_primitives_have_unique_algebra_carrier_keys` test is the structural pre-condition for single-satisfier match. At pilot scope it's always true; full-reference scope may introduce intentional ambiguity (e.g., `i64` and `isize` both inhabit OrderedRing on 64-bit platforms). When that lands, minimum-satisfier discipline is what disambiguates. Engine ships the discipline now even though pilot scope doesn't exercise it. +- Variant naming in `RustPrimitive` (`IntegerPrimitive`/`NonIntegerPrimitive`) was discussed but not blocked at pilot time. If full-reference scope (Float, Decimal) makes `IntegerPrimitive` feel mis-named, renaming is worker discretion at that future scope, not Engine-Phase-1 scope. From a3bc3c3cefe42f06c3b8daec549410bfc6c95ac9 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 22:21:16 -0400 Subject: [PATCH 02/10] docs(t-ground-engine-brief): add fallback pointer for unresolved pilot-receipt forward-reference Address Director draft-review observation on PR #767: the brief referenced docs/briefs/grounding-pilot-receipt.md as a forward-pointer, but that doc isn't yet on main. Worker reading the brief in the intervening window would hit a dead link. Brief now lists the receipt as primary source and PR #765's merged body + specific comment threads as the fallback (LGTM comment 4317308089 for the four-lesson enumeration, codex-P2-adjudication comment 4317414841 for the state-space-discipline lesson). Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/t-ground-engine-phase-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/briefs/t-ground-engine-phase-1.md b/docs/briefs/t-ground-engine-phase-1.md index ba7ef9fb86c..b597a7030fe 100644 --- a/docs/briefs/t-ground-engine-phase-1.md +++ b/docs/briefs/t-ground-engine-phase-1.md @@ -18,7 +18,7 @@ 4. **[`docs/thesis/target-grounding-proposal.md`](../thesis/target-grounding-proposal.md).** Minimum-satisfier discipline, fail-closed tie-breaking with structured diagnostics, the three-way L4 split. 5. **[`docs/single-emitter-design.md`](../single-emitter-design.md).** The architectural design Engine operationalizes: "the mapping should fall out from the algebra, not from a hand-maintained table." 6. **[`MODELING.md`](../../MODELING.md)** (especially M9: DFS the concept DAG) and **[`INVARIANTS.md`](../../INVARIANTS.md).** Same governing rules as pilot. -7. **Pilot receipt** (manager-authored, in flight at the time of dispatch — check `docs/briefs/grounding-pilot-receipt.md` or successor) — captures the four headline lessons Engine inherits. +7. **Pilot receipt.** Manager-authored synthesis of the four headline lessons Engine inherits. **Primary source**: `docs/briefs/grounding-pilot-receipt.md` once authored. **Fallback if not yet on main at the time you read this**: the same lessons are captured in [PR #765's merged body](https://github.com/gunb-ai/gunbc/pull/765) and the LGTM comment thread ([`comment 4317308089`](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317308089) for the four-lesson enumeration; [`comment 4317414841`](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317414841) for the state-space-discipline lesson from the codex P2 adjudication). Read both — receipt is synthesis, the PR thread is the empirical record. --- From 288d3cddd725d208e2792a33833c0252dc131b56 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 22:23:43 -0400 Subject: [PATCH 03/10] docs(t-ground-engine-brief): unify audit-doc location with existing work-product convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address codex API-review observation on PR #767: brief had internal inconsistency — pilot-receipt referenced under docs/briefs/ (existing convention) but engine-substrate-audit referenced under a new docs/r2-grounding/ subdirectory that doesn't exist. Reviewer flagged the new-directory creation as worth confirming intent. Audit moved to docs/briefs/t-ground-engine-substrate-audit.md to match existing convention (siblings: ci-ratchet-architecture-audit.md, file-preference-dependency-audit-2026-04-22.md, complexity-v2-v3-comparison-receipt.md). docs/briefs/ is the established location for manager/worker work-product docs (briefs, audits, receipts). Per feedback_audit_adjacent_authority_first.md, respecting existing convention beats introducing new directory structure. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/t-ground-engine-phase-1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/briefs/t-ground-engine-phase-1.md b/docs/briefs/t-ground-engine-phase-1.md index b597a7030fe..1d77fe44406 100644 --- a/docs/briefs/t-ground-engine-phase-1.md +++ b/docs/briefs/t-ground-engine-phase-1.md @@ -63,7 +63,7 @@ Before implementation, audit where Engine lives. Three options, ordered by proje The PR description must lead with the audit result and the resulting choice. **Do not skip the audit** — defaulting to (b) without auditing (a) is the missing-modeling pattern called out in `feedback_model_before_fixing.md`. -Audit deliverable: write up findings in `docs/r2-grounding/engine-substrate-audit.md` (≤ 300 lines, create the directory if it doesn't exist). Conclude with (a) or (b), with substrate-gap flags if (b). +Audit deliverable: write up findings in `docs/briefs/t-ground-engine-substrate-audit.md` (≤ 300 lines). Conclude with (a) or (b), with substrate-gap flags if (b). The `docs/briefs/` location matches existing convention for manager/worker work-product docs (audits, receipts) — see siblings like `ci-ratchet-architecture-audit.md` and `complexity-v2-v3-comparison-receipt.md`. If (b), the substrate gaps surfaced are escalation-class — flag to manager, do not invent workarounds. @@ -121,7 +121,7 @@ Per `feedback_root_causes_over_quick_fixes.md`: no quick fixes. If Engine is blo PR lands with: -- `docs/r2-grounding/engine-substrate-audit.md` documenting the (a) vs (b) decision and any substrate-gap flags. +- `docs/briefs/t-ground-engine-substrate-audit.md` documenting the (a) vs (b) decision and any substrate-gap flags. - Production walker in the chosen location, consuming `.dag` directly, no Rust-constant mirror. - Variant-aware routing across `IntegerPrimitive | NonIntegerPrimitive`. - 10/10 routing-parity tests passing against the production walker. From 6fd81ea9e597476063e2359106158f96d6a8b1d3 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 22:50:22 -0400 Subject: [PATCH 04/10] =?UTF-8?q?docs(grounding):=20post-pilot=20manager?= =?UTF-8?q?=20bundle=20=E2=80=94=20receipt=20+=20Director=20escalation=20+?= =?UTF-8?q?=20working-state=20update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three R2 Grounding Manager artifacts authored after T-Ground-Pilot merge (PR #765) and T-Ground-Engine-Phase-1 audit merge (PR #768): 1. grounding-pilot-receipt.md — manager-authored synthesis of the five pilot lessons (Stratum-B finding, mirroring-as-substrate-ask, fail-closed contract baseline, SG-0 location reasoning, state-space discipline as full-reference precedent). Receipt is what carries the pilot's empirical findings forward into Engine + full-reference + Dissolve scopes without future workers re-deriving from the PR thread. 2. t-ground-engine-substrate-escalation.md — Director-routed escalation for the substrate gap blocking Engine-Phase-1 implementation. Cites the Phase 0 audit (PR #768) as substantive evidence and recommends Route 3: route the extdeps-loader ask through the Pure Bootstrap to Zero program (PB-1 / PB-Bootstrap-Process scope overlap) rather than as a discrete substrate sub-lane. Engine implementation re-dispatches in (b.i) sibling-crate form once the substrate ask closes. 3. grounding-manager.md — working-state update. Pilot ✅, Engine-Phase-1 audit ✅ + parked, decisions log populated for the first time, Director open question added (substrate routing), Pure Bootstrap to Zero Manager cross-manager notification queued. Status banner amended to reflect Director-discretionary dispatch reality (formal R2 promotion still pending R1 close). No code, substrate, or test changes. Manager-work bundle per feedback_bundle_workstreams_per_pr.md. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/grounding-manager.md | 50 +++--- docs/briefs/grounding-pilot-receipt.md | 109 ++++++++++++++ .../t-ground-engine-substrate-escalation.md | 142 ++++++++++++++++++ 3 files changed, 282 insertions(+), 19 deletions(-) create mode 100644 docs/briefs/grounding-pilot-receipt.md create mode 100644 docs/briefs/t-ground-engine-substrate-escalation.md diff --git a/docs/briefs/grounding-manager.md b/docs/briefs/grounding-manager.md index 4686fe34138..8e68699ffc8 100644 --- a/docs/briefs/grounding-manager.md +++ b/docs/briefs/grounding-manager.md @@ -1,11 +1,13 @@ # R2 Grounding Manager Brief -**Status:** `PROPOSAL` — pending R2 proposal -([`docs/r2-structure.md`](../r2-structure.md), PR #754) merge + -R1 all-gates-green closure. Until then, this brief is the R2 -Grounding Manager's scope-in-preparation; it does not dispatch -work. On R2 promotion, the `PROPOSAL` banner lifts and this brief -becomes the live dispatch authority for the lane. +**Status:** `PROPOSAL` (formal) → `ACTIVE` (Director-discretionary). +Formal R2 promotion still pending R1 all-gates-green closure + +[`docs/r2-structure.md`](../r2-structure.md) promotion to ROADMAP. +Director-discretionary dispatch has been used since 2026-04-25 for +T-Ground-Pilot (PR #765, merged) and T-Ground-Engine-Phase-1 audit +(PR #768, merged). Engine implementation parked pending substrate +routing — see [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). +Working state at the bottom of this brief reflects current dispatch state. ## Orient before reading @@ -248,11 +250,11 @@ to director before dispatching full-reference work. Lane-owner dispatch status (update as sub-deliverables close): -**T-Ground-Pilot:** -- [ ] Rust primitive `.dag` declarations (i8–i64, u8–u64, bool, Unit) -- [ ] Toy inhabitance-search engine -- [ ] Routing-stability tests against pilot set (parity with current table) -- [ ] Pilot receipt document +**T-Ground-Pilot:** ✅ COMPLETE (PR #765 merged 2026-04-25 commit `2909f9e05`; receipt in [`grounding-pilot-receipt.md`](grounding-pilot-receipt.md)) +- [x] Rust primitive `.dag` declarations (i8–i64, u8–u64, bool, Unit) +- [x] Toy inhabitance-search engine +- [x] Routing-stability tests against pilot set (parity with current table) +- [x] Pilot receipt document **T-Ground-Rust:** - [ ] Numeric types (integer, float, character) @@ -278,11 +280,12 @@ Lane-owner dispatch status (update as sub-deliverables close): - [ ] Array, slice, map, struct, pointer - [ ] Function, interface, channel -**T-Ground-Engine:** -- [ ] Inhabitance-search walker -- [ ] Minimum-satisfier selection -- [ ] Fail-closed tie-breaking with structured diagnostic -- [ ] Cross-type coercion paths (e.g., UTF-8 `Char ↔ u8`) +**T-Ground-Engine:** ⏸️ PARKED — Phase 0 substrate audit complete (PR #768 merged 2026-04-25 commit `4afc0d794`); implementation parked pending Director routing of substrate ask. See [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). +- [x] Phase 0 substrate audit (concluded escalation-class) +- [ ] Inhabitance-search walker (Phase 1, blocked on substrate routing) +- [ ] Minimum-satisfier selection (Phase 1) +- [ ] Fail-closed tie-breaking with structured diagnostic (Phase 1; pilot established the contract baseline) +- [ ] Cross-type coercion paths (e.g., UTF-8 `Char ↔ u8`) (Phase 2; blocks on full-reference) **T-Ground-Tests:** - [ ] Routing-stability TestClaim variant declared @@ -299,16 +302,25 @@ Lane-owner dispatch status (update as sub-deliverables close): - [ ] Remove `TypeRealization.carrier: String` field from `src/v3/std/emit_model.dag` - [ ] Remove emit-pipeline call sites reading the old surface - [ ] All test claims assert against the new structural authority (no residual reads of deleted scaffolding) +- [ ] Delete `src/v3/grounding_pilot/` workspace member (scope-expansion confirmed in PR #765) +- [ ] Delete Engine sibling crate if Route 1/3 dispatched as (b.i) (scope-expansion contingent on Director routing) - [ ] Track 13 closure PR lands — single step Decisions log (append as they happen): -- _(none yet)_ +- **2026-04-25** — Pilot dispatched and merged under Director-discretionary dispatch (R2 promotion gates not yet formally fired). PR #765. +- **2026-04-25** — Pilot lessons synthesized into [`grounding-pilot-receipt.md`](grounding-pilot-receipt.md). Five carry-forwards: Stratum-B finding, mirroring-as-substrate-ask, fail-closed contract baseline, SG-0 location reasoning, state-space discipline as full-reference precedent. +- **2026-04-25** — Pilot's `RustPrimitive` partition (`IntegerPrimitive | NonIntegerPrimitive`) locked as full-reference precedent shape via codex P2 adjudication. Future widening to flat record is out of scope. +- **2026-04-25** — Engine-Phase-1 brief landed (PR #767, `t-ground-engine-phase-1.md`). Audit-first discipline; no Rust-constant mirroring; variant-aware walker; SG-0 untouched. +- **2026-04-25** — Engine-Phase-1 Phase 0 audit landed (PR #768, `t-ground-engine-substrate-audit.md`). Conclusion: both options (a) and (b) block on the same substrate gaps; escalation-class. Engine implementation parked. +- **2026-04-25** — Engine substrate ask escalated to Director via [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). Manager recommends Route 3: route Gap 1 close through Pure Bootstrap to Zero program (PB-1 / PB-Bootstrap-Process scope overlap). Open questions for director: -- _(none yet — program is pre-dispatch)_ +- **Engine substrate routing** — Route 1 / 2 / 3 / 4 per [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). Manager recommends Route 3. +- **R2 promotion timing** — formally still PROPOSAL pending R1 all-gates-green closure. R1 Census Close landed (PR #763) but Director-discretionary dispatch has been used for Pilot + Engine-Phase-1-audit. Consider formalizing the promotion or making the discretionary mode explicit in `r2-structure.md`. Cross-manager notifications queued: -- _(none yet — awaits R1 close + substrate-capability closure signals from Surface and Testgen Managers)_ +- **Pure Bootstrap to Zero Manager** (PR #766) — substrate ask: extdeps-load + Declaration accessor for `dsl/extdeps/languages/*/primitives.dag`. Surface on Director Route 3 endorsement (or pre-coordinate if Director endorses pre-coordination). See escalation doc §"Concrete ask." +- **Surface / Testgen Managers** (R1, archived on R1 close per `r2-structure.md`) — pilot's fail-closed-by-construction shape (`GroundingError::{Ambiguous, NoInhabitant}`) is general-purpose, not Grounding-specific. If their wind-down work hasn't closed yet, this shape is reusable as a contract baseline. diff --git a/docs/briefs/grounding-pilot-receipt.md b/docs/briefs/grounding-pilot-receipt.md new file mode 100644 index 00000000000..d9d4d3f2e53 --- /dev/null +++ b/docs/briefs/grounding-pilot-receipt.md @@ -0,0 +1,109 @@ +# T-Ground-Pilot — Receipt + +**Status**: COMPLETE. Pilot lane closed via [PR #765](https://github.com/gunb-ai/gunbc/pull/765) (merged commit `2909f9e05`, 2026-04-25). + +**Purpose**: capture the lessons the pilot established empirically, so they carry forward into Engine + full-reference + Dissolve scopes without requiring future workers to re-derive them from the PR thread. Manager-authored synthesis per the [grounding-manager brief](grounding-manager.md) ("Pilot deliverable #4 — manager scope, not worker scope"). + +**Audience**: T-Ground-Engine workers (any phase), T-Ground-Rust / -Python / -Go workers (when substrate unblocks), T-Ground-Tests workers, R2 Grounding Manager (working-state inputs), Director (program-scope review). + +--- + +## Framing question the pilot answered + +*Does inhabitance-search routing — consuming structural target-primitive declarations and selecting by algebra-homomorphism — produce the same target-primitive selection as today's name-keyed table lookup, on a small Rust pilot set?* + +**Answer**: Yes, with a finding. Routing parity stratifies into two strata: + +- **Stratum A** (3 of 10 pilot types — `Int(=Int64)→i64`, `Bool→bool`, `Unit→()`): exact match against today's `rust_type_checkpoints`. +- **Stratum B** (7 of 10 — `Int8/16/32`, `UInt8`–`UInt64`): engine produces canonical width-correct primitive that the name-keyed table cannot reach. The fallback `OrderedRing→i64` algebra-inhabitant is width-blind (would mis-route `Int8` to `i64`); `Semiring` has no inhabitant declared at all (unsigned types fail-closed today). + +The proposal's central architectural claim — *structural `(algebra, carrier)` matching strictly subsumes name-keyed lookup* — was empirically demonstrated. The proposal did not need amendment. + +--- + +## The five lessons + +These are the carry-forwards. Each cites its empirical source (the PR commit or comment that produced it) and names where the lesson routes forward. + +### Lesson 1 — Stratum-B finding: full-reference scope is larger than implicit baseline + +**What we learned.** Today's table-driven coercion surface (`dsl/extdeps/languages/rust/types.dag`'s `rust_type_checkpoints` + `rust_algebra_inhabitants`) covers far less than the implicit baseline assumed. Of the 10 pilot types, only 3 have name-keyed routing entries; 7 either mis-route via width-blind fallbacks or fail-closed entirely. + +**Source.** [PR #765 body — "Parity finding (pilot-success signal, not an escalation)"](https://github.com/gunb-ai/gunbc/pull/765); [LGTM comment 4317308089](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317308089). + +**Forward routing.** T-Ground-Rust / -Python / -Go workers and brief authors must internalize: *the full-reference lanes' true scope is "model the language reference's primitives" + "extend routing onto previously fail-closed surface."* The latter is invisible from the existing tables — it only becomes visible by enumerating the language reference and discovering what's missing. Brief authors for the full-reference lanes should not size scope by counting existing table rows. + +**Forward routing (T-Ground-Dissolve).** Dissolution doesn't just swap table-routing for engine-routing on covered surface — it also extends routing onto previously fail-closed surface. The dissolution PR is a strict-superset behavior change, not a like-for-like swap. + +### Lesson 2 — Mirroring is forbidden; eliminating it is a substrate ask + +**What we learned at pilot time.** The pilot's Rust-constant mirror of `dsl/extdeps/languages/rust/primitives.dag` (and of `dsl/std/integer.dag`'s type-mappings) is a load-bearing concession with hand-sync risk. The lesson, as originally written: *Engine's load-bearing scope is to consume `.dag` declarations directly, eliminating the mirror.* + +**What the audit revealed (post-pilot).** The mirror existed precisely because the v3 substrate doesn't load `dsl/extdeps/languages/*` into the bootstrap Dag at all (`bootstrap.rs:16-19` — *"Production bootstrap does not inject target-language realizations"*). The pilot's choice to mirror was forced by the substrate, not by pilot-scope convenience. Eliminating the mirror is a **substrate-capability question**, not an Engine-internal question. + +**Source.** Pilot mirroring discipline first articulated in [PR #765 LGTM comment 4317308089](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317308089); substrate dependency confirmed in [the Phase 0 audit](t-ground-engine-substrate-audit.md) (PR #768 merged 2026-04-25). + +**Forward routing.** Engine cannot honor "no mirroring" without the extdeps loader closing. See `docs/briefs/t-ground-engine-substrate-escalation.md` for the routing decision. + +**Forward routing (full-reference lanes).** Same constraint: T-Ground-Python / -Go cannot consume their respective `dsl/extdeps/languages/*/primitives.dag` files without the extdeps loader. Their dispatch shape depends on the same substrate close. + +### Lesson 3 — Fail-closed by construction is the contract baseline + +**What we learned.** The pilot proactively shipped `GroundingError::{Ambiguous, NoInhabitant}` plus structural tests (`pilot_primitives_have_unique_algebra_carrier_keys`, `missing_inhabitant_fails_closed`). The original pilot brief allowed deferring fail-closed discipline to Engine; the worker chose to lock it at pilot scope per `feedback_fail_closed_discipline.md`. + +**Source.** Pilot crate `src/v3/grounding_pilot/src/lib.rs`, fail-closed shape per [PR #765](https://github.com/gunb-ai/gunbc/pull/765). + +**Forward routing.** Engine doesn't need to *introduce* fail-closed selection — only generalize it (minimum-satisfier selection, structured diagnostics naming candidates). Pilot's bare-vector `Ambiguous { candidates }` is the floor; Engine produces a real diagnostic per the proposal's L4 surface. **This is a contract, not a suggestion** — Engine that drops fail-closed shape regresses against pilot. + +**Forward routing (T-Ground-Tests).** L4 witness-based certification can rely on the contract being load-bearing in the engine, not just decorative. Tests can assert against `Ambiguous` / `NoInhabitant` outcomes as first-class behaviors. + +### Lesson 4 — SG-0 ratchet drives Engine location decision + +**What we learned.** The pilot's manager-brief candidate location (`src/v3/compiler/src/pilot/grounding_pilot.rs`) would have ratchet-bumped the SG-0 hand-Rust ratchet on `src/v3/compiler/`. Worker restructured to a sibling crate (`src/v3/grounding_pilot/`) — strictly better than the manager-brief default because workspace-member removal is a cleaner "deletable as a unit" than module deletion. + +**Source.** [PR #765 PR body — "File-location decisions"](https://github.com/gunb-ai/gunbc/pull/765); manager endorsement in [LGTM comment 4317308089](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317308089). + +**Forward routing.** If Engine remains hand-Rust temporarily (sharpened (b.i) per the substrate-escalation), it must inherit the same SG-0 constraint — sibling-crate or `.dag`-defined, never under `src/v3/compiler/`. The Engine-Phase-1 brief codified this in its Phase 0 audit options ((c) `src/v3/compiler/` is REJECTED on SG-0 grounds). + +**Forward routing (T-Ground-Dissolve).** Dissolve scope already expanded to delete `src/v3/grounding_pilot/`. If Engine ships in a sibling crate, Dissolve scope expands further to delete that crate too. Both deletions are workspace-member removals (clean). + +### Lesson 5 — State-space discipline: precedent shape for full-reference + +**What we learned.** The original `RustPrimitive` declaration carried `overflow: IntegerOverflow?` with a doc-comment convention ("none for non-integer primitives"). Codex P2 review caught the gap: the type admitted illegal state combinations (`bool: Some(TwoComplementWrap)`, `i64: None`). Manager called for a structural fix per `feedback_state_space_vs_behavioral_invariants` and `feedback_no_validation_passes`. Worker partitioned `RustPrimitive` into `IntegerPrimitive | NonIntegerPrimitive` — overflow lives only on the integer variant; structurally absent from non-integer. + +**Source.** Codex P2 finding + manager adjudication in [comment 4317414841](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317414841); structural-fix commit on the pilot branch. + +**Forward routing.** `RustPrimitive`'s sum-type partition is the **precedent shape** that `PythonPrimitive` / `GoPrimitive` inherit. T-Ground-Python / -Go briefs must require state-space discipline at the type-shape level (not via doc-comment convention or `Option`-with-validation). Specifically: + +- Identify per-target the analog axes where overflow / Copy-trait / mutability / GIL-affinity / etc. only apply to a subset of primitives. +- Partition the per-target `Primitive` type structurally so subset-only fields live only on the variants where they're meaningful. + +**Forward routing (Engine).** Variant-aware walker handling is a contract: `find_inhabitant` and equivalents must dispatch on `IntegerPrimitive | NonIntegerPrimitive` to extract the variant-typed `algebra` field. The Engine-Phase-1 brief codified this via the state-space-discipline test requirement. + +**Forward routing (T-Ground-Dissolve).** Widening `RustPrimitive` back to a flat record is locked out of scope per the codex P2 adjudication. Dissolve cannot simplify the partition away. + +--- + +## What this receipt does NOT contain + +- **Worker-level implementation details.** The pilot's engine code, test names, and per-line decisions live in [PR #765](https://github.com/gunb-ai/gunbc/pull/765) and `src/v3/grounding_pilot/src/lib.rs`. This receipt is lessons, not history. +- **Brief amendments.** Lessons that should reshape future briefs are flagged; the actual amendments happen in the relevant brief PRs. +- **Director-routed substrate decisions.** The mirroring lesson's substrate ask is documented in [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md), not here. + +--- + +## Cross-program implications + +- **Pure Bootstrap to Zero program.** The extdeps-loader gap (Lesson 2 forward routing) overlaps directly with PB-1 / PB-Bootstrap-Process scope (`bootstrap.rs` data-driven loader). See substrate-escalation doc for concrete coordination ask. +- **R1 Substrate Manager (archived on R1 close).** The pilot's lessons about state-space discipline, fail-closed contract, and structural over conventional are general-purpose and should inform DB-11 + cardinality-substrate design decisions if those sub-lanes haven't yet finalized their type shapes. The lessons are framework-level, not Grounding-specific. +- **R2 Grounding Manager working state.** Lane checklist updated in `grounding-manager.md`. Pilot lane ✅. Engine-Phase-1 audit complete + parked pending substrate routing. + +--- + +## Lineage + +- Parent program: ROADMAP.md §"Post-R1 Program — Grounding Completeness" (current); §"Release R2 Program" → T-Ground (post-promotion). +- Parent thesis claim: THESIS.md Tier 1 → "Grounding completeness." +- Parent architectural design: [`docs/single-emitter-design.md`](../single-emitter-design.md). +- Parent worked-examples doc: [`docs/thesis/target-grounding-proposal.md`](../thesis/target-grounding-proposal.md). +- Sibling artifacts: [`grounding-manager.md`](grounding-manager.md), [`t-ground-engine-phase-1.md`](t-ground-engine-phase-1.md), [`t-ground-engine-substrate-audit.md`](t-ground-engine-substrate-audit.md), [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). diff --git a/docs/briefs/t-ground-engine-substrate-escalation.md b/docs/briefs/t-ground-engine-substrate-escalation.md new file mode 100644 index 00000000000..401ef41260f --- /dev/null +++ b/docs/briefs/t-ground-engine-substrate-escalation.md @@ -0,0 +1,142 @@ +# T-Ground-Engine — Substrate Escalation to Director + +**Status**: PROPOSAL — pending Director routing decision. R2 Grounding Manager → Director. Engine-Phase-1 implementation parked until this routes. + +**Source evidence**: [`docs/briefs/t-ground-engine-substrate-audit.md`](t-ground-engine-substrate-audit.md) (PR #768, merged commit `4afc0d794`, 2026-04-25). Citations spot-verified against current main. + +--- + +## TL;DR + +T-Ground-Engine-Phase-1 cannot dispatch as scoped. The Phase 0 substrate audit found that **both** the `.dag`-defined walker (option a) and the pure sibling-crate `.dag`-consumer (option b) block on the same substrate gap: `dsl/extdeps/languages/*` is not loaded into the bootstrap Dag and there is no public accessor for downstream code to read its declarations as parsed values. The pilot's Rust-constant mirror existed precisely because of this gap. + +**Recommendation**: route the substrate ask through the Pure Bootstrap to Zero program rather than as a discrete substrate sub-lane. PB-1 and PB-Bootstrap-Process already own `bootstrap.rs` evolution; the extdeps-load + Declaration-accessor work is a natural early sub-lane of that program. Sequencing the ask early in PB-1 (rather than after full PB-1 lands) avoids parking Engine-Phase-1 for the program's full XXL duration. + +--- + +## What's blocked + +| Lane | Block reason | +|---|---| +| T-Ground-Engine-Phase-1 (implementation) | Substrate Gap 1 (extdeps loader). Brief's "no Rust-constant mirror" requirement is unsatisfiable today. | +| T-Ground-Tests | Blocks on Engine + at least one full-reference. Doubly blocked. | +| T-Ground-Dissolve | Blocks on everything. | +| T-Ground-Rust / -Python / -Go | Block on DB-11 + cardinality-substrate (independent of this escalation, but flagged: same extdeps-loader gap will block their `primitives.dag` consumption when those briefs eventually dispatch). | + +The Engine-Phase-1 brief itself is not invalidated — its design contracts (no mirroring, state-space discipline, fail-closed by construction, SG-0 untouched) remain load-bearing. Only the **dispatch shape** changes based on the routing decision. + +--- + +## Substrate gaps the audit identified + +### Gap 1 — extdeps not loaded into bootstrap Dag + +`src/v3/compiler/src/bootstrap.rs:131-151` (`load_runtime_bootstrap_authorities`) chains `STAGED_FILES`, `V3_SPECS`, `COMPILER_FILES` only. `dsl/extdeps/languages/rust/primitives.dag` is in none of these sets. Header at `bootstrap.rs:16-19` is explicit: + +> Production bootstrap does not inject target-language realizations. Realization facts for emitted languages live in `dsl/extdeps/languages/*` per the thesis; compiler code does not manufacture those. + +A `.dag`-side walker cannot reach `rust_pilot_primitives` via name resolution. A sibling-crate walker that wants to read parsed declarations symbolically faces the same gap: no public `Dag::load_extdeps_language(…)` entry point exists. + +### Gap 2 — surface/emission features for a `.dag` walker not yet shipped + +Independent of Gap 1, option (a) requires `.dag` capabilities not yet emitted end-to-end: + +- `src/v3/std/list.dag:6-15`: *"the current compiler still lacks full structural recursion + list-body emission support."* +- `src/v3/std/list.dag:57-64`: *"generic `data` items are not yet part of the surface grammar."* +- Heterogeneous-variant pattern matching (`IntegerAlgebra | NonIntegerAlgebra` discrimination across a `List` walk) is not demonstrated end-to-end by any existing `.dag` program. + +Each gap independently rules out option (a). Gap 1 alone rules out pure (b). + +--- + +## Three routes (audit's two + sharpened middle path) + +### Route 1 (audit's first option) — close Gap 1 only; sibling-crate Engine + +Substrate work: bootstrap loads `dsl/extdeps/languages/rust/primitives.dag` plus a stable accessor returning `Declaration`/`Node` for `rust_pilot_primitives`. Engine becomes a sibling crate that walks the parsed `Declaration` structurally. + +- **Pros**: smallest unblocking step. Eliminates pilot's mirror. Engine ships in this phase. Doesn't require Gap 2 closure. +- **Cons**: Engine is hand-Rust (sibling crate) interpreting `.dag` AST — transitional, not thesis-terminal. Audit characterizes this as "interpret `.dag` AST in Rust" which is the layer Engine should eventually eliminate. Honest read: this is a **bridge**, not the destination. +- **Dissolution trigger**: when Gap 2 closes naturally (PB-1 / PB-Bootstrap-Process ships list-body emission + heterogeneous-variant pattern matching), sibling-crate Engine collapses into a `.dag` walker (Engine-Phase-2 or T-Ground-Dissolve). + +### Route 2 (audit's second option) — pursue option (a) directly + +Bundle Gap 1 close with `.dag` walker authoring; schedule Gap 2 closure as Engine-Phase-1 prereqs. + +- **Pros**: project-thesis-aligned in one motion. No transitional bridge. +- **Cons**: scope inflates substantially. Engine-Phase-1 becomes an XL+ program by absorbing list-body emission + sum-variant pattern matching scope. Probably parks Engine for quarters. + +### Route 3 (manager-sharpened, recommended) — route Gap 1 close through Pure Bootstrap to Zero program + +Same destination as Route 1, but the substrate work doesn't dispatch as a discrete sub-lane — it gets sequenced inside [Pure Bootstrap to Zero Manager](pure-bootstrap-zero-manager.md)'s scope. + +**Why this fits**: +- PB-1 (data-driven bootstrap loader) already owns `bootstrap.rs` evolution. Adding extdeps-load to the data-driven loader is a natural sub-lane (PB-1-a or new sub-lane). +- PB-Bootstrap-Process declares the bootstrap workflow as data; whether to load extdeps is itself a workflow decision that program already manages. +- Avoids creating a discrete "extdeps loader" Director-routed lane that overlaps with PB-1's scope. +- The existing PB-1 sub-lane breakdown can absorb the ask without scope-inflation if sequenced correctly. + +**Concrete ask** (for Director coordination with Pure Bootstrap to Zero Manager): +- Add to PB-1's sub-lane breakdown (or call out as PB-Bootstrap-Process completion criterion): "Bootstrap loader can load `dsl/extdeps/languages/*/primitives.dag` (or equivalent target-language realization files) into the production Dag, with a stable public accessor returning parsed `Declaration` for downstream consumers." +- Sequence this sub-lane **early** in PB-1 (before full PB-1 lands), so Engine-Phase-1 unblocks without waiting for the whole XXL program. +- Once it lands, Engine-Phase-1 re-dispatches in (b.i) form: sibling crate walks `Declaration` structurally; no Rust-constant mirror. + +**Pros**: leverages an existing parallel-program manager's authority over `bootstrap.rs`. Avoids Director micromanagement of an isolated sub-lane. Routing is a manager-to-manager handoff that Director coordinates rather than schedules. + +**Cons**: depends on Pure Bootstrap to Zero Manager accepting the ask within their program's scope. If they reject (e.g., scope creep argument), falls back to Route 1's discrete sub-lane. + +### Route 4 (passive) — park Grounding program until substrate matures naturally + +No substrate ask. Wait for PB-1 to land naturally, including extdeps-load if it happens. If PB-1's scope doesn't naturally include extdeps-load, Engine remains parked indefinitely. + +- **Pros**: zero director cost. +- **Cons**: program drifts. Pilot's empirical findings stale before they inform full-reference scope. Stratum-B finding (Lesson 1 of pilot receipt) starts to lose currency. +- **Recommendation**: **only** if Route 3 is rejected and Route 1 is also rejected. Default-to-passive is the worst outcome for thesis claim Tier 1. + +--- + +## What unblocks on each routing decision + +| Route | Engine re-dispatches | Full-reference re-dispatches | Tests/Dissolve dispatch | +|---|---|---|---| +| Route 3 (recommended) | After PB-1 sub-lane closes — likely weeks if sequenced early | After DB-11 + cardinality close (independent) | After Engine + at least one full-reference | +| Route 1 (fallback) | After discrete substrate sub-lane closes — likely similar timeline if Director-prioritized | Same as Route 3 | Same as Route 3 | +| Route 2 | After XL+ Engine-Phase-1 ships — likely quarters | Same as Route 3 | Same as Route 3 | +| Route 4 | After PB-1 ships full scope — if scope naturally includes extdeps-load | Same as Route 3 | Same as Route 3 | + +Note that Routes 1, 3, and 4 converge on the same Engine shape (sibling crate, structural Declaration walker, mirroring eliminated). They differ only in **how** the substrate ask is routed and **when** the dependency closes. + +--- + +## What stays parked regardless + +- **T-Ground-Rust / -Python / -Go full-reference dispatch** — independent gates (DB-11 + cardinality-substrate). Will hit the same extdeps-loader gap when those briefs dispatch; pre-emptively flagging here so the substrate close benefits all four lanes simultaneously. +- **T-Ground-Tests** — blocks on Engine + full-reference. +- **T-Ground-Dissolve** — blocks on everything. + +--- + +## Decision Director needs to make + +1. **Routing** — Route 1, 2, 3, or 4? (Manager recommends Route 3.) +2. **If Route 3** — coordinate with Pure Bootstrap to Zero Manager to add the extdeps-loader ask to PB-1 scope, sequenced early. Manager ready to draft the cross-manager-coordination message on Director signal. +3. **If Route 1** — schedule a discrete substrate sub-lane. Manager defers to Director on which substrate program owns it. +4. **If Route 2 or 4** — manager surfaces the parking decision and updates ROADMAP / working state accordingly. + +--- + +## What manager does in parallel (no Director input needed) + +- Working state in `grounding-manager.md` updated: Pilot ✅, Engine-Phase-1 audit ✅ + parked, escalation queued. +- Pilot receipt landed at [`grounding-pilot-receipt.md`](grounding-pilot-receipt.md). +- Cross-manager notification queued: surface to Pure Bootstrap to Zero Manager once Director chooses Route 3 (or directly if Director endorses pre-coordination). + +--- + +## Lineage + +- Parent program: ROADMAP.md §"Post-R1 Program — Grounding Completeness" → T-Ground-Engine. +- Source evidence: [`t-ground-engine-substrate-audit.md`](t-ground-engine-substrate-audit.md) (worker-authored Phase 0 audit, PR #768). +- Pilot empirical record: [PR #765](https://github.com/gunb-ai/gunbc/pull/765), [`grounding-pilot-receipt.md`](grounding-pilot-receipt.md). +- Adjacent program: [`pure-bootstrap-zero-manager.md`](pure-bootstrap-zero-manager.md). +- Engine brief: [`t-ground-engine-phase-1.md`](t-ground-engine-phase-1.md) (parked; re-dispatch shape determined by routing decision). From b900270057a3e96bec3722b8b0e2b2fe01ea33bb Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 22:53:14 -0400 Subject: [PATCH 05/10] docs(grounding): record Director Route 1 routing + manager-side input for loader-close brief Director chose Route 1 (small loader-close, ad-hoc Director dispatch) over manager's Route 3 recommendation. Substantive reasoning preserved in escalation doc's new "Decision" section: PB-1 migrates EXISTING fixture sets; deciding the bootstrap shape includes a new fifth set is upstream of PB-1's pattern, not adjacent to it. Faster unblock for Engine (days vs quarters). Escalation doc updated: - New "Decision" section at top records Route 1 choice, Director's three-point reasoning, cross-program coordination handling, and what the manager recommendation got wrong (upstream vs pattern distinction). - Original "Decision Director needs to make" section preserved as decision history with strikethroughs and resolved-to references. - New "Manager-side input for the loader-close brief" section: five consumer-side requirements Engine sharpened-(b) needs, plus a flag on SG-0 ratchet handling. grounding-manager.md updated: - Decisions log: Route 1 entry added with manager's internalization note. - Open questions for director: substrate routing marked RESOLVED. - Cross-manager notifications: Pure Bootstrap to Zero notification cancelled (Director handles directly). No code changes. Documentation only. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/grounding-manager.md | 5 ++- .../t-ground-engine-substrate-escalation.md | 40 ++++++++++++++++--- 2 files changed, 38 insertions(+), 7 deletions(-) diff --git a/docs/briefs/grounding-manager.md b/docs/briefs/grounding-manager.md index 8e68699ffc8..4ed224d04f5 100644 --- a/docs/briefs/grounding-manager.md +++ b/docs/briefs/grounding-manager.md @@ -314,13 +314,14 @@ Decisions log (append as they happen): - **2026-04-25** — Engine-Phase-1 brief landed (PR #767, `t-ground-engine-phase-1.md`). Audit-first discipline; no Rust-constant mirroring; variant-aware walker; SG-0 untouched. - **2026-04-25** — Engine-Phase-1 Phase 0 audit landed (PR #768, `t-ground-engine-substrate-audit.md`). Conclusion: both options (a) and (b) block on the same substrate gaps; escalation-class. Engine implementation parked. - **2026-04-25** — Engine substrate ask escalated to Director via [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). Manager recommends Route 3: route Gap 1 close through Pure Bootstrap to Zero program (PB-1 / PB-Bootstrap-Process scope overlap). +- **2026-04-25** — Director chose **Route 1** (small loader-close, ad-hoc Director dispatch). Manager recommendation overruled with substantive reasoning: PB-1 migrates *existing* fixture sets; deciding the bootstrap shape includes a new fifth set is upstream of PB-1's pattern. Faster unblock: sharpened (b) Engine within days vs quarters for full Pure Bootstrap to Zero scope. Manager internalized the upstream-vs-pattern distinction for future cross-manager flagging. Open questions for director: -- **Engine substrate routing** — Route 1 / 2 / 3 / 4 per [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). Manager recommends Route 3. +- ~~**Engine substrate routing**~~ — RESOLVED 2026-04-25. Route 1 chosen by Director. - **R2 promotion timing** — formally still PROPOSAL pending R1 all-gates-green closure. R1 Census Close landed (PR #763) but Director-discretionary dispatch has been used for Pilot + Engine-Phase-1-audit. Consider formalizing the promotion or making the discretionary mode explicit in `r2-structure.md`. Cross-manager notifications queued: -- **Pure Bootstrap to Zero Manager** (PR #766) — substrate ask: extdeps-load + Declaration accessor for `dsl/extdeps/languages/*/primitives.dag`. Surface on Director Route 3 endorsement (or pre-coordinate if Director endorses pre-coordination). See escalation doc §"Concrete ask." +- ~~**Pure Bootstrap to Zero Manager** (PR #766) — substrate ask~~ — Director chose Route 1 (ad-hoc dispatch, not routed through Zero-Floor). Director handles Zero-Floor heads-up directly per cross-program coordination. No manager-side notification queued. - **Surface / Testgen Managers** (R1, archived on R1 close per `r2-structure.md`) — pilot's fail-closed-by-construction shape (`GroundingError::{Ambiguous, NoInhabitant}`) is general-purpose, not Grounding-specific. If their wind-down work hasn't closed yet, this shape is reusable as a contract baseline. diff --git a/docs/briefs/t-ground-engine-substrate-escalation.md b/docs/briefs/t-ground-engine-substrate-escalation.md index 401ef41260f..5a5e7c4e48b 100644 --- a/docs/briefs/t-ground-engine-substrate-escalation.md +++ b/docs/briefs/t-ground-engine-substrate-escalation.md @@ -1,11 +1,27 @@ # T-Ground-Engine — Substrate Escalation to Director -**Status**: PROPOSAL — pending Director routing decision. R2 Grounding Manager → Director. Engine-Phase-1 implementation parked until this routes. +**Status**: ROUTED — Director chose **Route 1** on 2026-04-25 (small loader-close, ad-hoc Director dispatch). Manager originally recommended Route 3; Director overruled with substantive reasoning (see "Decision" section below). Engine-Phase-1 implementation re-dispatches in sharpened-(b) form once the loader-close PR lands. **Source evidence**: [`docs/briefs/t-ground-engine-substrate-audit.md`](t-ground-engine-substrate-audit.md) (PR #768, merged commit `4afc0d794`, 2026-04-25). Citations spot-verified against current main. --- +## Decision (recorded post-routing) + +**Route 1 chosen.** Director's reasoning (preserved verbatim from cross-session brief): + +1. **Doesn't fit cleanly in Zero-Floor's program.** PB-1 scope = migrating four *existing* bootstrap fixture sets (`std_fixtures` / `STAGED_FILES` / `V3_SPECS` / `COMPILER_FILES`) to generated constructors. Adding a fifth set (`dsl/extdeps/languages/*`) is upstream of PB-1 — it requires deciding the bootstrap shape includes it before PB-1's pattern applies. PB-Bootstrap-Process scope (`bootstrap.dag` declares workflow as data) is a discrete decision that can land before that lane exists. PB-Substrate generates `dag.rs` from `substrate.dag`; loader is adjacent but not the same surface. +2. **The "no target-language realizations in bootstrap" comment at `bootstrap.rs:16-19` is a stale design assertion.** It was set when Engine didn't exist. Engine needs the realizations. Revisiting that decision = small dispatch, not program-scope work. +3. **Faster unblock for Engine.** Route 1 (small loader-close) unblocks sharpened (b) Engine within a few days. Routing through Pure Bootstrap to Zero would have required PB-1 + PB-Substrate + emission-pipeline maturity all to land first. + +**Cross-program coordination handled by Director.** Heads-up to Pure Bootstrap to Zero Manager (`stern-swift-335`) flagged: PB-1's eventual constructor-emission pattern will absorb the new fifth fixture set when PB-1-b/c/d/e ship; no coordination conflict on `dag.rs` shape because loader-close doesn't touch substrate types. + +**What the manager recommendation got wrong.** Route 3's appeal was avoiding a discrete sub-lane that overlaps with PB-1. Director's correction: the overlap is illusory — PB-1 migrates *existing* fixture sets, doesn't decide *which* sets exist. Loader-close is a shape decision upstream of PB-1's pattern. Manager will internalize this distinction for future cross-manager flagging. + +The routes section below is preserved as decision history. + +--- + ## TL;DR T-Ground-Engine-Phase-1 cannot dispatch as scoped. The Phase 0 substrate audit found that **both** the `.dag`-defined walker (option a) and the pure sibling-crate `.dag`-consumer (option b) block on the same substrate gap: `dsl/extdeps/languages/*` is not loaded into the bootstrap Dag and there is no public accessor for downstream code to read its declarations as parsed values. The pilot's Rust-constant mirror existed precisely because of this gap. @@ -118,10 +134,24 @@ Note that Routes 1, 3, and 4 converge on the same Engine shape (sibling crate, s ## Decision Director needs to make -1. **Routing** — Route 1, 2, 3, or 4? (Manager recommends Route 3.) -2. **If Route 3** — coordinate with Pure Bootstrap to Zero Manager to add the extdeps-loader ask to PB-1 scope, sequenced early. Manager ready to draft the cross-manager-coordination message on Director signal. -3. **If Route 1** — schedule a discrete substrate sub-lane. Manager defers to Director on which substrate program owns it. -4. **If Route 2 or 4** — manager surfaces the parking decision and updates ROADMAP / working state accordingly. +~~Original asks (resolved 2026-04-25 — see "Decision" section at top):~~ + +1. ~~**Routing** — Route 1, 2, 3, or 4? (Manager recommends Route 3.)~~ → **Route 1 chosen.** +2. ~~**If Route 3** — coordinate with Pure Bootstrap to Zero Manager.~~ → **N/A (Route 3 not chosen).** +3. ~~**If Route 1** — schedule a discrete substrate sub-lane. Manager defers to Director on which substrate program owns it.~~ → **Director ad-hoc dispatch; loader-close worker authored under Director scope. Manager supplies Engine consumer requirements (see manager-side input below).** +4. ~~**If Route 2 or 4** — manager surfaces the parking decision and updates ROADMAP / working state accordingly.~~ → **N/A.** + +### Manager-side input for the loader-close brief + +Engine-Phase-1's sharpened-(b) form requires the loader close to enable a **specific consumer interface**. Loader brief author should ensure these are satisfied so Engine can re-dispatch directly without a follow-up amendment: + +1. **Bootstrap loads `dsl/extdeps/languages/rust/primitives.dag`** into the production Dag. (For initial close, Rust target only is sufficient — Python / Go primitives.dag files don't exist yet.) +2. **Public accessor returns `rust_pilot_primitives` as parsed `Declaration`/`Node`** to a downstream Rust caller, walkable structurally without re-implementing the parser. Audit characterizes this as the (b.i) shape — sibling-crate Engine reads `Declaration` and extracts `(target_name, algebra-variant, carrier-variant, is_copy[, overflow])` per element. +3. **Stable enough shape that Engine doesn't have to reach into private `Dag` internals.** If the public accessor returns something that requires Engine to depend on parser-internal types, the loader close hasn't fully unblocked Engine. +4. **Revisit `bootstrap.rs:16-19` comment.** The "Production bootstrap does not inject target-language realizations" assertion is the stale design Director called out. Loader-close PR should update or delete this comment in the same change (avoid leaving contradictory documentation). +5. **SG-0 ratchet handling.** Loader-close edits live in `src/v3/compiler/src/bootstrap.rs` — ratcheted hand-Rust territory. Either (a) expansion is acceptable as a Director-sanctioned bump (loader-close is small and serves a load-bearing thesis claim), or (b) loader-close lands in a transitional shape that PB-1 absorbs cleanly. Loader brief author should pick and document. + +These are consumer-side requirements, not implementation prescriptions. Manager defers to substrate-side judgment on internal shape. --- From b2c72dc33857b93945a1fe597665e5c7600c7c98 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 22:56:39 -0400 Subject: [PATCH 06/10] docs(t-ground-engine-brief): drop stale fallback now that receipt lands in same PR MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address claude-opus API review observation on PR #767 commit b9002700: the brief's §"Orient" point 7 carried a "fallback if receipt not yet on main" clause that's permanently stale once this bundle PR merges (receipt and brief land together). Also corrects "four headline lessons" → "five lessons" — the receipt captured an additional lesson (state-space discipline as full-reference precedent, from the codex P2 adjudication). Pointer to PR #765 retained as empirical-record reference, not as fallback. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/t-ground-engine-phase-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/briefs/t-ground-engine-phase-1.md b/docs/briefs/t-ground-engine-phase-1.md index 1d77fe44406..ba9cd3ef1df 100644 --- a/docs/briefs/t-ground-engine-phase-1.md +++ b/docs/briefs/t-ground-engine-phase-1.md @@ -18,7 +18,7 @@ 4. **[`docs/thesis/target-grounding-proposal.md`](../thesis/target-grounding-proposal.md).** Minimum-satisfier discipline, fail-closed tie-breaking with structured diagnostics, the three-way L4 split. 5. **[`docs/single-emitter-design.md`](../single-emitter-design.md).** The architectural design Engine operationalizes: "the mapping should fall out from the algebra, not from a hand-maintained table." 6. **[`MODELING.md`](../../MODELING.md)** (especially M9: DFS the concept DAG) and **[`INVARIANTS.md`](../../INVARIANTS.md).** Same governing rules as pilot. -7. **Pilot receipt.** Manager-authored synthesis of the four headline lessons Engine inherits. **Primary source**: `docs/briefs/grounding-pilot-receipt.md` once authored. **Fallback if not yet on main at the time you read this**: the same lessons are captured in [PR #765's merged body](https://github.com/gunb-ai/gunbc/pull/765) and the LGTM comment thread ([`comment 4317308089`](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317308089) for the four-lesson enumeration; [`comment 4317414841`](https://github.com/gunb-ai/gunbc/pull/765#issuecomment-4317414841) for the state-space-discipline lesson from the codex P2 adjudication). Read both — receipt is synthesis, the PR thread is the empirical record. +7. **Pilot receipt** — [`docs/briefs/grounding-pilot-receipt.md`](grounding-pilot-receipt.md). Manager-authored synthesis of the five lessons Engine inherits. The receipt is the synthesis; [PR #765](https://github.com/gunb-ai/gunbc/pull/765) is the empirical record (read it for per-decision context the receipt elides). --- From 25c84c1766fd8552d0cbc7565dcd5079745e9452 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 22:59:15 -0400 Subject: [PATCH 07/10] docs(grounding): purge residual pre-routing language across all four artifacts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address codex REQUEST_CHANGES on PR #767 commit b1cb3021 + sweep for adjacent stale references the original codex finding pointed at as a pattern. Fixes: - grounding-manager.md:283 (Engine status banner): "pending Director routing of substrate ask" → "Director routed Route 1; re-dispatches in sharpened-(b) form once loader-close PR merges." - grounding-manager.md:286 (Engine checklist Phase 1 line): "blocked on substrate routing" → "blocked on loader-close PR." - t-ground-engine-substrate-escalation.md §"What manager does in parallel": cancelled the Pure-Bootstrap-to-Zero notification bullet with strikethrough + explanation; added Engine re-dispatch readiness bullet to make the live forward path explicit. - t-ground-engine-substrate-escalation.md §"Three routes" header: added decision-history banner to prevent skim-readers from treating the present-tense "recommended"/"fallback" labels as live state. - grounding-pilot-receipt.md:99 (cross-program implications, R2 Grounding Manager working state bullet): "parked pending substrate routing" → "parked pending loader-close PR; Route 1 in flight as ad-hoc Director dispatch." decisions log entries with original Route 3 recommendation are preserved as historical record (decision logs should not rewrite history); the fix is to ensure live-state lines describe live state. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/grounding-manager.md | 4 ++-- docs/briefs/grounding-pilot-receipt.md | 2 +- docs/briefs/t-ground-engine-substrate-escalation.md | 7 +++++-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/briefs/grounding-manager.md b/docs/briefs/grounding-manager.md index 4ed224d04f5..6c37c9b7ac1 100644 --- a/docs/briefs/grounding-manager.md +++ b/docs/briefs/grounding-manager.md @@ -280,9 +280,9 @@ Lane-owner dispatch status (update as sub-deliverables close): - [ ] Array, slice, map, struct, pointer - [ ] Function, interface, channel -**T-Ground-Engine:** ⏸️ PARKED — Phase 0 substrate audit complete (PR #768 merged 2026-04-25 commit `4afc0d794`); implementation parked pending Director routing of substrate ask. See [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). +**T-Ground-Engine:** ⏸️ PARKED — Phase 0 substrate audit complete (PR #768 merged 2026-04-25 commit `4afc0d794`); Director routed Route 1 (small loader-close, ad-hoc Director dispatch). Engine re-dispatches in sharpened-(b) form once the loader-close PR merges. See [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). - [x] Phase 0 substrate audit (concluded escalation-class) -- [ ] Inhabitance-search walker (Phase 1, blocked on substrate routing) +- [ ] Inhabitance-search walker (Phase 1, blocked on loader-close PR) - [ ] Minimum-satisfier selection (Phase 1) - [ ] Fail-closed tie-breaking with structured diagnostic (Phase 1; pilot established the contract baseline) - [ ] Cross-type coercion paths (e.g., UTF-8 `Char ↔ u8`) (Phase 2; blocks on full-reference) diff --git a/docs/briefs/grounding-pilot-receipt.md b/docs/briefs/grounding-pilot-receipt.md index d9d4d3f2e53..bf6f309aea7 100644 --- a/docs/briefs/grounding-pilot-receipt.md +++ b/docs/briefs/grounding-pilot-receipt.md @@ -96,7 +96,7 @@ These are the carry-forwards. Each cites its empirical source (the PR commit or - **Pure Bootstrap to Zero program.** The extdeps-loader gap (Lesson 2 forward routing) overlaps directly with PB-1 / PB-Bootstrap-Process scope (`bootstrap.rs` data-driven loader). See substrate-escalation doc for concrete coordination ask. - **R1 Substrate Manager (archived on R1 close).** The pilot's lessons about state-space discipline, fail-closed contract, and structural over conventional are general-purpose and should inform DB-11 + cardinality-substrate design decisions if those sub-lanes haven't yet finalized their type shapes. The lessons are framework-level, not Grounding-specific. -- **R2 Grounding Manager working state.** Lane checklist updated in `grounding-manager.md`. Pilot lane ✅. Engine-Phase-1 audit complete + parked pending substrate routing. +- **R2 Grounding Manager working state.** Lane checklist updated in `grounding-manager.md`. Pilot lane ✅. Engine-Phase-1 audit complete + parked pending loader-close PR (Director routed Route 1; substrate ask is in flight as ad-hoc Director dispatch). --- diff --git a/docs/briefs/t-ground-engine-substrate-escalation.md b/docs/briefs/t-ground-engine-substrate-escalation.md index 5a5e7c4e48b..866fb686591 100644 --- a/docs/briefs/t-ground-engine-substrate-escalation.md +++ b/docs/briefs/t-ground-engine-substrate-escalation.md @@ -67,6 +67,8 @@ Each gap independently rules out option (a). Gap 1 alone rules out pure (b). ## Three routes (audit's two + sharpened middle path) +> **Decision-history section.** The labels below ("recommended", "fallback", route ordering) reflect the manager's pre-routing analysis. **Director chose Route 1** — see the "Decision" section at the top of this doc for the live state. The route descriptions are preserved as decision history; their present-tense framing should be read as past-tense in light of the routing. + ### Route 1 (audit's first option) — close Gap 1 only; sibling-crate Engine Substrate work: bootstrap loads `dsl/extdeps/languages/rust/primitives.dag` plus a stable accessor returning `Declaration`/`Node` for `rust_pilot_primitives`. Engine becomes a sibling crate that walks the parsed `Declaration` structurally. @@ -157,9 +159,10 @@ These are consumer-side requirements, not implementation prescriptions. Manager ## What manager does in parallel (no Director input needed) -- Working state in `grounding-manager.md` updated: Pilot ✅, Engine-Phase-1 audit ✅ + parked, escalation queued. +- Working state in `grounding-manager.md` updated: Pilot ✅, Engine-Phase-1 audit ✅ + parked pending loader-close PR, Route 1 decision recorded. - Pilot receipt landed at [`grounding-pilot-receipt.md`](grounding-pilot-receipt.md). -- Cross-manager notification queued: surface to Pure Bootstrap to Zero Manager once Director chooses Route 3 (or directly if Director endorses pre-coordination). +- ~~Cross-manager notification queued~~: cancelled. Director chose Route 1 over Route 3; Director handles Pure Bootstrap to Zero Manager heads-up directly per cross-program coordination. No manager-side notification needed. +- Engine re-dispatch readiness: when loader-close PR is ready-for-review or merged, manager authors the sharpened-(b) Engine-Phase-1 re-dispatch brief against the actual public-accessor shape and dispatches a worker. --- From a8396e170255ec37643194c5731a652c6c28fb69 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 23:13:46 -0400 Subject: [PATCH 08/10] docs(t-ground-engine-brief): add status banner to prevent Phase 0 re-run trap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address claude-opus API review observation on PR #767 commit fa769e3c: the brief still has Phase 0 audit instructions, but Phase 0 already happened (PR #768 merged) and Director routed Route 1. A worker reading the brief in the interim — between this PR merging and the sharpened-(b) re-dispatch brief landing — could mistakenly re-run an audit whose answer is already locked in. Reviewer recommended deferring to re-dispatch authoring time. Going one step further with a pre-emptive status banner at the top: small touch that closes the trap immediately rather than relying on working-state cross-reference. Banner names that the audit is settled, points at the audit + escalation docs, and clarifies that the structural contracts carry forward while the Phase 0 instructions below are decision history. Brief stays as the structural-contract anchor. Re-dispatch brief authored post-loader-close-merge will supersede this one substantively. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/t-ground-engine-phase-1.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/briefs/t-ground-engine-phase-1.md b/docs/briefs/t-ground-engine-phase-1.md index ba9cd3ef1df..b95107baf5e 100644 --- a/docs/briefs/t-ground-engine-phase-1.md +++ b/docs/briefs/t-ground-engine-phase-1.md @@ -1,5 +1,7 @@ # T-Ground-Engine — Phase 1 (Pilot-Scope Production Walker) +> **Status update (2026-04-25)** — Phase 0 substrate audit complete: see [`t-ground-engine-substrate-audit.md`](t-ground-engine-substrate-audit.md) (PR #768, merged). Director routed Route 1: small loader-close via ad-hoc Director dispatch, then Engine re-dispatches in **sharpened-(b)** form (sibling crate consuming `.dag` declarations via the loader's public accessor). See [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). **Workers: do not re-run Phase 0** — the audit is settled. The structural contracts in this brief (no mirroring, state-space discipline, fail-closed by construction, SG-0 untouched) carry forward. Phase 0 instructions below are decision history. Re-dispatch brief authored against the loader-close PR's actual public-accessor shape will supersede this one. + **Status**: PROPOSAL — same formal gates as the parent program (R1 all-gates-green closure + R2 promotion of [`docs/r2-structure.md`](../r2-structure.md)). Pilot merge ([PR #765](https://github.com/gunb-ai/gunbc/pull/765), commit `2909f9e05`) is a necessary-not-sufficient signal. Director-discretionary dispatch is honored under the same posture the pilot dispatched under. **Lane**: T-Ground-Engine (M) per ROADMAP.md §"Post-R1 Grounding lanes". This brief covers **Phase 1 only** — the pilot-scope subset. Engine grows in subsequent phases as full-reference lanes land (cross-type coercion paths, container types, Python/Go targets). From 17fa80c8311fd55aad002a798abca0e2028a365b Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 23:15:43 -0400 Subject: [PATCH 09/10] docs(grounding): final live-state pass + dual-status tracked-debt entry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address openai-pro meta-review on PR #767 commit 25c84c17 — three asks: 1. Live-state contradictions: re-swept and tightened five residual instances codex caught the pattern of: - escalation.md:87 — Route 3 heading: added "(originally recommended — overruled)" qualifier so the section heading itself reads as decision history. - escalation.md:120-123 — Routes table: added skim-prevention banner above table; bolded Route 1 row as "(Director chose)"; updated other route labels to "(originally recommended)" / "(originally analyzed)" so present-tense labels can't be misread as live state. - grounding-manager.md:316 — Decisions log entry: "Manager recommends" → "Manager recommended" with parenthetical pointing at the overruling entry that follows. Past-tense for past events while preserving the historical fact. 2. Dual-status (PROPOSAL formal / ACTIVE discretionary) tracking: added "Tracked debt" section to grounding-manager.md working state. Names owner (Director), forcing function (if convention survives one more dispatch, manager surfaces as escalation rather than open- question), and three resolution paths Director can pick. Cites feedback_state_space_vs_behavioral_invariants — status as an enum-with-implicit-modes admits illegal combinations. 3. Loader-close consumer checklist already preserved in escalation doc §"Manager-side input for the loader-close brief" — no action. decision-log entries with past-tense recommendation are preserved as historical record; only present-tense live-state references updated. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/grounding-manager.md | 8 ++++++-- docs/briefs/t-ground-engine-substrate-escalation.md | 12 +++++++----- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/briefs/grounding-manager.md b/docs/briefs/grounding-manager.md index 6c37c9b7ac1..f74002bbd59 100644 --- a/docs/briefs/grounding-manager.md +++ b/docs/briefs/grounding-manager.md @@ -313,13 +313,17 @@ Decisions log (append as they happen): - **2026-04-25** — Pilot's `RustPrimitive` partition (`IntegerPrimitive | NonIntegerPrimitive`) locked as full-reference precedent shape via codex P2 adjudication. Future widening to flat record is out of scope. - **2026-04-25** — Engine-Phase-1 brief landed (PR #767, `t-ground-engine-phase-1.md`). Audit-first discipline; no Rust-constant mirroring; variant-aware walker; SG-0 untouched. - **2026-04-25** — Engine-Phase-1 Phase 0 audit landed (PR #768, `t-ground-engine-substrate-audit.md`). Conclusion: both options (a) and (b) block on the same substrate gaps; escalation-class. Engine implementation parked. -- **2026-04-25** — Engine substrate ask escalated to Director via [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). Manager recommends Route 3: route Gap 1 close through Pure Bootstrap to Zero program (PB-1 / PB-Bootstrap-Process scope overlap). +- **2026-04-25** — Engine substrate ask escalated to Director via [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). Manager recommended Route 3: route Gap 1 close through Pure Bootstrap to Zero program (PB-1 / PB-Bootstrap-Process scope overlap). *(Past tense — overruled in next entry.)* - **2026-04-25** — Director chose **Route 1** (small loader-close, ad-hoc Director dispatch). Manager recommendation overruled with substantive reasoning: PB-1 migrates *existing* fixture sets; deciding the bootstrap shape includes a new fifth set is upstream of PB-1's pattern. Faster unblock: sharpened (b) Engine within days vs quarters for full Pure Bootstrap to Zero scope. Manager internalized the upstream-vs-pattern distinction for future cross-manager flagging. Open questions for director: - ~~**Engine substrate routing**~~ — RESOLVED 2026-04-25. Route 1 chosen by Director. -- **R2 promotion timing** — formally still PROPOSAL pending R1 all-gates-green closure. R1 Census Close landed (PR #763) but Director-discretionary dispatch has been used for Pilot + Engine-Phase-1-audit. Consider formalizing the promotion or making the discretionary mode explicit in `r2-structure.md`. +- **R2 promotion timing** — formally still PROPOSAL pending R1 all-gates-green closure. R1 Census Close landed (PR #763) but Director-discretionary dispatch has been used for Pilot + Engine-Phase-1-audit. Consider formalizing the promotion or making the discretionary mode explicit in `r2-structure.md`. **See Tracked debt below.** + +Tracked debt (manager surfaces, Director resolves): + +- **Dual-status convention (`PROPOSAL` formal / `ACTIVE` discretionary).** Currently load-bearing for two dispatched lanes (Pilot, Engine-Phase-1 audit) and likely a third (loader-close → Engine re-dispatch). **Owner**: Director. **Forcing function**: if this convention survives one more dispatch (i.e., loader-close lands and Engine re-dispatches under it), manager surfaces as escalation rather than queued open-question — the cost of dual-authority dispatch state grows non-linearly past three live dispatches per `feedback_state_space_vs_behavioral_invariants` (status as an enum-with-implicit-modes admits illegal combinations like "PROPOSAL but ACTIVE"). **Resolution paths** (Director picks one): (a) formalize R2 promotion explicitly via `r2-structure.md` amendment; (b) add a "Director-discretionary dispatch" mode to `r2-structure.md` as a first-class status alongside PROPOSAL/ACTIVE; (c) defer formalization with explicit "do not let this accumulate" sunset commitment. Cross-manager notifications queued: diff --git a/docs/briefs/t-ground-engine-substrate-escalation.md b/docs/briefs/t-ground-engine-substrate-escalation.md index 866fb686591..6d0ca002961 100644 --- a/docs/briefs/t-ground-engine-substrate-escalation.md +++ b/docs/briefs/t-ground-engine-substrate-escalation.md @@ -84,7 +84,7 @@ Bundle Gap 1 close with `.dag` walker authoring; schedule Gap 2 closure as Engin - **Pros**: project-thesis-aligned in one motion. No transitional bridge. - **Cons**: scope inflates substantially. Engine-Phase-1 becomes an XL+ program by absorbing list-body emission + sum-variant pattern matching scope. Probably parks Engine for quarters. -### Route 3 (manager-sharpened, recommended) — route Gap 1 close through Pure Bootstrap to Zero program +### Route 3 (manager-sharpened, **originally recommended — overruled**) — route Gap 1 close through Pure Bootstrap to Zero program Same destination as Route 1, but the substrate work doesn't dispatch as a discrete sub-lane — it gets sequenced inside [Pure Bootstrap to Zero Manager](pure-bootstrap-zero-manager.md)'s scope. @@ -115,12 +115,14 @@ No substrate ask. Wait for PB-1 to land naturally, including extdeps-load if it ## What unblocks on each routing decision +> The labels in the table below ("recommended", "fallback") were the manager's pre-routing analysis. Director chose **Route 1**; ignore the labels for live state. + | Route | Engine re-dispatches | Full-reference re-dispatches | Tests/Dissolve dispatch | |---|---|---|---| -| Route 3 (recommended) | After PB-1 sub-lane closes — likely weeks if sequenced early | After DB-11 + cardinality close (independent) | After Engine + at least one full-reference | -| Route 1 (fallback) | After discrete substrate sub-lane closes — likely similar timeline if Director-prioritized | Same as Route 3 | Same as Route 3 | -| Route 2 | After XL+ Engine-Phase-1 ships — likely quarters | Same as Route 3 | Same as Route 3 | -| Route 4 | After PB-1 ships full scope — if scope naturally includes extdeps-load | Same as Route 3 | Same as Route 3 | +| Route 3 (originally recommended) | After PB-1 sub-lane closes — likely weeks if sequenced early | After DB-11 + cardinality close (independent) | After Engine + at least one full-reference | +| **Route 1 (Director chose)** | After discrete substrate sub-lane (loader-close PR) closes — Director-dispatched ad-hoc | After DB-11 + cardinality close (independent) | After Engine + at least one full-reference | +| Route 2 (originally analyzed) | After XL+ Engine-Phase-1 ships — likely quarters | After DB-11 + cardinality close (independent) | After Engine + at least one full-reference | +| Route 4 (originally analyzed) | After PB-1 ships full scope — if scope naturally includes extdeps-load | After DB-11 + cardinality close (independent) | After Engine + at least one full-reference | Note that Routes 1, 3, and 4 converge on the same Engine shape (sibling crate, structural Declaration walker, mirroring eliminated). They differ only in **how** the substrate ask is routed and **when** the dependency closes. From 9bb074ab3fb74db371cac60e2ed0d4dc9f36ab29 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Fri, 24 Apr 2026 23:17:15 -0400 Subject: [PATCH 10/10] docs(grounding): fix top-of-file live-state stragglers (REQUEST_CHANGES round 2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address openai-pro REQUEST_CHANGES on PR #767 commit 25c84c17. Reviewer caught two contradictions my prior sweeps missed because I was searching for the lower-down banner patterns and the top-of-file headers/TL;DRs got skipped: - grounding-manager.md status banner (top of file, ~line 8): "Engine implementation parked pending substrate routing" → "parked pending the loader-close PR (Director routed Route 1 on 2026-04-25; substrate ask is in flight as ad-hoc Director dispatch)." - t-ground-engine-substrate-escalation.md TL;DR (~line 29): "Recommendation: route the substrate ask through the Pure Bootstrap to Zero program..." → replaced with "Live state (post-routing): Director chose Route 1 on 2026-04-25..."; explicit reference to the "Decision" section above for the substantive reasoning that overruled manager's original Route 3. Final sweep with broader grep (recommend.*Route 3 / recommendation.*Pure Bootstrap / pending substrate routing / pending Director routing) returned only explicit decision-history matches (struck-through, past-tense, or under the decision-history banner). No remaining live- state contradictions. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/grounding-manager.md | 5 +++-- docs/briefs/t-ground-engine-substrate-escalation.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/briefs/grounding-manager.md b/docs/briefs/grounding-manager.md index f74002bbd59..47d00580ec4 100644 --- a/docs/briefs/grounding-manager.md +++ b/docs/briefs/grounding-manager.md @@ -5,8 +5,9 @@ Formal R2 promotion still pending R1 all-gates-green closure + [`docs/r2-structure.md`](../r2-structure.md) promotion to ROADMAP. Director-discretionary dispatch has been used since 2026-04-25 for T-Ground-Pilot (PR #765, merged) and T-Ground-Engine-Phase-1 audit -(PR #768, merged). Engine implementation parked pending substrate -routing — see [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). +(PR #768, merged). Engine implementation parked pending the loader-close +PR (Director routed Route 1 on 2026-04-25; substrate ask is in flight as +ad-hoc Director dispatch) — see [`t-ground-engine-substrate-escalation.md`](t-ground-engine-substrate-escalation.md). Working state at the bottom of this brief reflects current dispatch state. ## Orient before reading diff --git a/docs/briefs/t-ground-engine-substrate-escalation.md b/docs/briefs/t-ground-engine-substrate-escalation.md index 6d0ca002961..270050e394b 100644 --- a/docs/briefs/t-ground-engine-substrate-escalation.md +++ b/docs/briefs/t-ground-engine-substrate-escalation.md @@ -26,7 +26,7 @@ The routes section below is preserved as decision history. T-Ground-Engine-Phase-1 cannot dispatch as scoped. The Phase 0 substrate audit found that **both** the `.dag`-defined walker (option a) and the pure sibling-crate `.dag`-consumer (option b) block on the same substrate gap: `dsl/extdeps/languages/*` is not loaded into the bootstrap Dag and there is no public accessor for downstream code to read its declarations as parsed values. The pilot's Rust-constant mirror existed precisely because of this gap. -**Recommendation**: route the substrate ask through the Pure Bootstrap to Zero program rather than as a discrete substrate sub-lane. PB-1 and PB-Bootstrap-Process already own `bootstrap.rs` evolution; the extdeps-load + Declaration-accessor work is a natural early sub-lane of that program. Sequencing the ask early in PB-1 (rather than after full PB-1 lands) avoids parking Engine-Phase-1 for the program's full XXL duration. +**Live state (post-routing)**: Director chose **Route 1** on 2026-04-25 — small loader-close via ad-hoc Director dispatch. Engine re-dispatches in **sharpened-(b)** form (sibling crate consuming `.dag` declarations via the loader's public accessor) once the loader-close PR merges. Manager's original Route 3 recommendation (route through Pure Bootstrap to Zero) was overruled with substantive reasoning preserved in the "Decision" section above. ---