feat(lang): scalar field assignment through mut parameters (Step 3, SH-013)

`m.field = expr` on a `mut` parameter now works and propagates to the caller
on every backend, removing the "List<Int> as a mutable cell" smell that
self-hosting the Mailbox forced (SH-007).

- Checker: a `mut` parameter (new AssignBinding::MutParam) permits field/index
  assignment (still rejects rebinding the parameter itself).
- VM: CallKnown carries the callee's mut-param positions; on frame completion
  (every return path: Return, tier-0, native, `?`-early, fall-off-end) each
  mut arg's final value is written back to the caller's register
  (apply_mut_writeback), matching AOT's &mut semantics. Backward compatible:
  empty mut_args is a no-op; List-based propagation is unchanged.
- Inliner skips mut-arg calls (they need the write-back).

Also noted: core already ships `Counter` (mut-scalar container). New test
backends_agree_on_mut_param_field_assignment (5-way). Full gate green:
feature differential 22/22, vm 112, corpus, checker 212/149, clippy clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Haofei

docs/rss-selfhost-ledger.md

@@ -282,3 +282,27 @@ Status:         open | decided | done
   within noise; was 345 vs 326). Telemetry `considered: 0` after warmup.
 - **Tests:** feature differential 21/21 (behavior-neutral).
 - **Status:** done.
+
+### SH-013 — scalar field assignment through a `mut` parameter (fixed)
+
+- **Tool:** Mailbox<T> (the List<Int>-as-cell smell, SH-007)
+- **Symptom:** `m.count = m.count + 1` on a `mut` param was rejected (RS0311), so
+  the mailbox held mutable scalars in 1-element lists and recomputed `count`.
+- **Root cause:** (1) the checker rejected any assignment rooted in a parameter;
+  (2) the VM copies `CallKnown` args into the callee window with no write-back, so
+  even if allowed, scalar field mutations wouldn't propagate (only `List` fields
+  did, via their shared `RefCell`). AOT already had `&mut` semantics.
+- **Classification:** language (checker) + VM (call semantics).
+- **Decision (DONE):**
+  - Checker: a `mut` parameter (`AssignBinding::MutParam`) allows field/index
+    assignment (not bare rebinding).
+  - VM: `CallKnown` carries the callee's `mut`-param positions; when the frame
+    completes (any return path), each `mut` arg's final value is written back to
+    the caller's register (`apply_mut_writeback`), matching AOT's `&mut`.
+  - Backward compatible: empty `mut_args` ⇒ no-op; List-based code already
+    propagated and is unchanged.
+- **Note:** core already ships `Counter` (`Counter.new/add/value`, a `mut`-scalar
+  container) — the stdlib alternative the review suggested already exists.
+- **Tests:** `backends_agree_on_mut_param_field_assignment` (5-way). Full gate
+  green: feature differential 22/22; vm 112; corpus; checker 212/149.
+- **Status:** done.

src/analyzer.rs

@@ -4897,6 +4897,9 @@ enum AssignBinding {
     MutLocal,
     ImmutableLocal,
     Param,
+    /// A `mut` parameter: not reassignable itself, but its fields/elements may be
+    /// updated in place (the mutation propagates to the caller, matching `&mut`).
+    MutParam,
 }
 
 #[derive(Clone)]
@@ -4929,11 +4932,12 @@ impl<'a> AssignChecker<'a> {
         self.scopes.clear();
         self.push_scope();
         for param in &function.params {
-            self.insert(
-                param.name.clone(),
-                AssignBinding::Param,
-                Some(type_ref_name(&param.ty)),
-            );
+            let binding = if param.effect == Some(DataEffect::Mut) {
+                AssignBinding::MutParam
+            } else {
+                AssignBinding::Param
+            };
+            self.insert(param.name.clone(), binding, Some(type_ref_name(&param.ty)));
         }
         self.block(&function.body);
         self.pop_scope();
@@ -5172,9 +5176,9 @@ impl<'a> AssignChecker<'a> {
                         format!("`{name}` is an immutable binding"),
                         format!("Declare `{name}` with `let mut` to allow reassignment."),
                     ),
-                    Some(AssignBinding::Param) => (
+                    Some(AssignBinding::Param | AssignBinding::MutParam) => (
                         format!("`{name}` is a parameter, not a reassignable local"),
-                        "Parameters are not reassignable. Bind a `let mut` local, or mutate through a `mut` parameter."
+                        "Parameters are not reassignable (even `mut` ones): a `mut` parameter's fields/elements may be updated, but the parameter binding itself can't be rebound. Bind a `let mut` local instead."
                             .to_string(),
                     ),
                     None => (
@@ -5244,6 +5248,9 @@ impl<'a> AssignChecker<'a> {
         };
         match self.resolve(root) {
             Some(AssignBinding::MutLocal) => {}
+            // A `mut` parameter's fields/elements may be updated in place (the
+            // mutation propagates to the caller, like `&mut`).
+            Some(AssignBinding::MutParam) => {}
             Some(AssignBinding::ImmutableLocal) => {
                 self.diagnostics.push(invalid_assignment_diagnostic(
                     span.clone(),

src/reg_vm/mod.rs

@@ -592,9 +592,12 @@ fn native_inline_leaf_calls(unit: &RegUnit, func: &RegFunction) -> Option<(Vec<R
                 dst,
                 function,
                 args,
+                mut_args,
             } => {
                 let callee = unit.functions.get(*function)?;
-                if !native_callee_inlinable(callee, args.len()) {
+                // Calls with `mut` args need a write-back at return; don't inline
+                // them (native-inlinable callees are side-effect-free anyway).
+                if !mut_args.is_empty() || !native_callee_inlinable(callee, args.len()) {
                     return None;
                 }
                 let base = next_reg;
@@ -1676,6 +1679,12 @@ enum RegInstr {
         dst: Reg,
         function: usize,
         args: Vec<Reg>,
+        /// Argument positions passed with `mut` (the callee's `mut` params). After
+        /// the call returns, each such argument's (possibly mutated) value is
+        /// written back to the caller's argument register, so a `mut` parameter's
+        /// field/element mutations propagate to the caller — matching AOT's
+        /// `&mut` semantics.
+        mut_args: Vec<usize>,
     },
     /// `spawn f(args)` / `async let`: start `function` as a new concurrent task
     /// and put a Task handle in `dst` (the spawning task keeps running).
@@ -3733,10 +3742,12 @@ impl RegLowerer<'_> {
                 // the generics before the lookup — otherwise a generic *function*
                 // call falls through and is mis-lowered as a struct construction.
                 if let Some(function) = self.function_ids.get(type_root_name(name)).copied() {
+                    let mut_args = self.user_mut_arg_positions(name);
                     self.emit(RegInstr::CallKnown {
                         dst,
                         function,
                         args: arg_regs,
+                        mut_args,
                     });
                 } else if self.is_native_function(None, name) {
                     let mut_args = self.native_mut_arg_positions(None, name);
@@ -5038,10 +5049,13 @@ impl RegLowerer<'_> {
                             return Ok(dst);
                         }
                         if let Some(function) = self.function_ids.get(&qualified_key).copied() {
+                            let mut_args =
+                                self.native_mut_arg_positions(Some(namespace_root), name_root);
                             self.emit(RegInstr::CallKnown {
                                 dst,
                                 function,
                                 args: arg_regs,
+                                mut_args,
                             });
                             return Ok(dst);
                         }
@@ -5106,6 +5120,12 @@ impl RegLowerer<'_> {
             .unwrap_or_default()
     }
 
+    /// `mut` parameter positions of a user function, so a `CallKnown` can write
+    /// the mutated arguments back to the caller (matching AOT's `&mut` params).
+    fn user_mut_arg_positions(&self, name: &str) -> Vec<usize> {
+        self.native_mut_arg_positions(None, name)
+    }
+
     fn variant_match(&mut self, value: &HirExpr, arms: &[HirMatchArm]) -> Result<bool, EvalError> {
         if arms.is_empty()
             || !arms
@@ -5842,6 +5862,11 @@ struct Frame {
     /// Absolute register in the caller that receives this frame's return value.
     /// `usize::MAX` marks a driver root (its value is returned out of `run_frame`).
     ret_dst: usize,
+    /// `mut`-argument write-backs to perform when this frame completes:
+    /// `(caller_abs_reg, this_frame_abs_reg)` pairs. The caller register receives
+    /// the parameter's final (possibly mutated) value, so `mut` params propagate.
+    /// Empty for the overwhelmingly common no-`mut`-arg call (then a no-op).
+    mut_writeback: Vec<(usize, usize)>,
 }
 
 /// Result of driving a task's call stack one slice at a time.
@@ -6448,6 +6473,7 @@ impl RegVm {
                 dst,
                 function: callee_id,
                 args,
+                mut_args,
             } = instr
             {
                 let callee = Rc::clone(&unit.functions[*callee_id]);
@@ -6458,6 +6484,11 @@ impl RegVm {
                     self.set_reg(next_base + index, value);
                 }
                 let result = self.run_frame(unit, callee, next_base)?;
+                // Propagate `mut` parameters back to the caller's argument regs.
+                for &pos in mut_args {
+                    let value = self.reg(next_base + pos).clone();
+                    self.set_reg(base + args[pos], value);
+                }
                 self.set_reg(base + *dst, result);
                 continue;
             }
@@ -7022,6 +7053,16 @@ impl RegVm {
         self.written[index] = true;
     }
 
+    /// Propagate a completing frame's `mut` parameters back to the caller: each
+    /// `(caller_reg, callee_reg)` copies the parameter's final value out. A no-op
+    /// for the common call with no `mut` args (empty `mut_writeback`).
+    fn apply_mut_writeback(&mut self, frame: &Frame) {
+        for &(caller_reg, callee_reg) in &frame.mut_writeback {
+            let value = self.reg(callee_reg).clone();
+            self.set_reg(caller_reg, value);
+        }
+    }
+
     #[inline(always)]
     fn take_reg(&mut self, index: usize) -> VmValue {
         assert!(
@@ -7055,6 +7096,7 @@ impl RegVm {
             ip: 0,
             base,
             ret_dst: usize::MAX,
+            mut_writeback: Vec::new(),
         });
         match self.drive(unit, floor)? {
             Outcome::Completed(value) => Ok(value),
@@ -7095,6 +7137,7 @@ impl RegVm {
             ip: 0,
             base: 0,
             ret_dst: usize::MAX,
+            mut_writeback: Vec::new(),
         }];
         self.tasks.insert(
             tid,
@@ -7415,6 +7458,7 @@ impl RegVm {
                 && let Some(value) = self.try_native(&func, base)
             {
                 let frame = self.frames.pop().expect("active frame");
+                self.apply_mut_writeback(&frame);
                 if self.frames.len() == floor {
                     return Ok(Outcome::Completed(value));
                 }
@@ -7429,6 +7473,7 @@ impl RegVm {
             if self.jit_enabled && ip == 0 && self.is_jit_eligible(&func) {
                 let value = self.run_jit(unit, &func, base)?;
                 let frame = self.frames.pop().expect("active frame");
+                self.apply_mut_writeback(&frame);
                 if self.frames.len() == floor {
                     return Ok(Outcome::Completed(value));
                 }
@@ -7447,6 +7492,7 @@ impl RegVm {
                     PureStep::Next => {}
                     PureStep::Return(value) => {
                         let frame = self.frames.pop().expect("active frame");
+                        self.apply_mut_writeback(&frame);
                         if self.frames.len() == floor {
                             return Ok(Outcome::Completed(value));
                         }
@@ -7462,13 +7508,21 @@ impl RegVm {
                             dst,
                             function: callee_id,
                             args,
+                            mut_args,
                         } => {
                             let callee = Rc::clone(&unit.functions[*callee_id]);
                             self.prepare_frame(next_base, callee.regs);
                             for (index, reg) in args.iter().enumerate() {
                                 let value = self.reg(base + *reg).clone();
                                 self.set_reg(next_base + index, value);
                             }
+                            // `mut` args: when this frame completes, write each
+                            // parameter's final value back to the caller's register
+                            // so mutations propagate (caller_abs_reg, callee_abs_reg).
+                            let mut_writeback = mut_args
+                                .iter()
+                                .map(|&pos| (base + args[pos], next_base + pos))
+                                .collect();
                             // Stackless call: save our resume point, push the callee, and
                             // re-enter the driver loop instead of recursing on the host
                             // stack — so an `await` deep in this chain can later suspend it.
@@ -7478,6 +7532,7 @@ impl RegVm {
                                 ip: 0,
                                 base: next_base,
                                 ret_dst: base + *dst,
+                                mut_writeback,
                             });
                             continue 'frames;
                         }
@@ -7839,6 +7894,7 @@ impl RegVm {
                                     // whole stackless driver.
                                     let err_value = value_err(error);
                                     let frame = self.frames.pop().expect("active frame");
+                                    self.apply_mut_writeback(&frame);
                                     if self.frames.len() == floor {
                                         return Ok(Outcome::Completed(err_value));
                                     }
@@ -7867,6 +7923,7 @@ impl RegVm {
             // Fell off the end of the function body without an explicit `Return`.
             // Lowering always appends one, so this is a defensive `Unit` return.
             let frame = self.frames.pop().expect("active frame");
+            self.apply_mut_writeback(&frame);
             if self.frames.len() == floor {
                 return Ok(Outcome::Completed(VmValue::Unit));
             }

tests/backend_differential.rs

@@ -543,6 +543,35 @@ fn backends_agree_on_manifest_inspector() {
     common::differential::assert_backends_agree("selfhost-manifest-inspector.rss", source, &[fixture]);
 }
 
+/// Scalar field assignment through a `mut` parameter must propagate to the caller
+/// on every backend (VM write-back == AOT `&mut`). Regression for ledger SH-013.
+#[test]
+fn backends_agree_on_mut_param_field_assignment() {
+    let source = "features: local\n\
+\n\
+struct Tally {\n\
+    n: Int\n\
+}\n\
+\n\
+fn bump(c: mut Tally) -> Unit {\n\
+    c.n = c.n + 1\n\
+}\n\
+\n\
+fn add(c: mut Tally, amount: Int) -> Unit {\n\
+    c.n = c.n + amount\n\
+}\n\
+\n\
+fn main() -> Unit {\n\
+    let mut c = Tally(n: 0)\n\
+    bump(c: mut c)\n\
+    bump(c: mut c)\n\
+    add(c: mut c, amount: 10)\n\
+    Log.write(message: read String.from_int(value: c.n))\n\
+    return Unit\n\
+}\n";
+    common::differential::assert_backends_agree("mut-param-field.rss", source, &[]);
+}
+
 /// A generic collection implemented in RSS itself: `benchmark/selfhost_mailbox.rss`
 /// (a fixed-capacity `Mailbox<T>` over parallel lists, with oldest-first and
 /// source-filtered takes). Regression for the generic-call lowering fix (a generic