Step 5: CEK IO suspension + R7RS modules (define-library/import)

Third CEK phase "io-suspended": perform suspends evaluation, host
resolves IO, cek-resume feeds result back. VM OP_PERFORM (opcode 112)
enables JIT-compiled functions to suspend. VM→CEK→suspend chain
propagates suspension across the JIT/CEK boundary via pending_cek.

R7RS define-library creates isolated environments with export control.
import checks the library registry and suspends for unknown libraries,
enabling lazy on-demand loading. Import qualifiers: only, prefix.

Server-side cek_run_with_io handles suspension by dispatching IO
requests to the Python bridge and resuming. guard composes cleanly
with perform for structured error recovery across IO boundaries.

2598/2598 tests (30 new: 15 core suspension, 3 JIT, 1 cross-boundary,
9 modules, 2 error handling). Zero regressions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

hosts/ocaml/bin/run_tests.ml

@@ -211,6 +211,8 @@ let make_test_env () =
     | [e; Keyword k; v] -> Sx_types.env_set (uw e) k v
     | _ -> raise (Eval_error "env-set!: expected env, key, value"));
 
+  bind "make-env" (fun _args -> Env (Sx_types.make_env ()));
+
   bind "env-extend" (fun args ->
     match args with
     | [e] -> Env (Sx_types.env_extend (uw e))
@@ -841,6 +843,60 @@ let make_test_env () =
     | [frame] -> Sx_ref.frame_type frame
     | _ -> raise (Eval_error "frame-type: expected 1 arg"));
 
+  (* IO suspension primitives — inline until retranspile *)
+  let is_suspended state =
+    match get_val state (String "phase") with String "io-suspended" -> true | _ -> false in
+  let step_loop state =
+    let s = ref state in
+    while not (match Sx_ref.cek_terminal_p !s with Bool true -> true | _ -> false)
+       && not (is_suspended !s) do
+      s := Sx_ref.cek_step !s
+    done;
+    !s in
+  bind "cek-step-loop" (fun args ->
+    match args with
+    | [state] -> step_loop state
+    | _ -> raise (Eval_error "cek-step-loop: expected 1 arg"));
+  bind "cek-resume" (fun args ->
+    match args with
+    | [state; result] ->
+      step_loop (Sx_ref.make_cek_value result (get_val state (String "env")) (get_val state (String "kont")))
+    | _ -> raise (Eval_error "cek-resume: expected 2 args"));
+  bind "cek-suspended?" (fun args ->
+    match args with
+    | [state] -> Bool (is_suspended state)
+    | _ -> raise (Eval_error "cek-suspended?: expected 1 arg"));
+  bind "cek-io-request" (fun args ->
+    match args with
+    | [state] -> get_val state (String "request")
+    | _ -> raise (Eval_error "cek-io-request: expected 1 arg"));
+  bind "make-cek-suspended" (fun args ->
+    match args with
+    | [req; env'; kont] ->
+      let d = Hashtbl.create 4 in
+      Hashtbl.replace d "phase" (String "io-suspended");
+      Hashtbl.replace d "request" req;
+      Hashtbl.replace d "env" env';
+      Hashtbl.replace d "kont" kont;
+      Dict d
+    | _ -> raise (Eval_error "make-cek-suspended: expected 3 args"));
+
+  (* --- Library registry --- *)
+  let lib_registry = Hashtbl.create 16 in
+  ignore (Sx_types.env_bind env "*library-registry*" (Dict lib_registry));
+  bind "library-loaded?" (fun args ->
+    match args with
+    | [spec] -> Sx_ref.library_loaded_p spec
+    | _ -> raise (Eval_error "library-loaded?: expected 1 arg"));
+  bind "library-exports" (fun args ->
+    match args with
+    | [spec] -> Sx_ref.library_exports spec
+    | _ -> raise (Eval_error "library-exports: expected 1 arg"));
+  bind "register-library" (fun args ->
+    match args with
+    | [spec; exports] -> Sx_ref.register_library spec exports
+    | _ -> raise (Eval_error "register-library: expected 2 args"));
+
   (* --- Strict mode --- *)
   (* *strict* is a plain value in the env, mutated via env_set by set-strict! *)
   ignore (Sx_types.env_bind env "*strict*" (Bool false));

hosts/ocaml/bin/sx_server.ml

@@ -281,6 +281,43 @@ let flush_batched_io result_str =
     !final
   end
 
+(** IO-aware CEK run — handles suspension by dispatching IO requests.
+    When the CEK machine suspends with a perform, this function sends
+    the IO request to the Python bridge, resumes with the response,
+    and repeats until evaluation completes. *)
+let cek_run_with_io state =
+  let s = ref state in
+  let is_terminal s = match Sx_ref.cek_terminal_p s with Bool true -> true | _ -> false in
+  let is_suspended s = match Sx_runtime.get_val s (String "phase") with String "io-suspended" -> true | _ -> false in
+  let rec loop () =
+    while not (is_terminal !s) && not (is_suspended !s) do
+      s := Sx_ref.cek_step !s
+    done;
+    if is_suspended !s then begin
+      let request = Sx_runtime.get_val !s (String "request") in
+      let op = match Sx_runtime.get_val request (String "op") with String s -> s | _ -> "" in
+      (* Extract args based on operation type *)
+      let args = match op with
+        | "import" ->
+          let lib = Sx_runtime.get_val request (String "library") in
+          [String "import"; lib]
+        | _ ->
+          let a = Sx_runtime.get_val request (String "args") in
+          (match a with List l -> l | _ -> [a])
+      in
+      let response = io_request op args in
+      s := Sx_ref.cek_resume !s response;
+      loop ()
+    end else
+      Sx_ref.cek_value !s
+  in
+  loop ()
+
+(** IO-aware eval_expr — like eval_expr but handles IO suspension. *)
+let _eval_expr_io expr env =
+  let state = Sx_ref.make_cek_state expr env (List []) in
+  cek_run_with_io state
+
 (** Bind IO primitives into the environment. *)
 let setup_io_env env =
   let bind name fn =
@@ -798,6 +835,21 @@ let _jit_compiling = ref false  (* re-entrancy guard *)
 
 let _jit_warned : (string, bool) Hashtbl.t = Hashtbl.create 16
 
+let rec make_vm_suspend_marker request saved_vm =
+  let d = Hashtbl.create 3 in
+  Hashtbl.replace d "__vm_suspended" (Bool true);
+  Hashtbl.replace d "request" request;
+  (* Create a resume function that continues this specific VM.
+     May raise VmSuspended again — caller must handle. *)
+  Hashtbl.replace d "resume" (NativeFn ("vm-resume", fun args ->
+    match args with
+    | [result] ->
+      (try Sx_vm.resume_vm saved_vm result
+       with Sx_vm.VmSuspended (req2, vm2) ->
+         make_vm_suspend_marker req2 vm2)
+    | _ -> raise (Eval_error "vm-resume: expected 1 arg")));
+  Dict d
+
 let register_jit_hook env =
   Sx_runtime._jit_try_call_fn := Some (fun f args ->
     match f with
@@ -807,7 +859,10 @@ let register_jit_hook env =
          (* Cached bytecode — run on VM, fall back to CEK on runtime error.
             Log once per function name, then stay quiet. Don't disable. *)
          (try Some (Sx_vm.call_closure cl args cl.vm_env_ref)
-          with e ->
+          with
+          | Sx_vm.VmSuspended (request, saved_vm) ->
+            Some (make_vm_suspend_marker request saved_vm)
+          | e ->
             let fn_name = match l.l_name with Some n -> n | None -> "?" in
             if not (Hashtbl.mem _jit_warned fn_name) then begin
               Hashtbl.replace _jit_warned fn_name true;
@@ -832,7 +887,10 @@ let register_jit_hook env =
            | Some cl ->
              l.l_compiled <- Some cl;
              (try Some (Sx_vm.call_closure cl args cl.vm_env_ref)
-              with e ->
+              with
+              | Sx_vm.VmSuspended (request, saved_vm) ->
+                Some (make_vm_suspend_marker request saved_vm)
+              | e ->
                 Printf.eprintf "[jit] %s first-call fallback to CEK: %s\n%!" fn_name (Printexc.to_string e);
                 Hashtbl.replace _jit_warned fn_name true;
                 None)