@volter/world-runtime 2.0.0 → 2.0.2

package/dist/src/pglite-host.mjs

@@ -18,16 +18,90 @@
 // the other's writes. A connection that dies mid-transaction is rolled back
 // before the lock is released.
 //
-// Identity is aliased, not faked: trust auth accepts the world's declared
-// user/password/database, but the backend is PGlite's single `postgres`
-// database — apps that introspect current_database() will see that. Worlds
-// accept this; an app needing true multi-database Postgres needs the
-// container backing.
+// Extensions: every contrib extension PGlite 0.5.8 ships (CONTRIB below) plus
+// pgvector (`vector`, from @electric-sql/pglite-pgvector, pinned to the
+// PGlite version) is loaded at create(), so `CREATE EXTENSION [IF NOT EXISTS]
+// pgcrypto | citext | "uuid-ossp" | unaccent | pg_trgm | btree_gist | hstore |
+// ltree | vector | …` behaves as on a Postgres with contrib installed. Nothing
+// is created up front — the app's migrations create what they use. An
+// extension outside this set (postgis, pg_cron, timescaledb, …) is absent
+// from pg_available_extensions and CREATE EXTENSION fails with Postgres's own
+// "extension … is not available" error. Loading the set costs boot time:
+// PGlite.create() in-memory, node 22 on darwin arm64 (this repo's dev box,
+// 2026-09-27, nothing else running in the process) took 1.66s bare and
+// 2.47s with the set; RSS was within 50 MB either way.
+//
+// Limits, stated plainly (measured on 0.5.8 through this gateway with `pg`
+// clients; pglite-backing.test.ts holds the extension and database checks):
+// - ONE database. Trust auth accepts any user/password/database in the
+//   startup packet, so a DATABASE_URL naming `/rallly` connects — but every
+//   name lands in PGlite's single `postgres` database: current_database()
+//   and current_user answer `postgres`, and all names share one catalog.
+//   PGlite itself ACCEPTS `CREATE DATABASE` (a pg_database row appears) yet
+//   nothing can ever connect to it, so this host fails the statement loudly
+//   (see refusal() below): 42P04 "already exists" when the name is the
+//   connection's own startup database (true: it connects, so check-then-
+//   create for the app's own database proceeds), 0A000 "not supported" for
+//   any other name. An app that needs a second real database (Prisma's
+//   shadow database for `migrate dev`, Django's `test_<name>`; `migrate
+//   deploy` needs none) needs the container backing.
+// - No COPY … FROM STDIN: refused with 0A000 (it aborts PGlite's backend);
+//   COPY … TO STDOUT works.
+// - ONE serialized session. Connections are accepted concurrently but run
+//   one at a time under the lock below; a client holding a transaction open
+//   blocks every other client until it ends — or until it has sat idle in
+//   that transaction (ReadyForQuery 'T' or 'E') for IDLE_IN_TRANSACTION_MS
+//   while another client waits: then it is terminated with the FATAL Postgres
+//   sends a session past idle_in_transaction_session_timeout (25P03), its
+//   transaction rolled back (writes made through it are lost, as on Postgres),
+//   and the next client runs. This DEVIATES from Postgres, whose timeout is off
+//   by default and where an idle open transaction holds only its row locks:
+//   here it would hold the whole database, so a transaction that waits on
+//   something else (an HTTP call inside it) for longer than the limit while
+//   another client queues is cut. A READ-ONLY batch another connection sends
+//   while the holder sits idle in its transaction does not wait: it runs as a
+//   guest in the holder's session, inside a savepoint (see enter()), and sees
+//   the holder's uncommitted rows — Postgres would show it only committed ones.
+//   While a guest's batch runs, the holder waits for it (its idle clock
+//   stopped); a guest batch still open after GUEST_TURN_MS while anyone waits
+//   (a cursor that has not sent its Sync) is cancelled (57014), its savepoint
+//   undone;
+//   a batch that begins with a read and goes on to write is refused (0A000).
+//   A connection that closes while it waits
+//   for the lock gives it up unrun (rallly walk 2: pg-pool evicted an idle
+//   client — its Terminate queued behind another connection's transaction,
+//   ran once that ended, left no ReadyForQuery, and held the lock forever). All connections share the one
+//   backend session, so session state leaks between them and outlives the
+//   connection that set it: SET (search_path, timezone…), temp tables and
+//   PREPAREd statements are visible to every other connection; session
+//   advisory locks do NOT exclude (a second connection's
+//   pg_try_advisory_lock on a held key returns true); a NOTIFY is delivered
+//   to the connection that sent it, not to the one that ran LISTEN.
+//   CREATE ROLE succeeds but connections never run as that role.
 import net from 'node:net';
 import { mkdirSync } from 'node:fs';
 import { PGlite } from '@electric-sql/pglite';
+import { vector } from '@electric-sql/pglite-pgvector';
 import { fromNodeSocket } from 'pg-gateway/node';
 
+// The contrib extensions shipped in @electric-sql/pglite/dist/contrib (the
+// module name; `uuid_ossp` installs as "uuid-ossp"). auto_explain is omitted:
+// it is a preload library with no CREATE EXTENSION control file.
+const CONTRIB = [
+  'amcheck', 'bloom', 'btree_gin', 'btree_gist', 'citext', 'cube', 'dict_int',
+  'dict_xsyn', 'earthdistance', 'file_fdw', 'fuzzystrmatch', 'hstore',
+  'intarray', 'isn', 'lo', 'ltree', 'moddatetime', 'pageinspect',
+  'pg_buffercache', 'pg_freespacemap', 'pg_stat_statements', 'pg_surgery',
+  'pg_trgm', 'pg_visibility', 'pg_walinspect', 'pgcrypto', 'seg', 'tablefunc',
+  'tcn', 'tsm_system_rows', 'tsm_system_time', 'unaccent', 'uuid_ossp',
+];
+const extensions = { vector };
+for (const name of CONTRIB) {
+  const extension = (await import(`@electric-sql/pglite/contrib/${name}`))[name];
+  if (!extension) throw new Error(`pglite-host: @electric-sql/pglite/contrib/${name} exports no ${name}`);
+  extensions[name] = extension;
+}
+
 function arg(name) {
   const index = process.argv.indexOf(name);
   const value = index >= 0 ? process.argv[index + 1] : undefined;
@@ -52,28 +126,234 @@ process.stderr.on('error', () => {});
 // PGlite's create() only progresses while something holds the event loop;
 // listening starts AFTER readiness so "port answers" means "serves queries"
 const initKeepAlive = setInterval(() => {}, 500);
-const dbReady = PGlite.create({ dataDir });
+const dbReady = PGlite.create({ dataDir, extensions });
 dbReady.catch((error) => {
   process.stderr.write(`pglite-host: backend failed to start: ${error?.message ?? error}\n`);
   process.exit(1);
 });
 
 // ---- transaction-affinity lock ---------------------------------------------
+// How long the holder may sit idle inside its transaction while another client
+// waits before it is terminated (see the limits above). Prisma's own default
+// interactive-transaction timeout is 5s; a session idle that long with others
+// queued is one no client is still driving.
+const IDLE_IN_TRANSACTION_MS = 5000;
 let holder = null;
 const waiters = [];
-async function acquire(token) {
-  while (holder !== null && holder !== token) {
+/** Each connection's socket, whether a message of it is running, and since
+ * when it has been idle. */
+const sessions = new Map();
+// A GUEST batch: while the holder sits idle inside its transaction (its last
+// ReadyForQuery 'T', no message of its own running, none half-sent), another
+// connection's READ-ONLY batch runs in the holder's session, inside a savepoint
+// released after it (rolled back to on an error, so the holder's transaction is
+// never aborted by it), and is answered ReadyForQuery 'I' as its own session
+// would be. An application that reads on a second pooled connection while its
+// first holds a transaction open (twenty's sign-up: a TypeORM transaction that
+// awaits a repository read on another connection) otherwise waits for a lock
+// the transaction never gives up. The read sees the holder's uncommitted rows —
+// a deviation from Postgres's isolation, stated in the limits above. Writes,
+// and a guest's own BEGIN, wait for the lock as before.
+let guestBatch = null;
+let guestStartedAt = 0;
+// How long a guest batch may hold its turn while the holder or a writer waits (a cursor that never sends its Sync
+// would otherwise hold every connection up): past it the guest's batch is refused and the waiters run.
+const GUEST_TURN_MS = 2000;
+function wakeAll() {
+  for (const wake of waiters.splice(0)) wake();
+}
+/** How `token` may run its next message: 'own' (it holds the lock, and its turn is claimed here, before any other
+ *  waiter wakes to look) or 'guest'. A holder waiting for its turn is `wanting`: no new guest starts ahead of it. */
+async function enter(token, session, data) {
+  for (;;) {
+    if (guestBatch === token) return 'guest';
+    if (guestBatch === null) {
+      if (holder === null || holder === token) {
+        holder = token;
+        session.busy = true;
+        session.wanting = false;
+        return 'own';
+      }
+      const host = sessions.get(holder);
+      if (host && !host.busy && !host.wanting && !host.midBatch && host.status === 'T'
+        && session.status !== 'T' && session.status !== 'E' && guestMessageAllowed(session, data)) {
+        guestBatch = token;
+        guestStartedAt = Date.now();
+        return 'guest';
+      }
+    }
+    if (holder === token) session.wanting = true;
     await new Promise((resolve) => waiters.push(resolve));
   }
-  holder = token;
 }
 function release(token) {
   if (holder !== token) return;
   holder = null;
-  const next = waiters.shift();
-  if (next) next();
+  wakeAll();
+}
+
+/** A statement's text with its string literals, quoted identifiers and comments blanked, or null when it cannot be
+ *  read safely (a dollar-quoted body, an unterminated literal): the caller then treats it as not read-only. */
+function statementSkeleton(text) {
+  // dollar quoting and backslash-escape strings (E'…', where \' does not close) are not read here: not read-only
+  // (a backslash anywhere, too: with standard_conforming_strings off, which one connection can set for the shared
+  // session, a plain '…' takes backslash escapes)
+  if (/\$[A-Za-z_0-9]*\$/.test(text) || text.includes('\\')) return null;
+  let out = '';
+  for (let i = 0; i < text.length;) {
+    const c = text[i];
+    if (c === "'" || c === '"') {
+      const end = text.indexOf(c, i + 1);
+      if (end < 0) return null;
+      let j = end;
+      while (text[j + 1] === c) { const next = text.indexOf(c, j + 2); if (next < 0) return null; j = next; }
+      out += ' ';
+      i = j + 1;
+    } else if (c === '-' && text[i + 1] === '-') {
+      const end = text.indexOf('\n', i);
+      i = end < 0 ? text.length : end;
+      out += ' ';
+    } else if (c === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2);
+      if (end < 0) return null;
+      i = end + 2;
+      out += ' ';
+    } else { out += c; i += 1; }
+  }
+  return out.trim();
+}
+
+/** Whether a statement only reads: one SELECT (or WITH/SHOW/VALUES/TABLE/EXPLAIN without ANALYZE) that writes,
+ *  locks or advances nothing, judged on its text with literals and comments removed. A false "no" only waits. */
+function readOnlySql(text) {
+  const sql = statementSkeleton(text);
+  if (sql === null) return false;
+  if (sql.replace(/;\s*$/, '').includes(';')) return false; // one statement only
+  if (!/^(select|with|show|values|table|explain)\b/i.test(sql)) return false;
+  return !/\b(insert|update|delete|merge|into|copy|analyze|call|do|set_config|nextval|setval|pg_(try_)?advisory\w*|pg_notify|lo_\w+|for\s+(update|share|no\s+key\s+update|key\s+share))\b/i.test(sql);
+}
+
+const text = (data, from) => data.subarray(from, data.indexOf(0, from)).toString('utf8');
+const asBuffer = (m) => Buffer.from(m.buffer, m.byteOffset, m.byteLength);
+
+/** Record, per connection, which named statements it prepared read-only (a Parse of its own or a guest's); a
+ *  PREPARE/DEALLOCATE/DISCARD sent as SQL forgets them all. */
+function noteStatement(session, message) {
+  const data = asBuffer(message);
+  if (data[0] === 0x51 /* Q */ && /\b(prepare|deallocate|discard)\b/i.test(text(data, 5))) session.statements.clear();
+  else if (data[0] === 0x50 /* P */) {
+    const name = text(data, 5);
+    session.statements.set(name, readOnlySql(text(data, 5 + Buffer.byteLength(name) + 1)));
+  } else if (data[0] === 0x43 /* C */ && data[5] === 0x53 /* S */) {
+    session.statements.delete(text(data, 6));
+  }
+}
+
+/** Whether a guest may run this message: a Query or Parse of read-only SQL, a Bind of a statement this connection
+ *  prepared read-only (the unnamed one included), and the batch's Describe/Execute/Sync/Flush/Close. */
+function guestMessageAllowed(session, message) {
+  const data = asBuffer(message);
+  switch (data[0]) {
+    case 0x51: return readOnlySql(text(data, 5)); // Q
+    case 0x50: { const name = text(data, 5); return readOnlySql(text(data, 5 + Buffer.byteLength(name) + 1)); } // P
+    case 0x42: { // B: portal name, then statement name; the unnamed one only as this batch parsed it
+      const portal = text(data, 5);
+      const statement = text(data, 5 + Buffer.byteLength(portal) + 1);
+      if (statement === '') return session.guestOpen && session.guestUnnamed === true;
+      return session.statements.get(statement) === true;
+    }
+    case 0x44: case 0x45: case 0x53: case 0x48: case 0x43: return session.guestOpen; // D E S H C, inside its batch
+    default: return false;
+  }
+}
+
+/** An ErrorResponse (and nothing else): the guest batch refused mid-way. */
+function errorResponse(code, message) {
+  const fields = ['SERROR', 'VERROR', `C${code}`, `M${message}`];
+  const body = Buffer.concat([...fields.map((f) => Buffer.from(`${f}\0`)), Buffer.from([0])]);
+  const head = Buffer.alloc(5);
+  head[0] = 0x45;
+  head.writeInt32BE(body.length + 4, 1);
+  return Buffer.concat([head, body]);
+}
+const READY_IDLE = Buffer.from([0x5a, 0, 0, 0, 5, 0x49]);
+
+/** A statement of the host's own around a guest; its failure (the holder's transaction already gone) is not fatal. */
+async function quiet(db, sql) {
+  try { await db.query(sql); } catch { /* the savepoint went with the transaction */ }
+}
+
+/** `response` with its last ReadyForQuery reporting `status`. */
+function withReadyStatus(response, status) {
+  const out = Buffer.from(response);
+  let offset = 0;
+  let at = -1;
+  while (offset + 5 <= out.length) {
+    const length = out.readInt32BE(offset + 1);
+    if (length < 4) break;
+    if (out[offset] === 0x5a && offset + 5 < out.length) at = offset + 5;
+    offset += 1 + length;
+  }
+  if (at >= 0) out[at] = status.charCodeAt(0);
+  return out;
+}
+
+/** Postgres's FATAL for a session past idle_in_transaction_session_timeout
+ * (postgres.c: ERRCODE_IDLE_IN_TRANSACTION_SESSION_TIMEOUT, 25P03). */
+function idleInTransactionFatal() {
+  const fields = ['SFATAL', 'VFATAL', 'C25P03', 'Mterminating connection due to idle-in-transaction timeout'];
+  const body = Buffer.concat([...fields.map((f) => Buffer.from(`${f}\0`)), Buffer.from([0])]);
+  const head = Buffer.alloc(5);
+  head[0] = 0x45; // 'E'
+  head.writeInt32BE(body.length + 4, 1);
+  return Buffer.concat([head, body]);
 }
 
+// the holder idle in its transaction past the limit while others wait: end it
+const idleWatch = setInterval(() => {
+  // a guest holding its turn past GUEST_TURN_MS while others wait: its batch is refused, its savepoint undone
+  if (guestBatch !== null && waiters.length > 0 && Date.now() - guestStartedAt > GUEST_TURN_MS) {
+    const guest = sessions.get(guestBatch);
+    const expired = guestBatch;
+    if (guest && guest.guestRefused && !guest.guestRunning) {
+      // a refused batch that never sends its Sync: its savepoint is already undone; its turn ends
+      guest.guestRefused = false;
+      guest.guestExpired = true;
+      guest.guestErrorSent = true;
+      const host = sessions.get(holder);
+      if (host) host.idleSince += Date.now() - guestStartedAt;
+      guestBatch = null;
+      wakeAll();
+    } else if (guest && guest.guestOpen && !guest.guestRunning) {
+      guest.guestOpen = false;
+      guest.guestUnnamed = false;
+      guest.guestExpired = true;
+      void dbReady.then(async (db) => {
+        await quiet(db, 'ROLLBACK TO SAVEPOINT volter_guest');
+        await quiet(db, 'RELEASE SAVEPOINT volter_guest');
+      }).then(() => {
+        if (guestBatch !== expired) return;
+        const host = sessions.get(holder);
+        if (host) host.idleSince += Date.now() - guestStartedAt;
+        guestBatch = null;
+        wakeAll();
+      });
+    }
+  }
+  if (holder === null || waiters.length === 0) return;
+  const session = sessions.get(holder);
+  // armed at ReadyForQuery inside a transaction, as Postgres arms it — never mid-pipeline
+  // a holder waiting for its turn (behind a guest) is sending, not idle; a guest's turn is not the holder's idleness
+  if (!session || session.busy || session.wanting || guestBatch !== null || session.terminated || (session.status !== 'T' && session.status !== 'E')) return;
+  if (Date.now() - session.idleSince < IDLE_IN_TRANSACTION_MS) return;
+  session.terminated = true;
+  process.stderr.write('pglite-host: terminated a connection idle in its transaction while others waited\n');
+  // the socket's close handler rolls the transaction back and releases the lock
+  session.socket.end(idleInTransactionFatal());
+  setTimeout(() => session.socket.destroy(), 500).unref();
+}, 250);
+idleWatch.unref();
+
 /** The transaction status of the LAST ReadyForQuery ('Z') message in a raw
  * protocol response, or null when the response carries none (mid-pipeline:
  * the sender keeps the lock). 'I' = idle, 'T' = in transaction, 'E' = failed
@@ -94,10 +374,152 @@ function lastReadyStatus(response) {
   return status;
 }
 
+// ---- CREATE DATABASE refusal -----------------------------------------------
+// PGlite accepts CREATE DATABASE (a pg_database row appears) but nothing can
+// ever connect to it: every startup database name aliases to `postgres`. A
+// client that "creates" a database and then connects to it would silently land
+// in the one real database (a Prisma shadow database would replay migrations
+// into it; a test runner would treat it as disposable). So the statement fails:
+// - naming the connection's OWN startup database (or `postgres`), with 42P04
+//   duplicate_database — true, since that name connects, and the answer
+//   check-then-create setup (`rails db:create`) tolerates;
+// - naming any other database, with 0A000 feature_not_supported, because a
+//   tool that treats 42P04 as "reuse it" would then connect to the alias of
+//   the real database and treat it as disposable.
+// The statement text is rewritten to a DO block that raises, so the BACKEND
+// reports the error and owns the protocol and transaction state
+// (ErrorResponse, aborted block, ReadyForQuery) as for any failing statement.
+//
+// COPY … FROM STDIN is refused the same way (0A000): PGlite 0.5.8 has no
+// copy-in sub-protocol over execProtocolRaw — the statement aborts the WASM
+// backend ("Program terminated with exit(1)") and every later call hangs, so
+// one bulk load would take the World's database down. COPY … TO STDOUT works.
+const LEADING = String.raw`^\s*(?:(?:--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)\s*)*`;
+const CREATE_DATABASE = new RegExp(`${LEADING}create\\s+database\\s+("(?:[^"]|"")+"|[^\\s;]+)?`, 'i');
+// Any statement of the text (a multi-statement Query included), comments
+// removed first, that begins with COPY and reaches FROM STDIN before its `;`.
+// Deliberately broad: a string literal holding such text is refused too,
+// the price of never letting one through.
+const COMMENTS = /--[^\n]*|\/\*[\s\S]*?\*\//g;
+const COPY_FROM_STDIN = /(?:^|;)\s*copy\b[^;]*?\bfrom\s+stdin\b/i;
+const DOLLAR_TAG = '$pglite_host$';
+const quoted = (text) => `'${text.replaceAll("'", "''")}'`;
+const raising = (errcode, message, detail, hint) => `DO ${DOLLAR_TAG} BEGIN RAISE EXCEPTION USING `
+  + `ERRCODE = '${errcode}', MESSAGE = ${quoted(message)}, DETAIL = ${quoted(detail)}, HINT = ${quoted(hint)}; `
+  + `END ${DOLLAR_TAG}`;
+
+/** The DO block refusing CREATE DATABASE `name` (unquoted as Postgres folds
+ * it; undefined when unparseable) on a connection whose startup database is
+ * `own`, in plain SQL literal quoting. */
+function refusal(name, own) {
+  const label = name && !name.includes(DOLLAR_TAG) ? ` "${name}"` : '';
+  const exists = name !== undefined && (name === own || name === 'postgres');
+  const detail = "The World's PGlite backing serves ONE database; every database name a client connects with is an alias for it, so CREATE DATABASE cannot make a separate one.";
+  const hint = 'Use the database named in DATABASE_URL, or run the World with a container runtime for multiple databases.';
+  return exists
+    ? raising('duplicate_database', `database${label} already exists`, detail, hint)
+    : raising('feature_not_supported', `CREATE DATABASE${label} is not supported: this World serves one database`, detail, hint);
+}
+
+const COPY_REFUSAL = raising('feature_not_supported',
+  "COPY FROM STDIN is not supported by the World's PGlite backing",
+  'PGlite has no copy-in protocol over the wire; the statement would abort the one database backend.',
+  'Load rows with INSERT (multi-row VALUES or batched statements), or run the World with a container runtime.');
+
+/** The replacement SQL for a statement this host refuses, or null. */
+function refusalFor(sql, own) {
+  const database = CREATE_DATABASE.exec(sql);
+  if (database) {
+    const spelled = database[1];
+    return refusal(spelled?.startsWith('"') ? spelled.slice(1, -1).replaceAll('""', '"') : spelled?.toLowerCase(), own);
+  }
+  return COPY_FROM_STDIN.test(sql.replace(COMMENTS, ' ')) ? COPY_REFUSAL : null;
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function cstringEnd(bytes, start) {
+  const end = bytes.indexOf(0, start);
+  return end < 0 ? bytes.length : end;
+}
+
+/** A frontend Query ('Q') or Parse ('P') message whose SQL this host refuses
+ * (CREATE DATABASE, COPY FROM STDIN), with that SQL replaced by its raising DO
+ * block; any other message is returned unchanged. `own` is the connection's
+ * startup database name. */
+function refuseStatements(message, own) {
+  const type = message[0];
+  if (type !== 0x51 /* 'Q' */ && type !== 0x50 /* 'P' */) return message;
+  // Parse = name\0 query\0 params…; Query = query\0
+  const queryStart = type === 0x50 ? cstringEnd(message, 5) + 1 : 5;
+  if (queryStart >= message.length) return message;
+  const queryEnd = cstringEnd(message, queryStart);
+  const replacement = refusalFor(decoder.decode(message.subarray(queryStart, queryEnd)), own);
+  if (replacement === null) return message;
+  const sql = encoder.encode(replacement);
+  const tail = message.subarray(queryEnd); // the query's NUL and, for Parse, its parameter types
+  const out = new Uint8Array(queryStart + sql.length + tail.length);
+  out.set(message.subarray(0, queryStart));
+  out.set(sql, queryStart);
+  out.set(tail, queryStart + sql.length);
+  new DataView(out.buffer).setInt32(1, out.length - 1);
+  return out;
+}
+
+// ---- extended-protocol error recovery --------------------------------------
+// Postgres answers an error inside an extended-protocol batch (Parse / Bind /
+// Describe / Execute) with ErrorResponse alone, discards messages until Sync,
+// and sends ONE ReadyForQuery for the Sync. PGlite's execProtocolRaw, fed one
+// message at a time, appends a ReadyForQuery to the ErrorResponse at once and
+// then answers the Sync with a second one. The client counts two and every
+// later result shifts by one (pg then crashes on a null handler). So the
+// ReadyForQuery that follows an error from an extended-protocol message is
+// dropped; the Sync's own one ends the batch (and releases the lock). Messages
+// that end a simple cycle — Query, Sync, FunctionCall, CopyDone, CopyFail —
+// keep theirs: Postgres always answers them with one.
+// Measured on PGlite 0.5.8 by feeding execProtocolRaw directly: Parse of
+// `SELECT 1/0` -> ParseComplete, Bind -> E Z(I), Execute -> nothing,
+// Sync -> Z(I).
+function withoutEarlyReady(message, response) {
+  const type = message[0];
+  // Query, Sync, FunctionCall, CopyDone, CopyFail
+  if (type === 0x51 || type === 0x53 || type === 0x46 || type === 0x63 || type === 0x66) return response;
+  let sawError = false;
+  let offset = 0;
+  while (offset + 5 <= response.length) {
+    const kind = response[offset];
+    const length = (response[offset + 1] << 24) | (response[offset + 2] << 16)
+      | (response[offset + 3] << 8) | response[offset + 4];
+    if (length < 4) return response; // malformed; pass through untouched
+    const end = offset + 1 + length;
+    if (kind === 0x45 /* 'E' */) sawError = true;
+    if (kind === 0x5a /* 'Z' */ && sawError) {
+      const out = new Uint8Array(response.length - (end - offset));
+      out.set(response.subarray(0, offset));
+      out.set(response.subarray(end), offset);
+      return out;
+    }
+    offset = end;
+  }
+  return response;
+}
+
 const server = net.createServer(async (socket) => {
   const token = {};
   let holding = false;
+  const session = { socket, busy: false, idleSince: Date.now(), terminated: false, closed: false, status: null, midBatch: false,
+    wanting: false, guestOpen: false, guestRefused: false, guestUnnamed: false, guestExpired: false, guestErrorSent: false, guestRunning: false, statements: new Map() };
+  sessions.set(token, session);
   socket.on('close', () => {
+    session.closed = true;
+    sessions.delete(token);
+    if (guestBatch === token) {
+      // a guest gone mid-batch: undo what it did in the holder's transaction
+      void dbReady
+        .then(async (db) => { if (session.guestOpen) { await quiet(db, 'ROLLBACK TO SAVEPOINT volter_guest'); await quiet(db, 'RELEASE SAVEPOINT volter_guest'); } })
+        .then(() => { session.guestOpen = false; guestBatch = null; wakeAll(); });
+      return;
+    }
     if (!holding) return;
     // the client vanished inside its transaction: roll it back, then let the
     // next connection in — never leak a half-open transaction into a stranger
@@ -113,16 +535,100 @@ const server = net.createServer(async (socket) => {
   await fromNodeSocket(socket, {
     serverVersion: '18.3 (PGlite)',
     auth: { method: 'trust' },
-    async onMessage(data, { isAuthenticated }) {
+    async onMessage(data, { isAuthenticated, clientParams }) {
       if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
       const db = await dbReady;
-      await acquire(token);
+      // a guest whose turn ran out: told once, the rest of its batch dropped until its Sync
+      if (session.guestExpired) {
+        if (data[0] === 0x53) { session.guestExpired = false; session.guestErrorSent = false; session.status = 'I'; return READY_IDLE; }
+        if (session.guestErrorSent) return new Uint8Array(0);
+        session.guestErrorSent = true;
+        return errorResponse('57014', 'the containerless Postgres (one session) cancelled this read: it ran beside another connection\'s open transaction longer than its turn allows');
+      }
+      const role = await enter(token, session, data);
+      if (role === 'guest') {
+        if (session.closed) return undefined;
+        const own = clientParams?.database || clientParams?.user;
+        const sync = data[0] === 0x53;
+        const endGuest = () => {
+          session.guestOpen = false;
+          session.guestRefused = false;
+          session.status = 'I';
+          guestBatch = null;
+          session.guestUnnamed = false;
+          // the holder's idle clock stops while a guest runs, and goes on from where it was
+          const host = sessions.get(holder);
+          if (host) host.idleSince += Date.now() - guestStartedAt;
+          wakeAll();
+        };
+        // a batch refused mid-way: its remaining messages are dropped until its Sync, as Postgres skips after an error
+        if (session.guestRefused) {
+          if (sync) { endGuest(); return READY_IDLE; }
+          return new Uint8Array(0);
+        }
+        if (session.guestOpen && !guestMessageAllowed(session, data)) {
+          session.guestRunning = true; // the expiry waits until this refusal is done
+          await quiet(db, 'ROLLBACK TO SAVEPOINT volter_guest');
+          await quiet(db, 'RELEASE SAVEPOINT volter_guest');
+          session.guestOpen = false;
+          session.guestRefused = true;
+          session.guestRunning = false;
+          return errorResponse('0A000', 'the containerless Postgres (one session) runs only reads beside another connection\'s open transaction; this batch began with a read and went on to write');
+        }
+        if (!session.guestOpen) { await quiet(db, 'SAVEPOINT volter_guest'); session.guestOpen = true; }
+        noteStatement(session, data);
+        if (data[0] === 0x50 && text(asBuffer(data), 5) === '') session.guestUnnamed = true;
+        let raw;
+        session.guestRunning = true;
+        try {
+          raw = await db.execProtocolRaw(refuseStatements(data, own));
+        } catch (error) {
+          process.stderr.write(`pglite-host: backend aborted: ${error?.message ?? error}\n`);
+          process.exit(1);
+        }
+        const response = withoutEarlyReady(data, raw);
+        const status = lastReadyStatus(response);
+        if (status === null) { session.guestRunning = false; return response; } // mid-batch: the guest keeps its turn until its Sync
+        // the savepoint is gone if the holder's transaction ended meanwhile (its socket closed): quiet, not fatal
+        if (status === 'E') await quiet(db, 'ROLLBACK TO SAVEPOINT volter_guest');
+        await quiet(db, 'RELEASE SAVEPOINT volter_guest');
+        session.guestRunning = false; // the batch has ended: nothing left for the expiry to cancel
+        endGuest();
+        return withReadyStatus(response, 'I');
+      }
+      // closed (or cut) while it waited: give the lock up without running the
+      // message — a Terminate run now would leave no ReadyForQuery to release it
+      if (session.closed || session.terminated) {
+        session.busy = false;
+        if (!holding) release(token);
+        return undefined;
+      }
       holding = true;
-      const response = await db.execProtocolRaw(data);
+      session.busy = true;
+      noteStatement(session, data);
+      // libpq's default: no database parameter means the user's name
+      const own = clientParams?.database || clientParams?.user;
+      let raw;
+      try {
+        raw = await db.execProtocolRaw(refuseStatements(data, own));
+      } catch (error) {
+        // SQL errors arrive as ErrorResponse bytes; a throw means the WASM
+        // backend itself aborted and every later call would hang. Exit so the
+        // World sees the service down (status fails) instead of a wedged port.
+        process.stderr.write(`pglite-host: backend aborted: ${error?.message ?? error}\n`);
+        process.exit(1);
+      }
+      session.busy = false;
+      session.idleSince = Date.now();
+      const response = withoutEarlyReady(data, raw);
       const status = lastReadyStatus(response);
+      session.midBatch = status === null;
+      if (status !== null) session.status = status;
       if (status === 'I') {
         holding = false;
         release(token);
+      } else if (status === 'T') {
+        wakeAll(); // idle in its transaction: a waiting reader may now run as a guest
       }
       return response;
     },

package/dist/src/prerequisites.js

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
 const realRunner = (cmd, args) => {
-    const result = spawnSync(cmd, args, { encoding: 'utf8' });
+    const result = spawnSync(cmd, args, { windowsHide: true, encoding: 'utf8' });
     return {
         status: result.status,
         stdout: result.stdout || '',

package/dist/src/process-groups.js

@@ -22,7 +22,7 @@ export function survivingOwnedGroups(pids) {
     });
     if (!candidates.length || process.platform === 'win32')
         return candidates;
-    const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], {
+    const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], { windowsHide: true,
         encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024,
     });
     if (result.status !== 0 || result.error)

package/dist/src/redirect-proxy.d.ts

@@ -11,7 +11,7 @@ import { type CaTrustInputs } from './ca-trust.js';
  *    the host was MITM'd, i.e. the host IS twinned in this world — so the bare "no twin for host"
  *    sent readers hunting for a `*_TWIN_URL` that was already set. On a shared host the path may
  *    belong to a vendor whose twin merely is not configured (youtube vs googleauth), OR to no pack
- *    at all (Google Calendar on www.googleapis.com has no twin yet) — the message states both,
+ *    at all (Google Drive on www.googleapis.com has no twin yet) — the message states both,
  *    because this refusal is exactly what replaced the silent mis-route that answered Calendar
  *    calls with plausible Google-shaped 404s from the gemini pack.
  */

package/dist/src/redirect-proxy.js

@@ -46,7 +46,7 @@ import { sessionTrustEnv } from "./ca-trust.js";
  *    the host was MITM'd, i.e. the host IS twinned in this world — so the bare "no twin for host"
  *    sent readers hunting for a `*_TWIN_URL` that was already set. On a shared host the path may
  *    belong to a vendor whose twin merely is not configured (youtube vs googleauth), OR to no pack
- *    at all (Google Calendar on www.googleapis.com has no twin yet) — the message states both,
+ *    at all (Google Drive on www.googleapis.com has no twin yet) — the message states both,
  *    because this refusal is exactly what replaced the silent mis-route that answered Calendar
  *    calls with plausible Google-shaped 404s from the gemini pack.
  */
@@ -55,7 +55,7 @@ export function noTwinMessage(host, path) {
         + 'This host is shared between vendors, and no pack in this world serves this path. Either the\n'
         + 'vendor that owns this path has a twin that is not configured — set its *_TWIN_URL (for\n'
         + 'www.googleapis.com: YOUTUBE_TWIN_URL serves /youtube/v3/*, GOOGLEAUTH_TWIN_URL serves the\n'
-        + 'OAuth2 token paths) — or this API has no twin pack yet (e.g. Google Calendar /calendar/v3/*),\n'
+        + 'OAuth2 token paths) — or this API has no twin pack yet (e.g. Google Drive /drive/v3/*),\n'
         + 'in which case this loud refusal is the honest outcome: the request is neither answered by the\n'
         + 'wrong twin nor leaked to the real vendor.\n';
 }
@@ -199,11 +199,11 @@ export function opensslAvailable() {
     // this env var in real usage.
     if (process.env.VOLTER_TEST_NO_OPENSSL === '1')
         return false;
-    const r = spawnSync('openssl', ['version'], { stdio: 'ignore' });
+    const r = spawnSync('openssl', ['version'], { windowsHide: true, stdio: 'ignore' });
     return r.status === 0;
 }
 function runOpenssl(args) {
-    const r = spawnSync('openssl', args, { encoding: 'utf8' });
+    const r = spawnSync('openssl', args, { windowsHide: true, encoding: 'utf8' });
     if (r.status !== 0)
         throw new Error(`openssl ${args[0]} failed: ${(r.stderr || r.stdout || '').trim()}`);
     return r.stdout;