feat(codegen): #234 S3 — effect-threaded async-boundary detection (ADR-016) (#277)

The WasmGC CPS async boundary is now ANY call whose effect row ⊇
`Async` (the S2b typecheck side-table), generalising the hardcoded
`async_primitives=["http_request_thenable"]` set. User-defined
`Async` functions now trigger the transform.

Mechanism (ADR-016 ordinal bridge): `Effect_sites` gains an
ordinal-keyed oracle. Producer: `Typecheck.populate_call_effects`
publishes `ordinal -> has_Async` (`eff_has_async` over the resolved
row) via `Effect_sites.set_async_by_ord`. Consumer:
`Codegen.generate_module` calls `Effect_sites.bind_consumer prog` on
the (post-optimizer) AST — the only optimizer is constant folding,
which never adds/removes/reorders a call, so the pre-order ordinal of
every `ExprApp` is stable across it and the producer's map keys
correctly; a call-count mismatch makes `bind_consumer` a no-op.
`is_async_prim_call` becomes `Effect_sites.is_async_call e || <old
structural set>` — the structural disjunct is the sound table-miss
fallback (empty oracle / count mismatch ⇒ exact pre-#234 behaviour;
zero regression). S4 retires the hardcoded set.

E2E `tests/codegen/effect_async_boundary.{affine,mjs}`: `fetchThing`
is a user `extern fn … / { Async }` — NOT `http_request_thenable`,
NOT in `async_primitives`. The compiler still synthesised the
#205/#199 continuation purely from its effect row (verified: emits
`Http.thenableThen` import + `__indirect_function_table` export; host
round-trip returns the settled status once; once-resumption traps).

Regression: all existing CPS e2e (http_cps_base/capture/chain,
http_response_reader) still green — the effect path coexists with
structural. `dune test --force` 290/290; full
`tools/run_codegen_wasm_tests.sh` green.

Refs #234. Not Closes — S4 (retire hardcoded set) remains; owner
closes per ISSUE-CLOSURE.

Author: hyperpolymath

lib/codegen.ml

@@ -1919,7 +1919,16 @@ let simple_pat_name (p : pattern) : string option =
     this list as wasm-path async stdlib primitives are added. *)
 let async_primitives = [ "http_request_thenable" ]
 
+(* ADR-016 / #234 S3: the async boundary is now ANY call whose effect
+   row ⊇ Async (the typecheck side-table, keyed by the shared
+   Effect_sites ordinal, consulted via [Effect_sites.is_async_call]),
+   generalising the structural-conservative hardcoded set. The
+   structural disjunct is retained as the sound table-miss fallback
+   (empty oracle / count-mismatch ⇒ exactly the pre-#234 behaviour;
+   zero regression). S4 retires [async_primitives]. *)
 let is_async_prim_call (e : expr) : bool =
+  Effect_sites.is_async_call e
+  ||
   match e with
   | ExprApp (ExprVar id, _) -> List.mem id.name async_primitives
   | _ -> false
@@ -2444,6 +2453,13 @@ let gen_imports (loader : Module_loader.t) (imports : import_decl list) (ctx : c
     Defaults to a fresh loader with [Module_loader.default_config ()] so that
     existing call sites keep working without modification. *)
 let generate_module ?loader (prog : program) : wasm_module result =
+  (* ADR-016 / #234 S3: bind the effect-side-table oracle to THIS
+     (post-optimizer) program's nodes. Ordinals are stable across the
+     constant-folding optimizer (it never adds/removes/reorders calls),
+     so the producer's ordinal→has-Async map keys correctly here. A
+     count-mismatch makes [bind_consumer] a no-op ⇒ structural
+     fallback. Safe if the producer never ran (empty ⇒ no-op). *)
+  Effect_sites.bind_consumer prog;
   let loader = match loader with
     | Some l -> l
     | None -> Module_loader.create (Module_loader.default_config ())

lib/effect_sites.ml

@@ -138,3 +138,62 @@ let to_list (prog : program) : (int * expr) list =
 (** [iter f prog] runs [f ordinal node] for every call site, in order. *)
 let iter (f : int -> expr -> unit) (prog : program) : unit =
   fold_calls (fun () ord e -> f ord e) () prog
+
+(* ── ADR-016 / #234 S3: ordinal-keyed async oracle ─────────────────────
+
+   The producer ([Typecheck.populate_call_effects]) records, per call-site
+   ORDINAL, whether the callee's effect row ⊇ [Async]. The consumer
+   ([Codegen]) runs on the *post-optimizer* AST. The only optimizer is
+   constant folding ([Opt.fold_constants_program]) which folds literal
+   bin/unops to literals but never adds, removes, or reorders a function
+   call ([ExprApp]) — so the pre-order ordinal of every call is STABLE
+   across optimization. Hence the ORDINAL (not physical identity) bridges
+   the producer's pre-opt AST and the consumer's post-opt AST, exactly as
+   ADR-016 specifies.
+
+   Lifecycle (per compilation): the producer fills [async_by_ord];
+   [bind_consumer prog] renumbers the (possibly post-opt) [prog] with the
+   SAME traversal and materialises a physical-identity predicate over
+   *that* prog's own nodes. Default empty ⇒ [is_async_call] is always
+   false ⇒ codegen falls back to the structural recogniser (the exact
+   pre-#234 behaviour; zero regression if the producer never ran or the
+   counts disagree). *)
+
+let async_by_ord : (int, bool) Hashtbl.t = Hashtbl.create 64
+let consumer_async : (expr * bool) list ref = ref []
+
+(** Producer entry: replace the ordinal→has-async map. *)
+let set_async_by_ord (tbl : (int, bool) Hashtbl.t) : unit =
+  Hashtbl.reset async_by_ord;
+  Hashtbl.iter (fun k v -> Hashtbl.replace async_by_ord k v) tbl
+
+(** Reset both sides (defensive; long-lived processes / LSP). *)
+let clear_async () =
+  Hashtbl.reset async_by_ord;
+  consumer_async := []
+
+(** Consumer entry: bind the predicate to [prog]'s own nodes. If the
+    call count disagrees with the producer's map size, the ordinal
+    bridge is not trustworthy (an optimizer changed call structure) ⇒
+    bind nothing, so codegen safely falls back to structural. *)
+let bind_consumer (prog : program) : unit =
+  if Hashtbl.length async_by_ord = 0 || count prog <> Hashtbl.length async_by_ord
+  then consumer_async := []
+  else
+    consumer_async :=
+      fold_calls
+        (fun acc ord node ->
+          let b =
+            match Hashtbl.find_opt async_by_ord ord with
+            | Some b -> b
+            | None -> false
+          in
+          (node, b) :: acc)
+        [] prog
+
+(** [is_async_call node] — does this call's (declared/inferred) effect
+    row include [Async]? Physical-identity lookup over the bound prog. *)
+let is_async_call (node : expr) : bool =
+  match List.assq node !consumer_async with
+  | b -> b
+  | exception Not_found -> false

lib/typecheck.ml

@@ -1808,7 +1808,21 @@ let populate_call_effects (ctx : context) (prog : Ast.program) : unit =
         | _ -> EPure
       in
       Hashtbl.replace ctx.call_effects ord row)
-    prog
+    prog;
+  (* ADR-016 / #234 S3: publish the ordinal→has-Async view for the
+     codegen consumer. `Async` lowers to the canonical `ESingleton
+     "Async"` (or appears in an `EUnion`, e.g. `/{Net,Async}`). *)
+  let rec eff_has_async (e : eff) : bool =
+    match e with
+    | EPure | EVar _ -> false
+    | ESingleton s -> s = "Async"
+    | EUnion es -> List.exists eff_has_async es
+  in
+  let async_tbl : (int, bool) Hashtbl.t = Hashtbl.create 64 in
+  Hashtbl.iter
+    (fun ord e -> Hashtbl.replace async_tbl ord (eff_has_async e))
+    ctx.call_effects;
+  Effect_sites.set_async_by_ord async_tbl
 
 let check_program ?(import_types : (string, scheme) Hashtbl.t option)
     (symbols : Symbol.t) (prog : Ast.program)

tests/codegen/effect_async_boundary.affine

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// issue #234 S3 — the payoff: the WasmGC CPS async boundary is now
+// detected from the callee's *effect row* (the typecheck side-table,
+// ADR-016), not a hardcoded name set. `fetchThing` is a USER-defined
+// async primitive — it is NOT `http_request_thenable` and NOT in
+// codegen's `async_primitives` list. The transform fires solely
+// because it is declared `/ { Async }`. Same #205/#199 host scaffold
+// as test_http_cps_base; `thenableThen` is in scope so the transform
+// can emit it.
+
+use Http::{Thenable, thenableThen};
+
+extern fn fetchThing(url: String) -> Thenable / { Async };
+extern fn thingStatus(t: Thenable) -> Int;
+
+pub fn launch() -> Int / { Async } {
+  let t = fetchThing("https://example.test/x");
+  thingStatus(t)
+}

tests/codegen/test_effect_async_boundary.mjs

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// issue #234 S3 — proves the effect-threaded async-boundary detection
+// end-to-end: the source uses `fetchThing` (a user-defined `/ {Async}`
+// extern, NOT `http_request_thenable`, NOT in codegen's hardcoded
+// `async_primitives`). The compiler still synthesised the #205/#199
+// continuation purely from the typecheck effect side-table (ADR-016).
+// Same host scaffold as test_http_cps_base.mjs.
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+
+let inst = null;
+const _handles = new Map();
+const _results = new Map();
+let _next = 1;
+let contFired = 0;
+let contReturn = null;
+let savedCb = null;
+
+function wrapHandler(closurePtr) {
+  return () => {
+    const tbl = inst.exports.__indirect_function_table;
+    const dv = new DataView(inst.exports.memory.buffer);
+    const fnId = dv.getInt32(closurePtr, true);
+    const envPtr = dv.getInt32(closurePtr + 4, true);
+    const fn = tbl.get(fnId);
+    const args = [envPtr];
+    while (args.length < fn.length) args.push(0);
+    return fn(...args);
+  };
+}
+
+const imports = {
+  wasi_snapshot_preview1: { fd_write: () => 0 },
+  env: {
+    fetchThing: (_urlPtr) => {
+      const h = _next++;
+      _handles.set(h, Promise.resolve({ status: 200 }));
+      return h;
+    },
+    thingStatus: (tHandle) => {
+      const v = _results.get(tHandle);
+      return v && typeof v.status === 'number' ? v.status : -1;
+    },
+  },
+  Http: {
+    thenableThen: (tHandle, onSettlePtr) => {
+      const cb = wrapHandler(onSettlePtr);
+      savedCb = cb;
+      Promise.resolve(_handles.get(tHandle)).then((v) => {
+        _results.set(tHandle, v);
+        contFired += 1;
+        contReturn = cb();
+      });
+      return 1;
+    },
+  },
+};
+
+const buf = await readFile('./tests/codegen/effect_async_boundary.wasm');
+inst = (await WebAssembly.instantiate(buf, imports)).instance;
+
+const disposable = inst.exports.launch();
+assert.ok(Number.isInteger(disposable), 'launch() returns synchronously');
+assert.equal(contFired, 0, 'continuation deferred until settlement');
+
+await new Promise((r) => setTimeout(r, 0));
+await Promise.resolve();
+
+assert.equal(contFired, 1, 'continuation fired exactly once');
+assert.equal(
+  contReturn,
+  200,
+  'effect-detected boundary: continuation read the settled status',
+);
+assert.throws(
+  () => savedCb(),
+  (e) => e instanceof WebAssembly.RuntimeError,
+  'second continuation entry traps (ADR-013 once-resumption)',
+);
+console.log('test_effect_async_boundary.mjs OK');