Merge branch 'main' into claude/bold-brahmagupta-0T7Bh

Author: hyperpolymath

docs/TECH-DEBT.adoc

@@ -170,7 +170,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/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`

lib/interp.ml

@@ -732,6 +732,29 @@ let create_initial_env () : env =
       | _ -> Error (TypeMismatch "log2 expects Float")
     ));
 
+    (* -- Mut effect builtins (STDLIB-04a, Refs #328) ----------------------
+       Backs the [stdlib/effects.affine] externs `make_ref`/`get`/`set`,
+       declared `/ Mut`. Distinct from the borrow-checker [&]/[&mut]
+       references: these are runtime mutable cells (parameterised type
+       [Ref<T>] in the stdlib). The interp uses [VMut] (an existing
+       mutable-cell variant in [Value]) so [get]/[set] go through the
+       same deref/assign primitives used by the [&mut]-surface. *)
+    ("make_ref", VBuiltin ("make_ref", fun args ->
+      match args with
+      | [v] -> Ok (VMut (ref v))
+      | _ -> Error (TypeMismatch "make_ref expects exactly one argument")
+    ));
+    ("get", VBuiltin ("get", fun args ->
+      match args with
+      | [VMut r] | [VRef r] -> Ok !r
+      | _ -> Error (TypeMismatch "get expects a Ref<T>")
+    ));
+    ("set", VBuiltin ("set", fun args ->
+      match args with
+      | [VMut r; v] -> r := v; Ok VUnit
+      | _ -> Error (TypeMismatch "set expects (Ref<T>, T)")
+    ));
+
     (* -- I/O builtins ------------------------------------------------------ *)
     ("panic", VBuiltin ("panic", fun args ->
       match args with

test/test_e2e.ml

@@ -3181,6 +3181,104 @@ let extern_tests = [
   Alcotest.test_case "extern fn → WASM import in 'env' namespace" `Quick test_extern_fn_codegen_emits_wasm_import;
 ]
 
+(* ---- STDLIB-04a: Mut effect externs (make_ref/get/set) ----
+
+   Hermetic round-trip on the interpreter: `make_ref(7)` allocates a
+   mutable cell, `set(r, 42)` mutates it, `get(r)` reads back the new
+   value. Proves the [Value.VMut] cell wiring (real implementation,
+   not a stub). Issue #328. *)
+
+let test_stdlib_04a_mut_round_trip () =
+  let src = {|
+effect Mut;
+extern fn make_ref<T>(x: T) -> Ref<T> / Mut;
+extern fn get<T>(r: Ref<T>) -> T / Mut;
+extern fn set<T>(r: Ref<T>, x: T) -> Unit / Mut;
+
+fn round_trip() -> Int / Mut {
+  let r = make_ref(7);
+  set(r, 42);
+  get(r)
+}
+
+const result: Int = round_trip();
+|} in
+  let prog = Parse_driver.parse_string ~file:"<test_stdlib_04a>" src in
+  match Interp.eval_program prog with
+  | Error e -> Alcotest.failf "interp failed: %s" (Value.show_eval_error e)
+  | Ok env ->
+    (match Value.lookup_env "result" env with
+     | Ok (Value.VInt 42) -> ()
+     | Ok v -> Alcotest.failf "expected VInt 42, got %s" (Value.show_value v)
+     | Error e -> Alcotest.failf "lookup failed: %s" (Value.show_eval_error e))
+
+(* `make_ref` on a non-Int value: round-trip a String to prove the cell
+   is value-polymorphic at runtime (matches the `<T>` signature). *)
+let test_stdlib_04a_mut_string_cell () =
+  let src = {|
+effect Mut;
+extern fn make_ref<T>(x: T) -> Ref<T> / Mut;
+extern fn get<T>(r: Ref<T>) -> T / Mut;
+extern fn set<T>(r: Ref<T>, x: T) -> Unit / Mut;
+
+fn round_trip() -> String / Mut {
+  let r = make_ref("alpha");
+  set(r, "omega");
+  get(r)
+}
+
+const result: String = round_trip();
+|} in
+  let prog = Parse_driver.parse_string ~file:"<test_stdlib_04a>" src in
+  match Interp.eval_program prog with
+  | Error e -> Alcotest.failf "interp failed: %s" (Value.show_eval_error e)
+  | Ok env ->
+    (match Value.lookup_env "result" env with
+     | Ok (Value.VString "omega") -> ()
+     | Ok v -> Alcotest.failf "expected VString \"omega\", got %s"
+                 (Value.show_value v)
+     | Error e -> Alcotest.failf "lookup failed: %s" (Value.show_eval_error e))
+
+(* Deno codegen lowers make_ref/get/set to the `{__cell: x}` host shape.
+   Proves the codegen_deno builtin table entries fire (was missing pre-
+   #328) — the emitted source must contain `__cell` references. *)
+let test_stdlib_04a_mut_deno_codegen () =
+  let src = {|
+effect Mut;
+extern fn make_ref<T>(x: T) -> Ref<T> / Mut;
+extern fn get<T>(r: Ref<T>) -> T / Mut;
+extern fn set<T>(r: Ref<T>, x: T) -> Unit / Mut;
+
+pub fn round_trip() -> Int {
+  let r = make_ref(0);
+  set(r, 99);
+  get(r)
+}
+|} in
+  let prog = Parse_driver.parse_string ~file:"<test_stdlib_04a>" src in
+  let loader = Module_loader.create (Module_loader.default_config ()) in
+  match Resolve.resolve_program_with_loader prog loader with
+  | Error (e, _) ->
+    Alcotest.failf "resolve failed: %s" (Resolve.show_resolve_error e)
+  | Ok (rctx, _) ->
+    (match Codegen_deno.codegen_deno prog rctx.symbols with
+     | Error e -> Alcotest.failf "deno-codegen failed: %s" e
+     | Ok js ->
+       let contains needle =
+         let nl = String.length needle and sl = String.length js in
+         let rec go i = i + nl <= sl &&
+           (String.sub js i nl = needle || go (i + 1))
+         in nl = 0 || go 0
+       in
+       Alcotest.(check bool) "emitted JS contains __cell shape"
+         true (contains "__cell"))
+
+let stdlib_04a_mut_tests = [
+  Alcotest.test_case "#328 make_ref/set/get round-trip (Int)" `Quick test_stdlib_04a_mut_round_trip;
+  Alcotest.test_case "#328 make_ref/set/get round-trip (String)" `Quick test_stdlib_04a_mut_string_cell;
+  Alcotest.test_case "#328 Deno codegen emits __cell shape" `Quick test_stdlib_04a_mut_deno_codegen;
+]
+
 (* ---- Issue #35 Phase 2 — Vscode bindings ----
 
    Verifies stdlib/Vscode.affine and stdlib/VscodeLanguageClient.affine
@@ -3871,6 +3969,7 @@ let tests =
     ("E2E Stdlib",           stdlib_tests);
     ("E2E Xmod Other Codegens", cross_module_other_codegens_tests);
     ("E2E Externs",              extern_tests);
+    ("E2E STDLIB-04a Mut #328",  stdlib_04a_mut_tests);
     ("E2E Vscode Bindings",      vscode_bindings_tests);
     ("E2E Array Type Sugar",     array_type_tests);
     ("E2E Qualified Paths #228",  qualified_path_tests);