docs(audit): 34-file SG-0 census audit for Zero-Floor program (file → why-hand-authored → PB-lane mapping)

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`