Merge branch 'main' into claude/pr351-no-techdebt

Author: hyperpolymath

.claude/CLAUDE.md

@@ -140,3 +140,117 @@ Rule: An issue is closed only by explicit merge of a PR with "Closes #N" OR by e
 Action (Hypatia): When asked to close an issue, confirm via a reply on the issue thread before doing so.
 Action (gitbot): Never use GitHub's "close issue" API directly; only close via PR merge with "Closes #N" keywords.
 
+## Agent operations notes
+
+Practical guidance for agents (Claude / other) operating in this repo,
+captured from parallel-bot session experience. Read once; saves turns.
+
+### CI signal reliability
+
+**"PR merged" does NOT mean "build green".** Auto-merge on this repo
+currently fires even when `build` or `lint` is failing — multiple
+recently-merged PRs (#334, #335, #336, #344) landed with `build` red,
+and the red persisted until PR #346's `FnExtern` interp fix. If you
+inherit a session reasoning about a recently-merged PR, do not assume
+its CI was green; check `mcp__github__pull_request_read` with method
+`get_check_runs` for the actual statuses, and check whether `main`
+itself is currently red before treating a build failure on your own
+PR as something *you* introduced.
+
+### Reading CI logs
+
+`WebFetch` against the GitHub Actions UI returns the React skeleton,
+not the log content. The fast paths for an agent are:
+
+* `mcp__github__pull_request_read` with method `get_check_runs` —
+  per-job status (queued / in_progress / success / failure) with
+  `details_url`. Sufficient for "did the build pass".
+* `mcp__github__pull_request_read` with method `get_status` —
+  combined commit status.
+* For actual log lines on a failed run, hand back to the user with
+  `gh run view --log-failed <run-id>`; do not loop trying to scrape
+  the UI.
+
+### Known-failing baseline checks
+
+These checks currently fail on *every* PR for repo-wide reasons, not
+because of any individual PR's changes. Do not waste turns
+investigating them on a per-PR basis:
+
+* `vscode-smoke` — npm 404 on `@hyperpolymath/affine-vscode` (the
+  in-editor harness depends on a not-yet-published npm package).
+* `migration-assistant` — was fixed by #342, but any branch created
+  from a base older than #342 will still see it red until rebased.
+* `governance / Language / package anti-pattern policy` — flags the
+  approved TypeScript exemptions (`affinescript-deno-test/*.ts`,
+  `editors/vscode/test/*.js`, etc., all documented in this file's
+  exemptions tables); the check has no allowlist for them.
+* The Hypatia security-scan bot comment — 143 findings; the bulk are
+  the same TypeScript exemption hits + pre-existing root files. A
+  real new finding will show as a *delta* in the count; otherwise
+  ignore.
+
+If a check from this list *changes status* on a PR (e.g.
+`vscode-smoke` suddenly passes, or Hypatia surfaces a new class of
+finding), that's signal worth investigating.
+
+### Branching discipline with concurrent merges
+
+When multiple agents are spawned in parallel, branch-creation time
+can lag `main` by hours and a stale base will silently revert other
+agents' work at merge time. **Before pushing any branch, run:**
+
+```
+git fetch origin main
+git rebase origin/main
+```
+
+Not just at branch-creation; immediately before push, after any
+in-session work. This guards against parallel-merge drift. Claude 1's
+STDLIB-04c branch (#337) accidentally reverted #334 and #335 because
+its base was stale; force-rebased to fix. Cheap to prevent, expensive
+to clean up.
+
+### Post-squash-merge branch divergence
+
+When a PR is squash-merged, the squashed commit on `main` gets a
+*new* SHA, distinct from any of the source-branch commits. If you
+then reset your local branch to `main` (or simply re-resolve it),
+`git status` reports N "ahead of origin/branch" — but those N
+commits are just the main-side commits the obsolete remote
+branch-tip never saw, not unpushed work.
+
+Recognising the situation:
+
+* The branch was already merged (PR closed, `merged: true`).
+* The local working tree matches `main`.
+* The remote branch still points at the *pre-merge* tip
+  (`origin/<branch>` is an old SHA, not the squashed one).
+* `git log origin/<branch>..HEAD` lists commits that look like
+  other people's work.
+
+Safe fix — pick the one matching intent:
+
+```
+git push origin --delete <branch>            # done with the branch
+git push --force-with-lease origin <branch>  # align the remote to main
+```
+
+`--force-with-lease` is safe here because nothing on the remote
+branch is unmerged work; force-push without `--lease` only matters
+if someone else pushed concurrently, which is irrelevant for an
+already-merged branch you're cleaning up.
+
+### Test-fixture hygiene for latent bug surfaces
+
+When you add a stdlib `extern fn` (or any other new declaration
+shape), add a test that feeds it to *every* downstream consumer
+(parse, resolve, typecheck, interp, every codegen target that
+shouldn't reject it). The PR #346 `FnExtern` interp bug had survived
+since the interpreter was written because no test had ever fed an
+inline `extern fn` to `Interp.eval_program` — STDLIB-04a's tests
+were the first, and only then did the missing match arm fire.
+
+Treat "first user of an existing-but-untested declaration shape" as a
+class-level surface, not a single test case.
+

.machine_readable/6a2/META.a2ml

@@ -985,8 +985,22 @@ Staged plan (ledger INT-03; each row = one gated PR):
   post-codegen step wraps it with the standard preview1->preview2
   adapter into a component; ownership section survival asserted;
   wasmtime component-run smoke. Codegen unchanged ⇒ reversible.
-- S4: native `wasi:clocks` + environment + argv via preview2 (wasmtime
-  host-testable), replacing the preview1 shims behind the component path.
+- S4 (DONE, slices S4a clock + S4b env_count/arg_count): on-demand
+  preview1 imports (`wasi_snapshot_preview1.clock_time_get`,
+  `environ_sizes_get`, `args_sizes_get`) via the Effect_sites
+  pre-scan, canonical-order indexing through
+  `ctx.wasi_func_indices`. NOTE divergence from this ADR's original
+  S4 wording ("native `wasi:clocks` + environment + argv via
+  preview2"): the slice shipped as preview1-shim, NOT native
+  preview2 calls. This is sufficient under the component path
+  because both adapters bridge the preview1 imports to
+  `wasi:clocks` / `wasi:cli` internally; switching the codegen
+  to emit `wasi:clocks/monotonic-clock@0.2.x.now()` directly only
+  pays off once preview2 is the default (deferred into S6c). The
+  ADR is amended here to record what actually shipped rather than
+  pretending S4 fulfilled the original wording. String accessors
+  (env_at/arg_at) need byte-level wasm IR (I32Load8U/I32Store8) for
+  buffer marshalling and remain a tracked follow-up.
 - S5: `wasi:filesystem` (open/read/write/close) — unblocks INT-06.
 - S6a (WIT export lifting, DONE): codegen emits a `_start : () -> ()`
   shim that calls `main` and drops its i32 result whenever a
@@ -999,13 +1013,33 @@ Staged plan (ledger INT-03; each row = one gated PR):
   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`.
+- S6b (sockets on-ramp, DONE): new `net_shutdown(fd, how) -> Int`
+  builtin (Effect `Net`, reserved) lowers to
+  `wasi_snapshot_preview1.sock_shutdown` via the same on-demand
+  canonical-order pattern as S4a/S4b (`optional_wasi` entry 4 in
+  `lib/codegen.ml`). The command adapter bridges to
+  `wasi:sockets/tcp` internally without surfacing a host-side
+  `wasi:sockets/*` requirement; `tests/componentize/sockets_smoke.sh`
+  gates the lift + a clock+env+sock combo for canonical-order
+  regression. Real-host invoke under wasmtime exits 0 on
+  `net_shutdown(stdin, RDWR)` (ENOTSOCK dropped). Larger socket
+  primitives (recv/send/accept) need byte-level wasm IR for buffer
+  / network-address marshalling and remain a tracked follow-up
+  alongside env_at/arg_at.
 - S6c: flip the default wasm target to component and demote the
-  preview1 stdout path to a named legacy target.
+  preview1 stdout path to a named legacy target. Bundled cleanup:
+  replace the on-demand preview1 shims emitted by S4a/S4b/S6b
+  (clock_time_get, environ_sizes_get, args_sizes_get,
+  sock_shutdown) with native preview2 calls
+  (`wasi:clocks/monotonic-clock`, `wasi:cli/environment`,
+  `wasi:sockets/tcp`) — this only pays off once preview2 is the
+  default, hence its placement here rather than as a standalone
+  pre-flip slice.
 """
 consequences = """
 - End-state is one-way (the component model becomes the canonical wasm
-  target) but reversible-in-progress: preview1 retained through S5.
+  target) but reversible-in-progress: preview1 retained as the default
+  through S6b; the flip happens at S6c.
 - S3..S6 are HARD-GATED on S2 (toolchain). Tracked as a follow-up
   issue; this is disclosed, not hidden.
 - typed-wasm ownership-section ABI is unchanged; the coordination
@@ -1070,34 +1104,23 @@ 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), 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.
+  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 (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.
+- 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
@@ -1286,8 +1309,9 @@ references = [
 
 [[adr]]
 id = "ADR-020"
-status = "proposed"
+status = "accepted"
 date = "2026-05-23"
+ratified = "2026-05-24"
 title = "Ownership-section schema versioning (0xAF sentinel + u8 version)"
 context = """
 The `affinescript.ownership` Wasm custom section has been frozen at
@@ -1366,8 +1390,9 @@ references = [
 
 [[adr]]
 id = "ADR-021"
-status = "proposed"
+status = "accepted"
 date = "2026-05-23"
+ratified = "2026-05-24"
 title = "Multi-producer ABI coordination model for typed-wasm carriers"
 context = """
 typed-wasm is a separate, language-agnostic compilation target with

docs/ECOSYSTEM.adoc

@@ -80,8 +80,7 @@ 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, DELIVERED 2026-05-19 —
-ADR-016, S1..S4 / PRs #270/#275/#276/#277/#278); the #225/#160 convergence
+effect-threaded async-boundary recogniser (#234); 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.
@@ -97,17 +96,6 @@ on the same footing as the other producers (ephapax). See the contract below.
 
 [IMPORTANT]
 ====
-This section is a *summary* of the contract.  The *authoritative*
-formal specification is
-link:specs/TYPED-WASM-INTERFACE.adoc[specs/TYPED-WASM-INTERFACE.adoc]
-(+ machine-readable companion
-link:specs/TYPED-WASM-INTERFACE.a2ml[specs/TYPED-WASM-INTERFACE.a2ml]).
-The roadmap of what would make typed-wasm a *natural and optimal*
-compilation target is
-link:specs/TYPED-WASM-ROADMAP.adoc[specs/TYPED-WASM-ROADMAP.adoc].
-ADR-020 (schema versioning) and ADR-021 (multi-producer model) are
-filed as PROPOSED in `.machine_readable/6a2/META.a2ml`.
-
 typed-wasm is a *separate, language-agnostic compilation target* with its own
 repository (`hyperpolymath/typed-wasm`), its own Idris2 proofs, its own
 ReScript surface, its own Rust verifier crate, and *its own other producers*
@@ -240,21 +228,30 @@ 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-unchanged.** **S6b (sockets on-ramp) DONE: new
+`net_shutdown(fd, how) -> Int` builtin (Effect `Net`, reserved)
+lowers to `wasi_snapshot_preview1.sock_shutdown` via the same
+on-demand canonical-order pattern as S4a/S4b (`optional_wasi`
+entry 4); the command adapter bridges to `wasi:sockets/tcp`
+internally without surfacing a host-side `wasi:sockets/*`
+requirement; `tests/componentize/sockets_smoke.sh` gates the
+lift + a clock+env+sock combo for canonical-order regression;
+wasmtime real-host invoke exits 0 on `net_shutdown(stdin, RDWR)`
+(ENOTSOCK errno is dropped). Larger socket primitives
+(recv/send/accept) require byte-level wasm IR for buffer /
+network-address marshalling — tracked alongside env_at/arg_at.**
+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).
-**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`
+— tracked as the next slice before/with S5. Remaining sub-slices
+(per ADR-015 canonical numbering in META.a2ml): S5 — bring up
+`wasi:filesystem` (open/read/write/close), which unblocks INT-06
+(server-side runtime profile); S6c — flip the default wasm
+target from preview1 → component, bundled with the optional
+native-preview2 cleanup that replaces the on-demand preview1
+shims emitted by S4a/S4b/S6b with direct `wasi:clocks` /
+`wasi:cli` / `wasi:sockets` calls (only pays off once preview2
+is the default, hence the bundling). 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