design-md-consolidation: audit close — JOURNAL entry + 3 follow-up items in roadmap (rustdoc sweep, architect-iron-law extension, drift-test fidelity widening)
This commit is contained in:
+115
@@ -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<Constraint>` (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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user