VBD decision 47 step 2, Generation A: bindings are immutable unless declared mut(name) (locals, patterns, comptime)

[shd101wyy]

Summary

This is decision 47 step 2 (locals, patterns and comptime), Generation A (plans/VALUES_BY_DEFAULT.md §6, "Decision 47: immutable bindings"). Every binding below module level is now immutable unless its name is wrapped in mut(...), like Rust's let mut.

• The marker in every binding position:

  • mut(x) := v, (mut(x) : T) = v, (mut(x) : T);
  • mut(x) :: v and comptime(mut(x)) := v
  • .Some(mut(v)) and (mut(w) := p) in a match pattern
  • { a, mut(b) }, { x : mut(b) } and (a, mut(b)) in a destructuring

  mut(x) : T on a parameter stays E0009. The evaluator strips the marker in place and records it against the declared name's token (register_mut_binding).

• E0917 (renamed E_IMMUTABLE_BINDING_WRITE) for the four writes to an unmarked binding:

  • reassignment (the first assignment of a (x : T); declaration, on each branch, is its initialization);
  • a field or Array element write to the binding's own storage;
  • a &mut lend: a &mut x argument, a &mut self receiver, y := &mut x, match(&mut x, …) or a &mut x capture;
  • the same lend made by a &mut self method call.

  A ref handle (today's collections, ref(struct)) is written through without the marker, but reassigning one needs it. String is a value, so s.push_str(..) needs mut(s).

• Bindings that rebind instead: parameters, capture-list entries and for element bindings take no mut. A write to one is E0917 with a "rebind it" help (mut(p_m) := p;, a move). For a for element, the help suggests for(&mut coll, x => …) instead. Reassigning a parameter stays E0902.

• E0918 is unchanged and checked first, so a runtime write to a mut(x) :: binding is still E0918.

• Scope: the rule is enforced outside src/, std/, the repository's scripts/ and build.yo, through the globals step's exemption (is_global_mut_rule_exempt), because the released seed still builds those trees.

• Census knob: YO_AUDIT_MUT_BINDINGS=1 prints every write ([mut-binding] how=… kind=… marked=…) without rejecting it.

• Migration: yo fix <path> --migrate mut-bindings inserts the markers and lists the parameter, capture-list and for-element writes to rebind by hand.

  • It holds a write made inside a comptime_expect_error argument until the case's outcome is known.
  • If the argument still raises, the case expects a different error, so the binding is marked to keep that error the one raised.
  • Otherwise the case expected the write error itself, and the binding stays unmarked.

• The tests/ sweep is that tool's output in its own regenerable commit (be581a2b9), followed by a separate commit of hand rebinds.

• Docs and registry:

  • DESIGN, ERROR_DIAGNOSTICS and CTFE in en-US and zh-CN;
  • the E0917/E0902 registry entries and examples;
  • .github/instructions and the syntax cheatsheet;
  • the plan's census and "as built" sections, and its Landed entry.

Deviations and behavior changes that need the maintainer's eye

1. Module-level mut(x) :: v is accepted. This goes against the plan's open-point recommendation (block scope only). The reason: tests/comptime.test.yo already reassigns a module-level :: binding at module level (_RW_M = i32(2);). Rejecting that would delete a working feature, which is beyond a Generation A; Generation A only asks for the marker. Whether module level keeps mut(x) :: is the maintainer's call, and rejecting it later is a one-line error.
2. A std API signature change. The 27 read-only methods of std/time (Duration.as_secs, Instant.elapsed, DateTime.to_unix, …) and the prelude's Array(T, N).len took self : &mut Self and now take self : &Self. With the old signatures, d.as_secs() on an unmarked Duration would be E0917 under this rule. Filed as issues/fixed/2026-10-17-std-time-read-only-methods-take-self-mut.md (S2), with a test that fails before the fix. yo doc output for these methods changes.
3. A diagnostic-order change. A &mut capture of a by-value parameter used to be rejected with "A &mut capture needs a writable place". A parameter is now an immutable binding, so E0917 ("Cannot lend &mut (a &mut capture) x: it is a parameter…") fires first. tests/closure_capture_list.test.yo now expects that text.

Ordering

The src/std sweep (Generation B) comes after V2b Generation B. Once the collections are values, their handle writes also need the marker: about 5,800 in src, 480 in std and 2,100 in tests.

Generation A does not depend on V2b:

• the rule applies only outside src/std;
• the tests/ sweep is regenerable;
• landing it first gets mut( parsed by a released seed one release earlier.

One obligation passes to V2b Generation B. The marker strip edits a call's argument list in place, which works only because ArrayList is a shared handle today. When ArrayList becomes a value, the strip must write the edited list back.

Verification

Re-gate after the rebase onto develop 29ceb209d (#1429, #1419, #1437, #1433, #1424). The numbers in the rest of this section are from the earlier base b94fd6968 unless marked post-rebase.

• Post-rebase build: tree yo build --std-path ./std (seed v0.2.64) rc=0; check ./src 278/278; tree check ./std 172/172.

• Post-rebase migration: yo fix --migrate mut-bindings over the 22 test files develop changed since b94fd6968 marked 108 bindings in 12 of them. They are committed separately and contain only mut(...) binding marks.

• Post-rebase tests (tree binary, YO_TEST_LEAK_VERDICT=0, one file per call, --parallel 1 --std-path ./std): every file rc=0.

  file	passed
  addr_of	8
  algebraic_effects	79
  async/combinators	56
  async/sm_ownership	46
  closure_param_forwarding	6
  collections/array_list	130
  cross_thread_wake	8
  derive	66
  derive_clone_complex	21
  dyn	39
  for_macro_borrow	25
  for_macro_borrow_strict	1
  for_macro_borrow_user_collection	3
  index	79
  iso	12
  match_async_arms	26
  move_only_collections	14
  parameter_modes	44
  prefix_operators	7
  rc	114
  thread_safety	4
  unit_as_value_type	19
  mut_bindings	13
  global_lend	10
  closure_capture_list	41
  comptime	47

• Post-rebase cli-diff (full run, tree binary): 399 PASS, 8 GOLDEN-DIFF, 1 NO-GOLDEN, 1 SKIP (network).

  • The 8 GOLDEN-DIFFs are cases that both VBD decision 39 Generation A: the borrowed for walks a cursor over a local borrow; indices(); E0911 across the macro boundary (B7 part 1) #1429 and this branch changed. The rebase kept VBD decision 39 Generation A: the borrowed for walks a cursor over a local borrow; indices(); E0911 across the macro boundary (B7 part 1) #1429's goldens, and those goldens hash neither this branch's syntax cheatsheet nor its marked fixture. That covers 7 cheatsheet-hash cases (build-stamp-dotted-dir, init, init-build-test, init-cwd, init-existing, skills-install, skills-install-zh) and check-strict-borrow-loop-calls-a-read-only-method, whose fixture hash moved because of its mut marks. In every case only an expected_tree hash line moved; rc and stdout are unchanged. All 8 were re-recorded with the tree binary and re-run: PASS 8.
  • The NO-GOLDEN, compile-allocator-fixed-oom, comes from the environment and also happens on develop. The probe's PARENT runs in the 64 KiB fixed heap, and it exhausts that heap when the caller's environment is about 2 KB larger than this shell's 34 KB. The largest passing pad is 27,187 bytes for develop's probe and 27,347 bytes for this branch's. With three large shell variables unset, the case PASSes. Filed as issues/2026-10-18-compile-allocator-fixed-oom-case-fails-under-a-large-caller-environment.md (S3).

• Post-rebase fmt and refs: tree fmt --check ./std ./tests ./src ./docs ./.github ./README.md (GATE 6) passes, and scripts/check-issue-refs.sh is green.

Pre-rebase gate (base b94fd6968):

Tree-built compiler, yo build --std-path ./std with seed v0.2.64: rc=0.

• yo check ./src --std-path ./std (seed): 278/278. yo check ./std --std-path ./std (tree binary): 172/172.

• Full language suite (yo test ./tests --exclude tests/internal --exclude tests/cli-cases --parallel 4): 5274 passed, 43 failed.

  • 41 were closure_capture_list (the diagnostic-order change above). After the expected-text fix, that file reruns at 41/41.
  • The other 2 come from the environment and fail the same way with develop's v0.2.64 binary on develop's own copies of the files, in the same shell:
    • tests/os/env.test.yo "temp_dir returns /tmp on Linux" (the shell sets TMPDIR=/tmp/nix-shell.…);
    • tests/time/datetime.test.yo "DateTime.now honours TZ: Asia/Tokyo" (no TZ data).

• tests/mut_bindings.test.yo (new, 13 tests) covers the four writes accepted and rejected, ref handles, typed declarations, first-assignment initialization, patterns, destructuring, comptime, E0918, parameter rebinds (and the move), &mut scrutinee and capture, read-only std receivers, and module-level mut ::.

• tests/internal, in-process (YO_TEST_IN_PROCESS=1, one run): 108 passed, 1311 failed, every failure leak-only, 0 non-leak failures. This is the same 108/1311 as d46's run on its own branch, and the same in-process leak artifact; check_watch has 12 leak-only failures on both sides. Each top file run alone with identical flags, develop (yo-dev-5425cd7bf, its tree) against this branch:

  file	develop pass / leak	this PR pass / leak
  types_utils	71 / 1	71 / 1
  lexer	68 / 0	68 / 0
  parser	62 / 0	62 / 0
  formatter	58 / 0	58 / 0
  types_guards	44 / 0	44 / 0
  verifier_list_len	24 / 1	24 / 1
  check_watch	0 / 12	0 / 12
  error	34 / 1	34 / 1

  The same tests leak on both sides: one each in types_utils ("raw-ptr predicate: a type object that contains itself terminates"), verifier_list_len, and error ("warnings: the stash dedupes…"), plus all 12 of check_watch's tests.

• cli-diff: after re-recording, 399 PASS, 0 GOLDEN-DIFF, 0 NO-GOLDEN, 1 SKIP (network). Every changed golden, and why:

  • Marked fixture (written locals declared mut). Only the fixture hash in expected_tree moved; rc and stdout are unchanged:
    • async-await-in-a-while-body-expression, async-await-in-an-expression-in-an-arm, async-state-machine-pools
    • audit-implicit-copy-lists-copies-of-live-values, audit-rc-write-census, build-run-args
    • check-strict-borrow-loop-calls-a-read-only-method, check-test-bodies-auto-boxed-dyn
    • compile-allocator-fixed, compile-allocator-fixed-oom, compile-allocator-fixed-oom-shapes
    • compile-emit-chunks, compile-emit-chunks-memory-cap, contracts-runtime-old-ensures
    • dyn-vtables-registering-futures-are-each-defined-once, inout-interior-borrow-growth-panics, raw-extern-future-sync-await-releases, fix-migrate-params
    • the four diagnostic cases whose intended error must stay the one raised: field-write-through-a-match-binding-is-e0908, local-borrow-conflict-is-e0911, loop-carried-move-is-rejected, move-on-one-way-out-of-a-loop-is-e0907
  • fix-migrate-explicit-copy: marked fixture; one listed site's column moves from 27:9 to 27:14, because mut( was inserted on that line.
  • explain-list: E0917's title is now "a write to an immutable binding".
  • fix-migrate-borrow-spelling: the case now runs --migrate mut-bindings after borrow-spelling, in phase order. That adds one fix: line and changes the output tree.
  • fix-migrate-mut-bindings: new case. It runs a dry run, then the fix, then check, which reports E0917 for a parameter write the tool lists but does not rewrite.
  • init, init-build-test, init-cwd, init-existing, skills-install, skills-install-zh, build-stamp-dotted-dir: the syntax cheatsheet changed.

• Census with the final binary, YO_AUDIT_MUT_BINDINGS=1:

  • src: 15,229 write sites, 9,547 bindings to mark;
  • std: 1,484 sites, 1,068 bindings;
  • tests: the migration marked 2,370 bindings and listed 9 parameter writes.

• fmt: tree binary fmt --check passes on every changed .yo and .md file. scripts/check-issue-refs.sh is green.

LLM attribution

• Model: Claude Opus 5.5
• Agent harness (optional): Claude Code

Deferred

• Generation B: sweep src/std/docs/markdown_yo and enforce everywhere, after V2b Generation B. The plan's census table sizes it.
• Re-pointing a local borrow (cur = &mut n.next) without mut(cur) is not checked yet. The mut(cur) := &mut place desugar comes with decision 43.
• The maintainer's call on module-level mut(x) :: (above).
• scripts/build_site.yo (25 bindings, 8 parameter writes) is built by the seed in release.yml, so scripts/ is exempt like src/std until Generation B.
• yo fix over several files still fails to evaluate some files (issues/2026-10-15-yo-fix-over-several-files-applies-one-files-generic-impls-to-anothers-same-named-type.md, S3). The sweep migrated those files one at a time.

🤖 Generated with Claude Code