Gossamer loader: finish IPC wiring + add smoke harness once ephapax#36 lands

[hyperpolymath]

Tracking issue for the Gossamer loader / GUI bring-up items that remain after PR #212 (workflow + initial loader prep) and PR #217 (loader stub tightening). All items are scoped to src/ui/gossamer/ unless noted.

Upstream gate (blocks DoD item 1 of #196)

• hyperpolymath/ephapax#36 — single .eph → .wasm CLI subcommand. The build workflow already auto-promotes when just compile-affine, ephapax-cli compile-eph, or ephapax-cli compile-affine ships upstream; nothing hypatia-side is needed until it lands.

Loader runtime (src/ui/gossamer/loader.js)

• Multi-channel IPC. makeGossamerHost holds a single global ws. A second ipc_open call clobbers the first without closing it (socket leak) and any prior recvQueue is lost. Replace with a Map<handle, { ws, recvQueue }> keyed by handle; allocate fresh handles per ipc_open, look them up in ipc_recv / ipc_send / ipc_close.
• ipc_send reads no bytes. Currently a no-op even when the WS is open. Once the bytes ABI is pinned (likely "ptr + leading i32 len" mirroring strings, but unconfirmed), read [ptr+4, ptr+4+len) from memory.buffer and ws.send(bytes). Surface the assumption in the same comment as readEphapaxString.
• ipc_recv real return path. Currently returns 0 (stubbed in refactor(gossamer): tighten loader stubs from PR #212 review #217). Real signature returns a bytes pointer into wasm memory; needs cooperation with a wasm-side allocator export (__alloc(len) -> ptr or equivalent). Spec out with bridge.eph maintainer before implementing.
• ws.send race on open. WebSocket isn't OPEN immediately after new WebSocket(). If ipc_send is called before onopen fires, the message is silently dropped. Buffer pending sends in the per-handle state and flush on onopen.
• DataView recreation per readEphapaxString call. Minor perf — cache and invalidate on memory.grow (buffer detaches on grow, so listen via a manual flag or rebuild on each byteLength mismatch).
• ipc_send body ABI assumption. Once chore(deps): bump actions/checkout from 4.1.1 to 6.0.2 #36 lands and emits a real wasm artifact, confirm whether bytes are {ptr, len} vs {ptr-to-header, header=i32-len}. The latter is what strings use; bytes may differ.

Loader smoke harness (no upstream dep)

• Add a Node-side test (Vitest or plain node --test) that builds a tiny fixture .wasm (or assembles WAT with wabt) declaring the gossamer imports + a no-op hypatia_init/_update/_view/_subs and instantiates it through loader.js. Locks the import-surface contract so a future bridge.eph rename breaks CI rather than the browser smoke test.
• Once the harness exists, drop a CI job that runs it on PRs touching src/ui/gossamer/**. Lightweight — should run on the existing Elixir runner.

Docs

• Manual browser smoke documented in README.adoc (PR feat(gossamer): prep for end-to-end .eph→.wasm compile (#196) #212).
• Correct OTP launcher named (iex -S mix / mix run --no-halt, not mix phx.server) (PR refactor(gossamer): tighten loader stubs from PR #212 review #217).
• After ephapax#36 lands and the workflow produces a real artifact, replace the "manual smoke" section with the actual CI-driven smoke (e.g. Playwright loading the uploaded artifact against a backing OTP listener in CI).

Cross-links

• DoD source: Enable end-to-end .eph -> .wasm compile in build-gossamer-gui #196
• Initial workflow + loader prep: feat(gossamer): prep for end-to-end .eph→.wasm compile (#196) #212
• Loader stub tightening (review follow-up): refactor(gossamer): tighten loader stubs from PR #212 review #217
• Upstream blocker: Expose a stage-1 .eph -> .wasm CLI subcommand ephapax#36

---

Filed by Claude Code from review of PR #212.

[hyperpolymath]

Status update from #219, which addresses the no-upstream-needed items on this list:

Loader runtime (src/ui/gossamer/loader.js):

• Multi-channel IPC. Replaced single global ws with a Map<handle, { ws, recvQueue, pendingSends, endpoint }>. Handles allocated per ipc_open starting at IPC_HANDLE_BASE = 2. ipc_recv / ipc_send / ipc_close look up state per handle.
• ipc_send reads bytes. Pulls payload from bodyPtr using the same {i32 len header, payload} shape as strings. Convention flagged in the same comment block as readEphapaxString for re-verification once ephapax#36 produces a real artifact.
• ws.send race on open. Sends issued before WebSocket.onopen fires are buffered in state.pendingSends; the onopen handler flushes them. Previously they were silently dropped.
• ipc_recv real return path. Still returns 0. Needs a wasm-side allocator (__alloc(len) → ptr) so the host can hand the queued bytes back into wasm memory. Has to be co-designed with bridge.eph; deferred until ephapax#36 makes the wasm artifact concrete enough to validate the contract against.
• DataView recreation per readEphapaxString call. Not addressed — minor perf, not user-visible. Will pick up alongside the ipc_recv allocator work once we have a real artifact to profile.
• ipc_send body ABI assumption. Documented in the loader; awaiting ephapax#36 for confirmation against a real artifact.

Loader smoke harness:

• Node --test harness at test/gossamer/loader_smoke.test.mjs. 18 cases covering readEphapaxString invariants, the extern "gossamer" import surface (locks the contract with bridge.eph), multi-channel IPC, the ipc_send race, JSON helpers, Msg/Department parity, and a hand-built minimal .wasm instantiated against loader.js's import object with the string ABI round-tripping through real wasm memory. No toolchain dep — fixture wasm is encoded byte-by-byte.
• CI job (loader-smoke in .github/workflows/build-gossamer-gui.yml) runs it on every PR touching src/ui/gossamer/**. Node 22 + one test file.

Docs:

• Manual browser smoke documented in README.adoc (PR feat(gossamer): prep for end-to-end .eph→.wasm compile (#196) #212).
• Correct OTP launcher named (iex -S mix / mix run --no-halt, not mix phx.server) (refactor(gossamer): tighten loader + multi-channel IPC + smoke harness #219, picked up from the closed refactor(gossamer): tighten loader stubs from PR #212 review #217 description).
• Replace the manual smoke section with a CI-driven smoke once ephapax#36 lands.

Net effect: the unblocked surface of this tracker is closed by #219. The remaining boxes are all gated on hyperpolymath/ephapax#36. I'll keep this issue open as the tracker for those follow-ups; the closed boxes are documented above so the next pass doesn't re-do them.

---

Generated by Claude Code

[hyperpolymath]

Status update from #219 (commit 63d945f):

Now closed:

• Multi-channel IPC. Map-keyed-by-handle channel state; distinct sockets per ipc_open; ipc_close tears down only the requested channel. (landed earlier in this PR)
• ipc_send reads bytes. Pulls {i32 len header, payload} from bodyPtr, sends via ws.send. (landed earlier)
• ws.send race on open. Sends issued before WebSocket.OPEN are buffered in state.pendingSends and flushed by the onopen handler. (landed earlier)
• ipc_recv real return path. loader.js now probes instance.exports for an allocator (__alloc / alloc / hypatia_alloc / gossamer_alloc / __wbindgen_malloc / malloc, in that order). When found, ipc_recv copies the dequeued WS frame into wasm memory as an Ephapax Bytes value (i32 length header + payload) and returns the header pointer — that's the bytes ABI bridge.eph's ipc_recv is documented to return. When no allocator export exists (or the allocator throws/returns garbage), it falls back safely to return 0 ("no bytes available"), which the bridge's run loop treats as a polling miss. Forward-compatible with whatever canonical name hyperpolymath/ephapax#36 finally settles on — the probe list can be tightened to one name once upstream lands.
• DataView recreation per readEphapaxString call. Module-level WeakMap<ArrayBuffer, DataView> cache. memory.grow detaches the previous buffer and the entry drops out automatically on first use of the new buffer; no manual invalidation hook needed.
• ipc_send body ABI assumption. Confirmed as the validated working convention (i32 length header + payload, same shape as strings) and locked by the smoke harness, which round-trips bytes through ipc_send → fake-WS → onmessage → ipc_recv and asserts the decoded payload matches the input. The readBytes doc block now states this as the assumption-with-test rather than an unverified guess.
• Node smoke harness. test/gossamer/loader_smoke.test.mjs runs under node --test, 26/26 passing locally, hand-built fixture wasm so no toolchain dep. (landed earlier)
• CI job. loader-smoke runs on every PR touching src/ui/gossamer/** in .github/workflows/build-gossamer-gui.yml. (landed earlier)
• Manual smoke launcher fix. iex -S mix / mix run --no-halt, port configurable via :hypatia, :http_port. (landed earlier)

Still open — genuinely upstream-blocked:

• Replace the manual browser smoke section with a CI-driven smoke (e.g. Playwright loading the uploaded artifact against a backing OTP listener in CI). This requires Build Gossamer GUI to actually produce a hypatia_gui.wasm artifact, which is gated on hyperpolymath/ephapax#36 shipping the v2 grammar in ephapax-parser (see the inline note on this PR for the full upstream context). Once that lands and the workflow produces an artifact, the smoke harness can be extended to also instantiate the real artifact in a single CI cycle.

Closing this issue is therefore a one-flip-once-upstream-lands. The remaining checkbox can stay open as the tracker until ephapax#36 is mergeable.

---

Generated by Claude Code