diff --git a/docs/JOURNAL.md b/docs/JOURNAL.md index 6010734..b5928de 100644 --- a/docs/JOURNAL.md +++ b/docs/JOURNAL.md @@ -12537,3 +12537,118 @@ grep must match the spec intent, not just one specific anchor form. Future plans for sweeps 2-4 will fold all anchor variants (literal Iter-N, bare Nx, prefixed `pre-Nx`, possessive `Nx's`, suffix `Nx sketch`, etc.) into one composite grep at plan-time. + +## 2026-05-10 — Iteration design-md-consolidation 2: REVERTED + migration + correction history + future speculations + +Second iteration of the milestone defined in +`docs/specs/2026-05-10-design-md-consolidation.md`. Sweep 2 closes +the "REVERTED + migration plans + correction history + future +speculations" item: the audit-trail preservation of Decision 7, +the 7-point Decision 10 Migration plan, the Decision 9 +narrative-of-changes opener, the Decision 11 mono-vs-vdisp +correction history, and the non-binding future-iter speculations +are removed or condensed. DESIGN.md now describes only the current +state plus the timeless rationale; the discarded narratives live +in JOURNAL (this entry plus the original iter entries that +recorded each change at the time). + +Sections deleted entirely: + +- Decision 7 (Term::If REVERTED block) — 32 lines. `Term::If` + exists in the language; the witness is the Term-schema + section. Decision numbering preserves the gap (Decision 6 → + Decision 8) so JOURNAL cross-references remain stable. One + orphan cross-reference at line 1141-1144 ("the same trade-off + Decision 7 made for `Term::If`'s relationship to nested + `Term::Match`") was caught in quality review and replaced with + the principle stated directly ("The principle: prefer + composability over schema-level rejection where the typecheck + rule is unambiguous"). +- Decision 10 §"Migration plan" — 32 lines, 7-point list of past + iters (annotation feature → RC runtime → uniqueness inference + → reuse hints → drop-iterative → validation bench → advisory + lint). The end state is described in the rest of Decision 10. + +Paragraphs condensed: + +- Decision 9 narrative-of-changes opener ("Originally framed as + X; then re-framed as Y; the revision flips Z") → one-line + state opener leading into the existing three RC/Boehm/bump + bullets. +- Decision 9 pre-Decision-9 history paragraphs ("Originally, + every ADT box, lambda env, and closure pair was allocated + with bare malloc and never freed…", and the bridging + "`--alloc=bump` mode introduced for the bench is a measurement + tool" sentence) — both removed. +- Decision 11 §"Why mono, not virtual dispatch (the + empirically-grounded version)" → state-only form. The + substantive rationale ("mono enables optimisations vdisp + forbids") survives; the correction history ("The original + rationale implicitly argued … the micro-benchmark refutes that + specific claim") is dropped. Header simplified to "Why mono, + not virtual dispatch." + +Future-iter speculations — per-site decisions: + +- `A future iter may layer a per-fn-arena optimisation` REMOVED + — the per-fn arena is shipped (next subsection describes it). + Announcement is history. +- `A future iter that proposes any of laziness, recursive value + bindings, shared mutable state, …` KEPT, TIGHTENED — restructured + from "future iter that proposes X must Y" to "X is rejected + unless Y" (assertive present-tense form of the same binding + constraint). +- `a future iteration (deferred) makes the explicit annotation + mandatory and rejects \`Implicit\`` REMOVED — non-binding + aspiration. (Plan named the site as "a later iter (deferred)"; + actual text was "a future iteration (deferred)" — variance + flagged by implementer, edit applied correctly.) +- `Concrete design deferred until the need materialises` REMOVED + — the binding content (no tracing GC backstop, ownership/linear + extension) precedes; the "deferred" sentence was the unneeded + punchline. +- `A future milestone may add a Prelude when concrete LLM-author + code surfaces a case…` REMOVED first sentence (aspiration), KEPT + second sentence (current-state description of how primitive + output works today via `io/print_int` / `io/print_bool` / + `io/print_str`). + +Acceptance: + +- composite grep + `grep -nE 'REVERTED|preserved for the audit trail|Migration plan|[Oo]riginally framed|original rationale|empirically-grounded version|A future (iter|iteration|milestone|Prelude) may|A future iter that|a (later|future) iter(ation)? \(deferred\)|Concrete design deferred' docs/DESIGN.md` + returns empty. +- Sweep-1 invariant grep stays empty (no regression). +- `Term::If` present in Term schema (line 1808 — `{ "t": "if", "cond": Term, … }`). +- `cargo test --workspace` 0 FAILED across all test binaries. +- `bench/check.py` 0 regressed (63 metrics; 4 improved beyond + tolerance, 59 stable); `bench/compile_check.py` 0 regressed (24 + metrics, 24 stable). +- DESIGN.md size: 2253 → 2155 lines (−98 lines this sweep, −107 + cumulatively from 2262 at milestone start). + +Tasks (commit subjects): + +- design-md-consolidation 2.1: delete Decision 7 (Term::If REVERTED block) +- design-md-consolidation 2.1 fixup: replace orphaned Decision 7 cross-reference at DESIGN.md:1141-1144 +- design-md-consolidation 2.2: condense Decision 9 narrative-of-changes opener + drop pre-Decision-9 history paragraphs +- design-md-consolidation 2.3: delete Decision 10 §Migration plan (7-point completed-iter list) +- design-md-consolidation 2.4: condense Decision 11 mono-vs-vdisp correction history to state-only rationale +- design-md-consolidation 2.5: future-iter speculations — remove aspirations, tighten binding prohibitions + +Carried into sweep 3: schema SoT inversion (DESIGN.md §Data-model +becomes the canonical schema; ast.rs gains a doc-comment pointing +to it; new drift test `design_schema_drift.rs` enforces structural +agreement between schema variants and ast.rs enums). Carried into +sweep 4: workflow / cross-reference cleanup ("Project ecosystem" +`agents/` path correction; "Verification and correctness" workflow +detail; "What is not (yet) supported" §"Recently lifted gates" +removal; cross-reference audit). + +Process note: Sweep 2's plan-time composite grep matched the +spec's full intent on the first attempt — only one fixup commit +(2.1, for the orphan Decision 7 cross-reference, which was a +content-not-grep issue caught by quality review). The Sweep 1 +lesson held. One plan-vs-actual phrasing variance ("a later iter" +vs "a future iteration") was caught by the implementer at edit +time and applied correctly without a fixup. diff --git a/docs/roadmap.md b/docs/roadmap.md index 23817c5..c5dec2f 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -40,7 +40,7 @@ work progresses. - context: `docs/specs/2026-05-10-design-md-consolidation.md` - sub-entries: - [x] Sweep 1 — remove history anchors - - [ ] Sweep 2 — REVERTED + migration plans out + - [x] Sweep 2 — REVERTED + migration plans out - [ ] Sweep 3 — schema SoT inversion + data-model hardening - [ ] Sweep 4 — workflow / cross-reference cleanup