@irisrun/channel-rest 0.1.0

package/dist/events.d.ts

@@ -0,0 +1,20 @@
+import type { Json, TurnOutcome } from "@irisrun/core";
+export type StreamEvent = {
+    type: "record";
+    record: Json;
+} | {
+    type: "delta";
+    text: string;
+} | {
+    type: "outcome";
+    sessionId: string;
+    status: TurnOutcome<Json>["status"];
+    output?: Json;
+    wait?: Json;
+    current?: number;
+    continuationToken?: string;
+} | {
+    type: "error";
+    message: string;
+};
+export declare function toOutcomeEvent<S extends Json>(sessionId: string, outcome: TurnOutcome<S>, token?: string): StreamEvent;

package/dist/events.js

@@ -0,0 +1,18 @@
+// Mirrors the buffered `turnResponse()` mapping, plus the rotated token. `token`
+// is omitted only when the channel did not (re)issue one.
+export function toOutcomeEvent(sessionId, outcome, token) {
+    const ev = {
+        type: "outcome",
+        sessionId,
+        status: outcome.status,
+    };
+    if (outcome.status === "finished" && outcome.output !== undefined)
+        ev.output = outcome.output;
+    if (outcome.status === "parked")
+        ev.wait = outcome.wait;
+    if (outcome.status === "contended")
+        ev.current = outcome.current;
+    if (token !== undefined)
+        ev.continuationToken = token;
+    return ev;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export declare const PACKAGE = "@irisrun/channel-rest";
+export { makeRestChannel } from "./server.js";
+export type { RestChannel, RestChannelOptions, TurnInputs } from "./server.js";
+export type { StreamEvent } from "./events.js";
+export { toOutcomeEvent } from "./events.js";
+export { acceptKey, decodeFrames, encodeTextFrame, encodeCloseFrame, encodePongFrame, makeWsFramer, } from "./ws.js";
+export type { WsFrame, WsFramerCallbacks } from "./ws.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// @irisrun/channel-rest — public surface (host; in-process node:http REST channel).
+export const PACKAGE = "@irisrun/channel-rest";
+export { makeRestChannel } from "./server.js";
+export { toOutcomeEvent } from "./events.js";
+export { acceptKey, decodeFrames, encodeTextFrame, encodeCloseFrame, encodePongFrame, makeWsFramer, } from "./ws.js";

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+import { type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { type HostAdapter } from "@irisrun/host";
+import type { Program, PerformerRegistry, LogicalClock, Json } from "@irisrun/core";
+import { type StreamEvent } from "./events.js";
+export interface TurnInputs<S extends Json> {
+    program: Program<S>;
+    performers: PerformerRegistry;
+    clock: LogicalClock;
+    defDigest: string;
+    snapshotThreshold?: number;
+    holderId?: string;
+}
+export interface RestChannelOptions<S extends Json> {
+    adapter: HostAdapter;
+    makeTurnInputs: (sessionId: string, body: Json, emit?: (ev: StreamEvent) => void) => TurnInputs<S> | Promise<TurnInputs<S>>;
+    mintSessionId?: () => string;
+    mintToken?: () => string;
+    webHandler?: (req: IncomingMessage, res: ServerResponse) => boolean;
+}
+export interface RestChannel {
+    server: Server;
+    listen(port?: number, host?: string): Promise<string>;
+    close(): Promise<void>;
+}
+export declare function makeRestChannel<S extends Json>(opts: RestChannelOptions<S>): RestChannel;

package/dist/server.js

@@ -0,0 +1,316 @@
+// makeRestChannel (ADR-0009, Spec 05 B3): an in-process node:http server speaking
+// the TWO-IDENTIFIER protocol. The channel MINTS the sessionId and OWNS/ISSUES the
+// continuationToken — the client presents it on the next call. Every turn ROTATES
+// the token; a missing/stale/malformed token is refused with a LOUD 4xx, never a
+// silent 200 (no-silent-failures). In-process for the suite; a real external HTTP
+// deploy is a manual smoke. Host-side (node:http + node:crypto); core stays pure.
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { runTurnOn } from "@irisrun/host";
+import { toOutcomeEvent } from "./events.js";
+import { wantsStream, openSse } from "./sse.js";
+import { writeHandshake, refuseUpgrade, makeWsFramer, encodeTextFrame, encodeCloseFrame, encodePongFrame, } from "./ws.js";
+const SESSION_MESSAGE = /^\/v1\/session\/([^/]+)\/message$/;
+function send(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(text);
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (raw === "")
+        return { ok: true, body: {} }; // an empty body is the empty object
+    try {
+        return { ok: true, body: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false }; // malformed JSON → loud 4xx upstream
+    }
+}
+function turnResponse(sessionId, token, outcome) {
+    const base = { sessionId, continuationToken: token, status: outcome.status };
+    if (outcome.status === "finished" && outcome.output !== undefined)
+        base.output = outcome.output;
+    if (outcome.status === "parked")
+        base.wait = outcome.wait;
+    if (outcome.status === "contended")
+        base.current = outcome.current;
+    return base;
+}
+export function makeRestChannel(opts) {
+    const mintSessionId = opts.mintSessionId ?? (() => randomUUID());
+    const mintToken = opts.mintToken ?? (() => randomUUID());
+    // The channel OWNS the current continuationToken per session (in-process here;
+    // a real deploy would persist it). It rotates on every committed turn.
+    const tokens = new Map();
+    // Sessions with a turn in flight — enforces the token's SINGLE-USE invariant
+    // under concurrency (the token rotates only after the turn commits, so without
+    // this a second concurrent request presenting the same valid token would slip
+    // past the check before rotation; ADR-0009 advertises single-use, so we honor it).
+    const inFlight = new Set();
+    // Rotate the continuationToken ONLY on a COMMITTED turn (single-use). A
+    // `contended` turn journaled nothing — the lease was held elsewhere — so the
+    // prior token stays valid and the client retries it (no rotation). A START turn
+    // (priorToken === null) always issues a fresh token. Used by all three paths
+    // (buffered/SSE/WS) so token discipline is identical across them.
+    const issueToken = (sessionId, outcome, priorToken) => {
+        if (priorToken !== null && outcome.status === "contended")
+            return priorToken;
+        const token = mintToken();
+        tokens.set(sessionId, token);
+        return token;
+    };
+    const runTurn = async (sessionId, body, emit) => {
+        const inputs = await opts.makeTurnInputs(sessionId, body, emit);
+        // onRecord is the per-REQUEST journal-timeline tap (only on a streaming
+        // request). It rides RunTurnOnOptions, NOT TurnInputs (per-session-static).
+        const onRecord = emit
+            ? (r) => emit({ type: "record", record: r })
+            : undefined;
+        return runTurnOn(opts.adapter, {
+            sessionId,
+            ...inputs,
+            ...(onRecord ? { onRecord } : {}),
+        });
+    };
+    // Drive one turn into an SSE stream: records + deltas, then a terminal outcome
+    // carrying the rotated token. Validation (loud 4xx) already ran in the handler
+    // BEFORE this opens the stream, so a refusal is never a half-open SSE.
+    const streamTurn = async (res, sessionId, body, priorToken) => {
+        const sse = openSse(res);
+        const emit = (ev) => sse.emit(ev);
+        let outcome;
+        try {
+            outcome = await runTurn(sessionId, body, emit);
+        }
+        catch (err) {
+            // The turn threw AFTER the stream opened — surface it in-band, loudly.
+            emit({ type: "error", message: err instanceof Error ? err.message : String(err) });
+            sse.end();
+            return;
+        }
+        emit(toOutcomeEvent(sessionId, outcome, issueToken(sessionId, outcome, priorToken)));
+        sse.end();
+    };
+    const handler = async (req, res) => {
+        const rawUrl = req.url ?? "";
+        const url = rawUrl.split("?")[0];
+        const stream = wantsStream(req, rawUrl);
+        // The optional web channel claims its GET routes BEFORE the POST-only guard.
+        // It returns false for non-asset paths, so `/v1/*` POST falls through unchanged.
+        if (opts.webHandler && opts.webHandler(req, res))
+            return;
+        if (req.method !== "POST") {
+            send(res, 405, { error: `method ${req.method} not allowed` });
+            return;
+        }
+        const parsed = await readBody(req);
+        if (!parsed.ok) {
+            send(res, 400, { error: "malformed JSON body" });
+            return;
+        }
+        const body = parsed.body;
+        // --- start: MINT a session + the first continuationToken --------------
+        if (url === "/v1/session") {
+            const sessionId = mintSessionId();
+            if (stream) {
+                await streamTurn(res, sessionId, body, null); // START → always issues a fresh token
+                return;
+            }
+            const outcome = await runTurn(sessionId, body);
+            const token = issueToken(sessionId, outcome, null);
+            send(res, 200, turnResponse(sessionId, token, outcome));
+            return;
+        }
+        // --- continue: REQUIRE the matching token, then ROTATE it -------------
+        const m = SESSION_MESSAGE.exec(url);
+        if (m) {
+            const sessionId = decodeURIComponent(m[1]);
+            if (!tokens.has(sessionId)) {
+                send(res, 404, { error: `unknown session '${sessionId}'` });
+                return;
+            }
+            const headerToken = req.headers["x-continuation-token"];
+            const presented = typeof body.continuationToken === "string"
+                ? body.continuationToken
+                : typeof headerToken === "string"
+                    ? headerToken
+                    : null;
+            if (presented === null || presented === "") {
+                send(res, 400, { error: "missing continuationToken" });
+                return;
+            }
+            if (presented !== tokens.get(sessionId)) {
+                send(res, 409, { error: "stale or invalid continuationToken" });
+                return;
+            }
+            // The token check above and this in-flight claim run in ONE event-loop
+            // callback with no interleaving, so a SECOND concurrent request presenting
+            // the same valid token is refused HERE — before the token rotates — instead
+            // of slipping past the check. The flag also keeps the token usable across a
+            // failed turn: we rotate ONLY on success, in the finally we just release.
+            if (inFlight.has(sessionId)) {
+                send(res, 409, { error: "a turn is already in flight for this session" });
+                return;
+            }
+            inFlight.add(sessionId);
+            try {
+                if (stream) {
+                    await streamTurn(res, sessionId, body, presented); // CONTINUE → rotate only if committed
+                }
+                else {
+                    const outcome = await runTurn(sessionId, body);
+                    const next = issueToken(sessionId, outcome, presented);
+                    send(res, 200, turnResponse(sessionId, next, outcome));
+                }
+            }
+            finally {
+                inFlight.delete(sessionId);
+            }
+            return;
+        }
+        send(res, 404, { error: `no route for ${url}` });
+    };
+    // A held WS connection drives the SAME two-identifier protocol over frames: the
+    // first frame with no token STARTS (mints a session); a frame with a token
+    // CONTINUES the connection's bound session. The token is read FRESH from the
+    // shared Map each turn (never cached), so it stays coherent with the REST/SSE
+    // paths' single-use rotation. (Cross-protocol concurrent driving of one session
+    // is unsupported but still SAFE — the shared inFlight Set prevents double commit.)
+    const runWsConnection = (socket, head) => {
+        let sessionId = null;
+        const sendEvent = (ev) => {
+            try {
+                socket.write(encodeTextFrame(JSON.stringify(ev)));
+            }
+            catch {
+                /* socket gone */
+            }
+        };
+        const handleMessage = async (text) => {
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                sendEvent({ type: "error", message: "malformed JSON frame" });
+                return;
+            }
+            const presented = typeof body.continuationToken === "string"
+                ? body.continuationToken
+                : null;
+            if (sessionId === null) {
+                if (presented !== null) {
+                    // a fresh connection can only START (no token); continuation needs a
+                    // session this connection already minted.
+                    sendEvent({ type: "error", message: "present no continuationToken to start a session" });
+                    return;
+                }
+                sessionId = mintSessionId();
+            }
+            else if (presented !== null) {
+                if (presented !== tokens.get(sessionId)) {
+                    sendEvent({ type: "error", message: "stale or invalid continuationToken" });
+                    return;
+                }
+            }
+            if (inFlight.has(sessionId)) {
+                sendEvent({ type: "error", message: "a turn is already in flight for this session" });
+                return;
+            }
+            const priorToken = tokens.get(sessionId) ?? null; // null on this connection's START turn
+            inFlight.add(sessionId);
+            try {
+                const outcome = await runTurn(sessionId, body, sendEvent);
+                sendEvent(toOutcomeEvent(sessionId, outcome, issueToken(sessionId, outcome, priorToken)));
+            }
+            catch (err) {
+                sendEvent({ type: "error", message: err instanceof Error ? err.message : String(err) });
+            }
+            finally {
+                inFlight.delete(sessionId);
+            }
+        };
+        const feed = makeWsFramer({
+            onText: (t) => {
+                void handleMessage(t);
+            },
+            onPing: (p) => {
+                try {
+                    socket.write(encodePongFrame(p));
+                }
+                catch {
+                    /* gone */
+                }
+            },
+            onClose: () => {
+                try {
+                    socket.write(encodeCloseFrame());
+                }
+                catch {
+                    /* gone */
+                }
+                socket.end();
+            },
+        });
+        if (head && head.length > 0)
+            feed(head);
+        socket.on("data", (chunk) => feed(chunk));
+        socket.on("error", () => {
+            /* a dropped connection is not a server error */
+        });
+    };
+    const server = createServer((req, res) => {
+        handler(req, res).catch((err) => {
+            // Never a silent 200: an internal failure surfaces as a loud 5xx.
+            const message = err instanceof Error ? err.message : String(err);
+            if (!res.headersSent)
+                send(res, 500, { error: `internal error: ${message}` });
+            else
+                res.end();
+        });
+    });
+    // WebSocket upgrade (ADR-0008 capability gate): a host that does not advertise
+    // `websockets` is refused LOUDLY (426, no 101) — never silently downgraded.
+    server.on("upgrade", (req, socket, head) => {
+        if (opts.adapter.capabilities.websockets !== true) {
+            refuseUpgrade(socket, "426 Upgrade Required");
+            return;
+        }
+        if ((req.url ?? "").split("?")[0] !== "/v1/ws") {
+            refuseUpgrade(socket, "404 Not Found");
+            return;
+        }
+        const key = req.headers["sec-websocket-key"];
+        const upgrade = String(req.headers["upgrade"] ?? "").toLowerCase();
+        if (upgrade !== "websocket" || typeof key !== "string") {
+            refuseUpgrade(socket, "400 Bad Request");
+            return;
+        }
+        writeHandshake(socket, key);
+        runWsConnection(socket, head);
+    });
+    return {
+        server,
+        listen(port = 0, host = "127.0.0.1") {
+            return new Promise((resolve) => {
+                server.listen(port, host, () => {
+                    const addr = server.address();
+                    const p = typeof addr === "object" && addr ? addr.port : port;
+                    // a wildcard bind (0.0.0.0/::) is reachable externally; the returned URL
+                    // uses loopback so a local client can always connect.
+                    const connectHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+                    resolve(`http://${connectHost}:${p}`);
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}

package/dist/sse.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { StreamEvent } from "./events.js";
+export declare function wantsStream(req: IncomingMessage, rawUrl: string): boolean;
+export interface SseWriter {
+    emit(ev: StreamEvent): void;
+    end(): void;
+    closed(): boolean;
+}
+export declare function openSse(res: ServerResponse): SseWriter;

package/dist/sse.js

@@ -0,0 +1,44 @@
+export function wantsStream(req, rawUrl) {
+    const accept = req.headers["accept"];
+    if (typeof accept === "string" && accept.includes("text/event-stream"))
+        return true;
+    const q = rawUrl.split("?")[1] ?? "";
+    return /(^|&)stream=1(&|$)/.test(q);
+}
+export function openSse(res) {
+    res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+    });
+    let closed = false;
+    res.on("close", () => {
+        closed = true;
+    });
+    return {
+        emit(ev) {
+            if (closed)
+                return;
+            try {
+                res.write(`event: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`);
+            }
+            catch {
+                closed = true; // socket gone — stop writing, never throw
+            }
+        },
+        end() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                res.end();
+            }
+            catch {
+                /* already gone */
+            }
+        },
+        closed() {
+            return closed;
+        },
+    };
+}

package/dist/ws.d.ts

@@ -0,0 +1,38 @@
+import type { Duplex } from "node:stream";
+export declare const MAX_WS_FRAME: number;
+/** RFC 6455 accept token: base64( sha1( Sec-WebSocket-Key + magic GUID ) ). */
+export declare function acceptKey(secWebSocketKey: string): string;
+export declare function writeHandshake(socket: Duplex, key: string): void;
+export declare function refuseUpgrade(socket: Duplex, statusLine: string): void;
+export interface WsFrame {
+    fin: boolean;
+    opcode: number;
+    masked: boolean;
+    payload: Buffer;
+}
+/**
+ * Parse zero or more COMPLETE frames from `buf`; return them plus the unconsumed
+ * tail (a partial frame is left for the next chunk). Client frames are masked; we
+ * unmask. Handles 7-bit, 16-bit (126), and 64-bit (127) payload lengths.
+ */
+export declare function decodeFrames(buf: Buffer): {
+    frames: WsFrame[];
+    rest: Buffer;
+};
+/** Server→client TEXT frame (FIN=1, opcode 0x1, unmasked). */
+export declare function encodeTextFrame(text: string): Buffer;
+/** Server close frame (FIN=1, opcode 0x8, 2-byte status code). */
+export declare function encodeCloseFrame(code?: number): Buffer;
+/** Server pong frame (FIN=1, opcode 0xA), echoing the ping payload. */
+export declare function encodePongFrame(payload: Buffer): Buffer;
+export interface WsFramerCallbacks {
+    onText: (text: string) => void;
+    onPing: (payload: Buffer) => void;
+    onClose: () => void;
+}
+/**
+ * A stateful chunk feeder: buffers partial frames across `data` events, reassembles
+ * a fragmented text message (text frame fin=0 then continuation frames), and routes
+ * control frames. Returns a `feed(chunk)` function. Unit-testable in isolation.
+ */
+export declare function makeWsFramer(cb: WsFramerCallbacks): (chunk: Buffer) => void;

package/dist/ws.js

@@ -0,0 +1,191 @@
+// Hand-rolled, zero-dep WebSocket (RFC 6455) for the streaming channel
+// (serve-streaming Task 5). Node 24 ships a WebSocket CLIENT but no SERVER, and
+// Iris has zero runtime deps — so we implement the handshake (node:crypto SHA-1)
+// and a minimal text-frame codec here, consistent with the repo's hand-rolled
+// MCP/gRPC/OCI protocols. Text frames only; ping/pong/close handled; client→server
+// frames are masked (per spec) and unmasked here; server→client frames are
+// unmasked. permessage-deflate is NOT negotiated (the handshake never echoes
+// Sec-WebSocket-Extensions), so the built-in client sends raw frames. Host-side.
+import { createHash } from "node:crypto";
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+// Hard cap on a single frame's declared payload (turn-request JSON is tiny). A
+// hostile client could otherwise declare a 64-bit length and dribble bytes,
+// growing the reassembly buffer without bound (DoS). decodeFrames THROWS on an
+// over-cap declaration so the connection is closed loudly rather than OOM'd.
+export const MAX_WS_FRAME = 4 * 1024 * 1024; // 4 MiB
+/** RFC 6455 accept token: base64( sha1( Sec-WebSocket-Key + magic GUID ) ). */
+export function acceptKey(secWebSocketKey) {
+    return createHash("sha1").update(secWebSocketKey + WS_GUID).digest("base64");
+}
+export function writeHandshake(socket, key) {
+    socket.write("HTTP/1.1 101 Switching Protocols\r\n" +
+        "Upgrade: websocket\r\n" +
+        "Connection: Upgrade\r\n" +
+        `Sec-WebSocket-Accept: ${acceptKey(key)}\r\n` +
+        "\r\n");
+}
+export function refuseUpgrade(socket, statusLine) {
+    try {
+        socket.write(`HTTP/1.1 ${statusLine}\r\nConnection: close\r\n\r\n`);
+    }
+    catch {
+        /* socket already gone */
+    }
+    socket.destroy();
+}
+/**
+ * Parse zero or more COMPLETE frames from `buf`; return them plus the unconsumed
+ * tail (a partial frame is left for the next chunk). Client frames are masked; we
+ * unmask. Handles 7-bit, 16-bit (126), and 64-bit (127) payload lengths.
+ */
+export function decodeFrames(buf) {
+    const frames = [];
+    let offset = 0;
+    while (offset + 2 <= buf.length) {
+        const b0 = buf[offset];
+        const b1 = buf[offset + 1];
+        const fin = (b0 & 0x80) !== 0;
+        const opcode = b0 & 0x0f;
+        const masked = (b1 & 0x80) !== 0;
+        let len = b1 & 0x7f;
+        let p = offset + 2;
+        if (len === 126) {
+            if (p + 2 > buf.length)
+                break;
+            len = buf.readUInt16BE(p);
+            p += 2;
+        }
+        else if (len === 127) {
+            // 64-bit length branch — kept for spec correctness even though the built-in
+            // client uses minimal encoding (Iris memory: don't drop it as "dead code").
+            if (p + 8 > buf.length)
+                break;
+            const big = buf.readBigUInt64BE(p);
+            p += 8;
+            if (big > BigInt(MAX_WS_FRAME)) {
+                throw new RangeError(`ws frame too large: ${big} > ${MAX_WS_FRAME}`);
+            }
+            len = Number(big);
+        }
+        // Reject an over-cap declaration BEFORE allocating/awaiting the payload (DoS guard).
+        if (len > MAX_WS_FRAME)
+            throw new RangeError(`ws frame too large: ${len} > ${MAX_WS_FRAME}`);
+        let maskKey = null;
+        if (masked) {
+            if (p + 4 > buf.length)
+                break;
+            maskKey = buf.subarray(p, p + 4);
+            p += 4;
+        }
+        if (p + len > buf.length)
+            break; // incomplete payload — wait for more bytes
+        let payload;
+        if (maskKey) {
+            payload = Buffer.allocUnsafe(len);
+            for (let i = 0; i < len; i++)
+                payload[i] = buf[p + i] ^ maskKey[i & 3];
+        }
+        else {
+            payload = Buffer.from(buf.subarray(p, p + len)); // copy out of the shared buffer
+        }
+        frames.push({ fin, opcode, masked, payload });
+        offset = p + len;
+    }
+    return { frames, rest: buf.subarray(offset) };
+}
+/** Server→client TEXT frame (FIN=1, opcode 0x1, unmasked). */
+export function encodeTextFrame(text) {
+    const payload = Buffer.from(text, "utf8");
+    const len = payload.length;
+    let header;
+    if (len < 126) {
+        header = Buffer.from([0x81, len]);
+    }
+    else if (len < 65536) {
+        header = Buffer.allocUnsafe(4);
+        header[0] = 0x81;
+        header[1] = 126;
+        header.writeUInt16BE(len, 2);
+    }
+    else {
+        header = Buffer.allocUnsafe(10);
+        header[0] = 0x81;
+        header[1] = 127;
+        header.writeBigUInt64BE(BigInt(len), 2);
+    }
+    return Buffer.concat([header, payload]);
+}
+/** Server close frame (FIN=1, opcode 0x8, 2-byte status code). */
+export function encodeCloseFrame(code = 1000) {
+    const body = Buffer.allocUnsafe(2);
+    body.writeUInt16BE(code, 0);
+    return Buffer.concat([Buffer.from([0x88, 2]), body]);
+}
+/** Server pong frame (FIN=1, opcode 0xA), echoing the ping payload. */
+export function encodePongFrame(payload) {
+    const len = Math.min(payload.length, 125); // control frames carry < 126 bytes
+    return Buffer.concat([Buffer.from([0x8a, len]), payload.subarray(0, len)]);
+}
+/**
+ * A stateful chunk feeder: buffers partial frames across `data` events, reassembles
+ * a fragmented text message (text frame fin=0 then continuation frames), and routes
+ * control frames. Returns a `feed(chunk)` function. Unit-testable in isolation.
+ */
+export function makeWsFramer(cb) {
+    let buf = Buffer.alloc(0); // annotated: decodeFrames' tail is Buffer<ArrayBufferLike>
+    let fragData = [];
+    let fragging = false;
+    return (chunk) => {
+        buf = Buffer.concat([buf, chunk]);
+        let frames;
+        let rest;
+        try {
+            ({ frames, rest } = decodeFrames(buf));
+        }
+        catch {
+            // over-cap frame (DoS guard) or malformed framing → close loudly, drop buffer
+            buf = Buffer.alloc(0);
+            cb.onClose();
+            return;
+        }
+        buf = rest;
+        for (const f of frames) {
+            // RFC 6455 §5.1: a server MUST fail the connection on an unmasked client frame.
+            if (!f.masked) {
+                cb.onClose();
+                return;
+            }
+            switch (f.opcode) {
+                case 0x8: // close
+                    cb.onClose();
+                    break;
+                case 0x9: // ping
+                    cb.onPing(f.payload);
+                    break;
+                case 0xa: // pong — ignore
+                    break;
+                case 0x1: // text (possibly fragmented)
+                    fragData = [f.payload];
+                    fragging = true;
+                    if (f.fin) {
+                        cb.onText(Buffer.concat(fragData).toString("utf8"));
+                        fragData = [];
+                        fragging = false;
+                    }
+                    break;
+                case 0x0: // continuation
+                    if (fragging) {
+                        fragData.push(f.payload);
+                        if (f.fin) {
+                            cb.onText(Buffer.concat(fragData).toString("utf8"));
+                            fragData = [];
+                            fragging = false;
+                        }
+                    }
+                    break;
+                default:
+                    break; // unknown opcode — ignore
+            }
+        }
+    };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@irisrun/channel-rest",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Iris in-process REST channel (ADR-0009) over node:http — the two-identifier protocol: the channel MINTS sessionId and OWNS/ISSUES the continuationToken; every turn rotates the token, and a missing/stale/malformed token is refused with a loud 4xx (never a silent 200). A real external HTTP deploy is a manual smoke.",
+  "exports": {
+    ".": {
+      "iris-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@irisrun/core": "^0.1.0",
+    "@irisrun/host": "^0.1.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xoai/iris.git",
+    "directory": "packages/channel-rest"
+  },
+  "homepage": "https://github.com/xoai/iris#readme",
+  "files": [
+    "dist"
+  ]
+}