diff --git a/docs/JOURNAL.md b/docs/JOURNAL.md index 4a97674..ffc01d3 100644 --- a/docs/JOURNAL.md +++ b/docs/JOURNAL.md @@ -12967,3 +12967,118 @@ Process retrospective: the schema axis. A reader can now trust DESIGN.md as state-only without filtering history-vs-state-vs-workflow on every paragraph. + +## 2026-05-10 — Audit close: design-md-consolidation milestone + +Audit run on milestone-close commit `c6e4333`. Three substantive +architect findings closed inline as audit-tidy `63df0c0`; one low +flagged and acknowledged. + +### Architect drift review + +`[high]` `docs/DESIGN.md` §Data-model `### Def` enumeration was +incomplete: `kind ∈ { "fn", "const", "type" }` omitted the `class` +and `instance` kinds, which are real shipped schema forms (per +ast.rs `Def::Class` / `Def::Instance` with `rename_all = +"lowercase"`). The class/instance JSON shapes were documented in +Decision 11 §Form-A schema but absent from the §Data-model +canonical summary — a split-section gap. Sweep 3's drift test was +GREEN because anchor strings (`"kind": "class"`, +`"kind": "instance"`) appeared *somewhere* in DESIGN.md, but the +section that claims to be canonical (§Data-model, post-Sweep-3 +SoT inversion) was incomplete. Closed: §Data-model `### Def` +extended with `class` and `instance` JSON blocks (full method +table for class, instance method table, optional doc, superclass +and default fields). Drift test stays GREEN. + +`[high]` `docs/DESIGN.md` §Data-model `Type` block: the +`{ "k": "forall", "vars": [...], "body": Type }` JSON example +omitted the `constraints` field. ast.rs `Type::Forall` carries +`constraints: Vec` (serde +`skip_serializing_if = "Vec::is_empty"`) per Decision 11; the +field is exercised by the typeclass machinery. Same split-section +problem as the Def gap. Closed: the Forall block now lists the +`constraints` field as an optional element, with the +`omitted-when-empty / hash-stable` comment. + +`[medium]` `docs/DESIGN.md` §"What is not (yet) supported" said +"No local recursive `let`. `let f = ... in ...` … recursion needs +a top-level def." Factually wrong: `Term::LetRec` +(`{ "t": "letrec", ... }`) enables local recursive *fn* bindings +and is fully documented in §Data-model and the pipeline. An LLM +reading this item would believe recursion requires a top-level +def and would not reach for `letrec`. Closed: the entry is +rewritten to "No recursive `let` for non-fn values. … Recursive +*fn* bindings are supported via `Term::LetRec`; the desugar pass +lifts most occurrences to a synthetic top-level fn, with +`lift_letrecs` finishing the residue after typecheck." This +distinguishes the two cases correctly (no value-cycle recursion +to preserve Decision 10's acyclicity invariant; fn-recursion is +fine via letrec). + +`[low]` `docs/DESIGN.md` line 1641 contains the path +`docs/specs/2026-05-09-22-typeclasses.md` — a deliberate exception +to the Sweep-1 grep `2026-[0-9]{2}-[0-9]{2}` because it's a real +filename, not a date anchor in prose. Sweep 1 noted this exception +in its own JOURNAL entry; the architect's iron-law standing-grep +list (queued as a follow-up from milestone close) needs to allow +paths beginning with `docs/specs/` to match without firing. Not +fixed in this audit (the architect-iron-law extension is a +separate follow-up); flagged here for the implementer who picks +it up. + +### Bench regression + +`bench/check.py` exit 0 — 63 metrics, 0 regressed, 4 improved +beyond tolerance, 59 stable. +`bench/compile_check.py` exit 0 — 24 metrics, 0 regressed, 0 +beyond tolerance, 24 stable. +`bench/cross_lang.py` exit 0 — 25 metrics, 0 regressed, 0 beyond +tolerance, 25 stable. + +The 4 latency improvements beyond tolerance in `bench/check.py` +are noise within the noise floor (this milestone touched no +code paths that affect runtime); ratification not required. + +### Rustdoc audit + +`cargo doc --no-deps` reports 16 warnings (15 in `ailang-check`, +1 in `ailang-core`). Spot-checked: every warning predates this +milestone (private-item links from public doc, unresolved +intra-crate links). The milestone didn't introduce them; closing +them is out-of-scope. Queued in `docs/roadmap.md` as a follow-up +todo: "rustdoc warning sweep (15+1 pre-existing private/unresolved +links)". The rule the milestone preserved at §Verification item 6 +("rustdoc warnings are fixed in the iteration that introduced +them, not as follow-up") implies the queue item is for the +iteration that *introduced* each warning — but since they predate +the milestone, treating them as a sweep is the only feasible +catch-up. + +### Audit close + +- Architect: 3 high/medium drift items closed inline + (`63df0c0`); 1 low flagged for the architect-iron-law follow-up. +- Bench: green across all three scripts. +- Rustdoc: 16 pre-existing warnings queued in roadmap. + +Tasks (commit subjects): + +- design-md-consolidation audit-tidy: close 3 architect drift items (Def kinds class/instance + Type::Forall constraints + letrec correction) + +The audit-tidy commit's diff: 41 insertions, 6 deletions in +`docs/DESIGN.md`. Drift test stays GREEN; workspace tests stay +GREEN. + +Process note: the architect's findings confirm the queued +"drift-test fidelity widening" follow-up from the milestone-close +summary. The current `design_schema_drift.rs` checks anchor +*presence* in DESIGN.md as a whole, not anchor *placement* in the +section that claims to be canonical (§Data-model). The two `[high]` +findings (missing `class`/`instance` Def kinds; missing +`constraints` field in Type::Forall) were both invisible to the +drift test for exactly this reason — the anchors existed, just in +the wrong section. A future widening would either (a) constrain +the test to scan only §Data-model + ParamMode block, or (b) +extract the JSON-schema blocks from §Data-model into a +machine-readable file the test consumes. Queued. diff --git a/docs/roadmap.md b/docs/roadmap.md index 74a9b8e..bca491f 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -82,6 +82,29 @@ work progresses. - [ ] **\[todo\]** 21'h iteration — final 21' carry-over (latency methodology pass). Numbering kept for continuity with the 21' arc. +- [ ] **\[todo\]** Rustdoc warning sweep — `cargo doc --no-deps` + reports 16 pre-existing warnings (15 in `ailang-check`, 1 in + `ailang-core`: private-item links from public doc, unresolved + intra-crate links). All predate the design-md-consolidation + milestone; treat as a one-off sweep. + - context: JOURNAL 2026-05-10 ("Audit close: design-md-consolidation"). +- [ ] **\[todo\]** Architect-iron-law standing-grep extension — + the architect agent's drift review should run the four sweep + invariant greps on every milestone-close so DESIGN.md cannot + silently regrow history anchors / REVERTED narratives / + workflow detail / stale cross-references. Path-anchored + exceptions (`docs/specs/2026-05-09-*`) need an allowlist. + - context: JOURNAL 2026-05-10 ("Milestone close: + design-md-consolidation"). +- [ ] **\[todo\]** `design_schema_drift.rs` fidelity widening — + current test checks anchor *presence* anywhere in DESIGN.md; + the audit found that `[high]` schema gaps in §"Data model" + are invisible because anchors live in Decision 11 instead. + Constrain the test to scan only §"Data model" + ParamMode + block, or extract JSON-schema blocks into a machine-readable + file the test consumes. + - context: JOURNAL 2026-05-10 ("Audit close"). + ## P3 — Ideas - [ ] **\[idea\]** Latency methodology rework — switch from per-run