toiljs 0.0.67 → 0.0.68

package/src/devserver/stream/host.ts

@@ -0,0 +1,42 @@
+/**
+ * Host-import surface for the dev STREAM (hot, L2/L3) box, mirroring the production edge's stream box
+ * (`toil-backend` `src/wasm/stream`). A `@stream` box is a HOT artifact: it imports the same request
+ * `env.*` runtime surface (so the ToilScript runtime + `@data`/crypto/env/`Date.now` code runs
+ * unchanged) and drives its lifecycle through the `stream_dispatch` export + the ingress/egress ring
+ * bridge ({@link ../index.js}), NOT through `handle`.
+ *
+ * The `stream.*` namespace (`stream.send` / `@channel`) is DEFERRED: the raw `@message` ring bridge -
+ * the only stream feature wired so far - needs NO host imports (the guest reads/writes the rings in
+ * its own linear memory). A box that does not use `stream.*` instantiates against `env.*` alone.
+ */
+
+import { buildDatabaseImports, type DbDevState, freshDbState } from '../db/index.js';
+import { buildCryptoImports, type CryptoState, freshCryptoState } from '../runtime/crypto.js';
+import { buildEnvImports, type MemoryRef } from '../runtime/host.js';
+
+/** Per-stream-box host scratch (DB + crypto), analogous to the daemon's `DaemonState`. Each resident
+ *  connection box carries its own, so two connections never share `@data` transaction scratch. */
+export interface StreamBoxState {
+    crypto: CryptoState;
+    db: DbDevState;
+}
+
+export function freshStreamBoxState(): StreamBoxState {
+    return { crypto: freshCryptoState(), db: freshDbState() };
+}
+
+/**
+ * The full `env` import object for a dev stream box: the request-surface `env.*` runtime (built by
+ * {@link buildEnvImports}) plus the crypto and `@data` namespaces. The response/stream `env.*`
+ * functions a box must not have (`set_status`/`respond_file`/...) are excluded by `buildEnvImports`
+ * itself, exactly as for the daemon cold box.
+ */
+export function buildStreamImports(ref: MemoryRef, state: StreamBoxState): WebAssembly.Imports {
+    return {
+        env: {
+            ...buildEnvImports(ref, state),
+            ...buildCryptoImports(ref, state.crypto),
+            ...buildDatabaseImports(ref, state.db),
+        },
+    };
+}

package/src/devserver/stream/index.ts

@@ -0,0 +1,308 @@
+/**
+ * Dev STREAM (L2/L3) emulation: load a `release-stream.wasm` hot artifact into a resident per-connection
+ * box and drive its lifecycle (`@connect` / `@message` / `@close` / `@disconnect`) through the
+ * `stream_dispatch` export + the ingress/egress RING BRIDGE - the dev-side port of the production
+ * `StreamBox` (`toil-backend` `src/wasm/stream/runtime.rs`). The ring wire format (RingControl 32B +
+ * RingFrame 12B + drained-reset + the packed-i64 reject bridge) AND the `@connect` info-block ABI are
+ * replicated BYTE-FOR-BYTE so a `@stream` app behaves identically under `npm run dev` and at the edge.
+ *
+ * RESIDENT: one box per connection, NEVER reset between events (linear memory persists across
+ * connect -> message -> close); a fresh `WebAssembly.Instance` per connection IS that residency.
+ *
+ * DEV LIMITATION vs the edge: Node's `WebAssembly` has NO gas-metering middleware, so a runaway guest
+ * loop is NOT gas-killed in dev (it hangs) - only a genuine wasm TRAP (unreachable / OOB / abort)
+ * surfaces, which the caller turns into a `STREAM_HOOK_TRAPPED` close. Packet gas, chunk reassembly,
+ * `@channel`, and the `stream.*` host imports are deferred exactly as on the edge.
+ */
+
+import { parseSurface } from '../wasm/surface.js';
+import { buildStreamImports, freshStreamBoxState, type StreamBoxState } from './host.js';
+
+// --- the stream_dispatch ABI (toil-backend src/wasm/stream/section.rs) ---
+const EVENT_CONNECT = 1;
+const EVENT_MESSAGE = 2;
+const EVENT_CLOSE = 3;
+const EVENT_DISCONNECT = 4;
+
+// --- ring wire format (05 sections 5-6; toil-backend src/wasm/stream/runtime.rs) ---
+const RING_CTRL_BYTES = 32; // RingControl header
+const RING_FRAME_HEADER = 12; // RingFrame header
+const RING_MAGIC = 0x3147_4e52; // "RNG1" little-endian
+const RING_VERSION = 1;
+const RC_WRITE = 12; // write_cursor offset in RingControl
+const RC_READ = 16; // read_cursor offset
+const FRAME_TYPE_DATA_RELIABLE = 1;
+const MAX_STREAM_FRAME_LEN = 65536; // 64 KiB per egress frame (05 6.1)
+
+// --- @connect info-block ABI (05 section 2.2; toil-backend runtime.rs write_connect_info) ---
+// Layout: [u64 stream_id][u8 transport][u8 _][u16 auth_len][u16 path_len][u16 _] then auth + path UTF8.
+const SI_TRANSPORT = 8;
+const SI_AUTH_LEN = 10;
+const SI_PATH_LEN = 12;
+const SI_RESERVED2 = 14;
+const SI_BODY = 16;
+const SI_TRANSPORT_WEBTRANSPORT = 1; // the v1 transport (the dev emulates it)
+
+/**
+ * Decode a guest's NEGATIVE `stream_dispatch` return into a `0x02xx` reject/close code (the Part-3
+ * bridge `-(0x10000 + code)`), clamped to the stream range `0x0200..=0x02FF`; an out-of-range value
+ * normalizes to `0x0208 STREAM_REJECTED`, mirroring `toil-backend` `decode_reject_code`.
+ */
+export function decodeRejectCode(rc: bigint): number {
+    const raw = Number((-rc - 0x10000n) & 0xffffn);
+    return raw >= 0x0200 && raw <= 0x02ff ? raw : 0x0208;
+}
+
+interface StreamExports {
+    readonly memory: WebAssembly.Memory;
+    readonly stream_dispatch: (eventKind: number, lo: number, hi: number) => bigint;
+    readonly stream_ring_offset?: () => number;
+    readonly stream_ring_capacity?: () => number;
+    readonly stream_egress_offset?: () => number;
+    readonly stream_egress_capacity?: () => number;
+    readonly stream_info_offset?: () => number;
+    readonly stream_info_capacity?: () => number;
+}
+
+interface Rings {
+    readonly ingressOff: number;
+    readonly ingressCap: number;
+    readonly egressOff: number;
+    readonly egressCap: number;
+}
+
+interface StreamInfo {
+    readonly offset: number;
+    readonly cap: number;
+}
+
+/** A `@message` dispatch outcome: the drained egress reply frames, or a guest reject code. */
+export type StreamMessageOutcome =
+    | { readonly kind: 'reply'; readonly frames: Buffer[] }
+    | { readonly kind: 'reject'; readonly code: number };
+
+/** A `@connect` outcome: the guest accepted (the box is usable) or rejected with a `0x02xx` code. */
+export type StreamConnectOutcome =
+    | { readonly kind: 'accept' }
+    | { readonly kind: 'reject'; readonly code: number };
+
+export class DevStreamBox {
+    private constructor(
+        private readonly exports: StreamExports,
+        private readonly _state: StreamBoxState,
+        private readonly rings: Rings | null,
+        private readonly streamInfo: StreamInfo | null,
+    ) {}
+
+    /** Compile + instantiate a resident stream box from a HOT `release-stream.wasm`. Fails closed: a
+     *  cold artifact, a missing `stream_dispatch`/`memory`, or a bad module throws. */
+    static load(wasm: Buffer): DevStreamBox {
+        const surface = parseSurface(wasm);
+        if (surface === 'invalid' || surface.targetMode !== 'hot') {
+            throw new Error('stream box requires a hot artifact with a valid toil.surface');
+        }
+        const ref: { memory: WebAssembly.Memory | null } = { memory: null };
+        const state = freshStreamBoxState();
+        const module = new WebAssembly.Module(new Uint8Array(wasm));
+        const instance = new WebAssembly.Instance(module, buildStreamImports(ref, state));
+        const exports = instance.exports as unknown as StreamExports;
+        if (
+            typeof exports.stream_dispatch !== 'function' ||
+            !(exports.memory instanceof WebAssembly.Memory)
+        ) {
+            throw new Error("stream artifact must export 'stream_dispatch' + 'memory'");
+        }
+        ref.memory = exports.memory;
+        const rings = DevStreamBox.resolveRings(exports);
+        const streamInfo = DevStreamBox.resolveStreamInfo(exports);
+        const box = new DevStreamBox(exports, state, rings, streamInfo);
+        if (rings) box.stampRings();
+        return box;
+    }
+
+    /** Whether the box carries the ring runtime (a pre-bridge fixture omits the exports). */
+    get hasRings(): boolean {
+        return this.rings !== null;
+    }
+
+    /** Whether the box carries the `@connect` info-block bridge (a `@connect(StreamInbound)` hook). */
+    get hasConnectBridge(): boolean {
+        return this.streamInfo !== null;
+    }
+
+    /**
+     * Fire `@connect`: write the connect-info block (stream id + transport + authority + path) into the
+     * guest's info region, dispatch `EVENT_CONNECT`, and decode the `StreamOutbound` accept/reject. On
+     * accept, clear any `@connect`-staged egress (initial-egress is deferred, like the edge) so it does
+     * not contaminate the first `@message` reply. A box without the bridge runs `@connect` context-free
+     * (the write is a no-op) and always accepts unless it returns a negative code.
+     */
+    onConnect(streamId: bigint, authority: string, path: string): StreamConnectOutcome {
+        this.writeConnectInfo(streamId, authority, path);
+        const rc = this.dispatch(EVENT_CONNECT, streamId);
+        if (rc < 0n) return { kind: 'reject', code: decodeRejectCode(rc) };
+        this.resetEgressRing();
+        return { kind: 'accept' };
+    }
+
+    /** Fire `@close` (graceful close). */
+    onClose(streamId: bigint): bigint {
+        return this.dispatch(EVENT_CLOSE, streamId);
+    }
+
+    /** Fire `@disconnect` (abrupt teardown). */
+    onDisconnect(streamId: bigint): bigint {
+        return this.dispatch(EVENT_DISCONNECT, streamId);
+    }
+
+    /** Drive the raw-bytes `@message` bridge: write `inbound` as one DATA_RELIABLE frame into the
+     *  ingress ring, fire `@message`, then drain the egress ring (reply) or surface the reject code.
+     *  A genuine wasm trap propagates (the caller maps it to a STREAM_HOOK_TRAPPED close). */
+    onMessage(streamId: bigint, inbound: Buffer): StreamMessageOutcome {
+        if (!this.rings) {
+            throw new Error('stream box has no ring runtime; the message bridge is unavailable');
+        }
+        this.ingressWrite(inbound);
+        const ret = this.dispatch(EVENT_MESSAGE, streamId);
+        if (ret < 0n) return { kind: 'reject', code: decodeRejectCode(ret) };
+        return { kind: 'reply', frames: this.egressDrain() };
+    }
+
+    private dispatch(eventKind: number, streamId: bigint): bigint {
+        const lo = Number(streamId & 0xffff_ffffn) | 0;
+        const hi = Number((streamId >> 32n) & 0xffff_ffffn) | 0;
+        return this.exports.stream_dispatch(eventKind, lo, hi);
+    }
+
+    private static resolveRings(e: StreamExports): Rings | null {
+        if (
+            typeof e.stream_ring_offset !== 'function' ||
+            typeof e.stream_ring_capacity !== 'function' ||
+            typeof e.stream_egress_offset !== 'function' ||
+            typeof e.stream_egress_capacity !== 'function'
+        ) {
+            return null;
+        }
+        return {
+            ingressOff: e.stream_ring_offset() >>> 0,
+            ingressCap: e.stream_ring_capacity() >>> 0,
+            egressOff: e.stream_egress_offset() >>> 0,
+            egressCap: e.stream_egress_capacity() >>> 0,
+        };
+    }
+
+    private static resolveStreamInfo(e: StreamExports): StreamInfo | null {
+        if (typeof e.stream_info_offset !== 'function' || typeof e.stream_info_capacity !== 'function') {
+            return null;
+        }
+        return { offset: e.stream_info_offset() >>> 0, cap: e.stream_info_capacity() >>> 0 };
+    }
+
+    private stampRings(): void {
+        const rings = this.rings;
+        if (!rings) return;
+        this.stampOne(rings.ingressOff, rings.ingressCap);
+        this.stampOne(rings.egressOff, rings.egressCap);
+    }
+
+    private stampOne(base: number, cap: number): void {
+        const dv = new DataView(this.exports.memory.buffer);
+        dv.setUint32(base + 0, RING_MAGIC, true);
+        dv.setUint16(base + 4, RING_VERSION, true);
+        dv.setUint16(base + 6, 0, true); // flags
+        dv.setUint32(base + 8, cap, true); // capacity
+        dv.setUint32(base + RC_WRITE, 0, true);
+        dv.setUint32(base + RC_READ, 0, true);
+    }
+
+    /** Write the `@connect` info block into the guest's info region (no-op if the box carries none).
+     *  Authority + path are bounded into `[SI_BODY, cap)` - truncated to fit, never an OOB write. */
+    private writeConnectInfo(streamId: bigint, authority: string, path: string): void {
+        const info = this.streamInfo;
+        if (!info) return;
+        const base = info.offset;
+        const body = Math.max(0, info.cap - SI_BODY);
+        const authBytes = Buffer.from(authority, 'utf8');
+        const authLen = Math.min(authBytes.length, 0xffff, body);
+        const pathBytes = Buffer.from(path, 'utf8');
+        const pathLen = Math.min(pathBytes.length, 0xffff, body - authLen);
+        const dv = new DataView(this.exports.memory.buffer);
+        dv.setBigUint64(base + 0, streamId, true);
+        dv.setUint8(base + SI_TRANSPORT, SI_TRANSPORT_WEBTRANSPORT);
+        dv.setUint8(base + SI_TRANSPORT + 1, 0); // reserved
+        dv.setUint16(base + SI_AUTH_LEN, authLen, true);
+        dv.setUint16(base + SI_PATH_LEN, pathLen, true);
+        dv.setUint16(base + SI_RESERVED2, 0, true); // reserved
+        const memU8 = new Uint8Array(this.exports.memory.buffer);
+        if (authLen > 0) memU8.set(authBytes.subarray(0, authLen), base + SI_BODY);
+        if (pathLen > 0) memU8.set(pathBytes.subarray(0, pathLen), base + SI_BODY + authLen);
+    }
+
+    /** Zero the egress ring cursors, discarding any staged frames. Safe between dispatches (the guest,
+     *  the sole egress producer, is idle). */
+    private resetEgressRing(): void {
+        const rings = this.rings;
+        if (!rings) return;
+        const dv = new DataView(this.exports.memory.buffer);
+        dv.setUint32(rings.egressOff + RC_WRITE, 0, true);
+        dv.setUint32(rings.egressOff + RC_READ, 0, true);
+    }
+
+    /** Host (producer) writes ONE inbound RingFrame into the ingress ring with the drained-reset
+     *  (host owns write_cursor; reset read_cursor only when the guest has drained). */
+    private ingressWrite(inbound: Buffer): void {
+        const rings = this.rings;
+        if (!rings) throw new Error('ingressWrite: no ring runtime');
+        const { ingressOff: base, ingressCap: cap } = rings;
+        const dv = new DataView(this.exports.memory.buffer);
+        const n = inbound.length;
+        const frameLen = RING_FRAME_HEADER + n;
+        if (frameLen > cap) {
+            throw new Error(`inbound frame (${String(frameLen)} B) exceeds ingress capacity`);
+        }
+        const w0 = dv.getUint32(base + RC_WRITE, true);
+        const r0 = dv.getUint32(base + RC_READ, true);
+        let w: number;
+        if (r0 === w0) {
+            dv.setUint32(base + RC_WRITE, 0, true);
+            dv.setUint32(base + RC_READ, 0, true);
+            w = 0;
+        } else {
+            w = w0;
+        }
+        if (w + frameLen > cap) throw new Error('ingress frame would not fit (v1 is no-wrap)');
+        const f = base + RING_CTRL_BYTES + w;
+        dv.setUint8(f + 0, RING_VERSION);
+        dv.setUint8(f + 1, FRAME_TYPE_DATA_RELIABLE);
+        dv.setUint16(f + 2, 0, true); // flags
+        dv.setUint32(f + 4, n, true); // length
+        dv.setUint32(f + 8, 0, true); // msg_seq
+        if (n > 0) new Uint8Array(this.exports.memory.buffer, f + RING_FRAME_HEADER, n).set(inbound);
+        dv.setUint32(base + RC_WRITE, w + frameLen, true);
+    }
+
+    /** Host (consumer) drains every egress RingFrame the guest staged, copying each payload out and
+     *  advancing the host-owned read_cursor. The guest does the drained-reset on its next write. */
+    private egressDrain(): Buffer[] {
+        const rings = this.rings;
+        if (!rings) return [];
+        const { egressOff: base, egressCap: cap } = rings;
+        const dv = new DataView(this.exports.memory.buffer);
+        const w = dv.getUint32(base + RC_WRITE, true);
+        let r = dv.getUint32(base + RC_READ, true);
+        const frames: Buffer[] = [];
+        while (r < w) {
+            const f = base + RING_CTRL_BYTES + r;
+            if (r + RING_FRAME_HEADER > cap) break; // header must fit the frame region
+            const len = dv.getUint32(f + 4, true);
+            if (len > MAX_STREAM_FRAME_LEN) break; // over-cap frame (contained, not over-read)
+            const span = RING_FRAME_HEADER + len;
+            if (r + span > cap) break; // payload must fit
+            const payloadOff = f + RING_FRAME_HEADER;
+            frames.push(Buffer.from(new Uint8Array(this.exports.memory.buffer, payloadOff, len)));
+            r += span;
+        }
+        dv.setUint32(base + RC_READ, r, true);
+        return frames;
+    }
+}

package/src/devserver/stream/manager.ts

@@ -0,0 +1,163 @@
+/**
+ * Dev STREAM connection driver: the resident per-connection box lifecycle for the dev server, a
+ * faithful port of the edge session driver `StreamWorker` (`toil-backend` `src/wasm/stream/worker.rs`)
+ * and a sibling of `DaemonHost`. It owns one resident {@link DevStreamBox} per live connection (state
+ * persists across that connection's events) and mtime-reloads the `release-stream.wasm` artifact so a
+ * rebuild during `npm run dev` is picked up - a NEW connection then gets the new artifact while live
+ * connections keep their resident box (mirroring the edge's per-connection pinning).
+ *
+ * It mirrors `StreamWorker`'s decisions byte-for-byte where they matter in dev: `acceptUpgrade` fires
+ * `@connect` with the connect context and HONORS the guest accept/reject (the `@connect` bridge);
+ * `dispatch` returns reply frames, a guest-reject close, or a TRAP-induced `STREAM_HOOK_TRAPPED` close
+ * that discards the poisoned box. The edge-only concerns it omits (the node-mode gate, the per-node
+ * RAM admission, and gas-metered kills) do not apply to a single-process dev server: dev serves one
+ * app, has no RAM budget, and Node's `WebAssembly` has no gas middleware (a runaway loop hangs in dev,
+ * only a real trap surfaces).
+ *
+ * Transport-agnostic: the dev WebSocket endpoint calls `acceptUpgrade` on a new socket, `dispatch` per
+ * inbound frame (feeding the reply frames back out, or closing on a close code), and `close`/
+ * `disconnect` on teardown. Kept transport-free so it is unit-testable without a socket.
+ */
+
+import fs from 'node:fs';
+
+import { DevStreamBox } from './index.js';
+
+/** `0x0208 STREAM_REJECTED`: the upgrade is refused for a non-`@connect` reason (no artifact / load
+ *  failure). Matches the edge `STREAM_REJECTED`. */
+export const STREAM_REJECTED = 0x0208;
+/** `0x0200 STREAM_HOOK_TRAPPED`: a hook TRAPPED (unreachable / OOB / abort); the box is discarded and
+ *  the connection closed. Matches the edge `STREAM_HOOK_TRAPPED`. */
+export const STREAM_HOOK_TRAPPED = 0x0200;
+
+/** The outcome of an upgrade accept attempt (mirrors the edge `StreamUpgradeOutcome`). */
+export type StreamUpgradeOutcome =
+    | { readonly kind: 'accepted'; readonly streamId: bigint }
+    | { readonly kind: 'rejected'; readonly code: number };
+
+/** The outcome of driving one inbound frame (mirrors the edge `StreamDatagramOutcome`). */
+export type StreamDispatchResult =
+    | { readonly kind: 'reply'; readonly frames: Buffer[] }
+    | { readonly kind: 'close'; readonly code: number }
+    | { readonly kind: 'noConnection' };
+
+interface ResidentConn {
+    readonly box: DevStreamBox;
+    readonly streamId: bigint;
+}
+
+export class StreamDevHost {
+    private bytes: Buffer | null = null;
+    private loadedMtimeMs = -1;
+    private readonly conns = new Map<string, ResidentConn>();
+    /** Host-assigned stream id source: monotonic, never 0 (05 section 2.2). */
+    private nextStreamId = 1n;
+
+    constructor(private readonly streamWasmPath: string) {}
+
+    /** Number of live stream connections. */
+    get activeConnections(): number {
+        return this.conns.size;
+    }
+
+    /** Whether a connection is live under `connId`. */
+    has(connId: string): boolean {
+        return this.conns.has(connId);
+    }
+
+    /**
+     * Accept (or reject) an upgrade for `authority` + `path`, mirroring `StreamWorker::accept_upgrade`:
+     * (re)load the artifact on mtime change, instantiate a resident box, fire `@connect` WITH the
+     * connect context, and HONOR the guest's accept/reject. Returns the host-assigned stream id on
+     * accept, or a `0x02xx` reject code. Fails closed (no connection registered, box dropped) on a
+     * missing/unreadable artifact (`0x0208`), a `@connect` reject (the guest's code), or a load/connect
+     * trap (`0x0200`). Throws only on a duplicate `connId`.
+     */
+    acceptUpgrade(connId: string, authority: string, path: string): StreamUpgradeOutcome {
+        if (this.conns.has(connId)) throw new Error(`stream connection '${connId}' is already open`);
+        this.refresh();
+        if (!this.bytes) return { kind: 'rejected', code: STREAM_REJECTED };
+        let box: DevStreamBox;
+        try {
+            box = DevStreamBox.load(this.bytes);
+        } catch {
+            return { kind: 'rejected', code: STREAM_REJECTED };
+        }
+        const streamId = this.allocStreamId();
+        let outcome;
+        try {
+            outcome = box.onConnect(streamId, authority, path);
+        } catch {
+            return { kind: 'rejected', code: STREAM_HOOK_TRAPPED }; // @connect trapped
+        }
+        if (outcome.kind === 'reject') return { kind: 'rejected', code: outcome.code };
+        this.conns.set(connId, { box, streamId });
+        return { kind: 'accepted', streamId };
+    }
+
+    /**
+     * Drive an inbound frame into the connection's `@message` hook, mirroring
+     * `StreamWorker::dispatch_datagram`: `reply` frames (to feed back out), a guest-`reject` `close`, a
+     * TRAP-induced `close` (discarding the poisoned box), or `noConnection` for an unknown id.
+     */
+    dispatch(connId: string, inbound: Buffer): StreamDispatchResult {
+        const conn = this.conns.get(connId);
+        if (!conn) return { kind: 'noConnection' };
+        try {
+            const out = conn.box.onMessage(conn.streamId, inbound);
+            if (out.kind === 'reply') return { kind: 'reply', frames: out.frames };
+            return { kind: 'close', code: out.code };
+        } catch {
+            // The @message hook TRAPPED (a real wasm trap; dev has no gas middleware) -> discard the
+            // poisoned box + close, mirroring the edge's STREAM_HOOK_TRAPPED (05 7.4).
+            this.conns.delete(connId);
+            return { kind: 'close', code: STREAM_HOOK_TRAPPED };
+        }
+    }
+
+    /** Graceful close: fire `@close` and drop the box. No-op if the connection is gone. */
+    close(connId: string): void {
+        const conn = this.conns.get(connId);
+        if (!conn) return;
+        try {
+            conn.box.onClose(conn.streamId);
+        } catch {
+            // a trapping @close still tears the connection down
+        }
+        this.conns.delete(connId);
+    }
+
+    /** Abrupt teardown: fire `@disconnect` and drop the box. No-op if the connection is gone. */
+    disconnect(connId: string): void {
+        const conn = this.conns.get(connId);
+        if (!conn) return;
+        try {
+            conn.box.onDisconnect(conn.streamId);
+        } catch {
+            // a trapping @disconnect still tears the connection down
+        }
+        this.conns.delete(connId);
+    }
+
+    /** (Re)read the artifact bytes when its mtime changes (mirrors `DaemonHost.refresh`). Clears the
+     *  bytes when the file is missing; leaves live connections' resident boxes untouched. */
+    private refresh(): void {
+        let mtimeMs: number;
+        try {
+            mtimeMs = fs.statSync(this.streamWasmPath).mtimeMs;
+        } catch {
+            this.bytes = null;
+            this.loadedMtimeMs = -1;
+            return;
+        }
+        if (mtimeMs === this.loadedMtimeMs && this.bytes) return;
+        this.bytes = fs.readFileSync(this.streamWasmPath);
+        this.loadedMtimeMs = mtimeMs;
+    }
+
+    private allocStreamId(): bigint {
+        const id = this.nextStreamId;
+        this.nextStreamId = id + 1n;
+        return id;
+    }
+}

package/src/devserver/stream/router.ts

@@ -0,0 +1,101 @@
+/**
+ * The dev STREAM ROUTER (doc 08 sections 4.1/4.2): the `streamModule` that `wireStreams` drives. It
+ * owns the `toilstream.catalog` route table + a single resident-box {@link StreamDevHost} for the app's
+ * `release-stream.wasm`, and turns a route-matched WebSocket upgrade into a {@link StreamWsSession}
+ * driving that box. `matchRoute` (4.2) lets `wireStreams` tell a `@stream` upgrade from a Vite-HMR one;
+ * both the catalog and the box mtime-reload so a rebuild during `npm run dev` is picked up.
+ */
+
+import fs from 'node:fs';
+
+import {
+    matchStreamRoute,
+    parseStreamCatalog,
+    type StreamCatalog,
+    type StreamDef,
+} from './catalog.js';
+import { StreamDevHost } from './manager.js';
+import { StreamWsSession } from './ws.js';
+
+/** The subset of the hyper-express `Websocket` the router drives (so it is unit-testable with a mock). */
+export interface StreamWs {
+    send(data: Buffer, isBinary: boolean): void;
+    close(code: number): void;
+    on(event: 'message', cb: (message: Buffer, isBinary: boolean) => void): void;
+    on(event: 'close', cb: () => void): void;
+}
+
+/** The upgrade context `wireStreams` stamps for a stream-route upgrade (doc 08 4.1). */
+export interface StreamUpgradeContext {
+    readonly kind: 'stream';
+    readonly route: string;
+    readonly url: string;
+    readonly authority: string;
+}
+
+export class StreamRouter {
+    private catalog: StreamCatalog = new Map();
+    private catalogMtimeMs = -1;
+    private readonly host: StreamDevHost;
+    private connSeq = 0;
+
+    constructor(private readonly streamWasmPath: string) {
+        this.host = new StreamDevHost(streamWasmPath);
+        this.refreshCatalog();
+    }
+
+    /** Live stream connections (diagnostics / tests). */
+    get activeConnections(): number {
+        return this.host.activeConnections;
+    }
+
+    /** doc 08 4.2: match a request path to a `@stream` route (re-reading the catalog on a rebuild), or
+     *  `null` when it is not a stream route (the upgrade is then proxied to Vite). */
+    matchRoute(path: string): StreamDef | null {
+        this.refreshCatalog();
+        return matchStreamRoute(this.catalog, path);
+    }
+
+    /** Handle a route-matched upgrade: open a resident box (`@connect`) and bridge the socket to it
+     *  (inbound frame -> `@message` -> reply frames out; socket close -> `@close`). On a `@connect`
+     *  reject the session closes the socket and registers no box. */
+    onUpgrade(ws: StreamWs, ctx: StreamUpgradeContext): void {
+        const connId = `s${String(++this.connSeq)}`;
+        const q = ctx.url.indexOf('?');
+        const path = q >= 0 ? ctx.url.slice(0, q) : ctx.url;
+        const session = new StreamWsSession(this.host, connId, ctx.authority, path, {
+            send: (frame) => {
+                ws.send(frame, true);
+            },
+            close: (code) => {
+                ws.close(code);
+            },
+        });
+        if (!session.onOpen()) return; // rejected -> socket closed, nothing resident
+        ws.on('message', (message: Buffer) => {
+            session.onMessage(message);
+        });
+        ws.on('close', () => {
+            session.onClose();
+        });
+    }
+
+    /** (Re)read the route table when the artifact mtime changes (mirrors `DaemonHost.refresh`). */
+    private refreshCatalog(): void {
+        let mtimeMs: number;
+        try {
+            mtimeMs = fs.statSync(this.streamWasmPath).mtimeMs;
+        } catch {
+            this.catalog = new Map();
+            this.catalogMtimeMs = -1;
+            return;
+        }
+        if (mtimeMs === this.catalogMtimeMs && this.catalog.size > 0) return;
+        try {
+            this.catalog = parseStreamCatalog(fs.readFileSync(this.streamWasmPath));
+        } catch {
+            this.catalog = new Map();
+        }
+        this.catalogMtimeMs = mtimeMs;
+    }
+}

package/src/devserver/stream/wire.ts

@@ -0,0 +1,58 @@
+/**
+ * doc 08 section 4.1: the stream-aware WebSocket router that REPLACES `wireWebsocketProxy` when the dev
+ * process serves streams. It intercepts upgrades whose path matches a `@stream` route (via the
+ * {@link StreamRouter}) and drives them as resident-box connections; every OTHER upgrade (Vite HMR) is
+ * piped upstream EXACTLY as before ({@link pipeToVite}), so HMR is byte-for-byte unchanged. The branch
+ * is decided in `app.upgrade` (which stamps `ctx.kind`) and dispatched in the single catch-all
+ * `app.ws` handler, mirroring the existing proxy's structure.
+ */
+
+import { type Request, type Response, type Server, type Websocket } from '@dacely/hyper-express';
+
+import { pipeToVite, type ViteTarget } from '../http/proxy.js';
+import { type StreamRouter, type StreamUpgradeContext, type StreamWs } from './router.js';
+
+/** Whether this dev process serves streams (doc 08 4.1): `regional` / `continental` / `all`. An
+ *  L1 (`hot`) or L4 (`daemon`) dev process does NOT - it rejects/redirects the upgrade. */
+export function streamEmulationEnabled(nodeMode: string): boolean {
+    return nodeMode === 'regional' || nodeMode === 'continental' || nodeMode === 'all';
+}
+
+export function wireStreams(app: Server, vite: ViteTarget, router: StreamRouter): void {
+    app.upgrade('/*', (request: Request, response: Response) => {
+        const def = router.matchRoute(request.path);
+        if (def !== null) {
+            // A @stream route: stamp the stream context; the ws handler drives the resident box.
+            response.upgrade({
+                kind: 'stream',
+                route: def.route,
+                url: request.url,
+                authority: request.headers['host'] ?? '',
+            });
+        } else {
+            // Anything else (Vite HMR): the existing proxy context, unchanged.
+            response.upgrade({
+                kind: 'vite',
+                url: request.url,
+                protocol: request.headers['sec-websocket-protocol'] ?? '',
+            });
+        }
+    });
+
+    app.ws(
+        '/*',
+        // idle_timeout 0: the stream emulator drives liveness itself; the Vite branch never idles out.
+        { message_type: 'Buffer', idle_timeout: 0, max_payload_length: 16 * 1024 * 1024 },
+        (ws: Websocket) => {
+            const ctx = ws.context as { kind?: string };
+            if (ctx.kind === 'stream') {
+                router.onUpgrade(
+                    ws as unknown as StreamWs,
+                    ws.context as unknown as StreamUpgradeContext,
+                );
+            } else {
+                pipeToVite(ws, vite, ws.context as { url: string; protocol: string });
+            }
+        },
+    );
+}