@query-farm/vgi-rpc 0.7.5 → 0.8.0

package/dist/launcher/index.d.ts

@@ -18,6 +18,7 @@
 export { computeHash } from "./hash.js";
 export { type LaunchConfig, launch } from "./launch.js";
 export { acquireLock, type FileLockHandle, tryAcquireLock } from "./lock.js";
+export { type ServeTcpHandle, type ServeTcpOptions, serveTcp } from "./serve-tcp.js";
 export { type ServeUnixHandle, type ServeUnixOptions, serveUnix } from "./serve-unix.js";
 export { defaultStateDir, type GcResult, gcStateDir, probeSocket, type SocketPaths, type StatusRow, socketPaths, statusRows, } from "./state.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/launcher/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACzF,OAAO,EACL,eAAe,EACf,KAAK,QAAQ,EACb,UAAU,EACV,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACzF,OAAO,EACL,eAAe,EACf,KAAK,QAAQ,EACb,UAAU,EACV,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/launcher/serve-tcp.d.ts

@@ -0,0 +1,66 @@
+import type { ExternalLocationConfig } from "../external.js";
+import type { Protocol } from "../protocol.js";
+import { type DispatchHook, type ServeStartHook } from "../types.js";
+/** Configuration for {@link serveTcp}. */
+export interface ServeTcpOptions {
+    /** Interface to bind.  Defaults to `127.0.0.1` (loopback only).  Binding a
+     *  routable address exposes the unauthenticated framing on the network. */
+    host?: string;
+    /** TCP port to bind.  Defaults to `0`, which lets the OS pick a free port
+     *  (reported via the `TCP:<host>:<port>` line and {@link onBound}). */
+    port?: number;
+    /** Self-terminate after this many seconds with zero connected clients.
+     *  Default: 300.  `0` disables the timer (server runs until killed). */
+    idleTimeout?: number;
+    /** Grace period after `listen()` succeeds before the idle timer starts
+     *  ticking.  Default: 5 — gives the first launcher caller a chance to
+     *  connect after the `TCP:<host>:<port>` announcement. */
+    startupGraceSeconds?: number;
+    /** Optional logical-service / protocol-contract version label. */
+    protocolVersion?: string;
+    /** Custom server identifier. */
+    serverId?: string;
+    /** Enable __describe__ method. Default: true. */
+    enableDescribe?: boolean;
+    /** Optional dispatch hook for observability. */
+    dispatchHook?: DispatchHook;
+    /** Optional external-storage config for large-batch externalisation. */
+    externalLocation?: ExternalLocationConfig;
+    /** Lifecycle hook fired once before the first dispatched request. */
+    onServeStart?: ServeStartHook;
+    /** Maximum listen backlog.  Default: 128. */
+    backlog?: number;
+    /** Called *after* `listen()` returns successfully but *before*
+     *  `TCP:<host>:<port>` is printed.  Invoked with the bound host and the
+     *  *actual* bound port (resolved when `port=0`). */
+    onBound?: (host: string, port: number) => void;
+    /** Override the stream used for the `TCP:<host>:<port>` line.  Defaults to
+     *  `process.stdout`. */
+    announcementSink?: NodeJS.WritableStream;
+}
+/** Handle returned by {@link serveTcp} for callers that want to stop the server. */
+export interface ServeTcpHandle {
+    /** Host the server is listening on. */
+    readonly host: string;
+    /** Actual bound TCP port (resolved from `0` when the OS auto-selects). */
+    readonly port: number;
+    /** Shut down the listener. */
+    stop(): Promise<void>;
+    /** Promise that resolves when the server has stopped (idle timeout, stop(),
+     *  or a fatal error).  Mirrors Python's blocking `serve()` return. */
+    readonly done: Promise<void>;
+}
+/**
+ * Bind a TCP socket and serve `protocol` over per-connection IPC streams.
+ *
+ * The network analog of {@link serveUnix}: same raw Arrow-IPC framing, only
+ * the listening socket differs.  Nagle's algorithm is disabled
+ * (`setNoDelay(true)`) on each connection so the lockstep request/response
+ * framing is not delayed waiting to coalesce writes.
+ *
+ * SECURITY: no authentication or TLS — trusted networks only; the default
+ * host is loopback (`127.0.0.1`).  Use the HTTP transport for untrusted
+ * networks.
+ */
+export declare function serveTcp(protocol: Protocol, options?: ServeTcpOptions): Promise<ServeTcpHandle>;
+//# sourceMappingURL=serve-tcp.d.ts.map

package/dist/launcher/serve-tcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-tcp.d.ts","sourceRoot":"","sources":["../../src/launcher/serve-tcp.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,cAAc,EAEpB,MAAM,aAAa,CAAC;AAQrB,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B;+EAC2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;2EACuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;4EACwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;8DAE0D;IAC1D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gDAAgD;IAChD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,qEAAqE;IACrE,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;wDAEoD;IACpD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C;4BACwB;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;0EACsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA2QzG"}

package/dist/types.d.ts

@@ -23,6 +23,8 @@ export declare enum MethodType {
  * - `PIPE` — Stdio worker (the standalone {@link VgiRpcServer} loop).
  * - `HTTP` — Fetch-style HTTP handler (`createHttpHandler`).
  * - `UNIX` — AF_UNIX socket handler (the launcher path).
+ * - `TCP` — AF_INET socket handler. Raw Arrow-IPC framing over a bare TCP
+ *   socket — no auth/TLS; use `HTTP` for untrusted networks.
  */
 export declare enum TransportKind {
     /** Stdio worker — the standalone {@link VgiRpcServer} loop. */
@@ -30,7 +32,10 @@ export declare enum TransportKind {
     /** Fetch-style HTTP handler (`createHttpHandler`). */
     HTTP = "http",
     /** AF_UNIX socket handler (the launcher path). */
-    UNIX = "unix"
+    UNIX = "unix",
+    /** AF_INET (TCP) socket handler. Raw Arrow-IPC framing over a bare TCP
+     *  socket — no authentication or TLS; trusted networks only. */
+    TCP = "tcp"
 }
 /**
  * Optional lifecycle hook fired once per process before the first

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi-rpc",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "homepage": "https://vgi-rpc-typescript.query.farm",
   "repository": {

package/src/client/index.ts

@@ -22,4 +22,5 @@ export type {
   PipeConnectOptions,
   StreamSession,
   SubprocessConnectOptions,
+  TcpConnectOptions,
 } from "./types.js";

package/src/client/tcp.ts

@@ -0,0 +1,68 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Raw-TCP RPC client.
+ *
+ * Node/Bun only — statically imports `node:net`, so this module is exported
+ * exclusively from the node barrel (`src/index.ts`), never from the
+ * runtime-agnostic core (which is re-exported into browser/workerd bundles).
+ *
+ * SECURITY: raw TCP carries no authentication or TLS — connect only to
+ * trusted endpoints. Use `httpConnect` for untrusted networks.
+ */
+
+import { connect } from "node:net";
+import type { RpcClient } from "./connect.js";
+import { pipeConnect } from "./pipe.js";
+import type { TcpConnectOptions } from "./types.js";
+
+/**
+ * Connect to a vgi-rpc server over a raw TCP socket and wrap it with
+ * {@link pipeConnect}. The network analog of `subprocessConnect`: identical
+ * lockstep raw Arrow-IPC framing, only the transport differs. Nagle's
+ * algorithm is disabled (`setNoDelay(true)`) so lockstep requests are not
+ * delayed coalescing writes. The returned client's {@link RpcClient.close}
+ * also destroys the socket.
+ *
+ * SECURITY: raw TCP carries **no authentication or TLS** — only connect to
+ * trusted endpoints. Use `httpConnect` for untrusted networks.
+ *
+ * @param host Hostname or IP address of the TCP server.
+ * @param port TCP port of the server.
+ * @param options Optional log/external-location configuration.
+ */
+export function tcpConnect(host: string, port: number, options?: TcpConnectOptions): RpcClient {
+  const socket = connect({ host, port });
+  socket.setNoDelay(true);
+  // Swallow socket errors so an EPIPE/ECONNRESET doesn't crash the process;
+  // the in-flight call surfaces the failure as an EOF on the reader instead.
+  socket.on("error", () => {});
+
+  const readable = socket as unknown as ReadableStream<Uint8Array>;
+  const writable = {
+    write(data: Uint8Array): void {
+      socket.write(data);
+    },
+    end(): void {
+      socket.end();
+    },
+  };
+
+  const client = pipeConnect(readable, writable, {
+    onLog: options?.onLog,
+    externalLocation: options?.externalLocation,
+  });
+
+  const originalClose = client.close;
+  client.close = () => {
+    originalClose.call(client);
+    try {
+      socket.destroy();
+    } catch {
+      // Socket may already be closed
+    }
+  };
+
+  return client;
+}

package/src/client/types.ts

@@ -49,6 +49,14 @@ export interface PipeConnectOptions {
   externalLocation?: import("../external.js").ExternalLocationConfig;
 }
 
+/**
+ * Options for {@link tcpConnect}, the raw-TCP-socket RPC client.
+ *
+ * SECURITY: raw TCP carries no authentication or TLS — connect only to
+ * trusted endpoints (use {@link httpConnect} for untrusted networks).
+ */
+export interface TcpConnectOptions extends PipeConnectOptions {}
+
 /** Options for {@link subprocessConnect}, which spawns a server process and pipes to it. */
 export interface SubprocessConnectOptions extends PipeConnectOptions {
   /** Working directory for the spawned process. Defaults to the current directory. */

package/src/index.ts

@@ -1,6 +1,9 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+// Node-only raw-TCP client (statically imports `node:net`, so it lives outside
+// the runtime-agnostic core that browser/workerd bundles re-export).
+export { tcpConnect } from "./client/tcp.js";
 // Full node/bun barrel: the runtime-agnostic core plus the node-only AF_UNIX
 // launcher. Cloudflare Worker / browser builds resolve `./index.workerd.ts`
 // (the `workerd`/`worker`/`browser` export conditions) instead, which omits
@@ -16,10 +19,13 @@ export {
   type LaunchConfig,
   launch,
   probeSocket,
+  type ServeTcpHandle,
+  type ServeTcpOptions,
   type ServeUnixHandle,
   type ServeUnixOptions,
   type SocketPaths,
   type StatusRow,
+  serveTcp,
   serveUnix,
   socketPaths,
   statusRows,

package/src/launcher/index.ts

@@ -22,6 +22,7 @@
 export { computeHash } from "./hash.js";
 export { type LaunchConfig, launch } from "./launch.js";
 export { acquireLock, type FileLockHandle, tryAcquireLock } from "./lock.js";
+export { type ServeTcpHandle, type ServeTcpOptions, serveTcp } from "./serve-tcp.js";
 export { type ServeUnixHandle, type ServeUnixOptions, serveUnix } from "./serve-unix.js";
 export {
   defaultStateDir,

package/src/launcher/serve-tcp.ts

@@ -0,0 +1,382 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * AF_INET (raw TCP) worker runner for vgi-rpc TypeScript.
+ *
+ * Bind a TCP socket on `(host, port)`, accept connections, and dispatch
+ * each via the same per-connection IPC-stream loop as {@link serveUnix}.
+ * This is the network analog of the AF_UNIX runner — identical raw
+ * Arrow-IPC framing, only the listening socket differs.  Implements the
+ * cross-language launcher contract:
+ *
+ * - Accept `[HOST:]PORT` (host defaults to `127.0.0.1`, port `0` lets the
+ *   OS pick a free port) and `--idle-timeout SEC`.
+ * - Emit `TCP:<host>:<port>\n` to stdout once bind+listen succeed, where
+ *   `<port>` is the *actual* bound port (resolved when `port=0`).
+ * - Self-terminate after `idleTimeout` seconds with zero connected
+ *   clients; the timer starts ticking only after a `startupGrace` window
+ *   so a slow first caller doesn't see the server vanish.
+ *
+ * SECURITY: raw TCP carries **no authentication or TLS** — it is the bare
+ * framing protocol on a socket.  The default host is loopback-only
+ * (`127.0.0.1`).  Binding a routable address (e.g. `0.0.0.0`) exposes the
+ * unauthenticated protocol on the network and must only be done on a
+ * trusted network; use the HTTP transport otherwise.
+ */
+
+import { createServer, type Server, type Socket } from "node:net";
+import { schema as makeSchema, serializeBatch } from "../arrow/index.js";
+import { DESCRIBE_METHOD_NAME } from "../constants.js";
+import { buildDescribeBatch } from "../dispatch/describe.js";
+import { dispatchStream } from "../dispatch/stream.js";
+import { dispatchUnary } from "../dispatch/unary.js";
+import { RpcError, VersionError } from "../errors.js";
+import type { ExternalLocationConfig } from "../external.js";
+import type { Protocol } from "../protocol.js";
+import {
+  type CallStatistics,
+  type DispatchHook,
+  type DispatchInfo,
+  MethodType,
+  type ServeStartHook,
+  TransportKind,
+} from "../types.js";
+import { IpcStreamReader } from "../wire/reader.js";
+import { applyDefaults, parseRequest } from "../wire/request.js";
+import { buildErrorBatch } from "../wire/response.js";
+import { IpcStreamWriter } from "../wire/writer.js";
+
+const EMPTY_SCHEMA = makeSchema([]);
+
+/** Configuration for {@link serveTcp}. */
+export interface ServeTcpOptions {
+  /** Interface to bind.  Defaults to `127.0.0.1` (loopback only).  Binding a
+   *  routable address exposes the unauthenticated framing on the network. */
+  host?: string;
+  /** TCP port to bind.  Defaults to `0`, which lets the OS pick a free port
+   *  (reported via the `TCP:<host>:<port>` line and {@link onBound}). */
+  port?: number;
+  /** Self-terminate after this many seconds with zero connected clients.
+   *  Default: 300.  `0` disables the timer (server runs until killed). */
+  idleTimeout?: number;
+  /** Grace period after `listen()` succeeds before the idle timer starts
+   *  ticking.  Default: 5 — gives the first launcher caller a chance to
+   *  connect after the `TCP:<host>:<port>` announcement. */
+  startupGraceSeconds?: number;
+  /** Optional logical-service / protocol-contract version label. */
+  protocolVersion?: string;
+  /** Custom server identifier. */
+  serverId?: string;
+  /** Enable __describe__ method. Default: true. */
+  enableDescribe?: boolean;
+  /** Optional dispatch hook for observability. */
+  dispatchHook?: DispatchHook;
+  /** Optional external-storage config for large-batch externalisation. */
+  externalLocation?: ExternalLocationConfig;
+  /** Lifecycle hook fired once before the first dispatched request. */
+  onServeStart?: ServeStartHook;
+  /** Maximum listen backlog.  Default: 128. */
+  backlog?: number;
+  /** Called *after* `listen()` returns successfully but *before*
+   *  `TCP:<host>:<port>` is printed.  Invoked with the bound host and the
+   *  *actual* bound port (resolved when `port=0`). */
+  onBound?: (host: string, port: number) => void;
+  /** Override the stream used for the `TCP:<host>:<port>` line.  Defaults to
+   *  `process.stdout`. */
+  announcementSink?: NodeJS.WritableStream;
+}
+
+/** Handle returned by {@link serveTcp} for callers that want to stop the server. */
+export interface ServeTcpHandle {
+  /** Host the server is listening on. */
+  readonly host: string;
+  /** Actual bound TCP port (resolved from `0` when the OS auto-selects). */
+  readonly port: number;
+  /** Shut down the listener. */
+  stop(): Promise<void>;
+  /** Promise that resolves when the server has stopped (idle timeout, stop(),
+   *  or a fatal error).  Mirrors Python's blocking `serve()` return. */
+  readonly done: Promise<void>;
+}
+
+/**
+ * Bind a TCP socket and serve `protocol` over per-connection IPC streams.
+ *
+ * The network analog of {@link serveUnix}: same raw Arrow-IPC framing, only
+ * the listening socket differs.  Nagle's algorithm is disabled
+ * (`setNoDelay(true)`) on each connection so the lockstep request/response
+ * framing is not delayed waiting to coalesce writes.
+ *
+ * SECURITY: no authentication or TLS — trusted networks only; the default
+ * host is loopback (`127.0.0.1`).  Use the HTTP transport for untrusted
+ * networks.
+ */
+export async function serveTcp(protocol: Protocol, options: ServeTcpOptions = {}): Promise<ServeTcpHandle> {
+  const host = options.host ?? "127.0.0.1";
+  const requestedPort = options.port ?? 0;
+  const idleTimeoutS = options.idleTimeout ?? 300;
+  const startupGraceS = options.startupGraceSeconds ?? 5;
+  const protocolVersion = options.protocolVersion ?? "";
+  const serverId = options.serverId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+  const enableDescribe = options.enableDescribe ?? true;
+  const dispatchHook = options.dispatchHook ?? null;
+  const externalConfig = options.externalLocation;
+  const onServeStart = options.onServeStart ?? null;
+  const backlog = options.backlog ?? 128;
+  const announcementSink = options.announcementSink ?? process.stdout;
+
+  // Cache for __describe__ — Web-Crypto digest is async, so memoise.
+  let describePromise: Promise<{ batch: import("../arrow/index.js").VgiBatch; protocolHash: string }> | null = null;
+  function describeInfo(): Promise<{ batch: import("../arrow/index.js").VgiBatch; protocolHash: string }> {
+    if (!describePromise) {
+      describePromise = buildDescribeBatch(protocol.name, protocol.getMethods(), serverId).then(
+        ({ batch, metadata }) => ({
+          batch,
+          protocolHash: metadata.get("vgi_rpc.protocol_hash") ?? "",
+        }),
+      );
+    }
+    return describePromise;
+  }
+
+  // Lifecycle: only commit `serveStartFired` after the hook returns successfully.
+  let serveStartFired = false;
+  async function notifyTransport(): Promise<void> {
+    if (serveStartFired) return;
+    if (onServeStart) {
+      await onServeStart(TransportKind.TCP);
+    }
+    serveStartFired = true;
+  }
+
+  const server: Server = createServer({ allowHalfOpen: false });
+
+  let activeConnections = 0;
+  let idleTimer: ReturnType<typeof setTimeout> | null = null;
+  let resolveDone: () => void = () => {};
+  let rejectDone: (err: unknown) => void = () => {};
+  const done = new Promise<void>((resolve, reject) => {
+    resolveDone = resolve;
+    rejectDone = reject;
+  });
+  let stopped = false;
+
+  function armIdleTimer(): void {
+    if (idleTimeoutS <= 0) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (activeConnections === 0 && !stopped) {
+        void shutdown();
+      }
+    }, idleTimeoutS * 1000);
+  }
+
+  function disarmIdleTimer(): void {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+  }
+
+  async function shutdown(): Promise<void> {
+    if (stopped) return;
+    stopped = true;
+    disarmIdleTimer();
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+    resolveDone();
+  }
+
+  server.on("connection", (socket) => {
+    // Disable Nagle so the lockstep framing is not delayed coalescing writes.
+    try {
+      socket.setNoDelay(true);
+    } catch {
+      // best-effort
+    }
+    activeConnections += 1;
+    disarmIdleTimer();
+    handleConnection(socket)
+      .catch((err) => {
+        // Per-connection errors must not take down the server — log to stderr
+        // and let the next connection proceed.
+        process.stderr.write(`vgi-rpc/tcp: connection failed: ${(err as Error)?.message ?? err}\n`);
+      })
+      .finally(() => {
+        activeConnections -= 1;
+        socket.destroy();
+        if (activeConnections === 0 && !stopped) {
+          armIdleTimer();
+        }
+      });
+  });
+
+  server.on("error", (err) => {
+    if (stopped) return;
+    rejectDone(err);
+  });
+
+  async function handleConnection(socket: Socket): Promise<void> {
+    // The reader takes any Node Readable; sockets are duplex Readables.
+    const reader = await IpcStreamReader.create(socket);
+    // Build the writer over the Socket itself, not its raw fd, so we go
+    // through `socket.write` + `'drain'` and yield the event loop while the
+    // kernel send buffer drains (see serve-unix.ts for the rationale).
+    const writer = new IpcStreamWriter(socket);
+
+    try {
+      // Fire on_serve_start lazily — first request retries on hook failure.
+      await notifyTransport();
+
+      while (true) {
+        try {
+          await serveOnce(reader, writer);
+        } catch (e: unknown) {
+          const err = e as { code?: string; message?: string };
+          // EOF/closed client → end this connection cleanly.
+          if (
+            err?.message?.includes("closed") ||
+            err?.message?.includes("Expected Schema Message") ||
+            err?.message?.includes("null or length 0") ||
+            err?.message?.includes("EOF") ||
+            err?.code === "EPIPE" ||
+            err?.code === "ERR_STREAM_PREMATURE_CLOSE" ||
+            err?.code === "ERR_STREAM_DESTROYED"
+          ) {
+            return;
+          }
+          throw e;
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+        // already closed
+      }
+    }
+  }
+
+  async function serveOnce(reader: IpcStreamReader, writer: IpcStreamWriter): Promise<void> {
+    const stream = await reader.readStream();
+    if (!stream) {
+      throw new Error("EOF");
+    }
+    const { schema, batches } = stream;
+    if (batches.length === 0) {
+      const err = new RpcError("ProtocolError", "Request stream contains no batches", "");
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA, err, serverId, null);
+      await writer.writeStream(EMPTY_SCHEMA, [errBatch]);
+      return;
+    }
+    const batch = batches[0];
+    let methodName: string;
+    let params: Record<string, unknown>;
+    let requestId: string | null;
+    try {
+      const parsed = parseRequest(schema, batch);
+      methodName = parsed.methodName;
+      params = parsed.params;
+      requestId = parsed.requestId;
+    } catch (e: unknown) {
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA, e as Error, serverId, null);
+      await writer.writeStream(EMPTY_SCHEMA, [errBatch]);
+      if (e instanceof VersionError || e instanceof RpcError) return;
+      throw e;
+    }
+
+    if (methodName === DESCRIBE_METHOD_NAME && enableDescribe) {
+      const { batch: descBatch } = await describeInfo();
+      await writer.writeStream(descBatch.schema, [descBatch]);
+      return;
+    }
+
+    const methods = protocol.getMethods();
+    const method = methods.get(methodName);
+    if (!method) {
+      const available = [...methods.keys()].sort();
+      const err = new Error(`Unknown method: '${methodName}'. Available methods: [${available.join(", ")}]`);
+      const errBatch = buildErrorBatch(EMPTY_SCHEMA, err, serverId, requestId);
+      await writer.writeStream(EMPTY_SCHEMA, [errBatch]);
+      return;
+    }
+
+    const methodType = method.type === MethodType.UNARY ? "unary" : "stream";
+    let requestData: Uint8Array | undefined;
+    try {
+      requestData = serializeBatch(batch);
+    } catch {
+      // best-effort
+    }
+    const { protocolHash } = await describeInfo();
+    const info: DispatchInfo = {
+      method: methodName,
+      methodType,
+      serverId,
+      requestId,
+      protocol: protocol.name,
+      protocolHash,
+      protocolVersion,
+      kind: TransportKind.TCP,
+      principal: "",
+      authDomain: "",
+      authenticated: false,
+      remoteAddr: "",
+      requestData,
+    };
+    const stats: CallStatistics = {
+      inputBatches: 0,
+      outputBatches: 0,
+      inputRows: 0,
+      outputRows: 0,
+      inputBytes: 0,
+      outputBytes: 0,
+    };
+
+    const token = dispatchHook?.onDispatchStart(info);
+    let dispatchError: Error | undefined;
+    applyDefaults(params, method.defaults);
+    try {
+      if (method.type === MethodType.UNARY) {
+        await dispatchUnary(method, params, writer, serverId, requestId, externalConfig, TransportKind.TCP);
+      } else {
+        await dispatchStream(method, params, writer, reader, serverId, requestId, externalConfig, TransportKind.TCP);
+      }
+    } catch (e) {
+      dispatchError = e instanceof Error ? e : new Error(String(e));
+      throw e;
+    } finally {
+      dispatchHook?.onDispatchEnd(token, info, stats, dispatchError);
+    }
+  }
+
+  // bind + listen
+  await new Promise<void>((resolve, reject) => {
+    server.listen({ host, port: requestedPort, backlog }, () => resolve());
+    server.once("error", (err) => reject(err));
+  });
+
+  const address = server.address();
+  const boundPort = typeof address === "object" && address ? address.port : requestedPort;
+
+  options.onBound?.(host, boundPort);
+  // Cross-language launcher contract: announce on stdout, then write nothing
+  // more to stdout for the rest of the process lifetime.
+  announcementSink.write(`TCP:${host}:${boundPort}\n`);
+
+  // Start the idle timer with a startup grace window.
+  if (idleTimeoutS > 0) {
+    setTimeout(() => {
+      if (activeConnections === 0 && !stopped) armIdleTimer();
+    }, startupGraceS * 1000).unref?.();
+  }
+
+  return {
+    host,
+    port: boundPort,
+    stop: shutdown,
+    done,
+  };
+}