tina4-nodejs 3.13.92 → 3.13.95

package/packages/core/src/sessionHandlers/respClient.ts

@@ -1,21 +1,17 @@
 /**
  * Tina4 synchronous RESP transport — shared by every Redis/Valkey session handler.
  *
- * The session-handler interface is synchronous, but node:net is async-only, so a
- * command runs in a short-lived `node -e` child (execFileSync) that blocks the
- * caller until it exits. This module is the ONE correct implementation of that
- * child; the Redis/Valkey handlers delegate here instead of inlining their own.
+ * The session-handler interface is synchronous but node:net is async-only, so
+ * this delegates to syncSocket, which owns ONE persistent connection per target
+ * behind a worker thread. See that file for why: the previous implementation ran
+ * every command in a short-lived `node -e` child, paying a process spawn AND a
+ * fresh TCP connection per command (p50 41ms, p99 487ms), and its long tail
+ * tripped the child's own deadline — the cause of the sessionHandlers flake.
  *
- * The bug this replaces: the old child parsed the reply on the socket "end" event.
- * Redis/Valkey keep the connection OPEN after a reply (they never half-close for a
- * GET/SET/DEL), so "end" never fires — the child waited out its timeout, exited
- * non-zero, and execFileSync re-threw it as a "transport failure". EVERY command
- * failed against a reachable server. Here the child parses replies INCREMENTALLY on
- * the "data" event (the same proven RESP parser cache.ts's RespClient uses): it
- * reads exactly the replies it sent commands for (AUTH? + SELECT? + the command),
- * then returns the LAST (command) reply.
+ * This module stays as the RESP-shaped seam the Redis/Valkey handlers call, so
+ * neither has to know how the synchronous transport is implemented.
  */
-import { execFileSync } from "node:child_process";
+import { syncCommand } from "./syncSocket.js";
 
 export interface RespTarget {
   host: string;
@@ -36,136 +32,13 @@ export interface RespTarget {
  *   `<label> error: ...`. A rejected handshake is a transport failure, not a
  *   result, so it is surfaced ahead of the command reply.
  *
- * Session values are JSON strings (they start with `{`), so they never collide
- * with the `__NULL__` / `__ERR__` sentinels the child uses on stdout.
+ * The miss/failure split is the whole contract: collapsing them is how a dead
+ * backend silently logs every user out instead of surfacing an outage.
  */
 export function respCommandSync(target: RespTarget, args: string[], label = "Redis"): string {
-  const host = target.host;
-  const port = target.port;
-  const password = target.password ?? "";
-  const db = target.db ?? 0;
-
-  const script = `
-    const net = require("node:net");
-    const host = ${JSON.stringify(host)};
-    const port = ${port};
-    const password = ${JSON.stringify(password)};
-    const db = ${db};
-    const args = ${JSON.stringify(args)};
-    // Replies to consume = AUTH? + SELECT? + the command. The LAST is our result.
-    const expected = (password ? 1 : 0) + (db !== 0 ? 1 : 0) + 1;
-
-    function encode(a) {
-      let c = "*" + a.length + "\\r\\n";
-      for (const s of a) c += "$" + Buffer.byteLength(s) + "\\r\\n" + s + "\\r\\n";
-      return c;
-    }
-
-    // Parse one RESP value at offset. Returns { value, next } or null if more bytes
-    // are needed (so a bulk string split across TCP chunks is handled correctly).
-    function parse(buf, off) {
-      if (off >= buf.length) return null;
-      const type = buf[off];
-      const crlf = buf.indexOf("\\r\\n", off + 1, "utf-8");
-      if (crlf === -1) return null;
-      const line = buf.toString("utf-8", off + 1, crlf);
-      const after = crlf + 2;
-      if (type === 0x2b) return { value: line, next: after };             // '+' simple string
-      if (type === 0x3a) return { value: line, next: after };             // ':' integer
-      if (type === 0x2d) return { value: { __err: line }, next: after };  // '-' error
-      if (type === 0x24) {                                                // '$' bulk string
-        const len = parseInt(line, 10);
-        if (len === -1) return { value: null, next: after };
-        if (after + len + 2 > buf.length) return null;
-        return { value: buf.toString("utf-8", after, after + len), next: after + len + 2 };
-      }
-      if (type === 0x2a) {                                                // '*' array
-        const count = parseInt(line, 10);
-        if (count === -1) return { value: null, next: after };
-        const arr = [];
-        let pos = after;
-        for (let i = 0; i < count; i++) {
-          const el = parse(buf, pos);
-          if (!el) return null;
-          arr.push(el.value);
-          pos = el.next;
-        }
-        return { value: arr, next: pos };
-      }
-      return { value: line, next: after };
-    }
-
-    const sock = net.createConnection({ host, port });
-    sock.setNoDelay(true);
-    let buffer = Buffer.alloc(0);
-    const replies = [];
-    let done = false;
-    const timer = setTimeout(() => { if (!done) { done = true; try { sock.destroy(); } catch (e) {} process.stderr.write("timeout"); process.exitCode = 1; } }, 3000);
-
-    function emit(s) {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      // The write callback guarantees stdout is flushed before exit (a bare
-      // process.exit can truncate piped stdout).
-      process.stdout.write(s, () => { try { sock.destroy(); } catch (e) {} });
-    }
-    function fail(msg) {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      try { sock.destroy(); } catch (e) {}
-      process.stderr.write(msg || "");
-      process.exitCode = 1;
-    }
-
-    sock.on("connect", () => {
-      let cmds = "";
-      if (password) cmds += encode(["AUTH", password]);
-      if (db !== 0) cmds += encode(["SELECT", String(db)]);
-      cmds += encode(args);
-      sock.write(cmds);
-    });
-    sock.on("data", (chunk) => {
-      buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
-      while (true) {
-        const p = parse(buffer, 0);
-        if (!p) break;
-        buffer = buffer.subarray(p.next);
-        replies.push(p.value);
-        if (replies.length < expected) continue;
-        // A rejected AUTH/SELECT is a transport failure — surface it first.
-        for (let i = 0; i < expected - 1; i++) {
-          const r = replies[i];
-          if (r && typeof r === "object" && r.__err !== undefined) { emit("__ERR__" + r.__err); return; }
-        }
-        const result = replies[expected - 1];
-        if (result && typeof result === "object" && result.__err !== undefined) emit("__ERR__" + result.__err);
-        else if (result === null || result === undefined) emit("__NULL__");
-        else emit(String(result));
-        return;
-      }
-    });
-    sock.on("error", (err) => fail(err.message));
-    sock.on("close", () => { if (!done) fail("connection closed before reply"); });
-  `;
-
-  let result: string;
-  try {
-    result = execFileSync(process.execPath, ["-e", script], {
-      encoding: "utf-8",
-      timeout: 5000,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-  } catch (err) {
-    // Non-zero exit = socket error / timeout / closed connection: a transport
-    // FAILURE, not a key miss. Surface it so the Session boundary logs + degrades
-    // (or re-throws under strict mode).
-    throw new Error(`${label} command failed: ${(err as Error).message}`);
-  }
-  if (result === "__NULL__") return "";       // genuine key miss
-  if (result.startsWith("__ERR__")) {
-    throw new Error(`${label} error: ${result.slice("__ERR__".length)}`);
-  }
-  return result;
+  return syncCommand(
+    { host: target.host, port: target.port, password: target.password, db: target.db },
+    args,
+    label,
+  );
 }

package/packages/core/src/sessionHandlers/sqlClient.ts

@@ -0,0 +1,290 @@
+/**
+ * Tina4 synchronous SQL transport for the database session backend.
+ *
+ * WHY IT EXISTS. The SessionHandler interface is SYNCHRONOUS and every SQL
+ * driver Node offers for a networked engine (pg, mysql2, tedious,
+ * node-firebird) is async-only. That mismatch was previously "resolved" by
+ * refusing every engine except SQLite: resolveDbPath() THREW on any non-sqlite
+ * TINA4_DATABASE_URL. So an app developed on SQLite and deployed on PostgreSQL
+ * did not start, in the one subsystem that decides whether anybody is logged in.
+ *
+ * The mismatch is not a reason to refuse an engine, because the fix already
+ * existed: syncBridge.ts. A Worker thread keeps its own event loop, so it can
+ * hold a long-lived driver connection and do ordinary async I/O, while the
+ * caller blocks in Atomics.wait until the worker writes its reply into a
+ * SharedArrayBuffer. RESP (Redis/Valkey), memcached and MongoDB have all ridden
+ * that bridge for months. This is a fifth consumer of a proven mechanism, not a
+ * new mechanism.
+ *
+ * SQLITE DOES NOT COME THROUGH HERE. `node:sqlite` is already synchronous, so
+ * routing it through a worker would add a thread hop and a JSON round-trip to
+ * the one engine that needs neither. DatabaseSessionHandler drives it directly.
+ *
+ * WHY THE DRIVERS ARE REQUIRED INSIDE THE WORKER rather than reaching for the
+ * ORM adapters: exactly the reason mongoClient.ts requires "mongodb" itself.
+ * The worker body is an eval'd CJS string, so a bare `require` is the one module
+ * resolution that works identically under tsx, under plain node, from source and
+ * from a built dist. @tina4/orm already declares pg / mysql2 / tedious as
+ * optional dependencies, so nothing new is installed for this - core stays
+ * zero-dependency.
+ *
+ * The SQL itself is NOT built here. The handler builds engine-neutral SQL with
+ * `?` placeholders - the same statement text as the Python master - and this
+ * transport rewrites the placeholders into the dialect the driver wants. Only
+ * the placeholder style and the CREATE TABLE types differ per engine.
+ */
+import { createRequire } from "node:module";
+import { getBridge, STATUS_OK, STATUS_TRANSPORT } from "./syncBridge.js";
+
+/**
+ * The SQL engines the database session backend speaks.
+ *
+ * This IS the invariant: it is the engine set of the ORM Database layer minus
+ * the two non-SQL entries (mongodb has its own session backend, odbc has no
+ * session story in any of the four frameworks). Naming it once means the
+ * refusal message and the dispatch can never disagree about what is supported.
+ */
+export const SQL_SESSION_ENGINES = ["sqlite", "postgres", "mysql", "mssql", "firebird"] as const;
+
+export type SqlSessionEngine = (typeof SQL_SESSION_ENGINES)[number];
+
+/** The engines that need the bridge - everything except already-sync SQLite. */
+export type BridgedEngine = Exclude<SqlSessionEngine, "sqlite">;
+
+/**
+ * A connection target for the worker.
+ *
+ * A PLAIN object, deliberately - never a `DatabaseUrl`. That class carries a
+ * cleartext password and its own docblock forbids persisting it across a
+ * structured-clone boundary (test/databaseUrlRedaction.test.ts enforces it).
+ * The worker genuinely needs credentials to authenticate, so it gets the fields
+ * it needs and nothing that renders itself.
+ */
+export interface SqlTarget {
+  engine: BridgedEngine;
+  host: string;
+  port: number;
+  database: string;
+  username: string | null;
+  password: string | null;
+}
+
+/**
+ * Connect budget, kept BELOW the bridge's 5s reply timeout on purpose. An
+ * unreachable server then surfaces as a real driver message ("ECONNREFUSED
+ * 127.0.0.1:5432") instead of the caller's generic "timed out after 5000ms",
+ * which says nothing about what is actually wrong. Same reasoning, same number
+ * as mongoClient's SERVER_SELECTION_MS.
+ */
+const CONNECT_TIMEOUT_MS = 3000;
+
+/** The driver each engine needs. All are already optional deps of @tina4/orm. */
+const DRIVER_PACKAGE: Record<BridgedEngine, string> = {
+  postgres: "pg",
+  mysql: "mysql2",
+  mssql: "tedious",
+  firebird: "node-firebird",
+};
+
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * Resolve the driver to an ABSOLUTE path, on the main thread, before the worker
+ * starts.
+ *
+ * A bare `require("pg")` inside the worker would resolve from the process
+ * WORKING DIRECTORY (an eval'd worker has no real filename to resolve from), so
+ * a server started from anywhere other than the project root would fail to find
+ * a driver that is installed. Resolving from THIS module instead walks up from
+ * the framework's own location, which is correct in the monorepo and in an
+ * installed app alike.
+ *
+ * @throws Error naming the missing package and how to install it.
+ */
+function driverPath(engine: BridgedEngine): string {
+  const packageName = DRIVER_PACKAGE[engine];
+  try {
+    return requireFromHere.resolve(packageName);
+  } catch {
+    throw new Error(
+      `The "database" session backend on ${engine} requires the "${packageName}" package. `
+      + `Install it with: npm install ${packageName}`,
+    );
+  }
+}
+
+const SQL_WORKER = `
+const target = workerData.target;
+const engine = target.engine;
+const driver = require(workerData.driverPath);
+
+let client = null;
+
+/**
+ * Rewrite the handler's neutral \`?\` placeholders into the driver's dialect.
+ * mysql2 and node-firebird already take \`?\`, so they are left alone.
+ */
+function convert(sql) {
+  if (engine === "postgres") { let n = 0; return sql.replace(/\\?/g, () => "$" + (++n)); }
+  if (engine === "mssql") { let n = 0; return sql.replace(/\\?/g, () => "@p" + (n++)); }
+  return sql;
+}
+
+async function connect() {
+  if (engine === "postgres") {
+    const Client = driver.Client || (driver.default && driver.default.Client);
+    const c = new Client({
+      host: target.host,
+      port: target.port,
+      user: target.username === null ? undefined : target.username,
+      password: target.password === null ? undefined : target.password,
+      database: target.database,
+      connectionTimeoutMillis: ${CONNECT_TIMEOUT_MS},
+    });
+    await c.connect();
+    return c;
+  }
+  if (engine === "mysql") {
+    const c = driver.createConnection({
+      host: target.host,
+      port: target.port,
+      user: target.username === null ? undefined : target.username,
+      password: target.password === null ? undefined : target.password,
+      database: target.database,
+      connectTimeout: ${CONNECT_TIMEOUT_MS},
+    });
+    await new Promise((resolve, reject) => c.connect((err) => (err ? reject(err) : resolve())));
+    return c;
+  }
+  if (engine === "mssql") {
+    const c = new driver.Connection({
+      server: target.host,
+      authentication: {
+        type: "default",
+        options: { userName: target.username, password: target.password },
+      },
+      options: {
+        database: target.database,
+        port: target.port,
+        trustServerCertificate: true,
+        encrypt: false,
+        connectTimeout: ${CONNECT_TIMEOUT_MS},
+      },
+    });
+    await new Promise((resolve, reject) => {
+      c.on("connect", (err) => (err ? reject(err) : resolve()));
+      c.connect();
+    });
+    return c;
+  }
+  if (engine === "firebird") {
+    return await new Promise((resolve, reject) => {
+      driver.attach(
+        {
+          host: target.host,
+          port: target.port,
+          database: target.database,
+          user: target.username,
+          password: target.password,
+        },
+        (err, db) => (err ? reject(err) : resolve(db)),
+      );
+    });
+  }
+  throw new Error("unsupported session SQL engine: " + engine);
+}
+
+function runMssql(sql, params) {
+  return new Promise((resolve, reject) => {
+    const rows = [];
+    const request = new driver.Request(convert(sql), (err) => (err ? reject(err) : resolve(rows)));
+    params.forEach((value, i) => {
+      // EVERY number binds as Float, never Int. tedious' Int is 32-bit and an
+      // expiry stamp is epoch SECONDS - an integral value above 2147483647
+      // (2038-01-19) would overflow and be stored as garbage, silently.
+      if (typeof value === "number") request.addParameter("p" + i, driver.TYPES.Float, value);
+      else if (value === null || value === undefined) request.addParameter("p" + i, driver.TYPES.NVarChar, null);
+      // length: Infinity means NVARCHAR(MAX). Without it tedious caps the
+      // parameter at 4000 characters and a large session TRUNCATES on write.
+      else request.addParameter("p" + i, driver.TYPES.NVarChar, String(value), { length: Infinity });
+    });
+    request.on("row", (columns) => {
+      const row = {};
+      columns.forEach((column) => { row[column.metadata.colName] = column.value; });
+      rows.push(row);
+    });
+    client.execSql(request);
+  });
+}
+
+async function run(sql, params) {
+  if (!client) client = await connect();
+  if (engine === "postgres") {
+    const result = await client.query(convert(sql), params);
+    return result.rows || [];
+  }
+  if (engine === "mysql") {
+    const results = await new Promise((resolve, reject) => {
+      client.query(sql, params, (err, rows) => (err ? reject(err) : resolve(rows)));
+    });
+    return Array.isArray(results) ? results : [];
+  }
+  if (engine === "mssql") return await runMssql(sql, params);
+  const rows = await new Promise((resolve, reject) => {
+    client.query(sql, params, (err, result) => (err ? reject(err) : resolve(result)));
+  });
+  return Array.isArray(rows) ? rows : [];
+}
+
+parentPort.on("message", (message) => {
+  void (async () => {
+    try {
+      const rows = await run(message.sql, message.params || []);
+      __reply(${STATUS_OK}, JSON.stringify(rows));
+    } catch (err) {
+      // Drop the connection so the NEXT command reconnects. A transient blip
+      // must not poison the channel for the life of the process.
+      try {
+        if (client) {
+          if (typeof client.end === "function") client.end();
+          else if (typeof client.close === "function") client.close();
+          else if (typeof client.detach === "function") client.detach();
+        }
+      } catch (ignored) {}
+      client = null;
+      __reply(${STATUS_TRANSPORT}, String((err && err.message) || err));
+    }
+  })();
+});
+`;
+
+/**
+ * Run one SQL statement synchronously against a networked engine.
+ *
+ * @returns the result rows - always an array, empty for a write or DDL.
+ * @throws Error on ANY driver failure (server unreachable, bad credentials,
+ *         SQL error). It is never swallowed into an empty result: for a session
+ *         store, "the database is down" and "no session yet" must stay
+ *         distinguishable, or a dead backend silently logs every user out.
+ */
+export function sqlCommandSync(
+  target: SqlTarget,
+  sql: string,
+  params: unknown[] = [],
+  label = "Database session",
+): Record<string, unknown>[] {
+  const key = `sql:${target.engine}:${target.host}:${target.port}:${target.database}:${target.username ?? ""}`;
+  const { status, payload } = getBridge(key, SQL_WORKER, {
+    target,
+    driverPath: driverPath(target.engine),
+  }).call({ sql, params }, label);
+
+  if (status !== STATUS_OK) {
+    throw new Error(`${label} command failed: ${payload}`);
+  }
+  try {
+    return JSON.parse(payload) as Record<string, unknown>[];
+  } catch {
+    return [];
+  }
+}

package/packages/core/src/sessionHandlers/syncBridge.ts

@@ -0,0 +1,190 @@
+/**
+ * Tina4 sync-over-async bridge — call an ASYNC worker from SYNCHRONOUS code.
+ *
+ * The SessionHandler interface is synchronous; every backend client Node offers
+ * (node:net, the mongodb driver) is async-only. The old resolution was to run
+ * each command in a short-lived `node -e` child and block on execFileSync. That
+ * works but pays a process spawn — and a fresh connection, and for Mongo a fresh
+ * driver load — PER COMMAND. Measured on this machine: spawn min 38ms / p50 41ms
+ * / p99 487ms, with a bare TCP connect adding a ~0.5-0.9s tail of its own. That
+ * tail tripped the child's deadline under load, which is what made the Valkey
+ * session tests flaky with the signature "a value that was just written reads
+ * back null" — the write timed out for the caller while still landing on the
+ * server.
+ *
+ * This is the ONE piece of plumbing that replaces it. A Worker thread keeps its
+ * own event loop, so it can do ordinary async I/O and hold a long-lived
+ * connection. The caller hands it a message with postMessage (delivered on the
+ * WORKER's loop, so a blocked main thread cannot deadlock it), then blocks in
+ * Atomics.wait until the worker writes a reply into a SharedArrayBuffer and
+ * Atomics.notify wakes it.
+ *
+ * Every session backend that needs sync-over-async uses this — RESP
+ * (Redis/Valkey), memcached's text protocol, and MongoDB — so the blocking
+ * handshake exists once rather than once per backend.
+ */
+import { Worker } from "node:worker_threads";
+
+/** Reply status, written by the worker into control[IDX_STATUS]. */
+export const STATUS_OK = 0;
+/** A healthy server answered with an error (RESP `-ERR`, a Mongo command error). */
+export const STATUS_ERROR = 1;
+/** A genuine miss — no such key/document. NOT a failure. */
+export const STATUS_NIL = 2;
+/** The reply did not fit the shared buffer. */
+export const STATUS_TOO_LARGE = 3;
+/** Connection/socket/driver failure, as opposed to an answer from a healthy server. */
+export const STATUS_TRANSPORT = 4;
+
+export const IDX_SEQ = 0;      // bumped by the worker on every reply; what Atomics.wait watches
+export const IDX_LENGTH = 1;   // reply byte length
+export const IDX_STATUS = 2;   // one of STATUS_*
+export const IDX_READY = 3;    // set to 1 by the worker as soon as its loop is running
+
+/**
+ * Reply payload ceiling. A session document beyond this is pathological, and a
+ * fixed buffer keeps the fast path allocation-free. A worker reports
+ * STATUS_TOO_LARGE rather than truncating — a silently truncated session would
+ * deserialise into garbage.
+ */
+export const DATA_BYTES = 8 * 1024 * 1024;
+
+/** How long a caller blocks before giving up on a reply. */
+export const REPLY_TIMEOUT_MS = 5000;
+
+/**
+ * How long the FIRST caller waits for a brand-new worker to come up.
+ *
+ * Boot and the command round-trip must not share one budget. Cold start is
+ * normally ~27ms, but on a loaded machine (the session suite spawns a batch of
+ * blocking Mongo children immediately beforehand) it can stretch — and when it
+ * ate into the 5s command budget the very first Valkey write failed with
+ * "timed out after 5000ms", which read exactly like the flake this transport
+ * was built to remove. Boot gets its own generous budget so the per-command
+ * timeout can stay tight and mean what it says.
+ */
+export const BOOT_TIMEOUT_MS = 15000;
+
+/**
+ * The worker-side helper, injected into every worker body. Kept here so the
+ * reply protocol is written once: a worker only has to call
+ * `__reply(status, payload)` and never touches Atomics itself.
+ */
+export const WORKER_REPLY_HELPER = `
+const __control = new Int32Array(workerData.controlBuffer);
+const __data = new Uint8Array(workerData.dataBuffer);
+const __encoder = new TextEncoder();
+
+// Announce readiness the moment this thread is executing. The parent blocks on
+// this before its first command, so a slow boot can never be mistaken for a
+// slow command. This is signalled by the worker's OWN bootstrap and needs no
+// message from the parent, so it is safe even while the parent is blocked.
+Atomics.store(__control, ${IDX_READY}, 1);
+Atomics.notify(__control, ${IDX_READY});
+
+function __reply(status, payload) {
+  let length = 0;
+  if (payload !== undefined && payload !== null && status !== ${STATUS_NIL}) {
+    const bytes = __encoder.encode(String(payload));
+    if (bytes.length > __data.length) {
+      Atomics.store(__control, ${IDX_STATUS}, ${STATUS_TOO_LARGE});
+      Atomics.store(__control, ${IDX_LENGTH}, 0);
+      Atomics.add(__control, ${IDX_SEQ}, 1);
+      Atomics.notify(__control, ${IDX_SEQ});
+      return;
+    }
+    __data.set(bytes, 0);
+    length = bytes.length;
+  }
+  Atomics.store(__control, ${IDX_STATUS}, status);
+  Atomics.store(__control, ${IDX_LENGTH}, length);
+  Atomics.add(__control, ${IDX_SEQ}, 1);
+  Atomics.notify(__control, ${IDX_SEQ});
+}
+`;
+
+export interface BridgeReply {
+  status: number;
+  payload: string;
+}
+
+export interface Bridge {
+  /** Send a message to the worker and BLOCK until it replies. */
+  call(message: unknown, label: string): BridgeReply;
+  worker: Worker;
+}
+
+const bridges = new Map<string, Bridge>();
+
+/**
+ * Get (or create) the bridge for a key. One worker per key, created once and
+ * unref'd so it can never hold the process open.
+ *
+ * @param key Identity of the connection target — same key, same worker
+ * @param workerSource The worker body; WORKER_REPLY_HELPER is prepended for it
+ * @param workerData Passed to the worker verbatim (plus the shared buffers)
+ */
+export function getBridge(key: string, workerSource: string, workerData: Record<string, unknown>): Bridge {
+  const existing = bridges.get(key);
+  if (existing) return existing;
+
+  const controlBuffer = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
+  const dataBuffer = new SharedArrayBuffer(DATA_BYTES);
+  const control = new Int32Array(controlBuffer);
+  const data = new Uint8Array(dataBuffer);
+
+  const worker = new Worker(
+    `const { parentPort, workerData } = require("node:worker_threads");\n${WORKER_REPLY_HELPER}\n${workerSource}`,
+    { eval: true, workerData: { ...workerData, controlBuffer, dataBuffer } },
+  );
+  // A session channel must never keep a process alive.
+  worker.unref();
+
+  // Block until the worker is up. A cold channel pays this once.
+  if (Atomics.load(control, IDX_READY) === 0) {
+    if (Atomics.wait(control, IDX_READY, 0, BOOT_TIMEOUT_MS) === "timed-out") {
+      void worker.terminate();
+      bridges.delete(key);
+      throw new Error(`session worker failed to start within ${BOOT_TIMEOUT_MS}ms`);
+    }
+  }
+
+  const decoder = new TextDecoder();
+  const bridge: Bridge = {
+    worker,
+    call(message: unknown, label: string): BridgeReply {
+      // Watch a monotonic counter rather than a flag: a counter cannot race with
+      // a reset, so a late reply from a previous (timed-out) call can never be
+      // mistaken for this one's.
+      const before = Atomics.load(control, IDX_SEQ);
+      worker.postMessage(message);
+
+      if (Atomics.wait(control, IDX_SEQ, before, REPLY_TIMEOUT_MS) === "timed-out") {
+        throw new Error(`${label} command failed: timed out after ${REPLY_TIMEOUT_MS}ms`);
+      }
+
+      const status = Atomics.load(control, IDX_STATUS);
+      const length = Atomics.load(control, IDX_LENGTH);
+
+      if (status === STATUS_TOO_LARGE) {
+        throw new Error(`${label} command failed: reply exceeds the ${DATA_BYTES} byte buffer`);
+      }
+      return { status, payload: decoder.decode(data.subarray(0, length)) };
+    },
+  };
+
+  bridges.set(key, bridge);
+  return bridge;
+}
+
+/**
+ * Terminate every worker. Tests and short-lived scripts call this so a spawned
+ * worker never outlives the work that created it — "reap what you spawn". Normal
+ * apps do not need it: the workers are unref'd.
+ */
+export function closeBridges(): void {
+  for (const { worker } of bridges.values()) {
+    void worker.terminate();
+  }
+  bridges.clear();
+}