feat(stdlib): STDLIB-04e — wire string_to_int alias + lock pure-extern semantics (Closes #332)

Originally scoped as bookkeeping ("real + tested; close-as-done"), but
re-auditing caught the same trap STDLIB-04c removed: `string_to_int`
declared in stdlib/effects.affine was unwired dead surface — no entry
in interp, codegen_deno, resolve, or typecheck. Any caller of
`use effects::{string_to_int}` would compile and fail at run.

Fix: wire `string_to_int` as the typed-alias of `parse_int` (canonical
name). Same semantics (`String -> Option<Int>`), same OCaml impl, same
`__as_parseInt` host shim. Adds 4 hermetic tests covering all three
externs' round-trip semantics ("E2E STDLIB-04e Pure #332"):

  * int_to_string(42)  == "42"
  * string_to_int("123") == Some(123)
  * string_to_int("abc") == None
  * string_length("hello") == 5

Updates `docs/TECH-DEBT.adoc` row 04e to DONE per the audit-split
contract (notes the dead-surface discovery for posterity).

Closes #332. Refs #175.

Author: claude

docs/TECH-DEBT.adoc

@@ -190,9 +190,13 @@ to mirror `++` |S3 |open — issue #330
 `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
+`string_length`) — *DONE* (Refs #332): `int_to_string` +
+`string_length` were already real-wired; `string_to_int` was unwired
+dead surface (re-audit caught the gap the initial sweep missed — same
+trap STDLIB-04c removed). Now the typed-alias of `parse_int` in interp
++ Deno codegen + resolve/typecheck seeds. 4 hermetic tests in "E2E
+STDLIB-04e Pure #332" lock the round-trip semantics. |S3 |DONE
+2026-05-24 (Refs #332)
 |===
 
 == Section D — INT (ecosystem integration)

lib/codegen_deno.ml

@@ -269,6 +269,10 @@ let () =
   b "trim"           (fun a -> Printf.sprintf "String(%s).trim()" (arg 0 a));
   b "int_to_string"  (fun a -> Printf.sprintf "String(%s)" (arg 0 a));
   b "float_to_string" (fun a -> Printf.sprintf "String(%s)" (arg 0 a));
+  (* STDLIB-04e (Refs #332): `string_to_int` is the typed-alias of
+     `parse_int` declared in stdlib/effects.affine. Same `__as_parseInt`
+     host shim, returns Option<Int>. *)
+  b "string_to_int"  (fun a -> Printf.sprintf "__as_parseInt(%s)" (arg 0 a));
   b "parse_int"      (fun a -> Printf.sprintf "__as_parseInt(%s)" (arg 0 a));
   b "parse_float"    (fun a -> Printf.sprintf "__as_parseFloat(%s)" (arg 0 a));
   b "char_to_int"    (fun a -> Printf.sprintf "__as_charToInt(%s)" (arg 0 a));

lib/interp.ml

@@ -623,6 +623,18 @@ let create_initial_env () : env =
       | [VFloat f] -> Ok (VString (string_of_float f))
       | _ -> Error (TypeMismatch "float_to_string expects Float")
     ));
+    (* STDLIB-04e (Refs #332): `string_to_int` is the typed-alias surface
+       declared in stdlib/effects.affine. Same semantics as `parse_int`
+       (the canonical name) — the alias was unwired before this PR, so
+       any caller of the documented extern would compile and fail at run. *)
+    ("string_to_int", VBuiltin ("string_to_int", fun args ->
+      match args with
+      | [VString s] ->
+        (match int_of_string_opt s with
+         | Some n -> Ok (VVariant ("Some", Some (VInt n)))
+         | None -> Ok (VVariant ("None", None)))
+      | _ -> Error (TypeMismatch "string_to_int expects String")
+    ));
     ("parse_int", VBuiltin ("parse_int", fun args ->
       match args with
       | [VString s] ->

lib/resolve.ml

@@ -62,6 +62,8 @@ let seed_builtins (symbols : Symbol.t) : unit =
   def "char_to_int"; def "int_to_char"; def "show";
   def "to_lowercase"; def "to_uppercase"; def "trim";
   def "int_to_string"; def "float_to_string"; def "string_length";
+  (* STDLIB-04e (Refs #332): `string_to_int` typed-alias for `parse_int` *)
+  def "string_to_int";
   def "parse_int"; def "parse_float";
   (* Numeric coercions and math *)
   def "int"; def "float";

lib/typecheck.ml

@@ -1413,6 +1413,8 @@ let register_builtins (ctx : context) : unit =
   bind_var ctx "to_uppercase" (TArrow (ty_string, QOmega, ty_string, EPure));
   bind_var ctx "trim"         (TArrow (ty_string, QOmega, ty_string, EPure));
   bind_var ctx "parse_int"    (TArrow (ty_string, QOmega, opt ty_int, EPure));
+  (* STDLIB-04e (Refs #332): `string_to_int` typed-alias of `parse_int`. *)
+  bind_var ctx "string_to_int" (TArrow (ty_string, QOmega, opt ty_int, EPure));
   bind_var ctx "parse_float"  (TArrow (ty_string, QOmega, opt ty_float, EPure));
   bind_var ctx "char_to_int"  (TArrow (ty_char, QOmega, ty_int, EPure));
   bind_var ctx "int_to_char"  (TArrow (ty_int, QOmega, ty_char, EPure));

test/test_e2e.ml

@@ -3279,6 +3279,83 @@ let stdlib_04a_mut_tests = [
   Alcotest.test_case "#328 Deno codegen emits __cell shape" `Quick test_stdlib_04a_mut_deno_codegen;
 ]
 
+(* ---- STDLIB-04e: Pure externs (Refs #332) ----
+
+   Three externs declared in stdlib/effects.affine as pure:
+     int_to_string : Int -> String
+     string_to_int : String -> Option<Int>
+     string_length : String -> Int
+
+   `int_to_string` + `string_length` were already wired; `string_to_int`
+   was unwired (dead surface — any caller would compile and fail at run).
+   This row wires `string_to_int` as the typed-alias of `parse_int` and
+   asserts hermetic round-trip semantics for all three. *)
+
+let test_stdlib_04e_int_to_string () =
+  let prog = Parse_driver.parse_string ~file:"<test>"
+    "fn f() -> String { int_to_string(42) }" 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 "f" env with
+     | Ok fn ->
+       (match Interp.apply_function fn [] with
+        | Ok (Value.VString "42") -> ()
+        | Ok v -> Alcotest.failf "expected VString \"42\", got %s"
+                    (Value.show_value v)
+        | Error e -> Alcotest.failf "apply failed: %s" (Value.show_eval_error e))
+     | Error e -> Alcotest.failf "lookup f failed: %s" (Value.show_eval_error e))
+
+let test_stdlib_04e_string_to_int_some () =
+  let prog = Parse_driver.parse_string ~file:"<test>"
+    "fn f() -> Option<Int> { string_to_int(\"123\") }" 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 "f" env with
+     | Ok fn ->
+       (match Interp.apply_function fn [] with
+        | Ok (Value.VVariant ("Some", Some (Value.VInt 123))) -> ()
+        | Ok v -> Alcotest.failf "expected Some(123), got %s"
+                    (Value.show_value v)
+        | Error e -> Alcotest.failf "apply failed: %s" (Value.show_eval_error e))
+     | Error e -> Alcotest.failf "lookup f failed: %s" (Value.show_eval_error e))
+
+let test_stdlib_04e_string_to_int_none () =
+  let prog = Parse_driver.parse_string ~file:"<test>"
+    "fn f() -> Option<Int> { string_to_int(\"abc\") }" 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 "f" env with
+     | Ok fn ->
+       (match Interp.apply_function fn [] with
+        | Ok (Value.VVariant ("None", None)) -> ()
+        | Ok v -> Alcotest.failf "expected None, got %s" (Value.show_value v)
+        | Error e -> Alcotest.failf "apply failed: %s" (Value.show_eval_error e))
+     | Error e -> Alcotest.failf "lookup f failed: %s" (Value.show_eval_error e))
+
+let test_stdlib_04e_string_length () =
+  let prog = Parse_driver.parse_string ~file:"<test>"
+    "fn f() -> Int { string_length(\"hello\") }" 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 "f" env with
+     | Ok fn ->
+       (match Interp.apply_function fn [] with
+        | Ok (Value.VInt 5) -> ()
+        | Ok v -> Alcotest.failf "expected VInt 5, got %s" (Value.show_value v)
+        | Error e -> Alcotest.failf "apply failed: %s" (Value.show_eval_error e))
+     | Error e -> Alcotest.failf "lookup f failed: %s" (Value.show_eval_error e))
+
+let stdlib_04e_pure_tests = [
+  Alcotest.test_case "#332 int_to_string(42) == \"42\"" `Quick test_stdlib_04e_int_to_string;
+  Alcotest.test_case "#332 string_to_int(\"123\") == Some(123)" `Quick test_stdlib_04e_string_to_int_some;
+  Alcotest.test_case "#332 string_to_int(\"abc\") == None" `Quick test_stdlib_04e_string_to_int_none;
+  Alcotest.test_case "#332 string_length(\"hello\") == 5" `Quick test_stdlib_04e_string_length;
+]
+
 (* ---- Issue #35 Phase 2 — Vscode bindings ----
 
    Verifies stdlib/Vscode.affine and stdlib/VscodeLanguageClient.affine
@@ -3970,6 +4047,7 @@ let tests =
     ("E2E Xmod Other Codegens", cross_module_other_codegens_tests);
     ("E2E Externs",              extern_tests);
     ("E2E STDLIB-04a Mut #328",  stdlib_04a_mut_tests);
+    ("E2E STDLIB-04e Pure #332", stdlib_04e_pure_tests);
     ("E2E Vscode Bindings",      vscode_bindings_tests);
     ("E2E Array Type Sugar",     array_type_tests);
     ("E2E Qualified Paths #228",  qualified_path_tests);