docs(adr): CORE-02 / #234 / ADR-016 — truth ledger to "DELIVERED" (#336)

## Summary

The effect-threaded async-boundary work (issue #234, ADR-016) shipped
end-to-end on 2026-05-19 via PRs #270 / #275 / #276 / #277 / #278, but
the ledger entries and several in-source comments were still describing
intermediate states (`"S1 done"`, `"Built, not yet consumed"`, `"falls
back to the structural recogniser"`). This PR brings them into agreement
with the realised end state. **No behavioural change** — pure
documentation truthing of work already merged.

### Ledger refresh

- `docs/TECH-DEBT.adoc` — **CORE-02** and **CONV-02** marked `*CLOSED
2026-05-19*` with the full S1..S4 / PR cross-reference and the
steady-state miss path.
- `docs/specs/SETTLED-DECISIONS.adoc` +
`.machine_readable/6a2/META.a2ml` ADR-016 — staging block records
per-slice PR numbers and `DONE` status; the *Fallback / safety*
paragraph rewritten so the steady-state miss path is "no transform" (S4
retired the structural recogniser).
- `docs/ECOSYSTEM.adoc` + `docs/specs/async-on-wasm-cps.adoc` — #234
marked DELIVERED with the PR list, removing the "follow-up, still
tracked" framing.

### In-source comment refresh

- `lib/codegen.ml` — `is_async_prim_call` docstring + the
`bind_consumer` call-site comment rewritten to describe the realised
behaviour (single-sourced from `Effect_sites.is_async_call`; table-miss
= no transform).
- `lib/effect_sites.ml` — async-oracle header no longer claims "falls
back to the structural recogniser".
- `lib/typecheck.ml` — `call_effects` field doc +
`populate_call_effects` comment no longer say "Built, not yet consumed".
- `test/test_main.ml` — Alcotest suite label `"Effect-sites (#234 S2a)"`
→ `"Effect-sites (#234, ADR-016)"`.

### Why zero behaviour risk

Code-side edits touch only `(* … *)` / `(** … *)` comment blocks
(stripped by the OCaml lexer) and one Alcotest suite-label string. No
identifier, no expression, no top-level binding is changed.

## Test plan

- [ ] CI: `dune build` clean
- [ ] CI: `dune test --force` green (gate baseline holds — the S2a
`Effect_sites` test suite + the S3
`tests/codegen/effect_async_boundary.affine` e2e are the in-tree
witnesses of the delivered behaviour)
- [ ] No new lints flagged

> Local `dune test` was not run in this session because the
remote-execution env's network policy blocks the non-GitHub opam hosts
(`erratique.ch`, `gitlab.inria.fr`, `ocaml.janestreet.com`) that
`menhir`, `cmdliner`, `fmt`, `sexplib0`, … fetch from, so the switch
could not be brought up. The actual S1..S4 behaviour was CI-verified at
merge time on each of #270/#275/#276/#277/#278.

https://claude.ai/code/session_01HZ3i2wX5R5rbY8Ycmug4Ao

---
_Generated by [Claude
Code](https://claude.ai/code/session_01HZ3i2wX5R5rbY8Ycmug4Ao)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/META.a2ml

@@ -1058,23 +1058,34 @@ Thread per-call-site effect rows from typecheck to codegen via a
   `let`-RHS call's effect row ⊇ `Async`” via a table lookup, replacing
   `is_async_prim_call`/`async_primitives`.
 - *Fallback / safety.* If the table has no entry for a site (e.g. a
-  pre-typecheck embedder path, or a synthesised node), codegen falls
-  back to the structural recogniser. The hardcoded set is retired only
-  once the table path is proven (final slice); over-conservative
-  fallback is always sound (= today's behaviour).
+  pre-typecheck embedder path, or a synthesised node), or the consumer
+  detects a producer/consumer count-mismatch, [Effect_sites.is_async_call]
+  returns false ⇒ the CPS transform simply does not fire for that call.
+  The pre-S4 plan retained the structural recogniser as the fallback
+  *until the table path was proven*; S4 (PR #278) retired the
+  hardcoded `async_primitives` set, so the steady-state fallback is
+  "no transform" — over-conservative, always sound.
 
 Staged (ledger #234; each a gated PR, full `dune test --force` +
 wasm e2e):
-- S1 (this): ADR-016 + plan. No code change.
-- S2: `lib/effect_sites.ml` shared numbering + typecheck builds &
-  returns the side-table. NO codegen behaviour change (table built,
-  unused) — pure, gate-neutral.
-- S3: pipeline threads the table; codegen boundary predicate switches
-  to the table with structural fallback; new e2e proving a
-  *user-defined* `Async` fn triggers the transform (the payoff). All
-  existing http_cps_* / http_response_reader stay green.
-- S4: retire the hardcoded `async_primitives` set (fallback remains
-  for table-miss only); doc truthing.
+- S1 (ADR-016 + plan, PR #270): DONE — no code change.
+- S2a (`lib/effect_sites.ml` shared numbering, PR #275): DONE — pure,
+  gate-neutral.
+- S2b (typecheck builds & returns the side-table, PR #276): DONE — no
+  codegen behaviour change yet.
+- S3 (pipeline threads the table; codegen boundary predicate switches
+  to the table with structural fallback; new e2e
+  `tests/codegen/effect_async_boundary.affine` proving a *user-defined*
+  `Async` fn triggers the transform — PR #277): DONE. All existing
+  http_cps_* / http_response_reader stay green.
+- S4 (retire the hardcoded `async_primitives` set; boundary is now
+  exactly `Effect_sites.is_async_call`; fallback remains for table-
+  empty / count-mismatch only — PR #278): DONE.
+
+*Delivery status:* CLOSED 2026-05-19 end-to-end. Issue #234 closed
+completed (`hyperpolymath/affinescript#234`). The structural name set
+no longer exists; the boundary is single-sourced from the typecheck
+effect side-table via the shared `Effect_sites` ordinal.
 """
 consequences = """
 - Generalises to user-defined `Async` functions; new async primitives

docs/ECOSYSTEM.adoc

@@ -80,7 +80,8 @@ made real; #228/ADR-014 module-qualified paths (estate port unblocker). |
 |*E* |typed-wasm convergence hardening (the transition runway): the
 AffineScript↔typed-wasm contract widened from L7+L10 toward full
 L1–6/L13–16 emitted-wasm enforcement; estate-wide re-validation (#235);
-effect-threaded async-boundary recogniser (#234); the #225/#160 convergence
+effect-threaded async-boundary recogniser (#234, DELIVERED 2026-05-19 —
+ADR-016, S1..S4 / PRs #270/#275/#276/#277/#278); the #225/#160 convergence
 ABI matured to "shared with Ephapax". |*planned* |Begins when D's substrate
 (INT-01..04, CORE-01) is closed; ends at a stable, multi-producer
 typed-wasm convergence ABI.

docs/TECH-DEBT.adoc

@@ -127,10 +127,20 @@ captured linears. |S1 |pt1 #240 + pt2 return-escape + `&mut` surface +
 pt3 Slice A NLL last-use DONE (Refs #177); residual = Slices B–D
 (flow-sensitive escape, origin variables, quantity integration) —
 issue #177
-|CORE-02 |Effect-handler dispatch on WasmGC (currently `UnsupportedFeature`;
-EH proposal or CPS). The #225 CPS line closes the async slice. |S2 |partial
-(#225 line CLOSED PR1..PR3d+PR4; #234 generalises the recogniser —
-ADR-016 ACCEPTED, side-table typecheck→codegen, staged S1..S4; S1 done)
+|CORE-02 |Effect-handler dispatch on WasmGC (was `UnsupportedFeature`;
+the chosen path is CPS over the EH proposal). The #225 CPS line closed
+the async slice; #234 generalised the boundary recogniser from a
+hardcoded name set to "any call whose effect row ⊇ `Async`". |S2
+|*CLOSED 2026-05-19* — #225 line CLOSED PR1..PR3d+PR4; #234 ADR-016
+delivered end-to-end (S1 #270 ADR; S2a #275 shared call-site
+numbering `lib/effect_sites.ml`; S2b #276 typecheck builds the
+ordinal→effect side-table; S3 #277 pipeline threads it + codegen
+boundary predicate switched + user-defined-`Async` e2e
+`tests/codegen/effect_async_boundary.affine`; S4 #278 hardcoded
+`async_primitives` set retired — boundary is now exactly
+`Effect_sites.is_async_call`). Issue #234 closed completed. Table-miss
+fallback (`Effect_sites.is_async_call` = false ⇒ no transform) remains
+as the sound table-empty / count-mismatch path.
 |CORE-03 |ADR-014: module-qualified type/effect path. Decision settled
 (both `.`/`::` accepted, `Pkg::Type` canonical, `.`→`::` for free via the
 `::`-fold). Was the estate's dominant parse blocker (525/1177 .affine).
@@ -293,7 +303,9 @@ Proven + locked (see INT-02)
 |CONV-01 |Estate-wide re-validation of the #199/#205 closure ABI (static →
 real wasm engine) |S2 |open #235
 |CONV-02 |Effect-threaded async-boundary detection (generalise the
-structural-conservative recogniser) |S2 |open #234
+structural-conservative recogniser) |S2 |*CLOSED 2026-05-19* — #234
+DELIVERED end-to-end (ADR-016 S1..S4; PRs #270/#275/#276/#277/#278).
+See CORE-02 above for the resolution narrative.
 |CONV-03 |#225/#160 convergence ABI matured to "shared with Ephapax" |S1
 |partial (PR3a/b/c merged)
 |CONV-04 |Widen emitted-wasm enforcement beyond L7+L10 toward L1–6/L13–16 |S2

docs/specs/SETTLED-DECISIONS.adoc

@@ -329,15 +329,23 @@ deterministic shared call-site numbering (a single traversal in a new
 keys cannot drift; no AST shape change). `Typecheck.check_program`
 populates `ordinal → effect_row` (declared and inferred) and returns
 it; `bin/main.ml` threads it into codegen (source-to-source backends
-ignore it); the CPS boundary predicate becomes a table lookup with the
-existing structural recogniser as the sound table-miss fallback.
-
-Staged (ledger #234): *S1* this ADR + plan (no code); *S2*
-`effect_sites.ml` + typecheck builds/returns the table (built, unused —
-gate-neutral); *S3* pipeline threads it, codegen switches to the table
-with structural fallback, new e2e proving a user-defined `Async` fn
-triggers the transform; *S4* retire the hardcoded set (fallback kept
-for table-miss only).
+ignore it); the CPS boundary predicate becomes a table lookup. The
+pre-S4 plan retained the existing structural recogniser as the
+table-miss fallback; S4 (#278) retired the hardcoded set, so the
+steady-state miss path is "no transform" — over-conservative, always
+sound.
+
+Staged (ledger #234): *S1* this ADR + plan (no code, PR #270); *S2a*
+`effect_sites.ml` shared call-site numbering (PR #275); *S2b* typecheck
+builds/returns the table (PR #276); *S3* pipeline threads it, codegen
+switches to the table with structural fallback, new e2e
+`tests/codegen/effect_async_boundary.affine` proving a user-defined
+`Async` fn triggers the transform (PR #277); *S4* retire the hardcoded
+`async_primitives` name set, the boundary is now exactly
+`Effect_sites.is_async_call` — table-empty / count-mismatch fallback
+([is_async_call] = false ⇒ no transform) is the sound miss path (PR
+#278). *Status:* DELIVERED 2026-05-19 end-to-end; issue #234 closed
+completed.
 
 This decision is settled; do not reopen without amending the ADR. Full
 ADR in `.machine_readable/6a2/META.a2ml` (ADR-016); ledger #234 /

docs/specs/async-on-wasm-cps.adoc

@@ -157,9 +157,12 @@ of* the verified Thenable-surface primitives.
   *DONE* — Deno-ESM (#226) + the typed-wasm CPS line PR1..PR3d all
   merged; this PR joint-closes #160 + #225. The ADR-013 delivery plan
   is complete; the transparent `fetch/get -> Response` surface is
-  delivered on both targets. (Two follow-ups, *not* part of this
-  slice, remain tracked: effect-threaded boundary generalisation
-  #234; estate #199/#205 re-validation #235.)
+  delivered on both targets. Follow-ups: the effect-threaded boundary
+  generalisation (#234, ADR-016) has since landed (S1..S4, PRs
+  #270/#275/#276/#277/#278, closed 2026-05-19 — the boundary is now
+  `Effect_sites.is_async_call` from the typecheck side-table, the
+  hardcoded `async_primitives` name set is retired); estate #199/#205
+  re-validation #235 remains tracked.
 
 == References
 

lib/codegen.ml

@@ -2016,20 +2016,15 @@ let simple_pat_name (p : pattern) : string option =
   | PatVar id -> Some id.name
   | _ -> None
 
-(** Recognised async-primitive calls (ADR-013 #225 PR3a, owner-chosen
-    structural-conservative async-boundary identification — see
-    affinescript#234 for the effect-threaded generalisation). The async
-    boundary is a `let` whose RHS is a call to one of these names. Extend
-    this list as wasm-path async stdlib primitives are added. *)
-(* ADR-016 / #234 S4: the hardcoded `async_primitives` name set is
-   RETIRED. The async boundary is exactly "a call whose effect row ⊇
-   Async", decided from the typecheck side-table keyed by the shared
-   [Effect_sites] ordinal ([Effect_sites.is_async_call]). The ADR's
-   "table-miss fallback" is the oracle being empty / count-mismatched
-   (⇒ [is_async_call] is always false ⇒ no transform = exact pre-#234
-   behaviour), NOT a name list — so no structural name disjunct
-   remains. `http_request_thenable` is still detected because
-   stdlib/Http.affine declares it `/ { Net, Async }`. *)
+(** Async-boundary predicate (ADR-016 / #234, S4 #278). True iff this
+    call's resolved effect row ⊇ `Async`, looked up via the typecheck
+    side-table keyed by the shared [Effect_sites] ordinal. The legacy
+    hardcoded `async_primitives = ["http_request_thenable"]` name set
+    (ADR-013 #225 PR3a) is retired — `http_request_thenable` is still
+    detected because stdlib/Http.affine declares it `/ { Net, Async }`,
+    and any user-defined `/ { Async }` callee triggers the transform
+    identically. Table-empty / count-mismatch ⇒ [is_async_call] = false
+    ⇒ no transform (the sound miss path). *)
 let is_async_prim_call (e : expr) : bool =
   Effect_sites.is_async_call e
 
@@ -2557,8 +2552,9 @@ let generate_module ?loader (prog : program) : wasm_module result =
      (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). *)
+     count-mismatch makes [bind_consumer] a no-op ⇒ [is_async_call] is
+     always false ⇒ no CPS transform (the sound S4 #278 miss path).
+     Safe if the producer never ran (empty ⇒ no-op). *)
   Effect_sites.bind_consumer prog;
   let loader = match loader with
     | Some l -> l

lib/effect_sites.ml

@@ -183,8 +183,8 @@ let iter (f : int -> expr -> unit) (prog : program) : unit =
    [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
+   false ⇒ codegen emits no CPS transform (the sound table-miss path
+   under S4 #278; zero regression if the producer never ran or the
    counts disagree). *)
 
 let async_by_ord : (int, bool) Hashtbl.t = Hashtbl.create 64

lib/typecheck.ml

@@ -193,10 +193,11 @@ type context = {
   (** ADR-016 / #234 S2b: per-call-site effect rows, keyed by the
       shared [Effect_sites] ordinal. Populated after a successful check
       pass; the value is the callee's declared effect row (EPure when
-      the callee is not a statically-named function). Built here but
-      NOT yet consulted by codegen — S3 threads & switches the WasmGC
-      CPS boundary predicate onto it (the structural recogniser remains
-      the sound table-miss fallback). *)
+      the callee is not a statically-named function). Built here and
+      published to [Effect_sites] for the WasmGC CPS boundary predicate
+      (S3, #277); the hardcoded name set is retired (S4, #278). A
+      table-miss / count-mismatch still falls back to "no transform"
+      ([Effect_sites.is_async_call] = false), which is sound. *)
 }
 
 type 'a result = ('a, type_error) Result.t
@@ -1792,17 +1793,18 @@ let check_decl (ctx : context) (decl : top_level) : (unit, type_error) Result.t
     [Resolve.resolve_program_with_loader] so that [ExprApp (ExprVar f, ...)]
     can resolve [f] to the imported function's scheme even though [f] does
     not appear in [prog.prog_decls]. *)
-(* ADR-016 / #234 S2b: build the per-call-site effect side-table.
-   Keyed by the shared [Effect_sites] ordinal so the (future) codegen
-   consumer agrees with this producer. A call's effect row is the
-   callee's *declared* row when the callee is a statically-named
-   function (`f(..)`, `m.f(..)`, through `ExprSpan`); otherwise EPure
-   (sound: S3's predicate is "row ⊇ Async ⇒ boundary", and an
-   over-conservative EPure just defers to the structural fallback —
-   exactly today's behaviour). Extern fns parse as [TopFn] with
-   [FnExtern]/[fd_eff] (parser.mly), so this covers the stdlib async
-   primitives and user `Async` fns uniformly. Pure traversal; built,
-   not yet consumed. *)
+(* ADR-016 / #234: build the per-call-site effect side-table. Keyed by
+   the shared [Effect_sites] ordinal so the codegen consumer agrees with
+   this producer. A call's effect row is the callee's *declared* row
+   when the callee is a statically-named function (`f(..)`, `m.f(..)`,
+   through `ExprSpan`); otherwise EPure (sound: the codegen predicate is
+   "row ⊇ Async ⇒ boundary", and an over-conservative EPure just means
+   "no transform" — the same as today's S4 table-miss path). Extern fns
+   parse as [TopFn] with [FnExtern]/[fd_eff] (parser.mly), so this
+   covers the stdlib async primitives and user `Async` fns uniformly.
+   After population the ordinal→has-Async projection is published via
+   [Effect_sites.set_async_by_ord] for the codegen consumer (S3 #277,
+   S4 #278). *)
 let populate_call_effects (ctx : context) (prog : Ast.program) : unit =
   let fn_eff : (string, eff) Hashtbl.t = Hashtbl.create 64 in
   List.iter
@@ -1925,8 +1927,9 @@ let check_program ?(import_types : (string, scheme) Hashtbl.t option)
        errors first (they are more fundamental). *)
     begin match Quantity.check_program_quantities prog with
     | Ok () ->
-      (* ADR-016 / #234 S2b: build the per-call-site effect side-table
-         on the fully-checked program. Built, not yet consumed. *)
+      (* ADR-016 / #234: build the per-call-site effect side-table on
+         the fully-checked program, and publish it to [Effect_sites] for
+         the codegen async-boundary predicate (S3/S4 — consumed). *)
       populate_call_effects ctx prog;
       Ok ctx
     | Error (qerr, span) ->

test/test_main.ml

@@ -11,6 +11,6 @@ let () =
       ("Golden", Test_golden.tests);
       ("Examples", Test_golden.example_tests);
       ("Effects (#59)", Test_effects.tests);
-      ("Effect-sites (#234 S2a)", Test_effect_sites.tests);
+      ("Effect-sites (#234, ADR-016)", Test_effect_sites.tests);
       ("TW L13 isolation (#10)", Test_tw_isolation.tests);
     ] @ Test_e2e.tests @ Test_stdlib_aot.tests)