|
| 1 | +// SPDX-License-Identifier: MPL-2.0 |
| 2 | +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> |
| 3 | += 2026-05-24/25 — Phase 0 Closure Pass |
| 4 | +:author: Jonathan D.A. Jewell |
| 5 | +:revdate: 2026-05-25 |
| 6 | +:toc: |
| 7 | + |
| 8 | +== Purpose |
| 9 | + |
| 10 | +Canonical written record of the two-day Phase 0 closure pass. |
| 11 | +Companion to `CHANGELOG.md` (which lists what shipped per release) |
| 12 | +and `docs/wiki/Phase-0-Status.md` (the live ledger). This document |
| 13 | +exists so a reader six months from now can reconstruct what |
| 14 | +happened, why, and where to look next. |
| 15 | + |
| 16 | +== Summary |
| 17 | + |
| 18 | +11 PRs landed across two sessions of focused engineering-surface |
| 19 | +stabilisation. Phase 0 §"What advancing to Phase 1 requires" gates: |
| 20 | + |
| 21 | +* **Gate 1** — every commit on main exits CI green (or explicitly |
| 22 | + advisory): **met** via PR #59 |
| 23 | +* **Gate 2** — codegen v0 emits valid wasm for example 01, |
| 24 | + verifiable end-to-end: **not yet** — terminal blocker; needs |
| 25 | + Idris2 parser + codegen implementation (weeks of work) |
| 26 | +* **Gate 3** — `ROADMAP.adoc` reflects reality: **met** via PR #60 |
| 27 | + and the drift-detection aspect that prevents recurrence |
| 28 | + |
| 29 | +State at end of pass: the project is *defensibly engineered* — a |
| 30 | +research prototype that builds, tests, ships without hand-holding, |
| 31 | +with honest CI status and a complete documentation surface for |
| 32 | +humans and machines. Not yet a working compile target; that's |
| 33 | +Phase 1. |
| 34 | + |
| 35 | +== PRs that landed (chronological) |
| 36 | + |
| 37 | +[cols="1,4",options="header"] |
| 38 | +|=== |
| 39 | +| PR | What |
| 40 | + |
| 41 | +| #46 | CI triage round 1 — three of six persistent red jobs fixed |
| 42 | + (cargo install, structural E2E, hypatia exemption) |
| 43 | + |
| 44 | +| #47 | `docs/PRODUCTION-PATH.adoc` canonical 6-phase plan; version |
| 45 | + axis ↔ phase axis mapping in `ROADMAP.adoc`; README pointer |
| 46 | + |
| 47 | +| #55 | `cargo audit` workflow — RustSec advisories on every PR and |
| 48 | + weekly cron |
| 49 | + |
| 50 | +| #57 | Track C audit-floor cleanup complete: real |
| 51 | + `tests/property/property_test.mjs` (29 assertions), |
| 52 | + `tests/aspect/security-envelope.mjs` (10), |
| 53 | + `tests/proof/regression.mjs` (25 + optional idris2 layer). |
| 54 | + The new security-envelope caught two real bugs the moment it |
| 55 | + ran: `.well-known/security.txt` still had template placeholders |
| 56 | + (`{{SECURITY_EMAIL}}`, `{{PGP_KEY_URL}}`, `{{FORGE}}`, |
| 57 | + `{{WEBSITE}}`), and `ffi/zig/src/main.zig` plus |
| 58 | + `.machine_readable/scripts/forge/git-cleanup.sh` were missing |
| 59 | + SPDX headers. Fixed in the same commit. |
| 60 | + |
| 61 | +| #58 | `tools/tree-sitter-twasm/` scaffold (Track A kickoff) — |
| 62 | + region-decls grammar v0 |
| 63 | + |
| 64 | +| #59 | A2ML / K9 / Build+E2E persistent-red jobs marked |
| 65 | + non-blocking via `continue-on-error: true` with explicit |
| 66 | + Phase 0 NOTE comments documenting the removal precondition |
| 67 | + for each |
| 68 | + |
| 69 | +| #60 | ROADMAP truthfulness audit — three real path drifts fixed |
| 70 | + (the `spec/10-levels-for-wasm.adoc` → `type-safety-levels-for-wasm.adoc` |
| 71 | + rename had five stale callers; EXPLAINME.adoc described a |
| 72 | + pre-restructure Idris2 ABI architecture; stray |
| 73 | + `src/abi/Foreign.idr` reference). Added `claim-envelope.mjs` |
| 74 | + §8 — path-reference drift detection that catches this class |
| 75 | + automatically going forward. |
| 76 | + |
| 77 | +| #61 | Wiki source-of-truth at `docs/wiki/` |
| 78 | + (`Home.md`, `Production-Path.md`, `Phase-0-Status.md`, |
| 79 | + `Comparison.md`, sync workflow) — the GitHub wiki had stale |
| 80 | + PMPL license and pre-restructure proof paths. |
| 81 | + Comprehensive `.machine_readable/6a2/STATE.a2ml` update: |
| 82 | + completion 55 → 70, new `production-phase` keys, |
| 83 | + `[test-surface]` enumeration of 545+ assertions across 11 |
| 84 | + surfaces, `[tracking-issues]` mapping each phase to its |
| 85 | + GitHub issue, removed ReScript from `depends-on`, added |
| 86 | + `ships-to` for AffineScript + Ephapax |
| 87 | + |
| 88 | +| #62 | tree-sitter v1 grammar — parses |
| 89 | + `examples/01-single-module.twasm` end-to-end with 0 ERROR |
| 90 | + nodes. Extended from ~80-line scaffold to ~270 lines |
| 91 | + covering memory declarations, function declarations |
| 92 | + (parameters, return types, effects), and all statement and |
| 93 | + expression forms used in example 01 (`region.get`, |
| 94 | + `region.set`, `region.scan`, `let [mut]`, assignment, |
| 95 | + `if/else`, `return`, binary operators with full precedence |
| 96 | + chain, `unary`, `is_null`, nested field paths) |
| 97 | + |
| 98 | +| #63 | Repo tidy for humans and machines: |
| 99 | + *RSR-template taxonomy alignment* — added `AUDIT.adoc` at |
| 100 | + root, `docs/onboarding/README.adoc`, `docs/status/README.adoc`, |
| 101 | + `docs/proposals/README.adoc`, `docs/architecture/ABI-PIPELINE.adoc`. |
| 102 | + *Eight deletions* — three template-residue QUICKSTARTs (still |
| 103 | + contained `{{BUILD_CMD}}`, `{{LANG_STACK}}` placeholders and |
| 104 | + "Typed Wasm — See README.adoc for details." body text), two |
| 105 | + heuristic `.invariants.md` artefacts, empty `docs/wikis/` |
| 106 | + placeholder, stray `generated/abi/README.adoc`. |
| 107 | + *README Quick Tour rebuilt* with current paths |
| 108 | + (`src/abi/TypedWasm/ABI/*.idr`, tree-sitter grammar, verifier |
| 109 | + crate, status documents, AUDIT.adoc, onboarding index). |
| 110 | + *Smoke job made graceful* for the in-flight ReScript → |
| 111 | + AffineScript parser migration (build step tries AffineScript |
| 112 | + first, ReScript as fallback, skips cleanly with CI warning if |
| 113 | + neither compiler is available; downstream invocations guard |
| 114 | + on `[ -f src/parser/Parser.mjs ]`). |
| 115 | + *`claim-envelope.mjs` §4 patch* — tolerates `tests/parser/*.mjs` |
| 116 | + build outputs whose `.affine` (or `.res`) source exists. |
| 117 | + *Duplication scrub* — stale ReScript references cleared from |
| 118 | + `.hypatia-ignore`, `README.adoc`, `AUDIT.adoc`. |
| 119 | +|=== |
| 120 | + |
| 121 | +== What changed in numbers |
| 122 | + |
| 123 | +[cols="2,1,1",options="header"] |
| 124 | +|=== |
| 125 | +| Surface | Before pass | After pass |
| 126 | + |
| 127 | +| Test assertions across all surfaces | ~430 | 545+ |
| 128 | +| CI jobs gating merge | unknown red+green mix; PRs merged with 8 red | all gating jobs green or explicitly advisory with documented removal precondition |
| 129 | +| Phase 0 gates met | 0 of 3 | 2 of 3 |
| 130 | +| Phase 0 issue ledger | placeholder TODO links | live cross-linked PR ledger |
| 131 | +| Documentation surface | template-residue + drift-prone | RSR-aligned + drift-checked |
| 132 | +| Wiki | 1 stale page (PMPL license, pre-restructure paths) | 5 current pages tracked in `docs/wiki/` with sync workflow |
| 133 | +| `.machine_readable/6a2/STATE.a2ml` | anchored to 2026-04-12, completion 55% | anchored to 2026-05-25, completion 70%, new `production-phase` and `[test-surface]` sections |
| 134 | +| Tree-sitter grammar | 0 lines | ~270 lines; parses example 01 with 0 ERROR |
| 135 | +| Stale `.res` references | 6 in `.hypatia-ignore` + others scattered | 0 in human-facing docs |
| 136 | +| Template-residue files at root | 3 QUICKSTARTs + 2 invariants.md | 0 |
| 137 | +|=== |
| 138 | + |
| 139 | +== What is *not* done (Phase 0 outstanding work) |
| 140 | + |
| 141 | +These three items together close Phase 0 → Phase 1: |
| 142 | + |
| 143 | +. **Idris2 parser at 188-test parity** with the AffineScript parser |
| 144 | + (currently at `src/parser/*.affine`). Multi-week implementation. |
| 145 | +. **Codegen v0** for `examples/01-single-module.twasm` end-to-end — |
| 146 | + the terminal gate-2 deliverable. Multi-week implementation. |
| 147 | +. **Track B AffineScript verifier migration** — swap |
| 148 | + `hyperpolymath/affinescript/lib/{tw_verify,tw_interface}.ml` for |
| 149 | + subprocess call to `typed-wasm-verify` binary; retire ~491 LOC of |
| 150 | + OCaml. Requires a separate Claude session pointed at the |
| 151 | + `affinescript` repo (cross-repo, MCP scope locked here to typed-wasm). |
| 152 | + |
| 153 | +== Process notes / lessons |
| 154 | + |
| 155 | +* **Drift-detection aspects pay for themselves immediately.** The |
| 156 | + security-envelope test introduced in PR #57 caught two real bugs |
| 157 | + before its first commit shipped — neither would have surfaced for |
| 158 | + months otherwise. Same pattern with claim-envelope §8 in PR #60. |
| 159 | + Whenever the project adds a new documentation surface or claims |
| 160 | + invariant, a corresponding aspect should land in the same PR. |
| 161 | + |
| 162 | +* **"Persistent red" CI is an honesty problem before it is a |
| 163 | + technical one.** PRs were merging with 8 red checks before this |
| 164 | + pass; the cargo-verify job intended to catch wasmparser breaks |
| 165 | + was *itself silently broken on every PR*. The fix wasn't to |
| 166 | + make the checks green by lowering the bar — it was to repair the |
| 167 | + checks that should be green and mark the ones that genuinely |
| 168 | + can't be (third-party action failures, in-flight migrations) |
| 169 | + as advisory with explicit removal preconditions in the workflow |
| 170 | + YAML. |
| 171 | + |
| 172 | +* **In-flight migrations need to land complete or be self-skipping.** |
| 173 | + The ReScript → AffineScript parser migration partially landed in |
| 174 | + one session (sources renamed) without updating the build |
| 175 | + wiring (`package.json` empty, workflow still ran `rescript build`) |
| 176 | + or the test scripts (`tests/e2e.sh` still asserted `.res`). |
| 177 | + Result: every subsequent PR's CI showed misleading red. Fixed by |
| 178 | + making the workflow + scripts gracefully detect and skip when |
| 179 | + the migration is mid-way, with CI annotations surfacing the |
| 180 | + actual gap. |
| 181 | + |
| 182 | +* **Bot signal-to-noise matters.** The Hypatia security scan posts |
| 183 | + 100+ findings on every PR; most are false positives matching its |
| 184 | + own banlist tokens inside Idris2 anti-pattern banner comments |
| 185 | + (e.g. `-- NO believe_me`). Documented in `AUDIT.adoc` and queued |
| 186 | + for upstream filing at `hyperpolymath/hypatia`. Skipping these as |
| 187 | + duplicates is correct; sinking time into each one would drown the |
| 188 | + PR loop. |
| 189 | + |
| 190 | +== Where to look next |
| 191 | + |
| 192 | +* `docs/PRODUCTION-PATH.adoc` — the 6-phase strategic plan |
| 193 | +* `docs/wiki/Phase-0-Status.md` — the live closure ledger |
| 194 | +* GitHub issue [#48](https://github.com/hyperpolymath/typed-wasm/issues/48) — Phase 0 tracking |
| 195 | +* GitHub issue [#49](https://github.com/hyperpolymath/typed-wasm/issues/49) — Phase 1 (next) |
| 196 | +* `.machine_readable/6a2/STATE.a2ml` — machine-readable state |
| 197 | +* `AUDIT.adoc` — hard rules and audit posture |
0 commit comments