Iter 16a-aux — DESIGN.md drift audit (post-15f)

After six feature iters since the last docs sweep, DESIGN.md had
visible drift. Patched in place rather than queueing the next
codegen-heavy iter against a stale spec.

DESIGN.md changes (+72 LOC):
- Decision 6: form (A) marked shipped (Iter 14c, sole projection
  since 15e); body kept as audit trail.
- Pipeline: desugar pass added between resolve+hash and typecheck;
  invariant noted that CheckedModule.symbols hashes from the
  original module, not the desugared one (so ail diff/manifest
  preserve on-disk identity).
- CLI: added deps, diff, workspace, builtins (shipped earlier but
  never doc'd).
- "What is not (yet) supported": re-anchored from "end of Iter 13"
  to "as of Iter 16a"; removed lifted gates (cross-module ADTs,
  no-GC, flat-pattern-only); added tighter follow-up gates
  (literal sub-patterns, local recursive let).
- "What IS supported": promoted nested Ctor patterns (16a),
  cross-module ADTs (14h), form-(A) text surface (14b/14c/15e),
  Boehm GC (Decision 9 / 14f) into the smoke-test list.
- Smoke tests: added std_list_demo, std_maybe_demo, std_either_demo,
  std_pair_demo, nested_pat fixtures.

JOURNAL: 16a-aux entry recording the drift sites and what was
explicitly *not* changed (Goal, Decisions 1-5, 7-9, Mangling,
Convention, Data model, Verification — spot-checked, all current).

Tests: 93/93 unchanged (doc-only). Build clean.
This commit is contained in:
2026-05-07 19:39:44 +02:00
parent 689c445d25
commit 20b412342d
2 changed files with 168 additions and 22 deletions
+74
View File
@@ -2815,3 +2815,77 @@ the demo's `seq` chain, surfaced immediately by the parser's
**Queue update.** 15f done. Remaining: 16b (local recursive `let`),
16c (Lit-in-Ctor patterns), 17a (per-fn arena). None blocking
further stdlib growth; each is a quality-of-life improvement.
---
## Iter 16a-aux — DESIGN.md drift audit (post-15f)
**Goal.** After six feature iters (14g, 14h, 15a15f, 16a) without a
docs sweep, the design doc had accumulated visible drift. Patch in
place rather than queueing the next codegen-heavy iter against a
stale spec — the user is unreachable for the broader memory-management
discussion that gates 17a, so this is the lowest-risk productive
move.
**Drift sites found and fixed (DESIGN.md +72 LOC).**
1. **Decision 6 status (L116).** Was: `(Iter 14b — WIP) ... Status: design pass in progress`.
Now: marks form (A) as shipped in Iter 14c, gated by the
round-trip test in `ailang-surface/tests/round_trip.rs`, and
notes that 15e made it the *sole* text projection (legacy
pretty-printer module helpers deleted). The body of the
section (constraints, candidate notations) remains as the
audit trail of the original design pass.
2. **Pipeline section (L687696).** Inserted the **desugar pass**
between resolve+hash and typecheck, with the load-bearing
invariant explicit: `CheckedModule.symbols` hashes from the
*original* module, not the desugared one, so `ail diff` /
`ail manifest` keep reporting the on-disk identity. Also
noted libgc linkage on the clang line.
3. **CLI section (L700708).** Added the four subcommands that
shipped in earlier iters but never made the doc: `deps`,
`diff` (single-module + `--workspace`), `workspace`, and
`builtins`. Reformatted to a two-column layout.
4. **"What is not (yet) supported" (L724746).** Re-anchored
from "end of Iter 13" to "as of Iter 16a". Removed three
gates that had been lifted: cross-module ADTs (14h), no-GC
(14f, Decision 9), flat-pattern-only (16a). Replaced with
tighter follow-up gates: literal sub-patterns inside Ctor
patterns; local recursive `let`. Added a *one-paragraph*
"recently lifted" preamble so a future reader sees both the
delta and the iter that produced it without consulting JOURNAL.
5. **"What IS supported" (L782+).** Promoted four capabilities
into the smoke-test list: nested Ctor patterns via desugar
(16a); cross-module ADTs (14h); the form-(A) text surface as
shipped (14b/14c/15e); Boehm GC (Decision 9 / 14f). Replaced
"ADTs + flat pattern matching" line with one that names both
the original 3 and the 16a extension.
6. **Pipeline regression smoke tests (L819).** Added the four
stdlib-demo fixtures (`std_list_demo`, `std_maybe_demo`,
`std_either_demo`, `std_pair_demo`) plus `nested_pat`. The
pre-existing entries (sum/list/hof/closure/list_map/sort/
poly_id/poly_apply/box/maybe_int) were preserved as-is.
**No code changes; tests still 93/93.** Verified with `cargo
build --workspace --quiet` — the doc-only edits do not affect
any compilation unit.
**What was *not* changed.** The Goal section, Decisions 15,
Decisions 79 (already accurate after their respective revert /
ship statuses), Mangling scheme, Convention for cross-module
references, Data model (Module/Def/Term/Type grammar), Verification
section. Spot-checked each — all match current implementation.
**Cumulative state, post-16a-aux.**
- Stdlib: unchanged (4 modules, 24 combinators).
- DESIGN.md: 804 → 876 LOC. JOURNAL.md grows by this entry.
- Drift baseline reset: any future iter that lifts a gate or
ships a new pipeline layer should patch the relevant section
in the same iter, not accumulate.
**Queue update.** 16a-aux done. Unchanged from post-15f:
16b (local recursive `let`), 16c (Lit-in-Ctor patterns),
17a (per-fn arena). 17a remains the explicit checkpoint before
any broader memory-management work — that decision is gated on
a joint conversation with the user.