Merge branch 'main' into claude/stdlib-04e-pure-done

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>

Author: hyperpolymath

.github/workflows/ci.yml

@@ -183,16 +183,22 @@ jobs:
         # ReScript source. Picks the existing res-to-affine test fixture
         # so any drift in the pinned commit's syntactic surface area
         # surfaces here rather than at walker-rule writing time.
+        #
+        # NOTE: tree-sitter-cli >= 0.25 repurposed `--paths` to mean "a
+        # file listing input source paths", not "a directory containing
+        # a grammar". Grammar lookup is now driven by the current
+        # working directory (the CLI walks up looking for grammar.js /
+        # src/parser.c), so we cd into the vendored grammar tree and
+        # pass an absolute path to the fixture. Without this, the step
+        # fails with `Failed to read paths file ... Is a directory`.
         run: |
           shopt -s nullglob
           fixtures=(tools/res-to-affine/test/fixtures/*.res)
           if [ ${#fixtures[@]} -eq 0 ]; then
             echo "no .res fixtures to smoke-parse; skipping"
             exit 0
           fi
-          tree-sitter parse \
-            --quiet \
-            "${fixtures[0]}" \
-            --paths tools/vendor/tree-sitter-rescript \
-            > /dev/null
+          fixture_abs="$(realpath "${fixtures[0]}")"
+          ( cd tools/vendor/tree-sitter-rescript \
+              && tree-sitter parse --quiet "${fixture_abs}" > /dev/null )
           echo "smoke-parsed: ${fixtures[0]}"

.machine_readable/6a2/META.a2ml

@@ -988,8 +988,20 @@ Staged plan (ledger INT-03; each row = one gated PR):
 - S4: native `wasi:clocks` + environment + argv via preview2 (wasmtime
   host-testable), replacing the preview1 shims behind the component path.
 - S5: `wasi:filesystem` (open/read/write/close) — unblocks INT-06.
-- S6: `wasi:sockets`; then flip the default wasm target to component
-  and demote the preview1 stdout path to a named legacy target.
+- S6a (WIT export lifting, DONE): codegen emits a `_start : () -> ()`
+  shim that calls `main` and drops its i32 result whenever a
+  parameter-less `fn main()` is present (`lib/codegen.ml`);
+  `tools/componentize.sh --command` wraps with the fetch-pinned
+  preview1->preview2 *command* adapter (wasmtime v44.0.1, sha256
+  8ff2ea78...) producing a component that exports `wasi:cli/run@0.2.x`
+  per `wit/affinescript.wit`. End-to-end gate:
+  `tests/componentize/command_smoke.sh` proves `wasmtime run` invokes
+  the component (exit 0), the ownership section survives, and the
+  lift is asserted. Purely additive: reactor consumers + game-loop
+  hooks are byte-unchanged.
+- S6b: `wasi:sockets`.
+- S6c: flip the default wasm target to component and demote the
+  preview1 stdout path to a named legacy target.
 """
 consequences = """
 - End-state is one-way (the component model becomes the canonical wasm
@@ -1058,23 +1070,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.
@@ -205,25 +206,44 @@ INT-01 ↔ INT-02. S1; unblocks INT-05/08/11. The `affinescript-dom-loader`
 satellite shell is downstream.
 |INT-03 |WASI preview2 / host I/O beyond stdout |#180 |S1, ADR-015
 ACCEPTED (owner-chosen full WASM Component-Model re-target). Staged
-S1..S6; legacy preview1 stdout path is the default until S6
-(reversible-in-progress). S2 toolchain provisioned (#251). **S3
+S1..S6; legacy preview1 stdout path remains the default until S6c
+(reversible-in-progress). S2 toolchain provisioned (#251). S3
 DONE: `tools/componentize.sh` wraps the emitted core module into a
 valid WASI-0.2 component via the fetch-pinned preview1→preview2
 *reactor* adapter (wasmtime v44.0.1, sha256-verified); the
 `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). S4a (clock) + S4b (env_count, arg_count) DONE:
+toolchain). S4a (clock) + S4b (env_count, arg_count) DONE:
 builtins lower to on-demand `wasi_snapshot_preview1.*` imports
 (Effect_sites pre-scan, canonical-order indexing through
 `ctx.wasi_func_indices`; zero impact on units that don't use them;
 verified with a multi-import combo regression). Component path
+bridges to `wasi:clocks`/`wasi:cli`. **S6a (WIT export lifting)
+DONE: `lib/codegen.ml` auto-emits a `_start : () -> ()` shim that
+calls `main` and drops its i32 result whenever a parameter-less
+`fn main()` is present. `tools/componentize.sh --command` wraps
+with the fetch-pinned preview1→preview2 *command* adapter
+(wasmtime v44.0.1, sha256 8ff2ea78…) — the resulting component
+exports `wasi:cli/run@0.2.x` per `wit/affinescript.wit`. End-to-end
+smoke `tests/componentize/command_smoke.sh` proves the lift, the
+ownership section survives, and `wasmtime run <component>` exits
+0 on real-host invoke. Purely additive: reactor consumers, the
+`__indirect_function_table` export, and game-loop hooks are
+byte-unchanged.** String accessors (env_at/arg_at) gated on a
+byte-level wasm-IR extension (I32Load8U/I32Store8 absent today)
+— tracked as the next slice before/with S5 filesystem. Remaining
+sub-slices: S5 (native clocks/env/argv via preview2), S6b
+(`wasi:sockets`), S6c (flip the default wasm target from preview1
+→ component). WIT world of record: `wit/affinescript.wit`
 bridges to `wasi:clocks`/`wasi:cli`. Real-host main-invoke deferred
-to S6 (WIT export-lifting / wasi:cli/run command shape). String
-accessors (env_at/arg_at) gated on a byte-level wasm-IR extension
-(I32Load8U/I32Store8 absent today) — tracked as the next slice
-before/with S5 filesystem.** WIT world of
-record: `wit/affinescript.wit`
+to S6 (WIT export-lifting / wasi:cli/run command shape).
+**S5 string accessors (env_at/arg_at) DONE: the wasm IR gained
+the byte-level load/store family (I32Load8U/I32Store8 + the full
+WebAssembly 1.0 §5.4.6 row, opcodes 0x2C..0x35 / 0x3A..0x3E);
+accessors lower to on-demand `environ_get`/`args_get` paired with
+the existing `*_sizes_get` import (dedup keeps each WASI import
+once even when both `*_count` and `*_at` are used).** 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;
 manual-only `publish-jsr.yml`; docs/PACKAGING.adoc). INT-01 dep

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).
@@ -183,6 +193,19 @@ round-trips + Deno codegen __cell-shape assertion) |S3 |DONE
 (`lib/interp.ml`, `lib/js_codegen.ml`, `lib/codegen_deno.ml`); sibling
 `panic` is wired and `error` should mirror it (divergent `T`) |S3 |open
 — issue #329
+|STDLIB-04c |`string_concat` extern — *REMOVED* (Refs #330): the
+canonical surface is the `++` operator (lowered in `Value.binop_string`
+and `__as_concat`); the extern was declared but never wired in any
+backend nor called from any stdlib/test/fixture — dead surface. The
+contract is now operator-only and one-source-of-truth. |S3 |DONE
+2026-05-24 (Refs #330)
+|STDLIB-04b |Throws extern `error<T>` — *LANDED* (Refs #329): mirrors
+`panic`'s divergent semantics with a polymorphic return (`<T>` unifies
+with the call-site expectation, unobservable at runtime). Wired in
+interp (`RuntimeError`), Deno codegen (`throw new Error`), resolve
+seed, and typecheck as a scheme (`poly1` so each call instantiates a
+fresh tyvar). 3 hermetic tests in "E2E STDLIB-04b error #329". |S3
+|DONE 2026-05-24 (Refs #329)
 |STDLIB-04c |`string_concat` extern — no direct wiring found; `++`
 operator independently lowered. Decide: remove (operator-only) or wire
 to mirror `++` |S3 |open — issue #330
@@ -229,16 +252,33 @@ 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→S4b |#180 ADR-015 (full
+|INT-03 |WASI preview2 / host I/O |S1→S6a |#180 ADR-015 (full
 Component-Model re-target, S1..S6); S2 toolchain #251 closed;
-S3 componentize done; **S4a (clock) + S4b (env_count, arg_count)
+S3 componentize done; S4a (clock) + S4b (env_count, arg_count)
 DONE — on-demand preview1 imports via Effect_sites pre-scan,
 canonical-order indexing through `ctx.wasi_func_indices`; combo
 regression proves no collision. String accessors (env_at/arg_at)
 gated on byte-level wasm IR (I32Load8U/I32Store8 absent today) —
-tracked next slice. Real-host main-invoke = S6 (WIT export
-lifting). Next S5
-(native clocks/env/argv)**
+tracked next slice. **S6a (WIT export lifting) DONE:
+`lib/codegen.ml` auto-emits a `_start : () -> ()` shim whenever
+a parameter-less `fn main()` is present (additive, no regression
+on reactor consumers); `tools/componentize.sh --command` wraps
+with the fetch-pinned command adapter (sha256
+8ff2ea78… / wasmtime v44.0.1, provisioned alongside the reactor
+adapter); `tests/componentize/command_smoke.sh` gates the
+contract end-to-end — `wasi:cli/run` lifted, ownership section
+survives, `wasmtime run` exits 0. Real-host main-invoke now
+works via `wasmtime run <component>`.** Remaining S6
+sub-slices: S5 (native clocks/env/argv), S6b (`wasi:sockets`),
+S6c (flip the default wasm target from preview1 → component)
+regression proves no collision. **S5 (env_at/arg_at) DONE — wasm
+IR extended with the byte-level load/store family
+(I32Load8U/I32Store8 and siblings); accessors lower to on-demand
+`environ_get`/`args_get` imports paired with the existing
+`*_sizes_get` (dedup keeps each WASI import exactly once even when
+both `*_count` and `*_at` are used in the same unit); guest
+allocates a length-prefixed AS string and byte-copies from the
+WASI buffer.** Real-host main-invoke = S6 (WIT export lifting)
 |INT-04 |Publish to JSR/npm |S2 |#181 packaging READY (dry-run green,
 manual workflow); compiler-binary distribution decided = **ADR-019**
 (#260, Releases + thin Deno/JSR shim, staged S1..S4) — S1/S2/S3
@@ -291,7 +331,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

@@ -302,8 +302,12 @@ change; *S2* toolchain provisioning (`wasm-tools`, `wasm-component-ld`,
 (codegen still emits core wasm; post-step wraps it via the standard
 preview1→preview2 adapter; ownership-section survival asserted; wasmtime
 component-run smoke); *S4* native `wasi:clocks`/environment/argv; *S5*
-`wasi:filesystem` (unblocks INT-06); *S6* `wasi:sockets`, then flip the
-default wasm target to component and demote preview1 to a legacy target.
+`wasi:filesystem` (unblocks INT-06); *S6a* (WIT export lifting) codegen
+auto-emits a `_start : () -> ()` shim around a parameter-less `fn main()`
+so `tools/componentize.sh --command` (preview1→preview2 *command*
+adapter) produces a real `wasi:cli/run`-exporting component that any
+WASI 0.2 host can invoke; *S6b* `wasi:sockets`; *S6c* flip the 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
@@ -329,15 +333,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