design: ratify 19a-arc in DESIGN.md (tidy)

Per CLAUDE.md tidy-iter at family boundaries. ailang-architect
flagged the canonical 'DESIGN.md silent' finding for the entire
19a-arc — same shape as family-20's 20e tidy.

Decision 10 schema-additions block gained 'Iter 19b —
FnDef.suppress' entry. New subsection 'Advisory diagnostics —
Iter 19a-arc' documents the over-strict-mode lint rule (incl.
heap-type filter rationale), Severity::Warning introduction, CLI
exit-on-Error gating, and the suppress mechanism. New subsection
'Why advisory + suppress instead of inference' pins the three
substantive reasons (annotation-states-intent, drift-bremse,
LLM-authoring forcing function) so future iters can't reopen the
decision without engaging the recorded rationale.

Migration plan extended with step 7 covering 19a/19a.1/19b.
Decision 10's mandatory-annotation rule is explicitly reaffirmed
as unchanged.

No code changes. Two architect findings deferred (codegen FnDef
fan-out, snapshot-fixture coupling). Data model (MVP) drift
predates 19b — separate iter.
This commit is contained in:
2026-05-08 19:41:43 +02:00
parent 50b68267fe
commit bfe49084de
2 changed files with 187 additions and 0 deletions
+93
View File
@@ -9442,3 +9442,96 @@ JOURNAL queue: empty again. Three pre-existing 20b deferrals
(let-inlining, `print` sugar, deeply-nested-match-on-sub-binder
in 19a.1) remain queued; all three need real-corpus signal that
hasn't surfaced.
## 2026-05-08 — 19a-arc tidy-iter (DESIGN.md ratification)
Per CLAUDE.md "Tidy-iter at family boundaries" — the 19a-arc
(19a + 19a.1 + 19b) closes with a tidy. `ailang-architect` ran
the drift review and reported the canonical "DESIGN.md silent"
finding, identical in shape to the one family-20's tidy-iter
(20e) caught: a substantial new mechanism shipped with no
ratification in the canonical spec.
### Architect findings
1. **DESIGN.md silent on the entire 19a-arc.** Zero hits for
`suppress` / `over-strict-mode` / `empty-suppress-reason` /
`Severity::Warning`. Schema-additions block didn't list
`FnDef.suppress`. Highest-leverage fix.
2. **Codegen carries `suppress: vec![]` in 7 synthetic FnDef
sites** (`crates/ailang-codegen/src/lib.rs` + lift / desugar
/ reuse_shape / uniqueness / pretty). Mechanically correct;
a `FnDef::default()` or `synthetic` constructor would absorb
the fan-out. Bounded; observation, not blocker.
3. **Snapshot-fixture coupling ratified by recurrence.** 19b
regenerated three pinned `.prose.txt` snapshots — exactly
the cross-family-coupling pattern 20e's item 3 named.
Promote to known structural cost, not a fix.
### Resolved this iter
**Item 1 — ratified.** Two edits to `docs/DESIGN.md`:
- **Schema additions** subsection (Decision 10) gained an
"Iter 19b — `FnDef.suppress`" entry: schema shape, form-A
surface, form-B render, the `skip_serializing_if` /
bit-identity invariant, and the regression-pinning tests.
- **New subsection "Advisory diagnostics — Iter 19a-arc"**
placed between "Schema additions" and "Inference
algorithm". Documents the `over-strict-mode` lint rule
(incl. the heap-type filter rationale), the
`Severity::Warning` introduction, the CLI exit-on-Error
gating, and the `mode-strict-because` suppression with
mandatory-reason.
- **New subsection "Why advisory + suppress instead of
inference"** documents the three substantive reasons that
the user surfaced earlier in the design conversation —
annotation-states-intent vs. inference-picks-weakest, the
drift-bremse role, and the LLM-authoring forcing function.
This pins the rationale so future iters can't reopen the
decision without engaging with the recorded reasons.
- **Migration plan** gained a 7th step covering the 19a-arc.
The ratification explicitly reaffirms that Decision 10's
mandatory-annotation rule is unchanged. The lint is *advisory*,
the suppress is an *escape hatch with reason*, neither weakens
the contract.
### Deferred
**Item 2 (codegen FnDef fan-out).** A `FnDef::default()` /
`synthetic_fn(...)` constructor would absorb the boilerplate
across the seven synthetic sites. Worth doing the next time a
schema-additive `FnDef` field lands; not worth doing speculatively.
**Item 3 (snapshot-fixture coupling).** Recorded as known
structural cost. The pattern: any iter that touches a fixture
which is pinned by `ailang-prose/tests/snapshot.rs` must also
re-render the `.prose.txt`. Mitigation would require a more
abstract pinning mechanism (e.g. shape-checking instead of
byte-equality), which is itself a substantive design choice and
not on the queue today.
**Data model (MVP) drift.** DESIGN.md's "Data model (MVP)"
section (around L12801325) shows pre-18a / pre-19b shapes for
`FnDef` and `Type::Fn` — no `param_modes`, no `ret_mode`, no
`suppress`. This drift predates 19b by several iters. Bringing
it current is its own iter (touches three or four shape blocks).
### State of the world
JOURNAL queue: empty. Both family-20 and the 19a-arc are now
tidied with their respective ratifications recorded in
DESIGN.md.
Remaining longer-term substantive forks (none queued, none
default):
- **Boehm retirement** (Decision 9 → Decision 10 endgame).
Validation bench shipped (18f); the orchestrator's call to
actually flip the default has not been made.
- **Family 21+** — language surface expansion (typeclasses,
polymorphic ADTs beyond the heutige form, IO/error
handling).
- **Data model (MVP) refresh.** Cosmetic doc-tidy iter to
bring the schema snapshot current.