@dormer/node-runtime 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@dormer/node-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Dormer Node.js side: host channel, router, streams, lifecycle plumbing",
+  "type": "module",
+  "license": "Apache-2.0 OR MIT",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@dormer/ipc": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veerareddyvishal144/dormer.git",
+    "directory": "runtime/node-runtime"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,392 @@
+// Frame channels: the host channel (inherited descriptor, HELLO/WELCOME, heartbeat, shutdown) and
+// the shared request/response/stream machinery that worker links reuse over MessagePorts.
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import net from "node:net";
+import {
+  FrameDecoder, FrameType, PROTO_VERSION, encodeFrame, msgpackFrame, binFrame, makeFrame, creditFrame, parseCredit,
+  unpack, type Frame, type Hello, type Welcome, type Req, type Res, type Err, type Evt, type StreamEnd,
+} from "@dormer/ipc";
+
+export interface IncomingRequest { route: number; id: number; m: string; a: unknown[]; signal: AbortSignal }
+export interface IncomingEvent { route: number; ch: string; data: unknown }
+
+/** Stable wire shape of a DormerError (`JSON.stringify(err)`), see `@dormer/types` `DormerErrorJSON`. */
+export interface DormerErrorJSON { name: "DormerError"; code: string; message: string; data?: unknown; retry: boolean }
+
+export class DormerError extends Error {
+  code: string; data?: unknown; retry: boolean;
+  constructor(code: string, message: string, data?: unknown, retry = false) {
+    super(message); this.name = "DormerError"; this.code = code; this.data = data; this.retry = retry;
+  }
+  toJSON(): DormerErrorJSON {
+    const j: DormerErrorJSON = { name: "DormerError", code: this.code, message: this.message, retry: this.retry };
+    if (this.data !== undefined) j.data = this.data;
+    return j;
+  }
+  /** Rebuild from `toJSON()` output or an ERR payload (`{c, msg, data, retry}`). */
+  static from(v: unknown): DormerError {
+    if (v instanceof DormerError) return v;
+    const o = (v ?? {}) as Partial<DormerErrorJSON> & Partial<Err>;
+    return new DormerError(o.code ?? o.c ?? "EINTERNAL", o.message ?? o.msg ?? "error", o.data, !!o.retry);
+  }
+}
+
+/** Minimal sink an `OutStream` needs: send frames and forget the stream when it ends. */
+export interface FrameSink { send(frame: Frame): void; streams: Map<number, OutStream> }
+
+/** Outgoing stream with credit-based flow control (PROTOCOL.md §5). */
+export class OutStream {
+  private credit = 0;
+  private waiters: Array<() => void> = [];
+  private ended = false;
+  private aborted = false;
+  private readonly ch: FrameSink;
+  readonly route: number;
+  readonly id: number;
+  constructor(ch: FrameSink, route: number, id: number) { this.ch = ch; this.route = route; this.id = id; }
+  grant(n: number) { this.credit += n; const w = this.waiters.splice(0); for (const f of w) f(); }
+  abort() { this.aborted = true; const w = this.waiters.splice(0); for (const f of w) f(); }
+  get isAborted() { return this.aborted; }
+  async write(chunk: Uint8Array): Promise<void> {
+    let off = 0;
+    while (off < chunk.byteLength) {
+      if (this.aborted) throw new DormerError("ECANCELED", "stream cancelled by peer");
+      if (this.credit <= 0) { await new Promise<void>((r) => this.waiters.push(r)); continue; }
+      const n = Math.min(this.credit, chunk.byteLength - off, 1024 * 1024);
+      this.ch.send(binFrame(FrameType.StreamChunk, this.route, this.id, chunk.subarray(off, off + n)));
+      this.credit -= n; off += n;
+    }
+  }
+  end(err?: { c: string; msg: string }) {
+    if (this.ended) return; this.ended = true;
+    const payload: StreamEnd = err ? { ok: false, c: err.c, msg: err.msg } : { ok: true };
+    this.ch.send(msgpackFrame(FrameType.StreamEnd, this.route, this.id, payload));
+    this.ch.streams.delete(this.id);
+  }
+}
+
+/** Default credit window granted by a stream consumer (PROTOCOL.md §5). */
+export const STREAM_WINDOW = 1024 * 1024;
+
+/** Consumer side of a stream: an async iterable of chunks that grants credit as it drains. */
+export class InStream implements AsyncIterable<Uint8Array> {
+  private queue: Uint8Array[] = [];
+  private waiters: Array<(v: IteratorResult<Uint8Array>) => void> = [];
+  private done: { ok: boolean; c?: string; msg?: string } | null = null;
+  private granted = 0;
+  private consumed = 0;
+  private readonly ch: FrameSink;
+  readonly route: number;
+  readonly id: number;
+  constructor(ch: FrameSink, route: number, id: number) { this.ch = ch; this.route = route; this.id = id; this.grant(STREAM_WINDOW); }
+  private grant(n: number) { this.granted += n; this.ch.send(creditFrame(this.route, this.id, n)); }
+  /** @internal */
+  push(chunk: Uint8Array) {
+    this.consumed += chunk.byteLength;
+    // keep roughly one window ahead of the producer
+    if (this.granted - this.consumed < STREAM_WINDOW / 2) this.grant(STREAM_WINDOW);
+    const w = this.waiters.shift();
+    if (w) w({ value: chunk, done: false }); else this.queue.push(chunk);
+  }
+  /** @internal */
+  end(e: { ok: boolean; c?: string; msg?: string }) {
+    this.done = e;
+    const ws = this.waiters.splice(0);
+    for (const w of ws) this.settle(w);
+  }
+  private settle(w: (v: IteratorResult<Uint8Array>) => void) {
+    const d = this.done!;
+    if (d.ok) w({ value: undefined as unknown as Uint8Array, done: true });
+    else w(Promise.reject(new DormerError(d.c ?? "EINTERNAL", d.msg ?? "stream failed")) as unknown as IteratorResult<Uint8Array>);
+  }
+  cancel() { if (!this.done) { this.done = { ok: false, c: "ECANCELED", msg: "cancelled by consumer" }; this.ch.send(makeFrame(FrameType.Cancel, this.route, this.id)); const ws = this.waiters.splice(0); for (const w of ws) this.settle(w); } }
+  [Symbol.asyncIterator](): AsyncIterator<Uint8Array> {
+    return {
+      next: () => {
+        const q = this.queue.shift();
+        if (q) return Promise.resolve({ value: q, done: false });
+        if (this.done) return new Promise<IteratorResult<Uint8Array>>((res, rej) => this.settle((v) => (v instanceof Promise ? (v as Promise<never>).catch(rej) : res(v))));
+        return new Promise<IteratorResult<Uint8Array>>((res, rej) => this.waiters.push((v) => (v instanceof Promise ? (v as Promise<never>).catch(rej) : res(v))));
+      },
+      return: () => { this.cancel(); return Promise.resolve({ value: undefined as unknown as Uint8Array, done: true }); },
+    };
+  }
+}
+
+/** Request/response/event/stream machinery over any frame transport. Subclasses implement `write`. */
+export abstract class FrameChannel extends EventEmitter implements FrameSink {
+  protected decoder = new FrameDecoder();
+  private nextId = 2; // even: Node-initiated
+  private nextStreamId = 2;
+  private pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  private inflight = new Map<string, AbortController>(); // `${route}:${id}` of requests we are handling
+  readonly streams = new Map<number, OutStream>();
+  readonly inStreams = new Map<number, InStream>();
+  closed = false;
+
+  protected abstract write(bytes: Uint8Array): void;
+
+  send(frame: Frame): void {
+    if (this.closed) return;
+    this.write(encodeFrame(frame));
+  }
+
+  /** Request to the peer (`host.*` methods on the host channel, any method on a worker link). */
+  call<T = unknown>(m: string, a: unknown[] = [], route = 0, signal?: AbortSignal): Promise<T> {
+    const id = this.nextId; this.nextId = (this.nextId + 2) >>> 0 || 2;
+    const req: Req = { a, m };
+    return new Promise<T>((resolve, reject) => {
+      if (this.closed) return reject(new DormerError("ECONNRESET", "channel closed"));
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      if (signal) {
+        if (signal.aborted) { this.pending.delete(id); return reject(new DormerError("ECANCELED", "aborted")); }
+        signal.addEventListener("abort", () => { if (this.pending.has(id)) this.send(makeFrame(FrameType.Cancel, route, id)); }, { once: true });
+      }
+      this.send(msgpackFrame(FrameType.Req, route, id, req));
+    });
+  }
+
+  /** Request a stream from the peer; resolves once the peer has opened it. */
+  async callStream(m: string, a: unknown[] = [], route = 0, signal?: AbortSignal): Promise<InStream> {
+    const r = await this.call<{ __dormerStream?: number }>(m, a, route, signal);
+    if (!r || typeof r.__dormerStream !== "number") throw new DormerError("EINVAL", `'${m}' is not a stream handler`);
+    const s = this.inStreams.get(r.__dormerStream) ?? this.openInStream(route, r.__dormerStream);
+    signal?.addEventListener("abort", () => s.cancel(), { once: true });
+    return s;
+  }
+  private openInStream(route: number, id: number): InStream { const s = new InStream(this, route, id); this.inStreams.set(id, s); return s; }
+
+  reply(route: number, id: number, r: unknown): void {
+    this.inflight.delete(`${route}:${id}`);
+    const res: Res = { r };
+    this.send(msgpackFrame(FrameType.Res, route, id, res));
+  }
+  replyError(route: number, id: number, c: string, msg: string, data?: unknown, retry = false): void {
+    this.inflight.delete(`${route}:${id}`);
+    const err: Err = { c, msg, retry, ...(data !== undefined ? { data } : {}) };
+    this.send(msgpackFrame(FrameType.Err, route, id, err));
+  }
+  event(route: number, ch: string, data: unknown): void {
+    const evt: Evt = { ch, data };
+    this.send(msgpackFrame(FrameType.Evt, route, 0, evt));
+  }
+  openStream(route: number, meta: Record<string, unknown>): OutStream {
+    const id = this.nextStreamId; this.nextStreamId = (this.nextStreamId + 2) >>> 0 || 2;
+    const s = new OutStream(this, route, id);
+    this.streams.set(id, s);
+    this.send(msgpackFrame(FrameType.StreamOpen, route, id, { meta }));
+    return s;
+  }
+
+  protected onData(d: Uint8Array) {
+    let frames: Frame[];
+    try { frames = this.decoder.push(d); }
+    catch (e) { this.emit("error", e); this.destroy(); return; }
+    for (const f of frames) this.onFrame(f);
+  }
+
+  protected abstract destroy(): void;
+
+  protected onFrame(f: Frame) {
+    switch (f.type) {
+      case FrameType.Req: {
+        const req = unpack<Req>(f.payload);
+        const ac = new AbortController();
+        this.inflight.set(`${f.route}:${f.id}`, ac);
+        const ir: IncomingRequest = { route: f.route, id: f.id, m: req.m, a: req.a ?? [], signal: ac.signal };
+        this.emit("request", ir);
+        break;
+      }
+      case FrameType.Res: { const p = this.pending.get(f.id); if (p) { this.pending.delete(f.id); p.resolve(unpack<Res>(f.payload).r); } break; }
+      case FrameType.Err: {
+        const p = this.pending.get(f.id);
+        if (p) { this.pending.delete(f.id); const e = unpack<Err>(f.payload); p.reject(new DormerError(e.c, e.msg, e.data, e.retry)); }
+        break;
+      }
+      case FrameType.Evt: { const e = unpack<Evt>(f.payload); this.emit("event", { route: f.route, ch: e.ch, data: e.data } satisfies IncomingEvent); break; }
+      case FrameType.Credit: { this.streams.get(f.id)?.grant(parseCredit(f.payload)); break; }
+      case FrameType.StreamOpen: { if (!this.inStreams.has(f.id)) this.openInStream(f.route, f.id); break; }
+      case FrameType.StreamChunk: { this.inStreams.get(f.id)?.push(f.payload); break; }
+      case FrameType.StreamEnd: { const s = this.inStreams.get(f.id); if (s) { this.inStreams.delete(f.id); s.end(unpack<StreamEnd>(f.payload)); } break; }
+      case FrameType.Cancel: {
+        const s = this.streams.get(f.id);
+        if (s) { s.abort(); break; }
+        this.inflight.get(`${f.route}:${f.id}`)?.abort();
+        break;
+      }
+      case FrameType.Ping: this.send(makeFrame(FrameType.Pong, f.route, f.id, f.payload)); break;
+      case FrameType.Pong: this.emit("pong", f); break;
+      default: this.emit("frame", f);
+    }
+  }
+
+  protected failAll(e: Error) {
+    for (const p of this.pending.values()) p.reject(e);
+    this.pending.clear();
+    for (const s of this.streams.values()) s.abort();
+    for (const s of this.inStreams.values()) s.end({ ok: false, c: (e as DormerError).code ?? "ECONNRESET", msg: e.message });
+    this.inStreams.clear();
+  }
+}
+
+export interface HostChannelOptions {
+  /** PING interval in ms (default 15 000; 0 disables). */
+  heartbeatMs?: number;
+  /** Missed PONGs before the channel is considered dead (default 2). */
+  maxMissedPongs?: number;
+  /** Development mode: never close on missed PONGs (a paused debugger must not kill the app). */
+  dev?: boolean;
+  /** Per-launch token to send in HELLO (named-endpoint fallback, ADR-0003 §3). */
+  token?: string;
+}
+
+/** True when the process was launched by a Dormer host (the host always sets one of these). */
+export function hasHostEnv(): boolean { return process.env.DORMER_CHANNEL_FD !== undefined || process.env.DORMER_CHANNEL_PIPE !== undefined; }
+
+/**
+ * Host channel over the inherited descriptor (fd 3) or, on the Windows fallback, a named pipe.
+ * May be created *deferred* (no socket yet): frames sent before `attach()` are buffered, so the
+ * router and app wiring can exist before the process decides whether a host is present.
+ */
+export class HostChannel extends FrameChannel {
+  private sock?: net.Socket;
+  private buffered: Uint8Array[] = [];
+  welcome?: Welcome;
+  private opts: Required<Omit<HostChannelOptions, "token">> & { token?: string };
+  private heartbeat?: NodeJS.Timeout;
+  private missedPongs = 0;
+  private pingSeq = 0;
+
+  /** Adopt the channel the host created (see `attachFromEnv`). */
+  static fromEnv(opts: HostChannelOptions = {}): HostChannel {
+    const ch = new HostChannel(undefined, opts);
+    ch.attachFromEnv();
+    return ch;
+  }
+
+  constructor(socket?: net.Socket, opts: HostChannelOptions = {}) {
+    super();
+    this.opts = { heartbeatMs: opts.heartbeatMs ?? 15_000, maxMissedPongs: opts.maxMissedPongs ?? 2, dev: opts.dev ?? process.env.DORMER_DEV === "1", token: opts.token };
+    if (socket) this.attach(socket);
+  }
+
+  /** The underlying socket; throws when the channel is still deferred. */
+  get socket(): net.Socket {
+    if (!this.sock) throw new DormerError("ENOTCONN", "host channel is not attached");
+    return this.sock;
+  }
+  get attached(): boolean { return this.sock !== undefined; }
+
+  /** Bind a connected socket and flush frames sent while deferred. Emits `attach`. */
+  attach(socket: net.Socket): void {
+    if (this.sock) throw new DormerError("EINVAL", "host channel already attached");
+    this.sock = socket;
+    socket.on("data", (d: Buffer) => this.onData(d));
+    socket.on("error", (e) => { this.closed = true; this.emit("error", e); });
+    socket.on("close", () => { this.closed = true; this.stopHeartbeat(); this.failAll(new DormerError("ECONNRESET", "host channel closed")); this.emit("close"); });
+    for (const b of this.buffered.splice(0)) socket.write(b);
+    this.emit("attach");
+  }
+
+  /**
+   * Attach to the channel the host created: `DORMER_CHANNEL_FD` or, when
+   * `DORMER_CHANNEL_PIPE=stdin`, a pipe name and token read from stdin (Windows fallback).
+   * Never guesses a descriptor: test runners also hand children an fd 3 (node --test's IPC pipe).
+   */
+  attachFromEnv(): void {
+    this.opts.dev = process.env.DORMER_DEV === "1" ? true : this.opts.dev;
+    if (process.env.DORMER_CHANNEL_PIPE === "stdin") {
+      const [name, token] = readStdinLines(2);
+      if (!name) throw new DormerError("EINVAL", "DORMER_CHANNEL_PIPE=stdin but no pipe name on stdin");
+      this.opts.token = token;
+      this.attach(net.connect(name));
+      return;
+    }
+    if (process.env.DORMER_CHANNEL_FD === undefined) throw new DormerError("ENOTSUP", "not running inside a Dormer host (DORMER_CHANNEL_FD is not set)");
+    const fd = Number(process.env.DORMER_CHANNEL_FD);
+    if (!Number.isInteger(fd) || fd < 0) throw new DormerError("EINVAL", `invalid DORMER_CHANNEL_FD '${process.env.DORMER_CHANNEL_FD}'`);
+    this.attach(new net.Socket({ fd, readable: true, writable: true }));
+  }
+
+  /** Detach the socket (listeners removed) so another channel can adopt it. Used by test injection. */
+  release(): net.Socket {
+    const s = this.socket;
+    s.removeAllListeners("data"); s.removeAllListeners("error"); s.removeAllListeners("close");
+    this.sock = undefined; this.stopHeartbeat();
+    return s;
+  }
+
+  protected write(bytes: Uint8Array): void { if (this.sock) this.sock.write(bytes); else this.buffered.push(bytes); }
+  protected destroy(): void { if (this.sock) this.sock.destroy(); else { this.closed = true; this.emit("close"); } }
+
+  async handshake(caps: string[] = ["bin", "stream"], token = this.opts.token): Promise<Welcome> {
+    const hello: Hello = { caps, min: PROTO_VERSION, proto: PROTO_VERSION, ...(token ? { token } : {}) };
+    this.send(msgpackFrame(FrameType.Hello, 0, 0, hello));
+    return new Promise((resolve, reject) => {
+      const t = setTimeout(() => reject(new DormerError("ETIMEDOUT", "no WELCOME from host")), 10_000);
+      this.once("welcome", (w: Welcome) => { clearTimeout(t); resolve(w); });
+    });
+  }
+
+  /** Heartbeat (PROTOCOL.md §2 PING/PONG): starts after WELCOME; `unref`'d so it never keeps the process alive. */
+  startHeartbeat(): void {
+    this.stopHeartbeat();
+    if (this.opts.heartbeatMs <= 0) return;
+    this.heartbeat = setInterval(() => {
+      if (this.closed) return this.stopHeartbeat();
+      if (this.missedPongs >= this.opts.maxMissedPongs) {
+        this.emit("heartbeat-lost", this.missedPongs);
+        // Destroy without an error payload: the "close" handler fails pending calls with
+        // ECONNRESET, and an unhandled "error" event would otherwise throw in apps without a listener.
+        if (!this.opts.dev) { console.error(`[dormer] host missed ${this.missedPongs} heartbeats; closing channel`); this.sock?.destroy(); return; }
+      }
+      this.missedPongs++;
+      const payload = new Uint8Array(4); new DataView(payload.buffer).setUint32(0, ++this.pingSeq >>> 0, true);
+      this.send(makeFrame(FrameType.Ping, 0, 0, payload));
+    }, this.opts.heartbeatMs);
+    this.heartbeat.unref();
+  }
+  stopHeartbeat(): void { if (this.heartbeat) { clearInterval(this.heartbeat); this.heartbeat = undefined; } }
+
+  /** Flush pending writes and exit. Used for `host:node.shutdown` and by `app.exit`. */
+  flushAndExit(code: number, graceMs = 500): void {
+    this.stopHeartbeat();
+    const bye = () => process.exit(code);
+    const t = setTimeout(bye, graceMs);
+    t.unref();
+    if (!this.sock || this.sock.destroyed || this.sock.writableEnded) return bye();
+    this.sock.end(() => { clearTimeout(t); bye(); });
+  }
+
+  protected onFrame(f: Frame) {
+    switch (f.type) {
+      case FrameType.Welcome: this.welcome = unpack<Welcome>(f.payload); this.startHeartbeat(); this.emit("welcome", this.welcome); return;
+      case FrameType.Pong: this.missedPongs = 0; break;
+      case FrameType.Evt: {
+        const e = unpack<Evt>(f.payload);
+        if (e.ch === "host:node.shutdown") {
+          const code = Number((Array.isArray(e.data) ? (e.data[0] as { code?: number })?.code : (e.data as { code?: number })?.code) ?? 0);
+          // Application code (e.g. `app`) may take over by listening for "shutdown"; otherwise exit now.
+          if (this.listenerCount("shutdown") > 0) this.emit("shutdown", code); else this.flushAndExit(code);
+          return;
+        }
+        break;
+      }
+    }
+    super.onFrame(f);
+  }
+}
+
+function readStdinLines(n: number): string[] {
+  const lines: string[] = []; let buf = ""; const chunk = Buffer.alloc(256);
+  while (lines.length < n) {
+    let got = 0;
+    try { got = fs.readSync(0, chunk, 0, chunk.length, null); } catch (e) { if ((e as NodeJS.ErrnoException).code === "EAGAIN") continue; throw e; }
+    if (got === 0) break;
+    buf += chunk.subarray(0, got).toString("utf8");
+    let i: number;
+    while ((i = buf.indexOf("\n")) >= 0 && lines.length < n) { lines.push(buf.slice(0, i).replace(/\r$/, "")); buf = buf.slice(i + 1); }
+  }
+  return lines;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { HostChannel, FrameChannel, hasHostEnv, OutStream, InStream, DormerError, STREAM_WINDOW, type FrameSink, type HostChannelOptions, type DormerErrorJSON, type IncomingRequest, type IncomingEvent } from "./channel.ts";
+export { Router, toDormerError, type CallContext, type Handler, type StreamHandler, type StreamSource, type EventHandler } from "./router.ts";
+export { PortChannel, WorkerLink, parent as workerParent, linkWorker, linkPort, type PortLike } from "./worker.ts";

package/src/router.ts

@@ -0,0 +1,136 @@
+// Method router: maps REQ frames to handlers, serialises results, drives pull-based streams.
+// Works over any `FrameChannel` (the host channel or a worker MessagePort link).
+import type { Readable } from "node:stream";
+import { FrameChannel, DormerError, type IncomingRequest, type IncomingEvent } from "./channel.ts";
+
+export interface CallContext { route: number; signal: AbortSignal; method: string }
+export type Handler = (ctx: CallContext, ...args: any[]) => unknown;
+export type StreamSource = AsyncIterable<Uint8Array> | Iterable<Uint8Array> | Readable;
+export type StreamHandler = (ctx: CallContext, ...args: any[]) => StreamSource | Promise<StreamSource>;
+export type EventHandler = (ctx: { route: number; channel: string }, ...args: any[]) => void;
+
+const DEV = process.env.DORMER_DEV === "1";
+
+export class Router {
+  private handlers = new Map<string, Handler>();
+  private streamHandlers = new Map<string, StreamHandler>();
+  private eventHandlers = new Map<string, Set<EventHandler>>();
+
+  readonly channel: FrameChannel;
+  constructor(channel: FrameChannel) {
+    this.channel = channel;
+    channel.on("request", (r: IncomingRequest) => void this.dispatch(r));
+    channel.on("event", (e: IncomingEvent) => this.dispatchEvent(e));
+  }
+
+  handle(method: string, fn: Handler): void {
+    if (this.handlers.has(method) || this.streamHandlers.has(method)) throw new Error(`Attempted to register a second handler for '${method}'`);
+    this.handlers.set(method, fn);
+  }
+  handleStream(method: string, fn: StreamHandler): void {
+    if (this.handlers.has(method) || this.streamHandlers.has(method)) throw new Error(`Attempted to register a second handler for '${method}'`);
+    this.streamHandlers.set(method, fn);
+  }
+  removeHandler(method: string): void { this.handlers.delete(method); this.streamHandlers.delete(method); }
+  on(channel: string, fn: EventHandler): () => void {
+    let set = this.eventHandlers.get(channel);
+    if (!set) { set = new Set(); this.eventHandlers.set(channel, set); }
+    set.add(fn);
+    return () => set!.delete(fn);
+  }
+
+  private dispatchEvent(e: IncomingEvent) {
+    const set = this.eventHandlers.get(e.ch);
+    if (!set) return;
+    const args = Array.isArray(e.data) ? e.data : [e.data];
+    for (const fn of set) { try { fn({ route: e.route, channel: e.ch }, ...args); } catch (err) { console.error(`[dormer] event handler for '${e.ch}' threw`, err); } }
+  }
+
+  private async dispatch(r: IncomingRequest) {
+    const ctx: CallContext = { route: r.route, signal: r.signal, method: r.m };
+    const h = this.handlers.get(r.m);
+    if (h) {
+      try {
+        const value = await h(ctx, ...r.a);
+        if (r.signal.aborted) return this.channel.replyError(r.route, r.id, "ECANCELED", "request cancelled");
+        this.channel.reply(r.route, r.id, value === undefined ? null : value);
+      } catch (err) { this.replyWithError(r, err); }
+      return;
+    }
+    const sh = this.streamHandlers.get(r.m);
+    if (sh) {
+      let source: StreamSource;
+      try { source = await sh(ctx, ...r.a); } catch (err) { return this.replyWithError(r, err); }
+      const out = this.channel.openStream(r.route, { method: r.m });
+      this.channel.reply(r.route, r.id, { __dormerStream: out.id });
+      void this.pump(source, out, r.signal);
+      return;
+    }
+    this.channel.replyError(r.route, r.id, "ENOTSUP", `No handler registered for '${r.m}'`);
+  }
+
+  private async pump(source: StreamSource, out: ReturnType<FrameChannel["openStream"]>, signal: AbortSignal) {
+    try {
+      for await (const chunk of source as AsyncIterable<Uint8Array | string>) {
+        if (signal.aborted || out.isAborted) break;
+        const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+        await out.write(bytes);
+      }
+      out.end(out.isAborted ? { c: "ECANCELED", msg: "stream cancelled" } : undefined);
+    } catch (err) {
+      const e = toDormerError(err);
+      out.end({ c: e.code, msg: e.message });
+      if (typeof (source as Readable).destroy === "function") (source as Readable).destroy();
+    }
+  }
+
+  private replyWithError(r: IncomingRequest, err: unknown) {
+    const e = toDormerError(err);
+    const data = DEV ? { stack: (err as Error)?.stack, ...(e.data !== undefined ? { detail: e.data } : {}) } : e.data;
+    this.channel.replyError(r.route, r.id, e.code, e.message, data, e.retry);
+  }
+}
+
+/** Node `ERR_*` codes → protocol codes (PROTOCOL.md §4). Anything else keeps a stable `data.nodeCode`. */
+const NODE_CODE_MAP: Record<string, string> = {
+  ERR_INVALID_ARG_TYPE: "EINVAL", ERR_INVALID_ARG_VALUE: "EINVAL", ERR_OUT_OF_RANGE: "EINVAL", ERR_INVALID_URL: "EINVAL",
+  ERR_MISSING_ARGS: "EINVAL", ERR_INVALID_FILE_URL_PATH: "EINVAL", ERR_INVALID_URL_SCHEME: "EINVAL", ERR_INVALID_STATE: "EINVAL",
+  ERR_ACCESS_DENIED: "EPERM",
+  ERR_UNSUPPORTED_ESM_URL_SCHEME: "ENOTSUP", ERR_FEATURE_UNAVAILABLE_ON_PLATFORM: "ENOTSUP", ERR_METHOD_NOT_IMPLEMENTED: "ENOTSUP", ERR_UNKNOWN_ENCODING: "ENOTSUP",
+  ERR_STREAM_PREMATURE_CLOSE: "ECONNRESET", ERR_STREAM_DESTROYED: "ECONNRESET", ERR_SOCKET_CLOSED: "ECONNRESET", ERR_STREAM_WRITE_AFTER_END: "ECONNRESET",
+  ERR_CHILD_PROCESS_STDIO_MAXBUFFER: "E2BIG", ERR_FS_FILE_TOO_LARGE: "E2BIG", ERR_STRING_TOO_LONG: "E2BIG",
+  ABORT_ERR: "ECANCELED",
+};
+const RETRYABLE = new Set(["EAGAIN", "EBUSY", "ETIMEDOUT", "ECONNRESET", "ECONNREFUSED", "EMFILE", "ENFILE"]);
+/** Node `SystemError` codes we forward unchanged (POSIX names, PROTOCOL.md §4 stable set). */
+const SYSTEM_CODE = /^E[A-Z0-9]{2,15}$/;
+
+/**
+ * Normalise anything thrown by a handler into a `DormerError` with a stable code:
+ * `DormerError` as is; `AbortError` → `ECANCELED`; Node `SystemError` (`ENOENT`, `EACCES`, ...)
+ * keep their code with `{syscall, path, errno}` in `data`; Node `ERR_*` codes map through
+ * `NODE_CODE_MAP` (else `EINTERNAL`) and keep the original in `data.nodeCode`; `TypeError` /
+ * `RangeError` / `SyntaxError` without a code → `EINVAL`; everything else `EINTERNAL`.
+ */
+export function toDormerError(err: unknown): DormerError {
+  if (err instanceof DormerError) return err;
+  if (err && typeof err === "object") {
+    const e = err as { code?: unknown; message?: unknown; name?: unknown; syscall?: unknown; path?: unknown; errno?: unknown; dest?: unknown };
+    const msg = typeof e.message === "string" ? e.message : String(err);
+    const code = typeof e.code === "string" ? e.code : undefined;
+    if (e.name === "AbortError" || code === "ABORT_ERR") return new DormerError("ECANCELED", msg);
+    if (code && SYSTEM_CODE.test(code)) {
+      const data: Record<string, unknown> = {};
+      if (typeof e.syscall === "string") data.syscall = e.syscall;
+      if (typeof e.path === "string") data.path = e.path;
+      if (typeof e.dest === "string") data.dest = e.dest;
+      if (typeof e.errno === "number") data.errno = e.errno;
+      return new DormerError(code, msg, Object.keys(data).length ? data : undefined, RETRYABLE.has(code));
+    }
+    if (code && code.startsWith("ERR_")) return new DormerError(NODE_CODE_MAP[code] ?? "EINTERNAL", msg, { nodeCode: code });
+    if (code) return new DormerError(code, msg);
+    if (e.name === "TypeError" || e.name === "RangeError" || e.name === "SyntaxError") return new DormerError("EINVAL", msg, { nodeCode: e.name });
+    return new DormerError("EINTERNAL", msg);
+  }
+  return new DormerError("EINTERNAL", String(err));
+}

package/src/worker.ts

@@ -0,0 +1,89 @@
+// Worker links: the Dormer frame protocol over a `worker_threads` MessagePort, so a handler can
+// move between the main backend and a worker without API change (ARCHITECTURE.md §4.4).
+// Frames travel as whole `Uint8Array` messages (transferred, not copied).
+import { isMainThread, parentPort, type MessagePort, type Worker } from "node:worker_threads";
+import { FrameChannel, DormerError } from "./channel.ts";
+import { Router, type Handler, type StreamHandler, type EventHandler } from "./router.ts";
+import type { Frame } from "@dormer/ipc";
+
+/** Anything with `postMessage` and `message` events: `MessagePort`, `Worker`, `parentPort`. */
+export interface PortLike {
+  postMessage(value: unknown, transferList?: readonly unknown[]): void;
+  on(event: "message", listener: (value: unknown) => void): unknown;
+  on(event: "close", listener: () => void): unknown;
+  on(event: "error", listener: (err: Error) => void): unknown;
+  on(event: "exit", listener: (code: number) => void): unknown;
+  off?(event: string, listener: (...args: any[]) => void): unknown;
+  close?(): void;
+  unref?(): void;
+  ref?(): void;
+}
+
+/** A `FrameChannel` over a MessagePort-like object. */
+export class PortChannel extends FrameChannel {
+  readonly port: PortLike;
+  constructor(port: PortLike) {
+    super();
+    this.port = port;
+    port.on("message", (m: unknown) => {
+      if (m instanceof Uint8Array) this.onData(m);
+      else if (m instanceof ArrayBuffer) this.onData(new Uint8Array(m));
+    });
+    const gone = () => { if (!this.closed) { this.closed = true; this.failAll(new DormerError("ECONNRESET", "worker link closed")); this.emit("close"); } };
+    try { port.on("close", gone); } catch {}
+    try { port.on("exit", gone); } catch {}
+    try { port.on("error", (e: Error) => this.emit("error", e)); } catch {}
+  }
+  protected write(bytes: Uint8Array): void {
+    // encodeFrame returns a fresh buffer, so transferring it is safe.
+    this.port.postMessage(bytes, [bytes.buffer]);
+  }
+  protected destroy(): void { this.close(); }
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.failAll(new DormerError("ECONNRESET", "worker link closed"));
+    try { this.port.close?.(); } catch {}
+    this.emit("close");
+  }
+}
+
+/**
+ * Two-way link: `call`/`callStream`/`send` towards the peer, `handle`/`handleStream`/`on` for
+ * requests the peer sends us. The same object shape is used on both sides of a worker.
+ */
+export class WorkerLink {
+  readonly channel: PortChannel;
+  readonly router: Router;
+  constructor(port: PortLike) {
+    this.channel = new PortChannel(port);
+    this.router = new Router(this.channel);
+  }
+  /** Invoke `method` on the peer. `opts.signal` cancels (the peer sees `ctx.signal` abort). */
+  call<T = unknown>(method: string, ...args: unknown[]): Promise<T> { return this.channel.call<T>(method, args, 0); }
+  callWith<T = unknown>(opts: { signal?: AbortSignal }, method: string, ...args: unknown[]): Promise<T> { return this.channel.call<T>(method, args, 0, opts.signal); }
+  /** Consume a stream handler on the peer as an async iterable of `Uint8Array` chunks. */
+  stream(method: string, ...args: unknown[]): Promise<AsyncIterable<Uint8Array> & { cancel(): void }> { return this.channel.callStream(method, args, 0); }
+  /** Fire-and-forget event to the peer (`link.on(channel, fn)` on the other side). */
+  send(channel: string, ...args: unknown[]): void { this.channel.event(0, channel, args); }
+  handle(method: string, fn: (ctx: { signal: AbortSignal; method: string }, ...args: any[]) => unknown): void { this.router.handle(method, fn as Handler); }
+  handleStream(method: string, fn: StreamHandler): void { this.router.handleStream(method, fn); }
+  removeHandler(method: string): void { this.router.removeHandler(method); }
+  on(channel: string, fn: (...args: any[]) => void): () => void { return this.router.on(channel, ((_ctx, ...a) => fn(...a)) as EventHandler); }
+  onClose(fn: () => void): void { this.channel.on("close", fn); }
+  close(): void { this.channel.close(); }
+}
+
+let parentLink: WorkerLink | undefined;
+/** Inside a worker: the link back to the thread that created us (throws on the main thread). */
+export function parent(): WorkerLink {
+  if (isMainThread || !parentPort) throw new DormerError("EINVAL", "WorkerLink.parent() is only available inside a worker thread");
+  return parentLink ??= new WorkerLink(parentPort as unknown as PortLike);
+}
+
+/** Wrap an existing `Worker` (main side). */
+export function linkWorker(worker: Worker): WorkerLink { return new WorkerLink(worker as unknown as PortLike); }
+/** Wrap one end of a `MessageChannel` (same-thread tests, or ports handed to workers). */
+export function linkPort(port: MessagePort): WorkerLink { return new WorkerLink(port as unknown as PortLike); }
+
+export type { Frame };

package/test/channel.test.ts

@@ -0,0 +1,115 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import net from "node:net";
+import { FrameDecoder, FrameType, encodeFrame, msgpackFrame, unpack, makeFrame, creditFrame, type Frame } from "@dormer/ipc";
+import { HostChannel, Router } from "../src/index.ts";
+
+// A fake host on the other end of a socketpair-like duplex (two connected TCP sockets on loopback,
+// used only inside this test process).
+async function pair(): Promise<[net.Socket, net.Socket]> {
+  const server = net.createServer();
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  const port = (server.address() as net.AddressInfo).port;
+  const [a, b] = await Promise.all([
+    new Promise<net.Socket>((r) => server.once("connection", r)),
+    new Promise<net.Socket>((r) => { const s = net.connect(port, "127.0.0.1", () => r(s)); }),
+  ]);
+  server.close();
+  return [a, b];
+}
+
+class FakeHost {
+  dec = new FrameDecoder(); frames: Frame[] = []; waiters: Array<(f: Frame) => void> = []; sock: net.Socket;
+  constructor(sock: net.Socket) { this.sock = sock; sock.on("data", (d) => { for (const f of this.dec.push(d)) { const w = this.waiters.shift(); w ? w(f) : this.frames.push(f); } }); }
+  next(): Promise<Frame> { const f = this.frames.shift(); return f ? Promise.resolve(f) : new Promise((r) => this.waiters.push(r)); }
+  send(f: Frame) { this.sock.write(encodeFrame(f)); }
+}
+
+test("handshake, request dispatch, errors, events", async () => {
+  const [hostSock, nodeSock] = await pair();
+  const host = new FakeHost(hostSock);
+  const ch = new HostChannel(nodeSock);
+  const router = new Router(ch);
+  router.handle("ipc:add", (_ctx, a: number, b: number) => a + b);
+  router.handle("ipc:fail", () => { const e = new Error("nope") as Error & { code: string }; e.code = "EFAIL"; throw e; });
+  const seen: unknown[] = [];
+  router.on("send:log", (_ctx, ...args) => seen.push(args));
+
+  const hp = ch.handshake(["bin", "stream"]);
+  const hello = await host.next();
+  assert.equal(hello.type, FrameType.Hello);
+  assert.deepEqual(unpack(hello.payload), { caps: ["bin", "stream"], min: 1, proto: 1 });
+  host.send(msgpackFrame(FrameType.Welcome, 0, 0, { caps: ["bin", "stream"], proto: 1, route: 0 }));
+  assert.equal((await hp).route, 0);
+
+  host.send(msgpackFrame(FrameType.Req, 7, 1, { m: "ipc:add", a: [2, 3] }));
+  const res = await host.next();
+  assert.deepEqual([res.type, res.route, res.id, unpack(res.payload)], [FrameType.Res, 7, 1, { r: 5 }]);
+
+  host.send(msgpackFrame(FrameType.Req, 7, 3, { m: "ipc:fail", a: [] }));
+  const err = await host.next();
+  assert.equal(err.type, FrameType.Err);
+  assert.equal((unpack(err.payload) as { c: string }).c, "EFAIL");
+
+  host.send(msgpackFrame(FrameType.Req, 7, 5, { m: "ipc:missing", a: [] }));
+  assert.equal((unpack((await host.next()).payload) as { c: string }).c, "ENOTSUP");
+
+  host.send(msgpackFrame(FrameType.Evt, 7, 0, { ch: "send:log", data: ["hello", 42] }));
+  await new Promise((r) => setTimeout(r, 10));
+  assert.deepEqual(seen, [["hello", 42]]);
+
+  // Node -> host call
+  const p = ch.call("host.window.create", [{ width: 1 }]);
+  const req = await host.next();
+  assert.equal(req.type, FrameType.Req);
+  host.send(msgpackFrame(FrameType.Res, 0, req.id, { r: { route: 9 } }));
+  assert.deepEqual(await p, { route: 9 });
+
+  hostSock.destroy(); nodeSock.destroy();
+});
+
+test("pull-based stream with credit", async () => {
+  const [hostSock, nodeSock] = await pair();
+  const host = new FakeHost(hostSock);
+  const ch = new HostChannel(nodeSock);
+  const router = new Router(ch);
+  router.handleStream("ipc:bytes", async function* (_ctx, n: number) {
+    for (let i = 0; i < n; i++) yield new Uint8Array(1000).fill(i);
+  });
+  host.send(msgpackFrame(FrameType.Req, 2, 11, { m: "ipc:bytes", a: [3] }));
+  const open = await host.next();
+  assert.equal(open.type, FrameType.StreamOpen);
+  const res = await host.next();
+  const streamId = (unpack(res.payload) as { r: { __dormerStream: number } }).r.__dormerStream;
+  assert.equal(streamId, open.id);
+  // no credit yet: nothing should arrive
+  await new Promise((r) => setTimeout(r, 20));
+  assert.equal(host.frames.length, 0);
+  host.send(creditFrame(2, streamId, 1500));
+  const c1 = await host.next(); assert.equal(c1.type, FrameType.StreamChunk); assert.equal(c1.payload.byteLength, 1000);
+  const c2 = await host.next(); assert.equal(c2.payload.byteLength, 500); // split by credit
+  host.send(creditFrame(2, streamId, 10_000));
+  const c3 = await host.next(); assert.equal(c3.payload.byteLength, 500);
+  const c4 = await host.next(); assert.equal(c4.payload.byteLength, 1000);
+  const end = await host.next(); assert.equal(end.type, FrameType.StreamEnd); assert.deepEqual(unpack(end.payload), { ok: true });
+  hostSock.destroy(); nodeSock.destroy();
+});
+
+test("ping/pong and cancel of in-flight request", async () => {
+  const [hostSock, nodeSock] = await pair();
+  const host = new FakeHost(hostSock);
+  const ch = new HostChannel(nodeSock);
+  const router = new Router(ch);
+  let sawAbort = false;
+  router.handle("ipc:slow", (ctx) => new Promise((resolve) => { ctx.signal.addEventListener("abort", () => { sawAbort = true; resolve("late"); }); }));
+  host.send(makeFrame(FrameType.Ping, 0, 0, new Uint8Array([1, 2])));
+  const pong = await host.next(); assert.equal(pong.type, FrameType.Pong); assert.deepEqual([...pong.payload], [1, 2]);
+  host.send(msgpackFrame(FrameType.Req, 4, 21, { m: "ipc:slow", a: [] }));
+  await new Promise((r) => setTimeout(r, 10));
+  host.send(makeFrame(FrameType.Cancel, 4, 21));
+  const err = await host.next();
+  assert.equal(err.type, FrameType.Err);
+  assert.equal((unpack(err.payload) as { c: string }).c, "ECANCELED");
+  assert.equal(sawAbort, true);
+  hostSock.destroy(); nodeSock.destroy();
+});

package/test/errors.test.ts

@@ -0,0 +1,30 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { toDormerError, DormerError } from "../src/index.ts";
+
+test("error code mapping is stable", () => {
+  const sys = Object.assign(new Error("ENOENT: no such file"), { code: "ENOENT", errno: -2, syscall: "open", path: "/nope" });
+  const e1 = toDormerError(sys);
+  assert.equal(e1.code, "ENOENT"); assert.deepEqual(e1.data, { syscall: "open", path: "/nope", errno: -2 }); assert.equal(e1.retry, false);
+  assert.equal(toDormerError(Object.assign(new Error("busy"), { code: "EBUSY" })).retry, true);
+  const e2 = toDormerError(Object.assign(new TypeError("bad arg"), { code: "ERR_INVALID_ARG_TYPE" }));
+  assert.equal(e2.code, "EINVAL"); assert.deepEqual(e2.data, { nodeCode: "ERR_INVALID_ARG_TYPE" });
+  assert.equal(toDormerError(Object.assign(new Error("denied"), { code: "ERR_ACCESS_DENIED" })).code, "EPERM");
+  assert.equal(toDormerError(Object.assign(new Error("weird"), { code: "ERR_SOMETHING_NEW" })).code, "EINTERNAL");
+  const abort = new Error("aborted"); abort.name = "AbortError";
+  assert.equal(toDormerError(abort).code, "ECANCELED");
+  assert.equal(toDormerError(new RangeError("x")).code, "EINVAL");
+  assert.equal(toDormerError(new Error("plain")).code, "EINTERNAL");
+  assert.equal(toDormerError("string").code, "EINTERNAL");
+  assert.equal(toDormerError(Object.assign(new Error("app"), { code: "MY_APP_CODE" })).code, "MY_APP_CODE");
+});
+
+test("DormerError serialises and revives", () => {
+  const e = new DormerError("EPERM", "no", { why: 1 }, true);
+  const j = JSON.parse(JSON.stringify(e));
+  assert.deepEqual(j, { name: "DormerError", code: "EPERM", message: "no", data: { why: 1 }, retry: true });
+  const back = DormerError.from(j);
+  assert.ok(back instanceof DormerError); assert.equal(back.code, "EPERM"); assert.equal(back.retry, true);
+  assert.equal(DormerError.from({ c: "ENOENT", msg: "m", retry: false }).code, "ENOENT");
+  assert.equal(JSON.stringify(new DormerError("X", "y")), '{"name":"DormerError","code":"X","message":"y","retry":false}');
+});

package/test/fixtures/echo-worker.ts

@@ -0,0 +1,6 @@
+import { workerParent } from "../../src/index.ts";
+const link = workerParent();
+link.handle("echo", (_ctx, ...args: unknown[]) => JSON.stringify(args));
+link.handle("askMain", () => link.call("main.time"));
+link.handle("double", (_ctx, b: Uint8Array) => new Uint8Array(b.map((v) => v * 2)));
+link.handleStream("count", async function* (_ctx, n: number) { for (let i = 0; i < n; i++) yield new Uint8Array(10).fill(i); });

package/test/lifecycle.test.ts

@@ -0,0 +1,67 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import net from "node:net";
+import { FrameDecoder, FrameType, encodeFrame, msgpackFrame, makeFrame, unpack, type Frame } from "@dormer/ipc";
+import { HostChannel } from "../src/index.ts";
+
+async function pair(): Promise<[net.Socket, net.Socket]> {
+  const server = net.createServer();
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  const port = (server.address() as net.AddressInfo).port;
+  const [a, b] = await Promise.all([
+    new Promise<net.Socket>((r) => server.once("connection", r)),
+    new Promise<net.Socket>((r) => { const s = net.connect(port, "127.0.0.1", () => r(s)); }),
+  ]);
+  server.close();
+  return [a, b];
+}
+class FakeHost {
+  dec = new FrameDecoder(); frames: Frame[] = []; waiters: Array<(f: Frame) => void> = []; sock: net.Socket;
+  constructor(sock: net.Socket) { this.sock = sock; sock.on("data", (d) => { for (const f of this.dec.push(d)) { const w = this.waiters.shift(); w ? w(f) : this.frames.push(f); } }); }
+  next(): Promise<Frame> { const f = this.frames.shift(); return f ? Promise.resolve(f) : new Promise((r) => this.waiters.push(r)); }
+  send(f: Frame) { this.sock.write(encodeFrame(f)); }
+}
+
+test("heartbeat pings after WELCOME, closes after missed pongs (non-dev), survives in dev", async () => {
+  for (const dev of [false, true]) {
+    const [hostSock, nodeSock] = await pair();
+    const host = new FakeHost(hostSock);
+    const ch = new HostChannel(nodeSock, { heartbeatMs: 10, maxMissedPongs: 2, dev });
+    let lost = 0; ch.on("heartbeat-lost", () => lost++);
+    const closed = new Promise<boolean>((r) => { ch.on("close", () => r(true)); setTimeout(() => r(false), 150); });
+    const hp = ch.handshake();
+    assert.equal((await host.next()).type, FrameType.Hello);
+    host.send(msgpackFrame(FrameType.Welcome, 0, 0, { caps: [], proto: 1, route: 0 }));
+    await hp;
+    const p1 = await host.next(); assert.equal(p1.type, FrameType.Ping);
+    host.send(makeFrame(FrameType.Pong, 0, 0, p1.payload)); // answered: counter resets
+    const p2 = await host.next(); assert.equal(p2.type, FrameType.Ping);
+    const p3 = await host.next(); assert.equal(p3.type, FrameType.Ping); // two unanswered
+    assert.equal(await closed, !dev, dev ? "dev mode must not close" : "non-dev closes the channel");
+    assert.ok(lost >= 1);
+    ch.stopHeartbeat();
+    hostSock.destroy(); nodeSock.destroy();
+  }
+});
+
+test("host:node.shutdown emits shutdown when handled, else flushes and exits", async () => {
+  const [hostSock, nodeSock] = await pair();
+  const host = new FakeHost(hostSock);
+  const ch = new HostChannel(nodeSock, { heartbeatMs: 0 });
+  const codes: number[] = [];
+  ch.on("shutdown", (code: number) => codes.push(code));
+  host.send(msgpackFrame(FrameType.Evt, 0, 0, { ch: "host:node.shutdown", data: [{ code: 3 }] }));
+  await new Promise((r) => setTimeout(r, 20));
+  assert.deepEqual(codes, [3]);
+
+  const realExit = process.exit; const exits: number[] = [];
+  (process as any).exit = (c: number) => { exits.push(c); };
+  const ch2 = new HostChannel(nodeSock, { heartbeatMs: 0 }); // second listener set, no shutdown handler
+  ch.removeAllListeners("shutdown");
+  host.send(msgpackFrame(FrameType.Evt, 0, 0, { ch: "host:node.shutdown", data: [{ code: 4 }] }));
+  await new Promise((r) => setTimeout(r, 50));
+  (process as any).exit = realExit;
+  assert.ok(exits.includes(4), `expected exit(4), got ${exits}`);
+  void ch2; void unpack;
+  hostSock.destroy(); nodeSock.destroy();
+});

package/test/worker.test.ts

@@ -0,0 +1,63 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { MessageChannel, Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { linkPort, linkWorker, DormerError } from "../src/index.ts";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+test("worker link over a MessageChannel: call, cancel, events, streams, errors", async () => {
+  const { port1, port2 } = new MessageChannel();
+  const a = linkPort(port1), b = linkPort(port2);
+  b.handle("add", (_ctx, x: number, y: number) => x + y);
+  b.handle("bytes", (_ctx, buf: Uint8Array) => new Uint8Array(buf.map((v) => v * 2)));
+  b.handle("fail", () => { throw Object.assign(new Error("missing"), { code: "ENOENT", syscall: "open", path: "/x" }); });
+  let sawAbort = false;
+  b.handle("slow", (ctx) => new Promise((resolve) => ctx.signal.addEventListener("abort", () => { sawAbort = true; resolve("late"); })));
+  b.handleStream("chunks", async function* (_ctx, n: number) { for (let i = 0; i < n; i++) yield new Uint8Array(70_000).fill(i); });
+  const seen: unknown[] = [];
+  b.on("log", (...args) => seen.push(args));
+
+  assert.equal(await a.call("add", 2, 3), 5);
+  const out = await a.call<Uint8Array>("bytes", new Uint8Array([1, 2, 3]));
+  assert.deepEqual([...out], [2, 4, 6]);
+  await assert.rejects(a.call("fail"), (e: DormerError) => e.code === "ENOENT" && (e.data as { syscall: string }).syscall === "open");
+  await assert.rejects(a.call("nope"), (e: DormerError) => e.code === "ENOTSUP");
+
+  const ac = new AbortController(); setTimeout(() => ac.abort(), 5);
+  await assert.rejects(a.callWith({ signal: ac.signal }, "slow"), (e: DormerError) => e.code === "ECANCELED");
+  assert.equal(sawAbort, true);
+
+  a.send("log", "hello", 42);
+  await new Promise((r) => setTimeout(r, 10));
+  assert.deepEqual(seen, [["hello", 42]]);
+
+  let total = 0, chunks = 0;
+  for await (const c of await a.stream("chunks", 20)) { total += c.byteLength; chunks++; }
+  assert.equal(total, 20 * 70_000);
+  assert.ok(chunks >= 20);
+
+  // consumer cancels a stream midway: the producer sees abort and ends
+  const s = await a.stream("chunks", 1000);
+  const it = s[Symbol.asyncIterator]();
+  await it.next();
+  s.cancel();
+  await new Promise((r) => setTimeout(r, 20));
+  assert.ok(b.channel.streams.size === 0, "producer stream removed after cancel");
+
+  a.close(); b.close();
+});
+
+test("real worker thread speaks the protocol both ways", async () => {
+  const worker = new Worker(join(here, "fixtures", "echo-worker.ts"));
+  const link = linkWorker(worker);
+  link.handle("main.time", () => 12345);
+  assert.equal(await link.call("echo", "x", 1), JSON.stringify(["x", 1]));
+  assert.equal(await link.call("askMain"), 12345);
+  const buf = await link.call<Uint8Array>("double", new Uint8Array([5, 6]));
+  assert.deepEqual([...buf], [10, 12]);
+  let n = 0; for await (const c of await link.stream("count", 3)) n += c.byteLength;
+  assert.equal(n, 3 * 10);
+  await worker.terminate();
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.