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

iter mut.2 — typecheck recognition of Term::Mut and Term::Assign

Date: 2026-05-15 Started from: 3a5b1d3347 Status: DONE Tasks completed: 7 of 7

Summary

Replaces the mut.1 dispatch stubs in synth (ailang-check) for Term::Mut and Term::Assign with real typecheck logic. Three new CheckError variants ship (MutAssignOutOfScope, AssignTypeMismatch, UnsupportedMutVarType) with kebab-coded code() arms and structured ctx() payloads, following the cli-diag-human bracketed-[code] convention. A new mut_scope_stack: &mut Vec<IndexMap<String, Type>> parameter threads through every synth call site (24 sites across lib.rs + mono.rs:712 / mono.rs:1337 + lift.rs:723 + builtins.rs in two test helpers); each entry-point caller (check_fn, check_const, mono re-synth, lift letrec-capture synth) opens a fresh empty stack at top-of-body. Term::Var resolution prepends the mut-scope check ahead of the existing locals/globals chain (innermost-first wins on shadowing). Term::Mut pushes a frame after gating each MutVar.ty against is_supported_mut_var_type (Int / Float / Bool / Unit), synths inits in the in-progress scope, unifies init type with declared, and synths the body in the extended scope. Term::Assign resolves the target name through the stack, returns MutAssignOutOfScope (with a flat-deduplicated available list) on miss, compares value type against the declared via subst.apply + equality (manual to preserve the AssignTypeMismatch diagnostic identity), and yields Type::unit() on success. Five .ail.json fixtures + a 5-test driver (mut_typecheck_pin.rs) cover each diagnostic plus the positive nested-shadow case; the carve-out inventory at carve_out_inventory.rs is extended 7 → 12 to accept them. examples/mut.ail (the mut.1 six-fn round-trip fixture) now typechecks clean via ail check. Codegen stubs unchanged — examples/mut.ail still cannot run end-to-end; that lands in mut.3. Full cargo test --workspace: 592 passed / 0 failed (was 579 at start of mut.2; +13 = 5 driver pins + 7 lib.rs mod tests pins + 1 inventory test count unchanged — the inventory entry count went from seven to twelve but the test itself was already counted).

Per-task notes

• iter mut.2.1 — CheckError variants + code() + ctx(): Three new variants land before the Internal variant with thiserror #[error("[code] message")] attributes per the cli-diag-human convention. code() arms return the canonical kebab strings (mut-assign-out-of-scope, assign-type-mismatch, mut-var-unsupported-type). ctx() arms emit the structured payloads named in the plan ({name, available}, {name, expected, actual}, {name, type}). One in-crate pin (mut_typecheck_diagnostics_have_kebab_codes) gates the code()

  • ctx() shape; RED → GREEN observed.

• iter mut.2.2 — synth signature threads mut_scope_stack: New parameter mut_scope_stack: &mut Vec<IndexMap<String, Type>> sits immediately after locals (canonical mid-position; matches the existing convention for per-fn-body lexical state). 18 recursive call sites in lib.rs::synth updated via pattern-by-pattern replace_all (each first-arg form had a unique-enough wrapper). Entry-point callers in check_fn:1934 and check_const:2687 declare a fresh empty stack. mono.rs's two re-synth sites at 712 + 1337 also declare a fresh empty stack (they begin from a top-of-body position). Plan-recon missed two more call sites: lift.rs:723 (letrec-capture re-synth) and builtins.rs (two test helpers synth_in_builtins_env + a FloatPatternNotAllowed pin) — both required for build green; both get fresh empty stacks. The in-test mq.3 call site at lib.rs:6663 also got the new parameter. Build was red structurally (E0061 at 23+ sites) until every call site was updated, then green.

• iter mut.2.3 — Term::Var prepends mut-scope resolution: A 5- line block at the top of the Var arm walks mut_scope_stack.iter().rev() innermost-first, returning the matched type cloned. Mut-vars are monomorphic per spec §"var element types" — no Forall instantiation, no FreeFnCall. Two pins (mut_var_resolution_shadows_outer_local, mut_var_resolution_picks_innermost_frame) directly populate the stack to isolate this change from the Mut-arm work in Task 4 (the plan's literal Let { Mut { ... } } shape would have hit the still-stubbed Mut arm at this stage; the property protected — mut-scope wins over locals + innermost-wins on shadowing — is identical). TDD discipline gap: the Var-arm edit landed before the pin tests were observed RED on disk; the reasoning is analytical (the pre-edit code consults locals.get(name) first, so with locals = { x → Int } the Var arm returned Int, failing the assert-Float; same logic for the two-frame test). Recorded as Concern.

• iter mut.2.4 — Term::Mut typecheck arm: Replaces the stub with real logic per plan Step 3. A file-scope helper is_supported_mut_var_type(&Type) -> bool gates each var's declared type to Int | Float | Bool | Unit (no args). Per-var loop synths the init in the outer scope plus the in-progress frame (the in-flight frame is cloned and pushed during the init synth, then popped — keeps mut_scope_stack truthful at every nested call), unifies init type with declared, inserts the (name → declared ty) entry into the frame. After all vars: push the completed frame, synth body in extended scope, pop frame (regardless of body outcome — the body_result is captured before pop). Two pins: mut_block_typechecks_with_int_var_and_returns_int (positive, initially RED because Assign was still stubbed — flipped GREEN by Task 5) and mut_block_rejects_str_var_with_unsupported_type (negative, GREEN at Task 4 close).

• iter mut.2.5 — Term::Assign typecheck arm: Replaces the stub with real logic per plan Step 3. Resolves the target name via mut_scope_stack.iter().rev().find_map(|f| f.get(name).cloned()). None case: flattens every name in every frame innermost-first, dedup-preserving-order via a manual contains check (small N, no need for a Set), returns MutAssignOutOfScope. Some case: synths the value, compares subst.apply(&declared) vs subst.apply(&value) via != (manual equality, NOT unify — unify would have emitted TypeMismatch, and the spec demands the distinct AssignTypeMismatch code), returns AssignTypeMismatch with rendered type strings on mismatch or Ok(Type::unit()) on match. Three pins: assign_to_in_scope_mut_var_synths_unit (positive), assign_to_out_of_scope_name_fires_diagnostic (None case), assign_with_wrong_value_type_fires_diagnostic (Some-mismatch case). RED → GREEN observed for all three.

• iter mut.2.6 — Five fixtures + driver test: Five .ail.json fixtures land under examples/ (carve-out style, per the Boss decision in the carrier overriding the spec's literal crates/ailang-check/tests/-side placement). Each fixture is minimal — single-fn main, no imports, body shape exactly the one the plan named. The driver test crates/ailang-check/tests/mut_typecheck_pin.rs uses the canonical load_workspace + check_workspace + diagnostics.iter().map(|d| d.code.clone()).collect() pattern from method_collision_pin.rs and typeclass_22b2.rs — no todo!() survives. Carve-out inventory extended from seven to twelve to accept the five new fixtures (alphabetised; the comment block names mut.2 as the lineage). All 5 driver tests GREEN; carve-out inventory GREEN.

• iter mut.2.7 — Verify examples/mut.ail typechecks clean: cargo run --quiet --bin ail -- check examples/mut.ail reports ok (26 symbols across 2 modules) — zero diagnostics across all six fns (mut_empty, mut_single_var, mut_two_vars, mut_nested_shadow, mut_returns_bool, mut_returns_unit). Full cargo test --workspace: 592 / 0.

Concerns

• Task 3 TDD-ordering gap: the Term::Var arm prepend landed before the two pin tests were observed RED on disk. The reasoning that the pre-edit code would have failed both pins is analytical (locals-first resolution returns Int when locals = { x → Int }, contradicting both assert_eq!(Float) and assert_eq!(Bool)). The discipline gap is recorded per the implementer's Iron Law ("the test you wrote in RED MUST pass; no other test may regress" — and the spirit-not-ritual clause that tests-after prove nothing about whether they would have caught the regression pre-edit). Subsequent tasks (4 + 5) restored the RED-first sequencing; on those, the Mut / Assign stubs already emit CheckError::Internal so the pins were observed RED with the canonical pattern. No correctness impact; the pins protect the property correctly post-edit.

• Plan-recon missed three synth call sites beyond the four the plan enumerated (lib.rs 1885 + 2634; mono.rs 712 + 1337). The build-red structural signal flushed them out via E0061: lib.rs:6663 (in-test mq.3 helper), lift.rs:723 (letrec- capture re-synth), builtins.rs (synth_in_builtins_env at 351 + a FloatPatternNotAllowed test pin at 594). Each gets a fresh empty stack with the same "begins from top-of-body" rationale as mono.rs. No behavioural impact; documentary concern for the planner's next plan-recon dispatch.

• The carve-out inventory extension was strictly required (the inventory test enforces a closed list of examples/*.ail.json files) but was not explicitly named in the Boss carrier or the plan. Recording here so the planner's recon for future iters knows to enumerate the side-effect when fixtures land under examples/. The boundary call: the fixtures match §C4(a)'s precedent (negative typecheck fixtures as .ail.json so the diagnostic-code assertion is the load-bearing form, not the surface). The positive test_mut_nested_shadow_legal.ail.json is the one stretch — its load-bearing assertion is "zero diagnostics", which the form-A .ail form could equally carry. Landing it as .ail.json keeps all five mut.2 fixtures on one driver and one extension on the carve-out list; the alternative (splitting positive to .ail, negatives to .ail.json) would have produced two drivers or a hybrid loader. Conservative call documented for visibility.

Known debt

• Codegen stubs unchanged in mut.2 per the spec's iteration boundary. A Term::Mut or Term::Assign reaching lower_term still produces CodegenError::Internal. The full mut.ail E2E (build + run) lands in mut.3. The spec's Acceptance criterion #3 (mut_counter.ail + mut_sum_floats.ail build + run + print expected stdout) is mut.3-scoped.

• The Mut-arm's in-progress-frame clone-on-each-init is O(n²) over the var count. n is realistically ≤ 2 (the mut.ail fixture's mut_two_vars is the largest in the corpus). Not worth a more elaborate structure (e.g. pushing a single in- progress frame and mutating it across inits); the clone-pop shape keeps the stack truthful at every nested call and makes the per-var init scope obvious. Recording for visibility.

Files touched

Modified:

• crates/ailang-check/src/lib.rs — 3 new CheckError variants + 3 code() arms + 3 ctx() arms; synth signature gains mut_scope_stack after locals; 18 recursive synth call sites updated; 2 entry-point callers (check_fn, check_const) declare fresh empty stacks; in-test synth call (mq.3 helper) gets new param; Term::Var arm prepends mut-scope resolution (5-line block); Term::Mut stub replaced with real logic (push/pop frame, per-var init, body synth); Term::Assign stub replaced with real logic (find/None-MutAssignOutOfScope/Some-AssignTypeMismatch-or-Unit); file-scope helper is_supported_mut_var_type; 7 new tests in mod tests (mut_typecheck_diagnostics_have_kebab_codes, mut_var_resolution_shadows_outer_local, mut_var_resolution_picks_innermost_frame, mut_block_typechecks_with_int_var_and_returns_int, mut_block_rejects_str_var_with_unsupported_type, assign_to_in_scope_mut_var_synths_unit, assign_to_out_of_scope_name_fires_diagnostic, assign_with_wrong_value_type_fires_diagnostic) plus the synth_standalone helper.
• crates/ailang-check/src/mono.rs — 2 re-synth call sites (712, 1337) each get a fresh mut_scope_stack.
• crates/ailang-check/src/lift.rs — letrec-capture re-synth at :723 gets a fresh mut_scope_stack.
• crates/ailang-check/src/builtins.rs — 2 in-test synth calls (synth_in_builtins_env + FloatPatternNotAllowed pin) get a fresh mut_scope_stack.
• crates/ailang-core/tests/carve_out_inventory.rs — EXPECTED list 7 → 12, comment-block updated naming mut.2 as the lineage of the 5 new entries.

New:

• crates/ailang-check/tests/mut_typecheck_pin.rs — 5-test driver via canonical load_workspace + check_workspace + collect-codes pattern.
• examples/test_mut_assign_out_of_scope.ail.json
• examples/test_mut_assign_outside_mut.ail.json
• examples/test_mut_assign_type_mismatch.ail.json
• examples/test_mut_nested_shadow_legal.ail.json
• examples/test_mut_var_unsupported_type.ail.json

Stats

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