toiljs 0.0.116 → 0.0.118

package/src/devserver/ssr.ts

@@ -1,208 +0,0 @@
-/**
- * Dev-server edge SSR: splice the guest `render` values into a route's
- * template-with-holes and serve real server-rendered HTML, mirroring the
- * production edge (`toil-backend/src/host/template/assemble.rs`).
- *
- * The templates are extracted once at dev startup against the LIVE (Vite-
- * transformed) dev shell (see `compiler/template-build.ts extractDevSsrTemplates`)
- * so the served markup boots the dev client and hydrates in place. At request
- * time the dev server runs the real `render` export (`WasmServerModule.
- * dispatchRender`), this module decodes the values envelope and splices each
- * value at its manifest-fixed offset. The hash-coherence guard the prod edge
- * enforces is skipped in dev: the guest and the template are built together
- * here, so there is no deploy skew to catch — only fail-safe envelopes (status
- * >= 500 or no slots) fall back to client rendering.
- */
-
-/** One SSR route's spliceable template + its slot insertion points. */
-export interface DevSsrTemplate {
-    pattern: string;
-    name: string;
-    tmpl: Uint8Array;
-    entries: { id: number; offset: number }[];
-    /** Optional deployed template hash. Present for built/self-host SSR, omitted in dev. */
-    hash?: Uint8Array;
-}
-
-/** A matchable SSR route. */
-export interface SsrRoute {
-    /** Matches a request pathname (no query) to this route's template. */
-    test: (pathname: string) => boolean;
-    tmpl: Uint8Array;
-    entries: { id: number; offset: number }[];
-    /** Optional deployed template hash. When present, guest values must match it. */
-    hash?: Uint8Array;
-}
-
-/** The pathname of a request URL (strip the query string). */
-export function pathnameOf(url: string): string {
-    const q = url.indexOf('?');
-    return q < 0 ? url : url.slice(0, q);
-}
-
-/** Compile a route pattern (`/hello`, `/u/:name`, `/blog/[id]`, `/files/[...path]`,
- * `/*`) to a pathname matcher. Dynamic segments match one path segment; catch-all
- * (`[...x]` / `*`) matches the rest. Trailing slashes are ignored. */
-function patternToTest(pattern: string): (pathname: string) => boolean {
-    const norm = (p: string): string => (p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p);
-    let re = '';
-    // Tokenise into literal runs and dynamic/catch-all holes.
-    let i = 0;
-    while (i < pattern.length) {
-        const ch = pattern[i];
-        if (ch === ':') {
-            // `:name` — one segment.
-            i++;
-            while (i < pattern.length && /[A-Za-z0-9_]/.test(pattern[i])) i++;
-            re += '[^/]+';
-        } else if (ch === '*') {
-            re += '.*';
-            i++;
-        } else if (ch === '[') {
-            const end = pattern.indexOf(']', i);
-            const inner = end < 0 ? '' : pattern.slice(i + 1, end);
-            re += inner.startsWith('...') ? '.*' : '[^/]+';
-            i = end < 0 ? pattern.length : end + 1;
-        } else {
-            // Literal char, regex-escaped.
-            re += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            i++;
-        }
-    }
-    const compiled = new RegExp(`^${re}$`);
-    return (pathname: string): boolean => compiled.test(norm(pathname));
-}
-
-/** Build matchable SSR routes from the extracted dev templates. */
-export function buildSsrRoutes(templates: readonly DevSsrTemplate[]): SsrRoute[] {
-    return templates.map((t) => ({
-        test: patternToTest(t.pattern),
-        tmpl: t.tmpl,
-        entries: t.entries,
-        hash: t.hash,
-    }));
-}
-
-/** A decoded guest values envelope. */
-interface DecodedValues {
-    status: number;
-    hash: Uint8Array;
-    headers: [string, string][];
-    /** Slot value bytes keyed by numeric slot id. */
-    values: Map<number, Uint8Array>;
-}
-
-/** Decode the guest values envelope (mirrors the prod host `decode_values`). All
- * fields little-endian, no padding. Returns null on a malformed/short buffer. */
-function decodeValues(buf: Uint8Array): DecodedValues | null {
-    const dv = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
-    let o = 0;
-    const need = (n: number): boolean => o + n <= buf.byteLength;
-    try {
-        if (!need(2 + 32 + 2)) return null;
-        const status = dv.getUint16(o, true);
-        o += 2;
-        const hash = buf.subarray(o, o + 32);
-        o += 32;
-        const nHeaders = dv.getUint16(o, true);
-        o += 2;
-        const headers: [string, string][] = [];
-        const dec = new TextDecoder();
-        for (let i = 0; i < nHeaders; i++) {
-            if (!need(4)) return null;
-            const nameLen = dv.getUint16(o, true);
-            const valLen = dv.getUint16(o + 2, true);
-            o += 4;
-            if (!need(nameLen + valLen)) return null;
-            const name = dec.decode(buf.subarray(o, o + nameLen));
-            o += nameLen;
-            const val = dec.decode(buf.subarray(o, o + valLen));
-            o += valLen;
-            headers.push([name, val]);
-        }
-        if (!need(2)) return null;
-        const nSlots = dv.getUint16(o, true);
-        o += 2;
-        const values = new Map<number, Uint8Array>();
-        for (let i = 0; i < nSlots; i++) {
-            if (!need(2 + 1 + 4)) return null;
-            const id = dv.getUint16(o, true);
-            o += 2;
-            o += 1; // kind (the splice is kind-agnostic; the guest pre-escaped/stamped)
-            const len = dv.getUint32(o, true);
-            o += 4;
-            if (!need(len)) return null;
-            values.set(id, buf.subarray(o, o + len));
-            o += len;
-        }
-        return { status, hash, headers, values };
-    } catch {
-        return null;
-    }
-}
-
-function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
-    if (a.byteLength !== b.byteLength) return false;
-    for (let i = 0; i < a.byteLength; i++) {
-        if (a[i] !== b[i]) return false;
-    }
-    return true;
-}
-
-/** Splice ascending-offset inserts into the template (mirrors the host `assemble`). */
-function splice(tmpl: Uint8Array, inserts: { offset: number; value: Uint8Array }[]): Uint8Array {
-    const parts: Uint8Array[] = [];
-    let prev = 0;
-    for (const ins of inserts) {
-        if (ins.offset > prev) parts.push(tmpl.subarray(prev, ins.offset));
-        if (ins.value.length > 0) parts.push(ins.value);
-        prev = ins.offset;
-    }
-    if (tmpl.length > prev) parts.push(tmpl.subarray(prev));
-    return Buffer.concat(parts.map((p) => Buffer.from(p.buffer, p.byteOffset, p.byteLength)));
-}
-
-/** A spliced SSR response. */
-export interface SsrResult {
-    status: number;
-    headers: [string, string][];
-    html: Uint8Array;
-}
-
-/** The internal header a guest's `SlotValues.setTitle` rides in: the host splices its value into the
- * document `<title>` and strips it, so a per-request title never reaches the client as a real header. */
-const SSR_TITLE_HEADER = 'x-toil-ssr-title';
-
-/** Replace the document `<title>` content (the guest set a per-request title; the value is already
- * React-escaped). Mirrors the host `assemble` so dev and prod agree. */
-function replaceTitle(html: Uint8Array, title: string): Uint8Array {
-    const out = new TextDecoder()
-        .decode(html)
-        .replace(/<title>[\s\S]*?<\/title>/i, `<title>${title}</title>`);
-    return new TextEncoder().encode(out);
-}
-
-/**
- * Decode the guest envelope and splice it into `route`'s template. Returns null
- * to fall back to client rendering: a fail-safe envelope (status >= 500, e.g. no
- * renderer matched), no slots, or a decode error.
- */
-export function assembleSsr(route: SsrRoute, envelope: Uint8Array): SsrResult | null {
-    const decoded = decodeValues(envelope);
-    if (decoded === null) return null;
-    if (decoded.status >= 500 || decoded.values.size === 0) return null;
-    if (route.hash !== undefined && !sameBytes(decoded.hash, route.hash)) return null;
-    const inserts = route.entries
-        .map((e) => ({ offset: e.offset, value: decoded.values.get(e.id) ?? new Uint8Array(0) }))
-        .sort((a, b) => a.offset - b.offset);
-    let html = splice(route.tmpl, inserts);
-    // A guest-set per-request <title> (SlotValues.setTitle) rides in an internal header: splice it into
-    // the <title> and strip the header so it never reaches the client.
-    let headers = decoded.headers;
-    const ti = headers.findIndex(([k]) => k.toLowerCase() === SSR_TITLE_HEADER);
-    if (ti >= 0) {
-        html = replaceTitle(html, headers[ti][1]);
-        headers = headers.filter((_, i) => i !== ti);
-    }
-    return { status: decoded.status, headers, html };
-}

package/src/devserver/stream/catalog.ts

@@ -1,106 +0,0 @@
-/**
- * Parse a compiled HOT server wasm's `toilstream.catalog` custom section into the dev stream router's
- * route table (doc 08 section 3.1; emitted by the toilscript hot pass per RECONCILIATION Part 5 when
- * any `@stream` class exists). The dev router keys on `route` (the `@stream` class's fixed mount path)
- * to intercept matching WebSocket upgrades (section 4.1/4.2) and ignore the rest (Vite HMR).
- *
- * Byte layout (Part 5, all little-endian; mirrors the toilscript emitter + the edge decoder):
- *
- *   u16 format_version (= 1)
- *   u16 n_streams
- *   per stream:
- *     str name                     (the @stream class name)
- *     str route                    (the mount path, e.g. "/echo")
- *     u8  hook_presence_bitmask    (bit0 connect, bit1 message, bit2 close, bit3 disconnect)
- *     u8  declared_scope           (0 = L2 regional, 1 = L3 continental)
- *     u8  message_mode             (0 = raw bytes default, 1 = @data-typed)
- *     u32 max_frame_bytes
- *     u32 ingress_ring_bytes
- *     u32 message_value_data_id    (0 when message_mode = 0)
- *     u32 message_schema_version   (0 when message_mode = 0)
- *     u16 stream_index
- *
- * Fails closed via `DataReader.ok`: a short read mid-record stops the loop and yields the cleanly
- * decoded prefix; an absent/unparseable section yields an empty map (the dev router serves no stream).
- */
-
-import { DataReader } from 'toiljs/io';
-
-import { customSection } from '../wasm/sections.js';
-
-/** One `@stream` class's catalog entry (doc 08 section 3.1). */
-export interface StreamDef {
-    readonly name: string;
-    readonly route: string;
-    readonly hooks: {
-        readonly connect: boolean;
-        readonly message: boolean;
-        readonly close: boolean;
-        readonly disconnect: boolean;
-    };
-    readonly scope: 'regional' | 'continental';
-    readonly messageMode: 'raw' | 'data';
-    readonly maxFrameBytes: number;
-    readonly ingressRingBytes: number;
-    readonly messageValueDataId: number;
-    readonly messageSchemaVersion: number;
-    readonly streamIndex: number;
-}
-
-/** The dev router's route table, keyed by the `@stream` mount path. */
-export type StreamCatalog = Map<string, StreamDef>;
-
-/** Parse `toilstream.catalog` into a route table. Absent/unparseable -> empty (serve no stream). */
-export function parseStreamCatalog(wasm: Buffer): StreamCatalog {
-    const out: StreamCatalog = new Map();
-    let sec: Buffer | null;
-    try {
-        sec = customSection(wasm, 'toilstream.catalog');
-    } catch {
-        return out;
-    }
-    if (sec === null) return out;
-    const r = new DataReader(sec);
-    r.readU16(); // format_version
-    const n = r.readU16();
-    for (let i = 0; i < n && r.ok; i++) {
-        const name = r.readString();
-        const route = r.readString();
-        const bits = r.readU8();
-        const scope = r.readU8() === 1 ? 'continental' : 'regional';
-        const messageMode = r.readU8() === 1 ? 'data' : 'raw';
-        const maxFrameBytes = r.readU32();
-        const ingressRingBytes = r.readU32();
-        const messageValueDataId = r.readU32();
-        const messageSchemaVersion = r.readU32();
-        const streamIndex = r.readU16();
-        if (!r.ok) break;
-        out.set(route, {
-            name,
-            route,
-            hooks: {
-                connect: (bits & 1) !== 0,
-                message: (bits & 2) !== 0,
-                close: (bits & 4) !== 0,
-                disconnect: (bits & 8) !== 0,
-            },
-            scope,
-            messageMode,
-            maxFrameBytes,
-            ingressRingBytes,
-            messageValueDataId,
-            messageSchemaVersion,
-            streamIndex,
-        });
-    }
-    return out;
-}
-
-/** Exact-path route match (doc 08 section 4.2): strip the query string, then look the path up in the
- *  catalog. Returns the matched `@stream` def, or `null` when the path is not a stream route (the dev
- *  router then proxies the upgrade to Vite). */
-export function matchStreamRoute(catalog: StreamCatalog, path: string): StreamDef | null {
-    const q = path.indexOf('?');
-    const exact = q >= 0 ? path.slice(0, q) : path;
-    return catalog.get(exact) ?? null;
-}

package/src/devserver/stream/host.ts

@@ -1,42 +0,0 @@
-/**
- * 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

@@ -1,301 +0,0 @@
-/**
- * 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: accepted/rejected plus any immediate frames staged during the hook. */
-export type StreamConnectOutcome =
-    | { readonly kind: 'accept'; readonly initialEgress: Buffer[] }
-    | { readonly kind: 'reject'; readonly code: number; readonly initialEgress: Buffer[] };
-
-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' || !surface.flags.stream) {
-            throw new Error('stream box requires a hot stream 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`, decode the `StreamOutbound` accept/reject, and
-     * drain any staged egress as initial frames. 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);
-        const initialEgress = this.egressDrain();
-        if (rc < 0n) return { kind: 'reject', code: decodeRejectCode(rc), initialEgress };
-        return { kind: 'accept', initialEgress };
-    }
-
-    /** 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);
-    }
-
-    /** 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;
-    }
-}