diff --git a/docs/design-pure-bootstrap-zero-audit.md b/docs/design-pure-bootstrap-zero-audit.md new file mode 100644 index 00000000000..5fba81756da --- /dev/null +++ b/docs/design-pure-bootstrap-zero-audit.md @@ -0,0 +1,187 @@ +# Pure Bootstrap to Zero — 34-file SG-0 census audit + +**Status:** `LIVE` (deliverable). Authored as Pre-promotion Deliverable 1 +for [`docs/design-pure-bootstrap-zero.md`](design-pure-bootstrap-zero.md) +per its §"Pre-promotion deliverables" section. Cited by the cascade +promotion PR; consumed as evidence that the 0-floor target is structurally +reachable rather than an aspiration. + +**Authority:** Pure Bootstrap to Zero Program Manager (parallel to R2 per +[`docs/briefs/pure-bootstrap-zero-manager.md`](briefs/pure-bootstrap-zero-manager.md)). + +**Source-of-truth for entries:** `src/v3/compiler/tests/integration/sg0_census_test.rs` +`EXPECTED_HAND_AUTHORED_NON_TEST` array. Read live at audit-authoring time; +this doc does **not** restate counts that will drift. The lane mapping is +the durable contribution. + +## Count reconciliation + +The Zero-Floor Manager brief's reference snapshot says "35 NON_TEST files +at brief authoring (post #763 `lens_depth.rs` retirement)." Live count on +main at audit-authoring time is **34**. Either an additional retirement +landed between brief authoring and audit, or the snapshot was off-by-one. +The brief's snapshot line should refresh to 34 (or whatever live is at +cascade-merge time) when the cascade PR lands. Not load-bearing; the +audit walks the live array. + +## Frame + +The design doc claims that the "irreducible tier" (`build.rs`, +`bootstrap.rs`, `lib.rs`, `dag.rs`, `dag/ports.rs`, `dag/effects.rs`) +isn't structurally irreducible — each file is generatable from a `.dag` +authority. This audit substantiates that claim file-by-file across the +whole 34-entry census, not just the irreducible tier. + +For each file: **why it is currently hand-authored**, and **the +migration path that retires it**. Each row identifies a lane from the +Zero-Floor program's lane taxonomy +([brief §Slice](briefs/pure-bootstrap-zero-manager.md), [design doc +§Subsumed lanes / §New lanes](design-pure-bootstrap-zero.md)). + +## Findings before the table + +Two files in the live census have no explicit lane home in the brief's +lane taxonomy. Proposed lane assignments below; subject to Director sign-off +during cascade review. + +- **`src/v3/compiler/src/diagnostics.rs`** (1110 LOC). File header marks + "DEFERRED DISSOLUTION: Diagnostic enum is a scaffold" pointing at the + v3-modeling-analysis §CompilerDiagnostic 5-field target. **Proposed + lane: PB-Substrate** — Diagnostic + DiagnosticCategory are substrate + types modeled in `src/v3/std/diagnostics.dag` and should generate + alongside `dag.rs`. +- **`src/v3/compiler/src/pipeline_authority.rs`** (311 LOC). Reads + `PipelineStageBinding` declarations from the bootstrapped Dag to drive + pipeline ordering. **Proposed lane: PB-Bootstrap-Process** — the + pipeline-ordering reader is the runtime-side consumer of the + `bootstrap.dag` workflow declaration; it dissolves into the bootstrap- + data substrate when PB-Bootstrap-Process lands. + +## Lane-distribution summary + +| Lane | Files | % of 34 | +|---|---|---| +| PB-Substrate | 4 (incl. proposed `diagnostics.rs`) | 12% | +| PB-1 / PB-Bootstrap-Process | 2 (incl. proposed `pipeline_authority.rs`) | 6% | +| PB-4 / PB-5 / PB-6 (compiler-in-`.dag`) | 6 | 18% | +| PB-Lib + PB-Build | 2 | 6% | +| PB-Runtime | 4 | 12% | +| PB-Workflow | 2 | 6% | +| PB-Tier1-Sweep | 14 | 41% | + +PB-Tier1-Sweep is the largest group but has no independent migration +design — entries retire mechanically as their backing PB-* migration +lands. The substantive migration design is concentrated in PB-Substrate / +PB-1+Bootstrap-Process / PB-4/5/6 / PB-Runtime (16 files, 47% of the +census). + +## File-by-file table + +### PB-Substrate (4 files) + +Substrate types generate from `src/v3/std/substrate.dag`. Cementing +test: generated Rust matches the structural facts the substrate model +declares. + +| File | Why currently hand-authored | Migration path | +|---|---|---| +| `src/v3/compiler/src/dag.rs` | Core substrate types (Dag, Node, Port, Conj, Disj, Cardinality, Bit) hand-authored as Rust. `substrate.dag` exists and is non-trivially populated (398 LOC, TERMINAL-marked structural types matching the runtime enum surface) but is not yet the generation source. | Generate from `src/v3/std/substrate.dag`. | +| `src/v3/compiler/src/dag/ports.rs` | Port submodule of dag.rs; hand-authored alongside the parent. | Same emission pass as `dag.rs`. | +| `src/v3/compiler/src/dag/effects.rs` | Effects submodule; hand-authored alongside dag.rs. | Same emission pass as `dag.rs`. | +| `src/v3/compiler/src/diagnostics.rs` | Diagnostic enum + fail-closed `mark_unresolved` API. Header explicitly names "DEFERRED DISSOLUTION" pointing at v3-modeling-analysis §CompilerDiagnostic 5-field target. `src/v3/std/diagnostics.dag` exists (39 LOC) but is currently a stub relative to the target shape. | Extend `diagnostics.dag` to the 5-field shape; generate alongside `dag.rs`. Fail-closed API contract preserved per `feedback_fail_closed_is_boundary`. | + +### PB-1 / PB-Bootstrap-Process (2 files) + +Bootstrap-as-data conceptual core. PB-1 sub-lanes a-e migrate runtime +authorities to generated constructors; PB-Bootstrap-Process replaces +the residual orchestration with a `bootstrap.dag`-driven trampoline. + +| File | Why currently hand-authored | Migration path | +|---|---|---| +| `src/v3/compiler/src/bootstrap.rs` (~470 LOC) | Hand-Rust `Dag::new()` runs full compile pipeline on `include_str!`'d `.dag` source at every construction. Chicken-egg per design doc §"Bootstrap as data": `Dag::new()` needs the compiler pipeline. | PB-1 a-e migrates std/staged/specs/compiler authorities to generated constructors (already-scoped per [`pb-1-data-driven-bootstrap.md`](briefs/pb-1-data-driven-bootstrap.md), non-goals revised under 0-floor). PB-Bootstrap-Process then replaces residual orchestration with a `bootstrap.dag`-driven trampoline. | +| `src/v3/compiler/src/pipeline_authority.rs` | Reads `PipelineStageBinding` declarations from the bootstrapped Dag; Rust shim between bootstrap-data and pipeline execution. | Subsumed by `bootstrap.dag` workflow declaration: pipeline ordering reads structurally from the bootstrap data, not from a Rust accessor. | + +### PB-4 / PB-5 / PB-6 — compiler pipeline in `.dag` (6 files) + +| File | Why currently hand-authored | Migration path | +|---|---|---| +| `src/v3/compiler/src/lower.rs` | `lower.dag` authority + SG-3 series prerequisites not yet landed; hand-Rust lowering is the bridge. | **PB-4**: author `lower.dag`, build `regen_lower` binary, emit `lower_generated.rs`; retire `lower.rs`. | +| `src/v3/compiler/src/infer.rs` | `infer.dag` + SG-4 dispatch not yet landed. | **PB-5**: author `infer.dag` + dispatch; retire `infer.rs`. | +| `src/v3/compiler/src/emit.rs` | Emit dispatch hand-authored; spec-driven emission incomplete (Lane 1e dependency). | **PB-6**: emit reads structural facts from extdeps + spec authorities. | +| `src/v3/compiler/src/emit/python_target.rs` | Python target hand-authored alongside emit.rs. | **PB-6**: generate from `python.dag` spec authority. | +| `src/v3/compiler/src/emit/rust_target.rs` | Rust target hand-authored. | **PB-6**: generate from `rust.dag` spec authority. | +| `src/v3/compiler/src/emit_rust.rs` | Re-export shim retained for transition compatibility. | **PB-6**: shim collapses on `emit/rust_target.rs` retirement. | + +### PB-Lib + PB-Build — Cargo-convention trampolines (2 files) + +Per design doc §"Cargo conventions vs zero-source-tree" (Open call 1): +trampolines whose content is generated count as 0, because the file is +just a path-binding for Cargo, not hand-authored content. + +| File | Why currently hand-authored | Migration path | +|---|---|---| +| `src/v3/compiler/build.rs` | Cargo build script enumerates STAGED_FILES / V3_SPECS / COMPILER_FILES / extdeps_generated / gunbc_generated; hand-Rust today. | Generated trampoline that `include!()`s OUT_DIR-emitted content from emit authority. | +| `src/v3/compiler/src/lib.rs` | Cargo-convention crate root; module declarations + crate exports hand-authored. | Generated trampoline. | + +### PB-Runtime — test/lens runtime as data + tiny interpreter (4 files) + +ExecuteCommand-based TestClaim runner support landed (#688/#741); full +migration of these four files is the PB-Runtime scope. + +| File | Why currently hand-authored | Migration path | +|---|---|---| +| `src/v3/compiler/src/test_runner.rs` | Test runner hand-Rust. | Generate from `.dag` authority; runner becomes a generic interpreter over `TestClaim` data. | +| `src/v3/compiler/src/lens_apply.rs` | Lens application hand-Rust. | Generate from `.dag` authority; lens evaluator becomes data + tiny interpreter. | +| `src/v3/compiler/src/lens_testgen.rs` | Lens testgen hand-Rust. | Same shape as `lens_apply.rs` migration. | +| `src/v3/compiler/src/post_emit_verifier.rs` | Post-emit verifier hand-Rust. | Same shape; verifier becomes data + interpreter. | + +### PB-Workflow — Lane 2 dissolution dependency (2 files) + +| File | Why currently hand-authored | Migration path | +|---|---|---| +| `src/v3/compiler/src/workflow_idempotency.rs` | Lane 2 (workflow dissolution) hasn't landed. | Migrates as Lane 2 dissolution lands. | +| `src/v3/compiler/src/workflow_parallelism.rs` | Same; also gated on Stage 2e `.dag` surface. | Migrates after Stage 2e `.dag` surface lands. | + +### PB-Tier1-Sweep — per-file fast-retire (14 files) + +These retire as their backing PB-* migration lands. No standalone +migration design — each retires when its producer is generated. + +| File | Backing dependency | +|---|---| +| `src/v3/compiler/src/bin/regen_bootstrap.rs` | PB-Bootstrap-Process | +| `src/v3/compiler/src/bin/regen_lens.rs` | PB-Runtime | +| `src/v3/compiler/src/bin/regen_parse.rs` | PB-* parse migration | +| `src/v3/compiler/src/bin/regen_parse_tables.rs` | PB-* parse migration | +| `src/v3/compiler/src/bin/regen_tokenize.rs` | PB-* tokenize migration | +| `src/v3/compiler/src/bin/regen_v3.rs` | PB-Bootstrap-Process | +| `src/v3/compiler/src/bin/self_host_fixed_point.rs` | PB-Bootstrap-Process (DB-8 gate harness) | +| `src/v3/compiler/src/dag/builder.rs` | PB-Substrate (builder API regenerates with substrate types) | +| `src/v3/compiler/src/dimension.rs` | PB-Substrate / std modeling | +| `src/v3/compiler/src/lens_unused_parameters.rs` | Lens generalization (PB-Runtime adjacent) | +| `src/v3/compiler/src/regen_bootstrap_emit.rs` | PB-Bootstrap-Process | +| `src/v3/compiler/src/regen_parse_emit.rs` | PB-* parse migration | +| `src/v3/compiler/src/regen_parse_tables_emit.rs` | PB-* parse migration | +| `src/v3/compiler/src/tokenize_char_class.rs` | R1 T-Sub `sub_charclass_in_std_unicode`. Retirement closes Class 5 Gap 3 → unblocks R2 T-Substrate 4th sub-lane (Director-coordinated per brief Hand-off points). | + +## Manager note: first prototyped lane pick + +Per Director Q2 ("manager-call after audit, lean PB-Substrate if +substrate.dag is evaluable today"): **substrate.dag is non-trivially +populated** (398 LOC, TERMINAL-marked types mirroring `dag.rs`'s runtime +enum surface). On the strength of that probe the Zero-Floor Manager +commits to **PB-Substrate as the first prototyped lane closure** +(Pre-promotion Deliverable 4) — `dag.rs` / `dag/ports.rs` / `dag/effects.rs` +generated from `substrate.dag` with cementing test, cited by the cascade +PR. + +If the lane execution surfaces blockers (substrate-extension required, +emission gap, etc.), fall back to PB-1-a continuation per Director's +contingency note. STOP-AND-ESCALATE binds either way. + +## Cross-refs + +- Parent design: [`docs/design-pure-bootstrap-zero.md`](design-pure-bootstrap-zero.md) §"Pre-promotion deliverables" +- Manager brief: [`docs/briefs/pure-bootstrap-zero-manager.md`](briefs/pure-bootstrap-zero-manager.md) §"Sequence + dispatch" +- Subsumed brief: [`docs/briefs/pb-1-data-driven-bootstrap.md`](briefs/pb-1-data-driven-bootstrap.md) — non-goals invert under 0-floor (Pre-promotion Deliverable 2 amendment) +- Live count authority: `src/v3/compiler/tests/integration/sg0_census_test.rs` `EXPECTED_HAND_AUTHORED_NON_TEST`