AILang/docs/specs/0038-fieldtest-remove-mut-var-assign.md

Fieldtest — remove-mut-var-assign — 2026-05-18

Status: Draft — awaiting orchestrator triage Author: ailang-fieldtester (dispatched by skills/fieldtest)

Scope

The mut / var / assign local-mutable-state construct was removed from AILang entirely (milestone remove-mut-var-assign, single terminal iteration + one inline audit .tidy). The three Form-A keywords no longer lex; Term::Mut / Term::Assign / struct MutVar are gone from the AST; a JSON-AST carrying {"t":"mut"} / {"t":"assign"} fails closed as a serde unknown-variant. The surviving forms for everything that previously used a mutable local are let, if, loop, recur. There is no tombstone diagnostic by design (no-nostalgia). This field test empirically probes the removal thesis — that mut was redundant — by writing the four real-world tasks an imperative-trained author would instinctively reach for a mutable accumulator / flag / build-up / multi-state loop for, in the surface as it exists now, and quantifying whether the absence of mut forced a materially more awkward shape.

Examples

examples/fieldtest/remove-mut_1_sum_of_squares.ail — running numeric accumulator over a bounded range

• Computes sum_sq(10) = Σ i² for i in 1..=10 = 385 via a loop with two binders (i counter, acc total) and a tail recur.
• Fits the milestone's axis-1 (the canonical "imperative running accumulator over a range" — s = 0; for i: s += i*i).
• Outcome: ail check clean first try (ok (22 symbols across 2 modules)); ail build clean; stdout 385 — matches expected.

examples/fieldtest/remove-mut_2_grade_cascade.ail — conditional classification cascade

• grade(score) returns a letter-grade code (4=A … 0=F) via a let-threaded g updated by a cascade of four if-expressions. grade(95)=4, grade(72)=2, grade(50)=0.
• Fits axis-2 (the "set a code variable through a cascade of if-branches" shape an imperative author writes with one mutable flag).
• Outcome: ail check clean first try; ail build clean; stdout 4/2/0 — matches expected.

examples/fieldtest/remove-mut_3_horner_poly.ail — multi-step straight-line numeric build-up

• Horner-form evaluation of 2x⁴+3x³+0x²+5x+7 as a straight chain of five let acc shadowings. poly(2) = 73.
• Fits axis-3 (the textbook straight-line "acc = ...; acc = acc*x + c; ..." build-up).
• Outcome: ail check clean first try; ail build clean; stdout 73 — matches expected.

examples/fieldtest/remove-mut_4_bracket_scanner.ail — multi-state streaming state machine

• A bracket-balance scanner over a token stream (recursive Int list, 1=(, 2=), 0=other) threading (rest, depth, ok) via tail recursion; each match arm updates a subset of the state. balanced "(()())" = true, balanced ")(" = false.
• Fits axis-4 (the streaming-feel loop that threads more than one piece of state and updates a subset per branch — the strongest stress on the removal: an imperative author mutates one variable and leaves the others implicitly alone).
• Outcome: ail check clean first try (ok (24 symbols across 2 modules)); ail build clean; stdout true/false — matches expected.

All four .ail fixtures are additionally ail parse | render | parse byte-identical (Roundtrip Invariant holds for the surviving surface an author writes post-removal).

Findings

[working] Bounded-range accumulator: loop/recur is structurally equal to the imperative form, zero extra threading

• Surfaced in: remove-mut_1_sum_of_squares.ail.
• What happened: the imperative shape is two mutated locals (s, i) inside a for. The AILang shape is one loop with two binders + one recur — (loop (i Int 1) (acc Int 0) (if (> i n) acc (recur (+ i 1) (+ acc (* i i))))). Binder count, update count, and exit-condition are 1:1 with the imperative loop. No extra let threading, no extra recur argument beyond the two values the imperative loop also carries. Compiled and produced 385 on the first try.
• Why working: the milestone predicts loop/recur covers the bounded-accumulator case with no expressivity loss. The example is the affirmative evidence — the removed mut would have produced an identical binder/update count; the construct added nothing here. The diagnostic surface was never exercised because nothing was wrong (clean first try).
• Recommended downstream action: carry-on.

[working] Conditional cascade and straight-line build-up: let/if is the faithful, clean form

• Surfaced in: remove-mut_2_grade_cascade.ail, remove-mut_3_horner_poly.ail.
• What happened: both express what an imperative author writes as "one mutable variable, reassigned through a cascade" as a chain of shadowing let bindings (let g (if … g) … ×4 / let acc (+ (* acc x) c) … ×4), each step a pure expression, the final value unambiguous. Both checked clean first try, built, and produced exactly the expected output (4/2/0 and 73).
• Why working: this is the milestone's clause-2 thesis made executable from the author's chair — every mut accumulator/flag in these shapes is a let-shadow chain with no behavioural difference. The removal lost nothing; if anything the let form is safer (the grade cascade's final value is structurally the last let body, so the dead-write hazard mut permits — see the spec's mut_nested_shadow example — cannot arise here).
• Recommended downstream action: carry-on.

[working] Multi-state streaming machine: every branch must restate the full state tuple — and that is the local-reasoning pillar working as intended

• Surfaced in: remove-mut_4_bracket_scanner.ail.
• What happened: the imperative author writes depth = depth + 1 (one mutation; ok implicitly untouched) or ok = false (one mutation; depth implicitly untouched). The surviving-surface form is a tail-recursive scan threading (rest, depth, ok) where every tail-app must restate all three arguments even in a branch that changes only one — e.g. (tail-app scan more (+ depth 1) ok) re-passes the unchanged ok explicitly. Quantified: 5 tail-calls, each restating the ≥1 unchanged component (the "implicit leave-alone" of mutable state becomes an explicit pass-through). It checked clean on the first try and produced true/false correctly.
• Why working (and explicitly not a spec_gap): this is the closest any of the four tasks comes to friction — and it is the decisive negative-control for the removal thesis, so it is worth the careful classification. The "restate all state at each step" cost is not awkwardness imposed by the removal; it is precisely the explicit-dataflow property docs/DESIGN.md's local-reasoning pillar exists to enforce. mut's "update one, the rest implicitly persist across the loop back-edge" is the iterated-mutable-state reasoning lines 99–108 name as the canonical clause-3 failure: the reader must mentally carry the unwritten state across iterations. The tail-recursive form makes that state-flow syntactically present and locally checkable — exactly the trade the language is designed to make. Note loop/recur is not usable here (it rebinds positionally with no structural pattern; an ADT traversal needs match, so the surviving form is ordinary tail recursion) — but that is a property of ADT traversal, not of the mut removal: mut never offered ADT pattern-matching either. No expressivity was lost; verbosity rose by the count of unchanged-but-restated arguments, which is the intended cost of explicit dataflow.
• Recommended downstream action: carry-on. (If the orchestrator wants a forward note: the only conceivable ergonomic sugar here — a record/struct to bundle (depth, ok) so a branch updates one field — is an additive future question entirely orthogonal to mut; it must not be read as evidence against this removal.)

[working] mut keyword rejection is fail-closed with an actively-guiding diagnostic

• Surfaced in: an out-of-tree probe (/tmp/mut_probe.ail, deleted after the run — not left as a fixture; the milestone's own mut_removed_pin.rs already pins this and the §"What you DO NOT ship" rule forbids a rejection-only fixture with no let/if equivalent).
• What happened: a doc-faithful-but-stale author who still emits (mut (var s (con Int) 0) (assign s (app + s 1)) s) gets, at ail check, exit code 1 and: error: [surface-parse-error] parse error in term: unknown term head mut; expected one of app, tail-app, lam, let, let-rec, if, match, do, tail-do, seq, term-ctor, clone, reuse-as, loop, recur, lit-unit at byte 137. Identical structured payload via --json (code: surface-parse-error, severity: error). ail build also exits
  1. No panic, no tombstone, no degraded internal error.
• Why working: the removal spec mandates fail-closed with no dedicated "construct removed" diagnostic (no-nostalgia). The generic unknown term head path delivers exactly that — and as a bonus it enumerates the surviving valid term heads including loop, recur, let, so the very diagnostic an out-of-date author hits points them at the replacement forms. This is the clause-3 discriminator ("the wrong code fails to typecheck, not merely advised against") working precisely as the spec's "Removal made executable" criterion requires.
• Recommended downstream action: carry-on.

Recommendation summary

Finding	Class	Action
Bounded-range accumulator = loop/recur, zero extra threading	working	carry-on
Cascade + straight-line build-up = clean let/if	working	carry-on
Multi-state machine restates full tuple = local-reasoning pillar working	working	carry-on
mut keyword rejection fail-closed + guiding diagnostic	working	carry-on

Verdict on the removal thesis: Confirmed. Across all four imperative-instinct tasks the surviving let/if/loop/recur surface expressed the program cleanly and correctly on the first try; the removed mut would have added no expressivity (equal binder/update counts in the loop cases, a redundant shadow chain in the straight-line cases) and its only behavioural difference — the implicit cross-iteration persistence of un-restated state — is the exact clause-3 failure mode the removal exists to eliminate. No spec_gap, no friction, no bug surfaced. The empirical signal is fully consistent with the milestone's inverted feature-acceptance argument.