docs(adr): ADR-016 — effect-threaded async-boundary detection (#234 S1)

#234: the CPS transform's async-boundary detector is a hardcoded set
`async_primitives=["http_request_thenable"]` — brittle and blind to
user-defined `Async` fns. The generalisation ("boundary = any call
whose effect row ⊇ Async") touches the typecheck→codegen interface
(shared infra) → one-way-door fork, escalated (AskUserQuestion
2026-05-19). Owner chose the **side-table** mechanism over AST
annotation / codegen-local re-derivation.

This is slice S1 — the decision record only, no code (the discipline
for a one-way shared-infra change, mirroring ADR-015):
- ADR-016 in docs/specs/SETTLED-DECISIONS.adoc + the META.a2ml
  `[[adr]]` block (format-matched to ADR-012/014/015). Side-table
  keyed by a deterministic shared call-site numbering
  (`lib/effect_sites.ml`, called identically by typecheck & codegen so
  keys can't drift — no AST shape change, robust to future rebuilds);
  structural recogniser retained as the sound table-miss fallback.
  Staged S1..S4 (S2 build+return table unused/gate-neutral; S3
  pipeline+codegen switch + user-Async e2e; S4 retire hardcoded set).
- TECH-DEBT CORE-02 truthed (#225 line CLOSED; #234 ADR-016 accepted).

Gate: `dune test --force` 278/278 (no code; zero regression).

Refs #234. Not Closes — staged campaign; owner closes per ISSUE-CLOSURE.

Author: hyperpolymath

.machine_readable/6a2/META.a2ml

@@ -1016,3 +1016,82 @@ references = [
   "hyperpolymath/typed-wasm (multi-producer ownership-section ABI)",
   "WASI 0.2 / WebAssembly Component Model specification",
 ]
+
+[[adr]]
+id = "ADR-016"
+status = "accepted"
+date = "2026-05-19"
+title = "Effect-threaded async-boundary detection (side-table; #234)"
+context = """
+The WasmGC CPS transform (ADR-013) detects the async boundary
+*structurally*: a `let` whose RHS calls a primitive in a hardcoded set
+`async_primitives = ["http_request_thenable"]` (lib/codegen.ml). This
+was the deliberately-contained #225 PR3a scope. It is brittle: every
+new async stdlib primitive must be added to the set, and a
+user-defined `Async`-effecting function is invisible to it — blocking
+the fully transparent ADR-013 surface for user async code. #234 asks
+for the principled generalisation: the boundary is any call whose
+effect row ⊇ `Async`. This requires per-call effect information at
+codegen time. The AST (`lib/ast.ml`) carries no location or node id on
+`ExprApp`, and the owner-chosen mechanism (AskUserQuestion
+2026-05-19) is a typecheck→codegen side-table, NOT AST annotation.
+"""
+decision = """
+Thread per-call-site effect rows from typecheck to codegen via a
+*side-table*, keyed by a deterministic shared call-site numbering.
+
+- *Keying.* A single shared traversal (new `lib/effect_sites.ml`)
+  assigns every `ExprApp` an ordinal in a fixed pre-order walk of the
+  program. Both typecheck and codegen obtain ordinals by calling the
+  *same* function, so keys cannot drift. No AST shape change (the
+  pipeline already threads one `prog` value through resolve →
+  typecheck → borrow → quantity → codegen unmodified, but ordinals —
+  not physical identity — are the contract, which is robust to any
+  future node rebuild).
+- *Producer.* `Typecheck.check_program` populates
+  `(int, effect_row) Hashtbl.t` (call-site ordinal → resolved effect
+  row, declared *and* inferred) and returns it in its result context.
+- *Pipeline.* `bin/main.ml` threads the table into the codegen entry
+  alongside `prog` (one extra argument; the existing source-to-source
+  backends ignore it).
+- *Consumer.* The CPS detector's boundary predicate becomes “the
+  `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).
+
+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.
+"""
+consequences = """
+- Generalises to user-defined `Async` functions; new async primitives
+  need no codegen edit (closes the brittleness #234 names).
+- One-way-ish: introduces a typecheck→codegen data channel (shared
+  infra). Reversible per-slice (S2/S3 are additive; the structural
+  recogniser stays as the sound fallback throughout).
+- Source-to-source backends unaffected (they ignore the table arg).
+- This decision is settled; do not reopen without amending this ADR.
+  Ledger #234 / CORE-02 in docs/TECH-DEBT.adoc.
+"""
+references = [
+  "https://github.com/hyperpolymath/affinescript/issues/234",
+  "https://github.com/hyperpolymath/affinescript/issues/225",
+  "docs/specs/async-on-wasm-cps.adoc (ADR-013)",
+  "lib/codegen.ml (async_primitives / detect_async_base_case)",
+  "lib/typecheck.ml (check_program)",
+  "lib/effect_sites.ml (new; shared call-site numbering)",
+  "docs/specs/SETTLED-DECISIONS.adoc (ADR-016 section)",
+]

docs/TECH-DEBT.adoc

@@ -102,7 +102,8 @@ analysis. |S1 |pt1 #240 + pt2 return-escape DONE (Refs #177); pt2 residual
 parser-gated — 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
-(PR3a/b/c merged; #234 generalises the recogniser)
+(#225 line CLOSED PR1..PR3d+PR4; #234 generalises the recogniser —
+ADR-016 ACCEPTED, side-table typecheck→codegen, staged S1..S4; S1 done)
 |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).

docs/specs/SETTLED-DECISIONS.adoc

@@ -308,3 +308,37 @@ default wasm target to component and demote preview1 to a legacy target.
 This decision is settled; do not reopen without amending the ADR. Full
 ADR in `.machine_readable/6a2/META.a2ml` (ADR-015); ledger INT-03 in
 `docs/TECH-DEBT.adoc`; roadmap in `docs/ECOSYSTEM.adoc`.
+
+== Effect-Threaded Async-Boundary Detection (ADR-016)
+
+The WasmGC CPS transform (ADR-013) detects the async boundary
+*structurally* — a `let` whose RHS calls a primitive in a hardcoded set
+`async_primitives = ["http_request_thenable"]`. That was the contained
+#225 PR3a scope; it is brittle (every new async primitive needs a
+codegen edit) and blind to user-defined `Async` functions, blocking the
+fully transparent ADR-013 surface for user async code. #234 generalises
+it: the boundary is *any call whose effect row ⊇ `Async`*.
+
+The AST carries no location/node id on `ExprApp`, and the escalated
+one-way-door fork (AskUserQuestion 2026-05-19) was decided in favour of
+a *typecheck→codegen side-table*, not AST annotation.
+
+Decision: thread per-call effect rows via a side-table keyed by a
+deterministic shared call-site numbering (a single traversal in a new
+`lib/effect_sites.ml`, called identically by typecheck and codegen, so
+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).
+
+This decision is settled; do not reopen without amending the ADR. Full
+ADR in `.machine_readable/6a2/META.a2ml` (ADR-016); ledger #234 /
+CORE-02 in `docs/TECH-DEBT.adoc`.