Merge origin/main into claude/upbeat-gauss-D5f72

Reconciles PR #336 (CORE-02 / #234 / ADR-016 truth ledger to
DELIVERED) with two intervening main commits:

  f45afa1  feat(borrow): NLL last-use expiry for ref-bindings
           (CORE-01 pt3 Slice A, Refs #177) (#335)
  99ae5e3  feat(stdlib): STDLIB-04a — Mut effect externs
           (make_ref/get/set) → real impl (Closes #328) (#334)

Single conflict, docs/TECH-DEBT.adoc — HEAD updated CORE-02 (now
CLOSED 2026-05-19 with full ADR-016 S1..S4 narrative); origin/main
(#335) updated CORE-01 (Part 3 Slice A NLL last-use expiry LANDED).
Independent adjacent rows; resolution takes both — neither side
loses information.

The PR's comment edits in lib/codegen.ml, lib/effect_sites.ml,
lib/typecheck.ml, and the test/test_main.ml suite-label change all
survive intact through the merge.

Pure documentation + merge content. Zero behavioural risk.

Author: claude

.machine_readable/6a2/STATE.a2ml

@@ -68,7 +68,7 @@ test-files = 54
 # the feature is not enforced on user programs through the CLI pipeline.
 affine-types = "wired-and-reachable (Track A Manhattan plan complete 2026-04-10. Quantity semiring in lib/quantity.ml; invoked from typecheck.ml:1206 inside the standard CLI pipeline. Surface syntax per ADR-007 hybrid: @linear/@erased/@unrestricted attributes (Option C primary) on let/stmt-let/param/lambda-param, AND :1/:0/:ω numeric sugar (Option B) on let/stmt-let. Scaled Let rule per ADR-002 implemented in lib/quantity.ml ExprLet/StmtLet — closes BUG-001 (ω-let smuggles linear values) and BUG-002 (zero-let erasure). Four regression fixtures in test/e2e/fixtures/ exercise both surface forms. Behavioural enforcement verified via E2E Quantity test suite — 4 new passing tests, 0 regressions.)"
 linear-arrows = "enforced (2026-04-11): Three-part fix landed. (1) typecheck.ml lambda synth: |@linear x: T| e now synthesises T -[1]-> U (was always QOmega). (2) typecheck.ml lambda check mode: explicit param quantity annotation validated against expected TArrow quantity; unannotated params inherit context quantity. (3) quantity.ml ExprLambda: added env.errors accumulator; annotated lambda params declared via env_declare so env_use tracks them; usage verified with check_quantity after body walk; violations pushed to env.errors and drained at end of check_function_quantities (step 4). Saved/restored env.quantities entries to prevent scope leakage. Two E2E fixtures + 2 passing tests. 75 tests total, 0 regressions. Commit d2f9b7b pushed."
-borrow-checker = "phase-3-part-1-landed (CORE-01, PR #240 Refs #177, 2026-05-19, gate 263/263): borrow-graph validation wired — BorrowOutlivesOwner emitted (&local escaping its block), shared-XOR-exclusive enforced at use sites (UseWhileExclusivelyBorrowed), ownership derived from param type TyOwn/TyRef/TyMut (owned/ref/mut discipline now enforced from real parsed source — closed a latent hole), call-arg borrows temporary, ref-binding graph tracked. Part 2+ deferred: NLL/region inference, flow-sensitive escape via `outer = &x`, tighter quantity integration. Authoritative: docs/CAPABILITY-MATRIX.adoc + docs/TECH-DEBT.adoc CORE-01."
+borrow-checker = "phase-3-part-3-slice-A-landed (CORE-01, Refs #177, 2026-05-24): pt1 (#240, gate 263/263) borrow-graph validation wired — BorrowOutlivesOwner emitted (&local escaping its block), shared-XOR-exclusive enforced at use sites (UseWhileExclusivelyBorrowed), ownership derived from param type TyOwn/TyRef/TyMut (owned/ref/mut discipline now enforced from real parsed source — closed a latent hole), call-arg borrows temporary, ref-binding graph tracked. pt2 (gate 271→274 and 278→281) return-escape (return-of-ref-rooted-at-callee-owned-binding caught) + &mut e parser surface (zero Menhir conflict delta — exclusive borrow finally expressible from real source). pt3 Slice A NLL last-use expiry: forward pre-pass compute_last_use_index maps each symbol to its greatest mentioning statement index; check_block expires ref-bindings introduced in-block once their binder is dead, releasing the underlying borrow. Unblocks `let r = &x; print(*r); x = 2` and `let m = &mut x; let y = *m; x` while still rejecting same-block live aliasing (2 positive + 1 anti-regression hermetic tests in E2E Borrow Graph). Residual (Slices B–D): flow-sensitive escape via `outer = &x`, origin/region variables (Polonius surface) + loan-live-at-point dataflow across CFG joins, tighter quantity integration. Authoritative: docs/CAPABILITY-MATRIX.adoc + docs/TECH-DEBT.adoc CORE-01."
 row-polymorphism = "60% (records + effects rows implemented in typecheck/unify; not fully exercised end-to-end)"
 effects = "interpreter-complete (handler dispatch, PerformEffect propagation, ExprResume, multi-arg ops all wired in interp.ml 2026-04-11). WasmGC: ops registered as unreachable stubs; ExprHandle/ExprResume reject with UnsupportedFeature — full WASM dispatch needs EH proposal or CPS transform."
 dependent-types = "parse-only (TRefined AST node exists and refinement predicates parse, but predicates do not reduce; no SMT/decision procedure wired in)"

docs/CAPABILITY-MATRIX.adoc

@@ -84,16 +84,26 @@ enforced. Handlers: *interpreter-complete*; WasmGC dispatch is
 `UnsupportedFeature` pending the EH proposal or the CPS transform (the #225
 CPS line is closing the async slice of this).
 
-|Borrow checker |*partial — graph validation landed (CORE-01 pt 1)* |
+|Borrow checker |*partial — graph validation + NLL last-use landed
+(CORE-01 pts 1–3 Slice A)* |
 Place/borrow/move infra + use-after-move, conflicting-borrow,
 move-while-borrowed, lambda-capture. *CORE-01 part 1* (PR #240, Refs #177,
 gate 263/263): borrow-graph validation wired — `BorrowOutlivesOwner` now
 emitted (`&local` escaping its block); shared-XOR-exclusive enforced at
 *use* sites (`UseWhileExclusivelyBorrowed`); ownership now derived from the
 parameter *type* (`TyOwn/TyRef/TyMut`) so the owned/ref/mut discipline is
 actually enforced from real parsed source (closed a latent hole); call-arg
-borrows made temporary. *Deferred (CORE-01 pt 2+):* NLL/region inference,
-flow-sensitive escape via `outer = &x`, tighter quantity integration.
+borrows made temporary. *Part 2* (Refs #177): return-escape +
+`&mut e` parser surface (the exclusive borrow is finally expressible from
+source). *Part 3 Slice A* (Refs #177): non-lexical lifetimes —
+ref-bindings expire at their binder's *last use*, not at block exit
+(`compute_last_use_index` pre-pass + per-statement expiry in
+`check_block`). Patterns like `let r = &x; print(*r); x = 2` and
+`let m = &mut x; let y = *m; x` now type-check, while still-live borrows
+continue to block aliasing assignments. *Deferred (Slices B–D):*
+flow-sensitive escape via `outer = &x`; origin/region variables
+(Polonius surface) + loan-live-at-point dataflow across CFG joins;
+tighter quantity integration for captured linears.
 
 |Quantity / affine types |*enforced* |QTT semiring in `lib/quantity.ml`,
 invoked inside the standard CLI pipeline. `@linear`/`@erased`/`@unrestricted`

docs/TECH-DEBT.adoc

@@ -110,12 +110,23 @@ typed/codegen'd like `&e` — exclusivity is a static borrow property).
 `&`-in-`#{` literals and bare block-statements already parse on `main`;
 `-> &T`/`&T` *type* sigil deliberately **not** added — `ref T`/`mut T`
 keyword types already express reference types; a `&T` sigil is duplicate
-surface (ADR territory, not a soundness gap). *Part 2 residual — now the
-analysis, not surface:* NLL/region inference (Polonius) + flow-sensitive
-escape via `outer = &x` are now *expressible* (surface unblocked); the
-remaining work is the dataflow analysis itself. |S1 |pt1 #240 + pt2
-return-escape + `&mut` surface DONE (Refs #177); residual = NLL analysis
-— issue #177
+surface (ADR territory, not a soundness gap). *Part 3 Slice A — NLL
+last-use expiry LANDED* (Refs #177): a forward pre-pass
+(`compute_last_use_index`) maps each symbol to the greatest statement
+index that mentions it; after each statement, `check_block` expires any
+ref-binding introduced in that block whose binder is now dead, releasing
+the underlying borrow. Unblocks the canonical NLL patterns
+(`let r = &x; print(*r); x = 2`; `let m = &mut x; let y = *m; x`) while
+preserving soundness — the anti-aliasing rules still fire against
+statements that *do* use the binder (3 hermetic tests in "E2E Borrow
+Graph", two positive + one anti-regression). *Slices B–D residual:*
+flow-sensitive escape via assignment to an outer mutable
+(`outer = &x`); origin/region variables (Polonius surface) + loan-live-
+at-point dataflow across CFG joins; tighter quantity integration for
+captured linears. |S1 |pt1 #240 + pt2 return-escape + `&mut` surface +
+pt3 Slice A NLL last-use DONE (Refs #177); residual = Slices B–D
+(flow-sensitive escape, origin variables, quantity integration) —
+issue #177
 |CORE-02 |Effect-handler dispatch on WasmGC (was `UnsupportedFeature`;
 the chosen path is CPS over the EH proposal). The #225 CPS line closed
 the async slice; #234 generalised the boundary recogniser from a
@@ -169,7 +180,29 @@ complete; convergence ABI shared w/ Ephapax
 insert/set/remove/keys/values; AOT-gated (#136). Closes ESC-03 #247 (the
 #229 `Dict.t` target); unblocks the additive `Http.affine` headers→Dict
 upgrade
-|STDLIB-04 |Residual `extern` builtins → real implementations |S3 |open
+|STDLIB-04 |Residual `extern` builtins → real implementations (umbrella;
+split into 04a–04e 2026-05-24 per per-extern audit, one row per PR) |S3
+|open (5 sub-rows)
+|STDLIB-04a |Mut effect externs (`make_ref`/`get`/`set`) — *LANDED*
+(Refs #328): interp uses `VMut` cell (`lib/interp.ml`); Deno codegen
+lowers to `{__cell: x}` single-field object (`lib/codegen_deno.ml`);
+3 hermetic e2e tests in "E2E STDLIB-04a Mut #328" (Int + String
+round-trips + Deno codegen __cell-shape assertion) |S3 |DONE
+2026-05-24 (Refs #328)
+|STDLIB-04b |Throws extern `error<T>` — missing in all backends
+(`lib/interp.ml`, `lib/js_codegen.ml`, `lib/codegen_deno.ml`); sibling
+`panic` is wired and `error` should mirror it (divergent `T`) |S3 |open
+— issue #329
+|STDLIB-04c |`string_concat` extern — no direct wiring found; `++`
+operator independently lowered. Decide: remove (operator-only) or wire
+to mirror `++` |S3 |open — issue #330
+|STDLIB-04d |IO externs (`print`/`println`/`read_line`/`read_file`/
+`write_file`) — wired on all backends but no dedicated hermetic e2e
+tests; test-debt, not impl-debt |S3 |open — issue #331
+|STDLIB-04e |Pure externs (`int_to_string`/`string_to_int`/
+`string_length`) — real + tested (`lib/interp.ml:615-633`,
+`lib/codegen_deno.ml:263-272`); bookkeeping to mark DONE |S3 |open —
+issue #332
 |===
 
 == Section D — INT (ecosystem integration)

lib/borrow.ml

@@ -562,6 +562,113 @@ let check_return_escape (state : state) (symbols : Symbol.t)
        Error (BorrowOutlivesOwner (b, owner))
      | _ -> Ok ())
 
+(** NLL last-use pre-pass (CORE-01 pt3 / #177 Slice A).
+
+    Returns a map [sym_id -> max statement index at which the symbol is
+    mentioned anywhere inside [blk] (including nested blocks, lambda
+    bodies, handler arms, etc.)]. Statement indices are 0-based; the
+    block's tail expression, if any, is treated as the [n]-th "statement"
+    (where [n = List.length blk.blk_stmts]).
+
+    Used by [check_block] to expire ref-bindings introduced in this block
+    once their binder is dead, instead of holding them until lexical block
+    exit. The expiry releases the underlying borrow, so subsequent
+    statements may legally read or assign through the (no-longer-borrowed)
+    owner — the canonical Rust-style "non-lexical lifetime" win.
+
+    A symbol that never appears is simply absent from the table; callers
+    treat that as [-1] (last-use precedes the first statement → expire
+    immediately after the declaration). *)
+let compute_last_use_index (symbols : Symbol.t) (blk : block)
+    : (Symbol.symbol_id, int) Hashtbl.t =
+  let tbl : (Symbol.symbol_id, int) Hashtbl.t = Hashtbl.create 8 in
+  let bump (sym : Symbol.symbol_id) (idx : int) : unit =
+    match Hashtbl.find_opt tbl sym with
+    | Some cur when cur >= idx -> ()
+    | _ -> Hashtbl.replace tbl sym idx
+  in
+  let mark_var (idx : int) (id : ident) : unit =
+    match lookup_symbol_by_name symbols id.name with
+    | Some s -> bump s.Symbol.sym_id idx
+    | None -> ()
+  in
+  let rec visit_expr (idx : int) (e : expr) : unit =
+    match e with
+    | ExprVar id -> mark_var idx id
+    | ExprLit _ | ExprVariant _ -> ()
+    | ExprSpan (e, _) -> visit_expr idx e
+    | ExprApp (f, args) ->
+      visit_expr idx f; List.iter (visit_expr idx) args
+    | ExprField (b, _) | ExprTupleIndex (b, _) -> visit_expr idx b
+    | ExprIndex (b, i) -> visit_expr idx b; visit_expr idx i
+    | ExprTuple es | ExprArray es -> List.iter (visit_expr idx) es
+    | ExprRecord r ->
+      List.iter (fun (_, eo) -> match eo with Some e -> visit_expr idx e | None -> ()) r.er_fields;
+      (match r.er_spread with Some e -> visit_expr idx e | None -> ())
+    | ExprRowRestrict (e, _) -> visit_expr idx e
+    | ExprBinary (l, _, r) -> visit_expr idx l; visit_expr idx r
+    | ExprUnary (_, e) -> visit_expr idx e
+    | ExprLet lb ->
+      visit_expr idx lb.el_value;
+      (match lb.el_body with Some b -> visit_expr idx b | None -> ())
+    | ExprIf ei ->
+      visit_expr idx ei.ei_cond; visit_expr idx ei.ei_then;
+      (match ei.ei_else with Some e -> visit_expr idx e | None -> ())
+    | ExprMatch em ->
+      visit_expr idx em.em_scrutinee;
+      List.iter (fun arm ->
+        (match arm.ma_guard with Some g -> visit_expr idx g | None -> ());
+        visit_expr idx arm.ma_body
+      ) em.em_arms
+    | ExprBlock blk -> visit_block idx blk
+    | ExprLambda lam -> visit_expr idx lam.elam_body
+    | ExprReturn (Some e) -> visit_expr idx e
+    | ExprReturn None -> ()
+    | ExprHandle eh ->
+      visit_expr idx eh.eh_body;
+      List.iter (fun arm ->
+        match arm with
+        | HandlerReturn (_, b) -> visit_expr idx b
+        | HandlerOp (_, _, b) -> visit_expr idx b
+      ) eh.eh_handlers
+    | ExprResume (Some e) -> visit_expr idx e
+    | ExprResume None -> ()
+    | ExprTry et ->
+      visit_block idx et.et_body;
+      (match et.et_catch with
+       | Some arms ->
+         List.iter (fun arm ->
+           (match arm.ma_guard with Some g -> visit_expr idx g | None -> ());
+           visit_expr idx arm.ma_body) arms
+       | None -> ());
+      (match et.et_finally with Some b -> visit_block idx b | None -> ())
+    | ExprUnsafe ops ->
+      List.iter (fun op ->
+        match op with
+        | UnsafeRead e -> visit_expr idx e
+        | UnsafeWrite (a, b) -> visit_expr idx a; visit_expr idx b
+        | UnsafeOffset (a, b) -> visit_expr idx a; visit_expr idx b
+        | UnsafeTransmute (_, _, e) -> visit_expr idx e
+        | UnsafeForget e -> visit_expr idx e
+      ) ops
+  and visit_stmt (idx : int) (s : stmt) : unit =
+    match s with
+    | StmtLet sl -> visit_expr idx sl.sl_value
+    | StmtExpr e -> visit_expr idx e
+    | StmtAssign (lhs, _, rhs) -> visit_expr idx lhs; visit_expr idx rhs
+    | StmtWhile (c, b) -> visit_expr idx c; visit_block idx b
+    | StmtFor (_, it, b) -> visit_expr idx it; visit_block idx b
+  and visit_block (idx : int) (b : block) : unit =
+    List.iter (visit_stmt idx) b.blk_stmts;
+    match b.blk_expr with Some e -> visit_expr idx e | None -> ()
+  in
+  List.iteri (fun i s -> visit_stmt i s) blk.blk_stmts;
+  let tail_idx = List.length blk.blk_stmts in
+  (match blk.blk_expr with
+   | Some e -> visit_expr tail_idx e
+   | None -> ());
+  tbl
+
 (** Check borrows in an expression *)
 let rec check_expr (ctx : context) (state : state) (symbols : Symbol.t) (expr : expr) : unit result =
   match expr with
@@ -1000,10 +1107,41 @@ and check_block (ctx : context) (state : state) (symbols : Symbol.t) (blk : bloc
      ref-bindings introduced here do not leak past block exit. CORE-01. *)
   let block_locals_at_entry = state.block_local_syms in
   let ref_bindings_at_entry = state.ref_bindings in
-  let* () = List.fold_left (fun acc stmt ->
-    let* () = acc in
-    check_stmt ctx state symbols stmt
-  ) (Ok ()) blk.blk_stmts in
+  (* NLL last-use pre-pass (CORE-01 pt3 / #177 Slice A): compute the last
+     statement index at which each symbol is mentioned. After each
+     statement we expire any ref-binding introduced in *this* block whose
+     binder's last use has already passed, releasing the underlying
+     borrow. This is the non-lexical-lifetimes win — patterns like
+     [let r = &x; print(*r); x = 2] now type-check, while the
+     anti-aliasing rules remain sound because the borrow is still live
+     across statements that *do* use the binder. *)
+  let last_use = compute_last_use_index symbols blk in
+  let last_use_of (sym : Symbol.symbol_id) : int =
+    match Hashtbl.find_opt last_use sym with
+    | Some i -> i
+    | None -> -1
+  in
+  let is_outer_binding (sym : Symbol.symbol_id) : bool =
+    List.exists (fun (sym', _) -> sym' = sym) ref_bindings_at_entry
+  in
+  let expire_dead_ref_bindings (stmt_idx : int) : unit =
+    let dying, still_live =
+      List.partition (fun (sym, _b) ->
+        (not (is_outer_binding sym)) && last_use_of sym <= stmt_idx
+      ) state.ref_bindings
+    in
+    List.iter (fun (_sym, b) -> end_borrow state b) dying;
+    state.ref_bindings <- still_live
+  in
+  let* () =
+    let indexed = List.mapi (fun i s -> (i, s)) blk.blk_stmts in
+    List.fold_left (fun acc (i, stmt) ->
+      let* () = acc in
+      let* () = check_stmt ctx state symbols stmt in
+      expire_dead_ref_bindings i;
+      Ok ()
+    ) (Ok ()) indexed
+  in
   let* () = match blk.blk_expr with
     | Some e -> check_expr ctx state symbols e
     | None   -> Ok ()
@@ -1190,10 +1328,24 @@ let check_program (symbols : Symbol.t) (program : program) : unit result =
    bare block-statements already parsed; the `-> &T`/`&T` *type* sigil was
    deliberately not added (`ref T`/`mut T` keyword types already exist).
 
-   Still deferred — now the *analysis*, no longer parser-gated:
-   - Non-lexical lifetimes with region inference (Polonius-style).
+   CORE-01 pt3 Slice A (NLL last-use): ref-bindings introduced in a
+   block now expire at the binder's *last use*, not at block exit. A
+   forward pre-pass (compute_last_use_index) maps each symbol to the
+   greatest statement index that mentions it (the tail expression
+   counts as the n-th statement); after each statement, check_block
+   releases the underlying borrow of any in-block ref-binding whose
+   binder is now dead. Unblocks the canonical NLL patterns
+   ([let r = &x; print(*r); x = 2] and [let m = &mut x; let y = *m; x]),
+   while still rejecting real conflicts (the anti-aliasing rules fire
+   against statements that *do* use the binder, before expiry).
+   Outer-block ref-bindings are deliberately preserved — they expire
+   only at their own block's exit.
+
+   Still deferred — region-/flow-sensitive remainder:
    - Flow-sensitive escape via assignment to an outer mutable
-     (`outer = &x`) — now *expressible* (`&mut`, assignment, blocks all
-     parse); the remaining work is the dataflow analysis itself.
+     (`outer = &x`): the assignment must update the borrow graph the
+     way [let r = &x] already does.
+   - Origin/region variables (Polonius surface) + loan-live-at-point
+     dataflow across CFG joins (Slice C).
    - Tighter integration with the quantity checker for captured linears.
 *)

lib/codegen_deno.ml

@@ -275,6 +275,16 @@ let () =
   b "int_to_char"    (fun a -> Printf.sprintf "__as_intToChar(%s)" (arg 0 a));
   b "show"           (fun a -> Printf.sprintf "__as_show(%s)" (arg 0 a));
   b "panic"          (fun a -> Printf.sprintf "(() => { throw new Error(%s); })()" (arg 0 a));
+  (* Mut effect builtins (STDLIB-04a, Refs #328) — runtime mutable cells.
+     Distinct from borrow-checker [&]/[&mut] references: these back the
+     [stdlib/effects.affine] [Ref<T>] type declared `/ Mut`. Lowered as
+     a single-field object so [get]/[set] are O(1) field access; comma-
+     expression in [set] returns Unit (null) to match the extern's
+     signature `(Ref<T>, T) -> Unit / Mut`. *)
+  b "make_ref"       (fun a -> Printf.sprintf "({__cell: %s})" (arg 0 a));
+  b "get"            (fun a -> Printf.sprintf "((%s).__cell)" (arg 0 a));
+  b "set"            (fun a -> Printf.sprintf "(((%s).__cell = %s), null)"
+                                 (arg 0 a) (arg 1 a));
   (* ---- Http (issue #160) ---- *)
   (* `await` is legal: every caller of `http_request` is declared
      `/ Net, Async` and so is emitted as an `async function`