docs(fork-c/S0): setup contract — byte-baseline + commit-discipline, E6b disposition + two-corpus partition, A–E6 reuse/delete ledger
S0 of the ratified Fork C plan (zero-legacy name-resolution redesign, S0→S6).
Pure setup/documentation: NO production code change, NO behavior change.
Single-author output byte-identical to wt-stdlib-base by construction.
Deliverables under docs/fork-c/ (docs/, not current/, because current/ is
gitignored and the contract must be committed):
S0.1 — byte-baseline + commit-discipline: the committed examples/expected/*
snapshots are the single-author byte-identity reference; the zero-diff repro is
`zig build && zig build test && bash tests/run_examples.sh`. Resolver-target set
explicitly excluded + listed. Commit-classification rule: mirror | consumer-cutover | deletion.
S0.2 — E6b disposition + two-corpus partition: transitional E6b src NOT merged
(grep-clean: no resolveRegistrationSigTypeInSource / sig_registration_mode /
e6br_gate.test.zig on baseline). Harvested 0811–0829 trees + goldens (never the
src), empirically partitioned by running each through the base compiler vs the
E6b target:
- baseline-green (mirror-equivalence): 0795–0798 (merged) + 0823, 0828 — given
examples/expected/ markers, locked into the S0 baseline.
- resolver-target (known-wrong old behavior): 0811–0822, 0824–0827, 0829 + the
re-filed E6BR-5 nested-pattern regression — a listed xfail harness under
tests/resolver-target/ (manifest + TARGET goldens, NO active marker), flips
active+green at S3.9. 0811/0829 noted as old-selector-wrong on the E6b-unmerged
base; E6BR-5 subsumed by the whole-AST resolver, NOT an E6b attempt-6.
S0.3 — A–E6 reuse/delete ledger: every load-bearing A–E6 artifact mapped REUSED
(Fork C home) or DELETED/TRANSITIONAL (S3/S6 phase); E6c/d/e dropped, F/H/I/K
absorbed/superseded.
Gate over the baseline-green corpus: zig build + zig build test (LSP corpus sweep
574 files, no crash) + bash tests/run_examples.sh (540 passed, 0 failed) all exit 0.
This commit is contained in:
agra
102
docs/fork-c/S0.1-byte-baseline-and-commit-discipline.md
Normal file
102
docs/fork-c/S0.1-byte-baseline-and-commit-discipline.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# S0.1 — Byte-baseline (baseline-green only) + commit-classification discipline
|
||||
|
||||
Authority: `runs/stdlib/design/fork-c-plan/planspec-r3.json` (S0.1) +
|
||||
`runs/stdlib/design/fork-c-deepdive/reconciled.md` (§6 green-lock). Base:
|
||||
`wt-stdlib-base @ 1f755284d98c6e8ebba953045c06e35d8cbe6278` (A–E6a merged). This is
|
||||
documentation only — no production code change, no behavior change.
|
||||
|
||||
## 1. The byte-identity reference
|
||||
|
||||
The single-author byte-identity reference that **every later Fork C commit is checked
|
||||
against** is the committed `examples/expected/*` snapshot set on the baseline commit
|
||||
above. We do **not** copy every file into this doc; the snapshots ARE the reference,
|
||||
and the reproduction is a documented zero-diff command (§2). Single-author byte
|
||||
identity is held structurally by `nominal_id == 0 ≡ structural intern`
|
||||
(`src/ir/types.zig` `internNominal`), which S1–S2 keep additive and S3 preserves
|
||||
through ordinal-0 materialization.
|
||||
|
||||
The baseline-green corpus that the reference covers:
|
||||
|
||||
| segment | what | how it is exercised | count @ S0 |
|
||||
|---|---|---|---|
|
||||
| baseline-green examples | every `examples/<name>.sx` with an active `examples/expected/<name>.exit` marker (incl. the 6 harvested baseline-green cases `0795–0798`, `0823`, `0828`) | `bash tests/run_examples.sh` | **540** active markers |
|
||||
| FFI corpus | `examples/12xx–14xx` (96 entry trees; 95 with active markers; ~418 files incl. module/`.c`/`.h`/`.m` companions) | same runner (markers) | 95 active markers |
|
||||
| LSP completion/hover smoke | LSP unit tests under `zig build test` — `analyzeDocument` flat/namespaced import + the `lsp corpus sweep: every examples/*.sx analyzes without panicking` sweep + definition/references/inlayHint | `zig build test` | — |
|
||||
|
||||
> Count note: `reconciled.md §1` cites "116 files in `examples/12xx–14xx`". The live
|
||||
> tree has **96 entry `.sx` trees** (95 with active markers); the "116" is a stale
|
||||
> historical figure. What is load-bearing is the invariant — *all FFI 12xx–14xx
|
||||
> examples stay byte-stable* — which `run_examples.sh` enforces via their markers,
|
||||
> not the exact historical count.
|
||||
|
||||
## 2. The zero-diff reproduction method
|
||||
|
||||
`tests/run_examples.sh` runs `sx run <entry>` for every `<name>.sx` that has an
|
||||
`expected/<name>.exit` marker, normalizes stdout/stderr identically for expected and
|
||||
actual (address hashing → `0xADDR`; absolute `…/examples|issues/` paths → repo-relative),
|
||||
and diffs exit + stdout + stderr (+ optional `.ir`). A **zero-diff** run is the
|
||||
byte-identity check:
|
||||
|
||||
```sh
|
||||
export PATH="$HOME/.zvm/bin:$PATH"
|
||||
zig build # build the compiler under test
|
||||
zig build test # unit tests incl. the LSP completion/hover smoke + corpus sweep
|
||||
bash tests/run_examples.sh # must print "<N> passed, 0 failed, 0 skipped*, 0 timed out"
|
||||
```
|
||||
|
||||
Any later commit whose single-author output drifts shows up as a `FAIL` with a printed
|
||||
diff. `tests/run_examples.sh --update` regenerates the snapshots — it must **only** be
|
||||
run intentionally when a commit's classification (§3) authorizes an output change, and
|
||||
the diff reviewed. (* `skipped` counts `.exit` markers whose `.sx` is absent; it is 0
|
||||
on a clean tree.)
|
||||
|
||||
## 3. Resolver-target EXCLUSION (recorded, not silently absent)
|
||||
|
||||
The **resolver-target set** is **excluded from both** the byte-baseline AND the active
|
||||
`run_examples.sh` set, because it encodes known-wrong old behavior (silent resolve /
|
||||
exit 0 / under-diagnosis / wrong author) — a stale old-selector verdict must never
|
||||
enter the baseline as if it were correct. The exclusion is explicit and **listed**, not
|
||||
absent:
|
||||
|
||||
- the 17 harvested `08xx` resolver-target cases (`0811, 0812, 0813, 0814, 0815, 0816,
|
||||
0817, 0818, 0819, 0820, 0821, 0822, 0824, 0825, 0826, 0827, 0829`) + the re-filed
|
||||
**E6BR-5** regression;
|
||||
- enumerated in `tests/resolver-target/manifest.md`, with TARGET goldens in
|
||||
`tests/resolver-target/expected/`, held inactive (no `examples/expected/` marker) and
|
||||
asserted currently-failing by `tests/resolver-target/run_resolver_target.sh`;
|
||||
- full disposition in `S0.2-e6b-disposition-and-two-corpus-partition.md`.
|
||||
|
||||
They flip to active + green at **S3.9** and only then join the baseline.
|
||||
|
||||
## 4. Commit-classification discipline
|
||||
|
||||
Every future Fork C migration commit (S1→S6) is tagged with exactly one of three
|
||||
classes, stated in the commit subject/body so a reviewer knows what byte-effect to
|
||||
expect:
|
||||
|
||||
| tag | meaning | expected byte-effect on the baseline-green corpus |
|
||||
|---|---|---|
|
||||
| **`mirror`** | builds new facts / a new resolver path **in parallel**, while lowering still consumes the old path (S1–S2; the assert-only Debug mirror) | **zero** — single-author output byte-identical; provably zero byte-risk |
|
||||
| **`consumer-cutover`** | switches a consumer from the old path to the resolved facts (S3 materializer / calls / consts / protocol-registration / `#using`; S5 LSP) | **zero on baseline-green** — byte-identical by ordinal-0 materialization + payload-preserving facts; the only commits that may change resolver-target (the S3.9 flip is a cutover) |
|
||||
| **`deletion`** | removes a now-dead artifact (old name selectors, `*_by_source` mirrors, `type_bridge`, `findByName`, the grep gate, the S2 mirror) | **zero** — the deleted code had no live readers after its cutover; a surviving reader fails to compile |
|
||||
|
||||
Rules:
|
||||
- A commit is exactly one class; a cutover that also deletes its now-dead source is
|
||||
still a `consumer-cutover` if the delete is the same atomic cutover (e.g. S3.10
|
||||
removes the last old selector **and** the S2 mirror in the cutover commit).
|
||||
- `mirror` and `deletion` commits MUST be byte-zero on baseline-green; if a `mirror`
|
||||
commit changes a byte, it was not actually parallel — stop.
|
||||
- Only `consumer-cutover` may legitimately change output, and only the **resolver-target**
|
||||
corpus (never baseline-green) — that is the S3.9 flip.
|
||||
|
||||
## 5. Acceptance (S0.1) — self-check
|
||||
|
||||
- ✅ Byte-baseline of all baseline-green examples + FFI 12xx–14xx + LSP smoke captured
|
||||
and reproducible via the documented zero-diff command (§1–§2); the reference is the
|
||||
committed `examples/expected/*` at the baseline commit, re-checked by a zero-`FAIL`
|
||||
`run_examples.sh`.
|
||||
- ✅ Resolver-target set explicitly excluded from the byte-baseline AND the active
|
||||
`run_examples.sh` set, and recorded/listed (§3) — not silently absent.
|
||||
- ✅ The `mirror | consumer-cutover | deletion` classification rule is written (§4).
|
||||
- ✅ `zig build && zig build test && bash tests/run_examples.sh` green over the
|
||||
baseline-green corpus; no behavior change (S0 adds no production code).
|
||||
Reference in New Issue
Block a user