feat(wasi): #180 ADR-015 S4a — clock_now_ms builtin (preview1 → wasi:clocks via S3)

ADR-015 S4 first slice: clocks. Native WASI clocks via the preview1
import surface (the adapter S3 wraps it with bridges to preview2
`wasi:clocks` on a real host).

- `lib/wasi_runtime.ml`: `create_clock_time_get_import` + `gen_clock_now_ms`
  (emits `clock_time_get(clock_id, 0_precision, scratch)` → drops
  errno → loads i64 ns from scratch → `/ 1_000_000` → wrap to i32 ms;
  ~24-day wrap, documented).
- `lib/codegen.ml`: builtin special-case `clock_now_ms(clock_id) -> Int`
  (mirrors `print`'s `ExprVar`-name pattern). **Conditional import on
  use**: a pre-scan via `Effect_sites.fold_calls` adds the
  `wasi_snapshot_preview1.clock_time_get` import iff the unit calls
  `clock_now_ms` — units that don't use it are byte-identical to
  pre-S4a (zero LinkError surface for existing harnesses; the
  "import what you use" principle). Idx 1 after fd_write at 0, deterministic
  (cross-module imports from gen_imports follow); type indices are
  computed via `List.length`, so the +1 in ctx.types is a uniform
  shift (safe — verified by the gate). Hardcoded `clock_func_idx = 1`
  matches the assembly.
- `lib/typecheck.ml` register_builtins + `lib/resolve.ml` builtin list:
  `clock_now_ms : Int -> Int / { Time }` (`Time` is reserved; tracking
  only, like the rest of the v1 effect system).

Tests:
- `tests/codegen/clock_now_ms.{affine,mjs}` — host stubs
  `clock_time_get` writing 5_000_000_000 ns, asserts the guest
  returns 5000 (the ns/1_000_000 arithmetic + import wiring +
  CLOCK_MONOTONIC threading). V8 passes wasm i64 to JS as **BigInt**
  (3 params, not 4-split-i32) — load-bearing.
- The S3 componentize smoke + S3 path on the clock fixture: the
  component is structurally valid, the `affinescript.ownership`
  section survives, wasmtime loads it. Real-host main invoke
  through wasi:clocks needs WIT export lifting / `wasi:cli/run`
  command shape — that's S6, NOT S4 (the S4 contract is correct
  preview1 emission; the adapter does the preview2 bridge).

Gate: `dune test --force` 295/295; full
`tools/run_codegen_wasm_tests.sh` PASSED incl. the new test (the
critical proof that the import-space shift didn't break anything —
print, #199 closure ABI, #234 effect-table, #225 CPS, all green).
S3 smoke still PASSED. Zero regression.

Refs #180 — S4a done; next S4b (env+argv, same preview1-import
pattern), S5 filesystem (unblocks INT-06), S6 flip default. Not
Closes.

Author: hyperpolymath

docs/ECOSYSTEM.adoc

@@ -213,7 +213,15 @@ valid WASI-0.2 component via the fetch-pinned preview1→preview2
 `affinescript.ownership` section is proven to SURVIVE the wrap;
 `tests/componentize/smoke.sh` gates it (SKIP-safe without the
 toolchain). Codegen UNCHANGED — core preview1 stays the default
-(reversible).** Next: S4 native clocks/env/argv. WIT world of
+(reversible). S4a (clock) DONE: `clock_now_ms(clock_id)` builtin
+lowers to a `wasi_snapshot_preview1.clock_time_get` import (added
+on-demand via Effect_sites pre-scan; idx 1 after fd_write at 0;
+zero impact on units that don't use it). Component-path bridges to
+`wasi:clocks` via the reactor adapter; the component is
+structurally valid + ownership-preserving (real-host invocation
+deferred to S6: requires WIT export-lifting / wasi:cli command
+shape). Next: S4b env+argv (same preview1-import pattern), then
+S5 filesystem, S6 flip default.** WIT world of
 record: `wit/affinescript.wit`
 |INT-04 |Publish compiler + runtime to JSR (then npm) |#181 |runtime
 packaging READY (affine-js + affinescript-tea JSR dry-run green;

docs/TECH-DEBT.adoc

@@ -185,11 +185,14 @@ follow-up
 multi-ns import object, ownership accessor); 14 unit tests via pinned
 `deno task test` + `tests/modules/loader-bridge/` e2e on real
 compiler-emitted xmod wasm (closes INT-01↔INT-02). Unblocks INT-05/08/11
-|INT-03 |WASI preview2 / host I/O |S1→S3 |#180 ADR-015 (full
+|INT-03 |WASI preview2 / host I/O |S1→S4a |#180 ADR-015 (full
 Component-Model re-target, S1..S6); S2 toolchain #251 closed;
-**S3 DONE — `tools/componentize.sh` (pinned reactor adapter) →
-valid WASI-0.2 component, ownership section survives,
-`tests/componentize/smoke.sh` gates it; codegen unchanged. Next S4
+S3 componentize on-ramp done; **S4a (clock) DONE —
+`clock_now_ms(clock_id)` builtin lowers to a preview1
+`clock_time_get` import (Effect_sites pre-scan, on-demand → zero
+regression on non-clock units); component path bridges to
+wasi:clocks. Real-host main-invoke deferred to S6 (WIT export
+lifting). Next S4b
 (native clocks/env/argv)**
 |INT-04 |Publish to JSR/npm |S2 |#181 packaging READY (dry-run green,
 manual workflow); JSR publish authorised + dispatched (owner go

lib/codegen.ml

@@ -832,6 +832,27 @@ let rec gen_expr (ctx : context) (expr : expr) : (context * instr list) result =
         in
         Ok (ctx_with_heap, print_code)
 
+      | ExprVar id when id.name = "clock_now_ms" && List.length args = 1 ->
+        (* ADR-015 S4a (#180): clock_now_ms(clock_id) — i32 monotonic /
+           realtime milliseconds. Lowers to a `wasi_snapshot_preview1.
+           clock_time_get` call (import idx 1, hardcoded to match the
+           module-assembly ordering). Under the S3 component path the
+           reactor adapter bridges this to wasi:clocks on a real
+           preview2 host. Effect row is `Time` (tracking-only). *)
+        let* (ctx_with_arg, arg_code) = gen_expr ctx (List.hd args) in
+        let (ctx_with_arg2, clock_arg_local) =
+          alloc_local ctx_with_arg "__clock_id" in
+        let (ctx_with_scratch, scratch_local) =
+          alloc_local ctx_with_arg2 "__clock_scratch" in
+        let (ctx_with_heap, heap_idx) = ensure_heap_ptr ctx_with_scratch in
+        let clock_func_idx = 1 in
+        let code =
+          arg_code @ [LocalSet clock_arg_local] @
+          Wasi_runtime.gen_clock_now_ms
+            heap_idx clock_arg_local scratch_local clock_func_idx
+        in
+        Ok (ctx_with_heap, code)
+
       | ExprVar id when List.mem_assoc id.name ctx.variant_tags ->
         (* Enum constructor called as a function: Circle(5), Rect({x:1,y:2}), etc.
            Layout: [tag: i32][field1: i32][field2: i32]...
@@ -2467,11 +2488,39 @@ let generate_module ?loader (prog : program) : wasm_module result =
   let fd_write_type_idx = 0 in  (* Will be first type *)
   let fd_write_import_fixed = { fd_write_import with i_desc = ImportFunc fd_write_type_idx } in
 
-  let ctx_with_wasi = {
-    ctx with
-    types = fd_write_type :: ctx.types;
-    imports = fd_write_import_fixed :: ctx.imports;
-  } in
+  (* ADR-015 S4a (#180): register WASI `clock_time_get` only when the
+     unit actually calls `clock_now_ms` — adding it unconditionally
+     would force every host (incl. every test harness) to stub it,
+     breaking the principle "import what you use". Pre-scan via the
+     shared Effect_sites traversal. When emitted, the clock takes
+     import idx 1 (deterministically after fd_write at 0), which the
+     `clock_now_ms` builtin hardcodes. *)
+  let needs_clock =
+    Effect_sites.fold_calls
+      (fun acc _ord call ->
+        acc ||
+        match call with
+        | ExprApp (ExprVar id, _) -> id.name = "clock_now_ms"
+        | _ -> false)
+      false prog
+  in
+  let ctx_with_wasi =
+    if needs_clock then
+      let (clock_import, clock_type) = Wasi_runtime.create_clock_time_get_import () in
+      let clock_type_idx = 1 in
+      let clock_import_fixed = { clock_import with i_desc = ImportFunc clock_type_idx } in
+      {
+        ctx with
+        types = fd_write_type :: clock_type :: ctx.types;
+        imports = fd_write_import_fixed :: clock_import_fixed :: ctx.imports;
+      }
+    else
+      {
+        ctx with
+        types = fd_write_type :: ctx.types;
+        imports = fd_write_import_fixed :: ctx.imports;
+      }
+  in
 
   let* ctx_with_imports = gen_imports loader prog.prog_imports ctx_with_wasi in
 

lib/resolve.ml

@@ -53,6 +53,8 @@ let seed_builtins (symbols : Symbol.t) : unit =
   let def name = let _ = Symbol.define symbols name SKFunction Span.dummy Public in () in
   (* Console I/O *)
   def "print"; def "println"; def "eprint"; def "eprintln";
+  (* WASI time (ADR-015 S4a, #180) *)
+  def "clock_now_ms";
   (* String / char builtins *)
   def "len"; def "slice"; def "string_get"; def "string_sub"; def "string_find";
   def "char_to_int"; def "int_to_char"; def "show";

lib/typecheck.ml

@@ -1314,6 +1314,14 @@ let register_builtins (ctx : context) : unit =
   let float_binop = TArrow (ty_float, QOmega, TArrow (ty_float, QOmega, ty_float, EPure), EPure) in
   bind_var ctx "print" (TArrow (ty_string, QOmega, ty_unit, ESingleton "IO"));
   bind_var ctx "println" (TArrow (ty_string, QOmega, ty_unit, ESingleton "IO"));
+  (* ADR-015 S4a (#180): WASI clock primitive. `clock_now_ms(clock_id)`
+     -> Int (monotonic/realtime milliseconds, clock_id 0=realtime/
+     1=monotonic). Tracking effect `Time` (reserved). Lowers to a
+     `wasi_snapshot_preview1.clock_time_get` import on the wasm
+     target; on the S3 component path the reactor adapter bridges to
+     `wasi:clocks`. *)
+  bind_var ctx "clock_now_ms"
+    (TArrow (ty_int, QOmega, ty_int, ESingleton "Time"));
   bind_var ctx "eprint" (TArrow (ty_string, QOmega, ty_unit, ESingleton "IO"));
   bind_var ctx "eprintln" (TArrow (ty_string, QOmega, ty_unit, ESingleton "IO"));
   bind_var ctx "read_line"

lib/wasi_runtime.ml

@@ -13,6 +13,65 @@ open Wasm
 let fd_stdout = 1l
 let fd_stderr = 2l
 
+(** WASI clock-id constants (preview1 `wasi_snapshot_preview1`):
+    0 = REALTIME, 1 = MONOTONIC, 2 = PROCESS_CPUTIME, 3 = THREAD_CPUTIME. *)
+let clock_realtime = 0l
+let clock_monotonic = 1l
+
+(** Create the WASI `clock_time_get` import (ADR-015 S4a, #180).
+
+    Signature: `(clockid: i32, precision: i64, time_out: i32) -> errno: i32`.
+    Writes the timestamp (nanoseconds, i64) to `*time_out`. Through the
+    S3 componentize on-ramp the wasmtime preview1->preview2 reactor
+    adapter bridges this to `wasi:clocks/{monotonic,wall}-clock@0.2.*`
+    on a real host. *)
+let create_clock_time_get_import () : import * func_type =
+  let func_type = {
+    ft_params = [I32; I64; I32];  (* clockid, precision, time_out_ptr *)
+    ft_results = [I32];           (* errno *)
+  } in
+  let import = {
+    i_module = "wasi_snapshot_preview1";
+    i_name = "clock_time_get";
+    i_desc = ImportFunc 0;  (* Will be adjusted when added to module *)
+  } in
+  (import, func_type)
+
+(** Emit a `clock_now_ms(clock_id)` sequence. The caller has placed
+    [clock_arg_local] (the `i32` clock id) and allocated
+    [scratch_local] (an `i32` heap-pointer local) and threaded the
+    import [clock_func_idx]. Leaves the i32 monotonic/realtime
+    millisecond count on the stack (= ns / 1_000_000, wrapped to i32 —
+    documented lossy: 32-bit ms wraps after ~24 days, sufficient for
+    typical use; the precise i64 reader is a follow-up).
+
+    Layout: 8 bytes scratch (the i64 time_out the WASI host writes). *)
+let gen_clock_now_ms
+    (heap_ptr_global : int) (clock_arg_local : int)
+    (scratch_local : int) (clock_func_idx : int)
+    : instr list =
+  [
+    (* scratch = heap; heap += 8 *)
+    GlobalGet heap_ptr_global;
+    I32Const 8l; I32Add;
+    GlobalSet heap_ptr_global;
+    GlobalGet heap_ptr_global;
+    I32Const 8l; I32Sub;
+    LocalSet scratch_local;
+    (* clock_time_get(clock_id, 0 /* precision */, scratch); drop errno *)
+    LocalGet clock_arg_local;
+    I64Const 0L;
+    LocalGet scratch_local;
+    Call clock_func_idx;
+    Drop;
+    (* return (i32) (i64_load(scratch) / 1_000_000) *)
+    LocalGet scratch_local;
+    I64Load (3, 0);
+    I64Const 1_000_000L;
+    I64DivU;
+    I32WrapI64;
+  ]
+
 (** Create WASI fd_write import
 
     fd_write signature: (fd: i32, iovs: i32, iovs_len: i32, nwritten: i32) -> i32

tests/codegen/clock_now_ms.affine

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2026 hyperpolymath
+//
+// ADR-015 S4a (#180) — wasm-path smoke for `clock_now_ms`, the first
+// WASI clocks primitive. The builtin lowers to a
+// `wasi_snapshot_preview1.clock_time_get` import (added on-demand via
+// the codegen pre-scan; idx 1 right after fd_write); under the S3
+// component path the reactor adapter bridges this to `wasi:clocks`.
+//
+// The harness stubs the import with a known nanosecond value so the
+// guest's `ns / 1_000_000` computation is asserted exactly.
+
+pub fn main() -> Int / { Time } {
+  clock_now_ms(1)  // 1 = CLOCK_MONOTONIC
+}

tests/codegen/test_clock_now_ms.mjs

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2026 hyperpolymath
+//
+// ADR-015 S4a (#180) — assert the `clock_now_ms` builtin wires its
+// `wasi_snapshot_preview1.clock_time_get` import correctly and
+// computes `ns / 1_000_000` (wrapped to i32). Host-stubbed: no real
+// clock involved (the real-host path is the component smoke,
+// tests/componentize/smoke.sh).
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+
+const buf = await readFile('./tests/codegen/clock_now_ms.wasm');
+let inst = null;
+let observed = null; // (clock_id, precision, time_ptr) the guest asked for
+
+const imports = {
+  wasi_snapshot_preview1: {
+    fd_write: () => 0,
+    // Modern V8 passes wasm i64 to JS as BigInt (not two i32s):
+    // (clock_id: i32, precision: i64-as-BigInt, time_ptr: i32) -> i32.
+    clock_time_get: (clock_id, _precision, time_ptr) => {
+      // 5_000_000_000 ns = 5000 ms. Store i64 little-endian at time_ptr.
+      observed = { clock_id, time_ptr };
+      const dv = new DataView(inst.exports.memory.buffer);
+      dv.setBigUint64(time_ptr, 5_000_000_000n, true);
+      return 0; // errno OK
+    },
+  },
+};
+
+inst = (await WebAssembly.instantiate(buf, imports)).instance;
+const result = inst.exports.main();
+
+assert.ok(observed, 'guest called clock_time_get');
+assert.equal(observed.clock_id, 1, 'CLOCK_MONOTONIC threaded through');
+assert.equal(result, 5000, 'ns/1_000_000: 5_000_000_000 → 5000 ms');
+console.log('test_clock_now_ms.mjs OK');