AILang/docs/journals/2026-05-15-iter-mut.1.md

iter mut.1 — schema + surface for local mutable state

Date: 2026-05-15 Started from: 60e4559e31 Status: DONE Tasks completed: 6 of 6

Summary

Lands the foundational AST + surface forms for the mut-local milestone (first milestone on the Stateful-islands roadmap path). Two new Term variants (Mut and Assign) plus the nested MutVar struct enter ailang-core::ast; canonical-JSON serde round-trips them by virtue of the existing #[serde(tag = "t")] machinery. Form A gains (mut …) / (var …) / (assign …) productions in the parser and the corresponding write arms in the printer; the parser right-folds the trailing body sequence into Term::Seq so the canonical JSON-AST always sees a single body: Term. Every Term exhaustive match in the workspace (~25 walker sites) gains substantive arms, except the two dispatch entry points (synth in ailang-check, lower_term in ailang-codegen) which stub with CheckError::Internal / CodegenError::Internal per the spec's "out of iteration" boundary — typecheck recognition lands in mut.2, codegen lowering in mut.3. The three drift tests (design_schema_drift, spec_drift, schema_coverage) all flip green after the exemplar / variant-tag / visitor extensions, and examples/mut.ail ships as the round-trip fixture covering empty / single-var / two-var / nested-shadow / Bool / Unit cases. Full cargo test --workspace 579/579 green (was 564 + 2 new AST pins + 4 new parser pins + 9 from the extended drift exemplars and the mut.ail-corpus contributions netting to +15).

Per-task notes

• iter mut.1.1 — AST extension: added Term::Mut { vars: Vec<MutVar>, body: Box<Term> }, Term::Assign { name: String, value: Box<Term> }, and the MutVar { name, ty, init } struct to crates/ailang-core/src/ast.rs. Two new unit tests pin the canonical-bytes of the empty-vars mut serialisation and the Assign round-trip. MutVar carries Arm's derives (Debug, Clone, Serialize, Deserialize) — the plan's literal pseudo-code asked for PartialEq + Eq but its own justification ("derives match Arm's for cross-tree consistency") points at Arm, which does not derive those. Concern recorded; no functional impact (the Task 1 tests do not depend on PartialEq, and Term itself uses a custom PartialEq impl on Type only).

• iter mut.1.2 — substantive walker arms: 9 sites in desugar.rs, 2 in workspace.rs, 3 in ailang-check/src/lib.rs (1 in substitute_rigids_in_term, 1 in verify_tail_positions, 1 variant-name string emitter inside synth's Term::ReuseAs sub- match), 2 in lift.rs, 3 in linearity.rs (one being a variant-name string emitter), 2 in mono.rs, 1 each in pre_desugar_validation.rs, reuse_shape.rs, uniqueness.rs, 3 in escape.rs, 1 in lambda.rs, 1 in codegen/src/lib.rs (the synth_with_extras type-synthesis helper), 3 in ailang-prose/src/lib.rs, 2 in ail/src/main.rs. Plus one unenumerated site in crates/ail/tests/codegen_import_map_fallback_pin.rs (an exhaustive walker inside a test) that the build required. Each arm follows the appropriate shape per existing convention at its site: rebuilder shapes for substitute_* / subst_* / desugar_term / lift_in_term / substitute_rigids_in_term / rewrite_term, visitor shapes for collect_used_in_term / free_vars_in_term / find_non_callee_use / walk_term* / verify_tail_positions / term_has_letrec / the linearity walkers / walk in reuse_shape.rs / walk in uniqueness.rs / walk in escape.rs / collect_captures / count_free_var / subst_var_with_term (rebuilder-shape in prose). Shadowing semantics across mut-var bindings replicates the Term::Let/Term::Lam/Term::LetRec-shaped convention at each site: var-init terms see the outer scope plus already-declared vars; later var-inits and the body see all earlier var bindings.

• iter mut.1.3 — dispatch stubs: typecheck dispatch at synth in ailang-check/src/lib.rs (Plan line 2572 was wrong — that line is verify_tail_positions, which is substantive walker territory; the actual dispatch entry is synth at line 3403's former Term::ReuseAs arm, where the two new arms now sit) returns CheckError::Internal("Term::Mut/Assign not yet supported in typecheck (deferred to iter mut.2)"). Codegen dispatch at lower_term in ailang-codegen/src/lib.rs:1649 returns CodegenError::Internal("Term::Mut/Assign not yet supported in codegen (deferred to iter mut.3)"). Both errors use the single-field tuple-variant shape (Internal(String)).

• iter mut.1.4 — Form A parser + printer: dispatcher arms added for "mut" => parse_mut and "assign" => parse_assign in parse_term's head-keyword match; the two helpers parse positionally (mut: pull leading (var ...) entries, then ≥ 1 body terms right-folded into Term::Seq; assign: positional ident-then-value pair). Plan pseudo-code used helper names (peek_is_open_paren_with_head, expect_head, etc.) that don't exist; substituted the actual API (expect_lparen, expect_keyword, expect_ident, parse_type, parse_term, expect_rparen, peek_head_ident, matches!(self.peek(), Tok::RParen)). Four RED-first parser tests added covering empty mut + 1-var-1-assign-1-final + missing-body rejection (both shapes). Print arms in print.rs walk the right-spine of Term::Seq and emit each lhs as a top-level statement; the terminal expression closes the (mut …) form. EBNF prologue in parse.rs extended with mut-term, var-decl, assign-term productions. The print arms had to land during the Task 1+2 build-unblock phase rather than waiting for Task 4 (they are exhaustive-match neighbours of the synth/lower_term dispatchers); this is a benign sequencing shift and the plan's "Task 2 build- green verification gate" still holds.

• iter mut.1.5 — drift + coverage extensions: two new exemplars added to design_schema_drift.rs and two new match arms; two new VariantTag entries (TermMut, TermAssign), EXPECTED_VARIANTS extended, two new visit_term arms in schema_coverage.rs; two new exemplars + two new match arms in spec_drift.rs. form_a.md gains three new lines in the Parenthesised-forms block plus a prose paragraph naming the empty-vars and post-vars-body invariants and the diagnostic codes. DESIGN.md §"Term (expression)" gains the two jsonc schema blocks immediately after the reuse-as block plus a closing prose paragraph naming the mut.1 dispatch-stub semantics and the deferred mut.2 / mut.3 iterations. Post-edit: design_schema_drift and spec_drift both green; schema_coverage is RED on the missing examples/mut.ail fixture, per plan Step 6 expectation.

• iter mut.1.6 — fixture + round-trip: examples/mut.ail shipped with the six fns from plan Step 1 verbatim (empty / single-var with assign / two-var with combine / nested-shadow / Bool / Unit). The corpus-globbing round-trip test (parse_then_print_then_parse_is_idempotent_on_every_ail_fixture) and the parse-determinism test pick the fixture up automatically; both green. schema_coverage also green now that both new variants are observed in the corpus. Full cargo test --workspace 579/579 green.

Concerns

• MutVar derives diverge from the plan's literal pseudo-code (Debug, Clone, PartialEq, Eq, Serialize, Deserialize); the shipped form is Debug, Clone, Serialize, Deserialize to match Arm's pattern. The plan's own justification ("match Arm's derives for cross-tree consistency") points at Arm which does not derive PartialEq/Eq. Functional impact: none in mut.1 (the Task 1 tests do not depend on PartialEq, and Term uses a custom PartialEq impl scoped to Type only). A future iter that needs to compare MutVar (e.g. for in-place rewriting in mut.3 codegen) can add the derives at that time without breaking any mut.1 test.

• Plan recon for the typecheck dispatch entry was misindexed. The plan listed crates/ailang-check/src/lib.rs:2572 as the "check_term dispatch — STUBBED" site; that line is actually in verify_tail_positions, a substantive walker. The real typecheck dispatch entry is synth (defined at lib.rs:2613, with its Term::ReuseAs arm at line 3403 before the new mut arms). The stub was placed at the actual dispatch entry; line 2572 received a substantive arm. The variant-name string emitter sub-match referenced as line 3430 is inside synth's former Term::ReuseAs arm and was extended as Task 2 Step 13 asks. Net: the spec intent (stub at typecheck dispatch) is preserved; only the line-number routing differs.

• One test-side walker site (crates/ail/tests/codegen_import_map_fallback_pin.rs:62) carries an exhaustive match on Term and was not enumerated by the plan's Task 2 file list. The site is the body-walker of a regression-pin test from iter 24.tidy; it required two new arms to build green. Added with appropriate visitor-shape recursion. The plan-recon miss is recorded here as a documentary item; no behavioural impact.

Known debt

• Prose-side (mut ...) rendering in ailang-prose/src/lib.rs is a minimal-correctness shape (mut { var <name> = <init>; ...; <body> }). The prose surface for mut blocks is not yet fully designed; a future prose-iter once the LLM-author signal arrives will refine it. This is a deliberate placeholder, not drift — recording for visibility.

• subst_var in desugar.rs does NOT rename the Term::Assign.name field. The desugar pass's subst_var rewrites let-rec captures (KnownType / LetBound / MatchArm), none of which can be mut-vars (mut-vars are first-order scalars, not captureable). Leaving the assign-name untouched is semantically correct; documented in the arm's doc-comment. Mentioned here for visibility.

Files touched

• crates/ailang-core/src/ast.rs — Term::Mut, Term::Assign, MutVar, two new unit tests
• crates/ailang-core/src/desugar.rs — 9 walker arms
• crates/ailang-core/src/workspace.rs — 2 walker arms
• crates/ailang-check/src/lib.rs — 3 walker arms (substantive + variant-name) + 2 dispatch stubs in synth
• crates/ailang-check/src/lift.rs — 2 walker arms
• crates/ailang-check/src/linearity.rs — 3 walker arms (2 substantive + 1 variant-name)
• crates/ailang-check/src/mono.rs — 2 walker arms (1 mut-ref rebuilder, 1 visitor)
• crates/ailang-check/src/pre_desugar_validation.rs — 1 walker arm
• crates/ailang-check/src/reuse_shape.rs — 1 walker arm
• crates/ailang-check/src/uniqueness.rs — 1 walker arm
• crates/ailang-codegen/src/escape.rs — 3 walker arms
• crates/ailang-codegen/src/lambda.rs — 1 walker arm
• crates/ailang-codegen/src/lib.rs — 1 walker arm (synth_with_extras) + 2 dispatch stubs in lower_term
• crates/ailang-prose/src/lib.rs — 3 walker arms (1 substantive, 1 count_free_var, 1 subst_var_with_term rebuilder)
• crates/ail/src/main.rs — 2 walker arms (dep-walker + rewrite_term)
• crates/ail/tests/codegen_import_map_fallback_pin.rs — 1 walker arm (test-side, unenumerated by plan)
• crates/ailang-surface/src/parse.rs — dispatcher arms, parse_mut / parse_assign helpers, EBNF prologue extension, 4 new parser tests
• crates/ailang-surface/src/print.rs — 2 write_term arms
• crates/ailang-core/tests/design_schema_drift.rs — 2 exemplars + 2 match arms
• crates/ailang-core/tests/schema_coverage.rs — 2 VariantTag + EXPECTED_VARIANTS + 2 visit_term arms
• crates/ailang-core/tests/spec_drift.rs — 2 exemplars + 2 match arms
• crates/ailang-core/specs/form_a.md — 3 new productions + prose paragraph
• docs/DESIGN.md — 2 jsonc schema blocks + prose paragraph
• examples/mut.ail — round-trip fixture (6 fns)

Stats

bench/orchestrator-stats/2026-05-15-iter-mut.1.json