feat(params): scalar mut param write-back (SH-018) + spec §5A

Allow a `mut` parameter of a Copy scalar type (Int/Bool/Float/Char, …) to be
reassigned inside the callee, with the new value written back to the caller
(call-by-reference, `&mut`). Non-Copy `mut` params stay non-reassignable.

The reg-VM already writes every `mut` param's final register back (effect-based
mut_args), so no reg-VM/native change is needed. Two frontend touch-points:
- analyzer/assign.rs: permit rebinding a `mut` Copy-scalar parameter (gated on
  checks::local::is_copy_type_name); keep RS0311 for plain params and non-Copy
  `mut` params.
- rust_lower/lowerer.rs: emit `(*pos)` on read and as assignment target for a
  `mut` Copy-scalar param, since `mut T` already lowers to `&mut T`.

Adds pass fixture mut-scalar-writeback.rss (Int + Bool). Updates spec §5A and
the grammar comment, and ledger SH-018.

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

Author: olwang

crates/rsscript/src/analyzer/assign.rs

@@ -358,13 +358,25 @@ impl<'a> AssignChecker<'a> {
                         self.check_assignment_type(name, &stmt.value, &span);
                         return;
                     }
+                    // A `mut` parameter of a Copy scalar type (Int/Bool/Float/Char, …)
+                    // MAY be reassigned: it lowers to `&mut T`, and the new value is
+                    // written back to the caller, matching `&mut` semantics. Non-Copy
+                    // `mut` params (struct/collection) stay non-rebindable below.
+                    Some(AssignBinding::MutParam)
+                        if self
+                            .resolve_type(name)
+                            .is_some_and(|ty| crate::checks::local::is_copy_type_name(&ty)) =>
+                    {
+                        self.check_assignment_type(name, &stmt.value, &span);
+                        return;
+                    }
                     Some(AssignBinding::ImmutableLocal) => (
                         format!("`{name}` is an immutable binding"),
                         format!("Declare `{name}` with `let mut` to allow reassignment."),
                     ),
                     Some(AssignBinding::Param | AssignBinding::MutParam) => (
                         format!("`{name}` is a parameter, not a reassignable local"),
-                        "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."
+                        "Parameters are not reassignable (except a `mut` Copy-scalar one, which is written back to the caller): a non-Copy `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 => (

crates/rsscript/src/rust_lower/lowerer.rs

@@ -600,10 +600,28 @@ impl<'a> RustLowerer<'a> {
             || self.native_bindings.contains_key(&key)
     }
 
+    /// Whether `name` is a `mut` parameter of a Copy scalar type (Int/Bool/Float/…).
+    /// Such a parameter lowers to `&mut T` (call-by-reference write-back), so a bare
+    /// ident read/target must dereference it. Non-Copy `mut` params (struct/collection)
+    /// keep their `&mut Struct` binding and are never dereferenced here.
+    fn is_mut_copy_scalar_param(&self, name: &str) -> bool {
+        matches!(self.param_effects.get(name), Some(DataEffect::Mut))
+            && self
+                .value_types
+                .get(name)
+                .is_some_and(is_copy_type_ref)
+    }
+
     pub(super) fn lower_expr(&mut self, expr: &Expr) -> String {
         match expr {
             Expr::Ident(name, _) => {
-                if self.drop_field_names.contains(name) {
+                if self.is_mut_copy_scalar_param(name) {
+                    // A `mut` Copy-scalar parameter lowers to `&mut T`; a bare read
+                    // dereferences it so the value (and assignment through it) works
+                    // against the `&mut i64`/`&mut bool`/… binding. As an assignment
+                    // target this yields `(*pos) = …`, writing back to the caller.
+                    format!("(*{})", rust_value_ident(name))
+                } else if self.drop_field_names.contains(name) {
                     format!("self.{}", rust_ident(name))
                 } else if self.read_view_bindings.contains(name)
                     && self

crates/rsscript/tests/fixtures/pass/mut-scalar-writeback.rss

@@ -0,0 +1,29 @@
+// A `mut` parameter of a Copy scalar type may be reassigned inside the callee,
+// and the new value is written back to the caller (call-by-reference, `&mut`).
+// This lets self-hosted code pass a cursor as `mut pos` and advance it in place
+// instead of threading an index through return values (SH-018).
+
+fn advance(pos: mut Int) -> Unit {
+    pos = pos + 1
+    return Unit
+}
+
+fn toggle(flag: mut Bool) -> Unit {
+    flag = flag == false
+    return Unit
+}
+
+fn main() -> Unit {
+    let mut cursor = 0
+    advance(pos: mut cursor)
+    advance(pos: mut cursor)
+    // cursor is observably 2 after two write-backs.
+    Log.write(message: read String.from_int(value: cursor))
+
+    let mut flag = false
+    toggle(flag: mut flag)
+    if flag {
+        Log.write(message: read "on")
+    }
+    return Unit
+}

docs/ledgers/rss-selfhost-ledger.md

@@ -459,11 +459,24 @@ gap is VM value-representation / intrinsic-dispatch cost (the next big lever).
 - **Classification:** language (no method syntax / cursor mutation) + docs.
 - **Decision:** worked around by the return-the-new-index convention and a
   `code_at` sentinel helper; it reads cleanly enough and reaches full tier-0
-  parity (544/544). The general lever (method syntax or a mutable-cursor pattern)
-  is a language-ergonomics follow-up, not a blocker. Recorded so the plumbing
-  cost of self-hosting stateful passes is visible.
-- **Tests:** `crate::selfhost_parity::lexer_parity_corpus` (tier 0, 544/544).
-- **Status:** decided (worked around).
+  parity (544/544). The mutable-cursor lever is now available: a `mut`
+  **Copy-scalar** parameter (Int/Bool/Float/Char, …) may be reassigned inside the
+  callee and the new value is written back to the caller (`&mut` semantics), so a
+  scanner can take `i: mut Int` and do `i = i + 1` instead of returning the new
+  index. Method/`impl` syntax remains a separate follow-up.
+- **Fix:** the reg-VM already wrote a `mut` param's final register back to the
+  caller for every `mut` param (scalar included), so no reg-VM/native change was
+  needed. Only two frontend touch-points were added: (1) the assignment gate
+  (`analyzer/assign.rs`) now permits rebinding a `mut` Copy-scalar parameter
+  (checked via `checks::local::is_copy_type_name`), keeping RS0311 for plain
+  params and non-Copy `mut` params; (2) AOT lowering (`rust_lower/lowerer.rs`)
+  emits `(*pos)` on read and as the assignment target for such a param, since
+  `mut T` already lowers to `&mut T`. Non-Copy `mut` params keep their `&mut Struct`
+  lowering and stay non-reassignable (only fields/elements are mutable).
+- **Tests:** `crate::selfhost_parity::lexer_parity_corpus` (tier 0, 544/544);
+  `tests/fixtures/pass/mut-scalar-writeback.rss` (Int + Bool write-back).
+- **Status:** fixed (scalar Copy `mut` params are reassignable with caller
+  write-back; non-Copy `mut` params stay non-reassignable).
 
 ### SH-019 — a `fresh`-returning fn can't build its result via `mut` + `List.push`
 

docs/spec/RSScript_v0.7_Spec.md

@@ -978,15 +978,19 @@ place-conflict, effect, and resource checking as `mut` API calls (it is not an
 "expression-shaped" side effect). It comes in two forms:
 
 - **Rebind a `let mut` local:** `x = e`. The target's root must be a reassignable
-  local (a `let mut` binding). Parameters are never reassignable — even a `mut`
-  parameter: its fields/elements may be updated, but the parameter binding itself
-  cannot be rebound. The assigned value's type must match the local's type.
+  local (a `let mut` binding) or a `mut` **Copy-scalar** parameter. A non-Copy
+  `mut` parameter (struct/collection) is not reassignable: its fields/elements may
+  be updated, but the parameter binding itself cannot be rebound. A `mut`
+  parameter of a Copy scalar type (Int, Bool, Float, Char, …) **may** be reassigned;
+  the new value is written back to the caller, matching `&mut` (call-by-reference).
+  The assigned value's type must match the local's/parameter's type.
 - **Update a place inside a local:** `obj.field = e` or `list[i] = e`. The place
   must start from a `let mut` local in scope, and the same type rule applies.
 
 The target is validated to be a *place* during checking; assigning to a
-non-place, to a parameter root, or with a mismatched value type is a frontend
-diagnostic. Assignment to a place obeys the place-conflict rule (see pattern
+non-place, to a non-Copy parameter root (a `mut` Copy-scalar parameter root is
+allowed and written back to the caller), or with a mismatched value type is a
+frontend diagnostic. Assignment to a place obeys the place-conflict rule (see pattern
 matching), so a single statement cannot alias-mutate overlapping places. All
 *other* mutation — of container, managed, and resource state — is still expressed
 through explicit `mut` API calls (`Map.insert(map: mut m, ...)`), so mutation
@@ -5884,7 +5888,7 @@ stmt        = let | view | assign | return | if | match | for | loop | while
             | with | task-group | select | break | continue | expr ;
 let         = ( "let" | "local" ) [ "mut" ] pattern [ ":" type ] "=" expr ;
 view        = "view" ident "=" expr ;                (* borrowed-region binding, §20.2-1 *)
-assign      = place "=" expr ;                       (* §5A; place not parameter root *)
+assign      = place "=" expr ;                       (* §5A; place root not a non-Copy parameter; a `mut` Copy-scalar param root is allowed and written back *)
 return      = "return" [ expr ] ;
 if          = "if" expr block [ "else" ( if | block ) ] ;
 match       = "match" data-effect expr "{" { arm } "}" ;