@volter/world-runtime 3.0.47 → 3.0.49

package/dist/src/pglite-host.mjs

@@ -10,13 +10,11 @@
 // server starts listening only once the backend is ready, so a port that
 // answers is a port that serves.
 //
-// PGlite is a SINGLE-SESSION backend, so this host serializes connections
-// with a transaction-affinity lock: a connection acquires the global lock at
-// its first protocol message and keeps it for as long as the backend reports
-// an open transaction (ReadyForQuery status != 'I'). Without the hold, two
-// pooled clients interleave into one session and a ROLLBACK on one swallows
-// the other's writes. A connection that dies mid-transaction is rolled back
-// before the lock is released.
+// PGlite owns one backend session. Admit one authenticated connection only,
+// keep it until disconnect cleanup finishes, and refuse concurrent sessions
+// with FATAL 53300. The native/container backing supplies independent sessions.
+// The backend performs Sync, ROLLBACK and DISCARD ALL before another client
+// enters; no isolation, advisory-lock or prepared-name behavior is simulated.
 //
 // Extensions: every contrib extension PGlite 0.5.8 ships (CONTRIB below) plus
 // pgvector (`vector`, from @electric-sql/pglite-pgvector, pinned to the
@@ -33,57 +31,18 @@
 //
 // 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.
+// - ONE declared database and login, authenticated with the World's throwaway
+//   password. Undeclared databases fail 3D000; failed logins fail 28P01.
+//   current_database() and current_user come from the configured backend.
+//   CREATE DATABASE of the declared name fails 42P04, other names fail 0A000;
+//   multiple databases require the native or 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
-//   SQL PREPAREd statements are visible to every other connection (a
-//   statement prepared over the protocol is the connection's own: a name
-//   another live connection holds is renamed for it, and its own SQL
-//   EXECUTE/DEALLOCATE of that name is renamed with it; scopeNames — except
-//   in CREATE TABLE … AS EXECUTE, a comment between the verb and the name,
-//   a Query holding a backslash, and a DEALLOCATE sent through Parse, which
-//   reach the name as the backend holds it); 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.
+// - ONE wire session, including idle connections. A second authenticated
+//   connection fails FATAL 53300. Concurrent pools and distinct backend
+//   identities require the native or container backing. Session settings,
+//   temp objects, prepared statements, transactions and locks are the backend's
+//   own and are reset before its session is reused.
 //
 // Database timestamps use the World clock: PGlite reads Date.now() for now(),
 // CURRENT_TIMESTAMP, clock_timestamp() and transaction starts. Refresh the file
@@ -96,6 +55,7 @@ import net from 'node:net';
 import { mkdirSync, readFileSync } from 'node:fs';
 import clockForm from '@volter/world-core/world-clock';
 import { fromNodeSocket } from 'pg-gateway/node';
+import { BackendError } from 'pg-gateway';
 
 // ---- the World's time (above) --------------------------------
 const machineNow = Date.now.bind(Date);
@@ -147,6 +107,13 @@ function arg(name) {
 
 const port = Number(arg('--port'));
 const dataDir = arg('--data');
+const databaseUser = process.env.VOLTER_WORLD_PGLITE_USER;
+const databaseName = process.env.VOLTER_WORLD_PGLITE_DATABASE;
+const databasePassword = process.env.VOLTER_WORLD_PGLITE_PASSWORD;
+if (![databaseUser, databaseName, databasePassword].every(value => typeof value === 'string' && value.length > 0)) {
+  process.stderr.write('pglite-host: declared database identity and throwaway password are required\n');
+  process.exit(2);
+}
 if (!Number.isInteger(port) || port < 1 || port > 65535) {
   process.stderr.write('pglite-host: --port must be 1-65535\n');
   process.exit(2);
@@ -159,482 +126,46 @@ 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, extensions });
+const quoteIdentifier = value => `"${value.replaceAll('"', '""')}"`;
+async function openDeclaredDatabase() {
+  // PostgreSQL cannot rename its current database. Use its maintenance database
+  // before opening the declared one; old Worlds' rows in postgres stay intact.
+  const maintenance = await PGlite.create({ dataDir, extensions, database: 'template1' });
+  try {
+    const existing = await maintenance.query('SELECT datname FROM pg_database WHERE datname = $1', [databaseName]);
+    if (!existing.rows.length) {
+      const legacy = await maintenance.query("SELECT datname FROM pg_database WHERE datname = 'postgres'");
+      await maintenance.exec(legacy.rows.length
+        ? `ALTER DATABASE postgres RENAME TO ${quoteIdentifier(databaseName)}`
+        : `CREATE DATABASE ${quoteIdentifier(databaseName)}`);
+    }
+    const role = await maintenance.query('SELECT rolname FROM pg_roles WHERE rolname = $1', [databaseUser]);
+    if (!role.rows.length) await maintenance.exec(`CREATE ROLE ${quoteIdentifier(databaseUser)} LOGIN SUPERUSER`);
+  } finally { await maintenance.close(); }
+  const db = await PGlite.create({ dataDir, extensions, database: databaseName });
+  await db.exec(`SET SESSION AUTHORIZATION ${quoteIdentifier(databaseUser)}`);
+  return db;
+}
+const dbReady = openDeclaredDatabase();
 dbReady.catch((error) => {
   process.stderr.write(`pglite-host: backend failed to start: ${errorMessage(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 = [];
-/** 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 = machineNow();
-        return 'guest';
-      }
-    }
-    if (holder === token) session.wanting = true;
-    await new Promise((resolve) => waiters.push(resolve));
-  }
-}
-function release(token) {
-  if (holder !== token) return;
-  holder = null;
-  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);
-
-/** Prepared statements' protocol names each connection gives, kept apart where they would collide.
- *  Every connection shares the one backend session, and a client names its statements per connection: Prisma's engine
- *  starts each process at `s0`, so a second process's first Parse met "prepared statement "s0" already exists" (Postiz
- *  walk postiz-2: sign-up, and the post workflow's first read, which left no timer to publish the post). A name no other
- *  live connection holds goes to the backend as the client gave it, so SQL on it works as on Postgres; one another
- *  live connection holds goes as a short name of the host's own (`volter_s<N>`), and the connection's own simple-Query
- *  DEALLOCATE or EXECUTE of it is rewritten to match (sqlNames). Names are compared on their first 63 bytes, as Postgres compares them
- *  (NAMEDATALEN), and handled as bytes, never decoded. A closed connection's statements are closed on the next turn
- *  that begins outside any transaction (flushClosed). */
-const NAMEDATALEN = 63;
-/** backend statement name (latin1 of its bytes, first 63) -> the session holding it */
-const heldStatements = new Map();
-/** backend statement names of closed connections, closed at the next clean turn */
-const closedStatements = [];
-let renamed = 0;
-/** A name no statement has: what another connection's statement name is, to a connection that never prepared it. */
-const UNPREPARED = Buffer.from('volter_unprepared', 'latin1');
-const nameKey = (bytes) => bytes.subarray(0, NAMEDATALEN).toString('latin1');
-
-/** The name at `from` (its bytes, to the NUL) and where the field after it starts. */
-function cstring(data, from) {
-  const end = data.indexOf(0, from);
-  return { bytes: data.subarray(from, end), next: end + 1 };
-}
-
-/** The backend's name for a statement this connection names `bytes`; `claim` (a Parse on the connection's turn) takes
- *  one for a new statement, anything else only looks its name up. */
-function statementName(session, bytes, claim) {
-  if (bytes.length === 0) return bytes;
-  const own = session.names.get(bytes.toString('latin1'));
-  if (own) return own;
-  if (!claim) {
-    // a statement it never prepared: the backend answers as Postgres does, never with another live connection's
-    // statement of that name (it would not exist in this connection's own session)
-    const holder = heldStatements.get(nameKey(bytes));
-    return holder && holder !== session && !holder.closed ? UNPREPARED : bytes;
-  }
-  const key = nameKey(bytes);
-  const holder = heldStatements.get(key);
-  const backend = holder && holder !== session ? Buffer.from(`volter_s${(renamed += 1)}`, 'latin1') : bytes;
-  heldStatements.set(nameKey(backend), session);
-  session.names.set(bytes.toString('latin1'), backend);
-  return backend;
-}
-
-/** The message with its statement names as the backend knows them. Portals keep the client's names: a named portal
- *  lives only inside its transaction, and one transaction runs at a time. */
-function scopeNames(session, message, claim) {
-  const data = asBuffer(message);
-  const kind = data[0];
-  let parts;
-  if (kind === 0x50 /* P */) {
-    const name = cstring(data, 5);
-    parts = [statementName(session, name.bytes, claim), Buffer.from([0]), data.subarray(name.next)];
-  } else if (kind === 0x42 /* B */) {
-    const portal = cstring(data, 5);
-    const statement = cstring(data, portal.next);
-    parts = [data.subarray(5, portal.next), statementName(session, statement.bytes, false), Buffer.from([0]), data.subarray(statement.next)];
-  } else if ((kind === 0x44 /* D */ || kind === 0x43 /* C */) && data[5] === 0x53 /* S */) {
-    const name = cstring(data, 6);
-    const backend = statementName(session, name.bytes, false);
-    parts = [data.subarray(5, 6), backend, Buffer.from([0]), data.subarray(name.next)];
-  } else if (kind === 0x51 /* Q */ && claim) {
-    return sqlNames(session, message);
-  } else {
-    return message;
-  }
-  const body = Buffer.concat(parts);
-  if (body.length === data.length - 5 && body.equals(data.subarray(5))) return message;
-  const out = Buffer.alloc(5 + body.length);
-  out[0] = kind;
-  out.writeInt32BE(4 + body.length, 1);
-  body.copy(out, 5);
-  return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
-}
-
-/** A statement of a simple Query that DEALLOCATEs or EXECUTEs one statement, at the statement's start: the verb
- *  (EXPLAIN's options before EXECUTE included) and the name, quoted or not. */
-const STATEMENT_NAMED = /^((?:EXPLAIN\s+(?:\([^)]*\)\s*)?(?:ANALYZE\s+)?(?:VERBOSE\s+)?)?(?:DEALLOCATE\s+(?:PREPARE\s+)?|EXECUTE\s+))(?:"((?:[^"]|"")+)"|([A-Za-z_][A-Za-z0-9_$]*))(?=[\s(;]|$)/i;
-/** a quoted name as it is; an unquoted one folds to lower case, as Postgres folds it */
-const folded = (quoted, name) => (quoted !== undefined ? quoted.replace(/""/g, '"') : name.toLowerCase());
-const EMPTIES_ALL = /^(?:DEALLOCATE\s+(?:PREPARE\s+)?ALL|DISCARD\s+ALL)\s*;?\s*$/i;
-
-/** Where each statement of a Query begins, outside string literals, quoted identifiers, dollar-quoted bodies and
- *  comments (a statement's leading comments skipped), so a rewrite never touches a literal's text. */
-function statementStarts(sql) {
-  const starts = [];
-  let atStart = true;
-  for (let i = 0; i < sql.length;) {
-    const c = sql[i];
-    if (/\s/.test(c)) { i += 1; continue; }
-    if (c === '-' && sql[i + 1] === '-') { const end = sql.indexOf('\n', i); i = end < 0 ? sql.length : end + 1; continue; }
-    if (c === '/' && sql[i + 1] === '*') {
-      let depth = 1; let j = i + 2; // Postgres's block comments nest
-      while (j < sql.length && depth > 0) { if (sql.startsWith('/*', j)) { depth += 1; j += 2; } else if (sql.startsWith('*/', j)) { depth -= 1; j += 2; } else j += 1; }
-      i = j; continue;
-    }
-    if (atStart) { starts.push(i); atStart = false; }
-    if (c === ';') { atStart = true; i += 1; continue; }
-    if (c === "'" || c === '"') {
-      // E'…' takes backslash escapes; a plain '…' and "…" end at their quote, a doubled one inside
-      const escapes = c === "'" && /[Ee]/.test(sql[i - 1] ?? '') && !/[A-Za-z0-9_]/.test(sql[i - 2] ?? '');
-      let j = i + 1;
-      while (j < sql.length) {
-        if (escapes && sql[j] === '\\') { j += 2; continue; }
-        if (sql[j] === c) { if (sql[j + 1] === c) { j += 2; continue; } break; }
-        j += 1;
-      }
-      i = j + 1; continue;
-    }
-    // a `$` inside an identifier (`a$b$c`) opens nothing, as Postgres's lexer reads it
-    const dollar = c === '$' && !/[A-Za-z0-9_$]/.test(sql[i - 1] ?? '') ? /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i)) : null;
-    if (dollar) { const end = sql.indexOf(dollar[0], i + dollar[0].length); i = end < 0 ? sql.length : end + dollar[0].length; continue; }
-    i += 1;
-  }
-  return starts;
-}
-
-/** Each statement of the Query that DEALLOCATEs or EXECUTEs one name: where it is, its verb and the name. */
-function namedStatements(sql) {
-  const out = [];
-  for (const at of statementStarts(sql)) {
-    const m = STATEMENT_NAMED.exec(sql.slice(at));
-    if (m) out.push({ at, length: m[0].length, verb: m[1], name: folded(m[2], m[3]) });
-  }
-  return out;
-}
-
-/** A simple Query's DEALLOCATE or EXECUTE of a statement this connection prepared under a name of the host's own
- *  (another connection held the client's), or of a name another live connection holds: the statement it means, never
- *  the other connection's. Only statements' own text is rewritten (statementStarts); CREATE TABLE … AS EXECUTE and
- *  a DEALLOCATE sent through Parse are not. */
-function sqlNames(session, message) {
-  const data = asBuffer(message);
-  const sql = data.subarray(5, data.indexOf(0, 5)).toString('latin1');
-  // a backslash can end a plain '…' literal (standard_conforming_strings off, which one connection can set for the
-  // shared session): such a Query is not read, as statementSkeleton does not read one
-  if (sql.includes('\\')) return message;
-  let text = sql;
-  for (const n of namedStatements(sql).reverse()) {
-    const backend = statementName(session, Buffer.from(n.name, 'latin1'), false).toString('latin1');
-    if (backend !== n.name) text = `${text.slice(0, n.at)}${n.verb}"${backend}"${text.slice(n.at + n.length)}`;
-  }
-  if (text === sql) return message;
-  const body = Buffer.concat([Buffer.from(text, 'latin1'), Buffer.from([0])]);
-  const out = Buffer.alloc(5 + body.length);
-  out[0] = 0x51;
-  out.writeInt32BE(4 + body.length, 1);
-  body.copy(out, 5);
-  return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
-}
-
-/** What a client message closes: a statement (Close 'S', or a Query that is one DEALLOCATE), by the client's name,
- *  or ALL (a Query that is one DEALLOCATE ALL or DISCARD ALL, emptying the one session's statements, every
- *  connection's, as they did before scoping). */
-const ALL = Symbol('all');
-function closing(message) {
-  const data = asBuffer(message);
-  if (data[0] === 0x43 && data[5] === 0x53) { const name = cstring(data, 6).bytes; return name.length ? name : undefined; }
-  if (data[0] === 0x51) {
-    // one statement alone in its Query (one inside a longer Query settles when the connection closes)
-    const sql = data.subarray(5, data.indexOf(0, 5)).toString('latin1');
-    const starts = statementStarts(sql);
-    if (starts.length !== 1 && !(starts.length === 2 && /^;\s*$/.test(sql.slice(starts[1])))) return undefined;
-    if (EMPTIES_ALL.test(sql.slice(starts[0]))) return ALL;
-    const named = namedStatements(sql);
-    if (named.length === 1 && /^DEALLOCATE/i.test(named[0].verb)) return Buffer.from(named[0].name, 'latin1');
-  }
-  return undefined;
-}
-
-/** Free what a message closed once the backend has answered it: CloseComplete ('3') or the DEALLOCATE's
- *  CommandComplete ('C') first; a Close Postgres skipped (an earlier error in its batch) frees nothing. */
-function settleClose(session, name, response) {
-  if (!name || !response || !response.length || (response[0] !== 0x33 && response[0] !== 0x43)) return;
-  if (name === ALL) {
-    heldStatements.clear();
-    for (const other of sessions.values()) other.names.clear();
-  } else forget(session, name);
-}
-
-/** A statement the connection closed (Close 'S'): its backend name is free again. */
-function forget(session, bytes) {
-  const backend = session.names.get(bytes.toString('latin1'));
-  if (!backend) return;
-  session.names.delete(bytes.toString('latin1'));
-  if (heldStatements.get(nameKey(backend)) === session) heldStatements.delete(nameKey(backend));
-}
-
-/** A closed connection's statements, to close on the next clean turn (a leak otherwise: each connection's statements
- *  outlived it in the one session, 300 short connections x 20 statements aborted the backend). */
-function releaseStatements(session) {
-  for (const backend of session.names.values()) if (heldStatements.get(nameKey(backend)) === session) closedStatements.push(backend);
-  session.names.clear();
-}
-
-/** Close closed connections' statements with the protocol's Close (a SQL DEALLOCATE would replace the unnamed
- *  statement a batch may still Bind), at the start of a turn outside any transaction. */
-async function flushClosed(db) {
-  while (closedStatements.length) {
-    const backend = closedStatements.shift();
-    const body = Buffer.concat([Buffer.from('S', 'latin1'), backend, Buffer.from([0])]);
-    const close = Buffer.alloc(5 + body.length);
-    close[0] = 0x43;
-    close.writeInt32BE(4 + body.length, 1);
-    body.copy(close, 5);
-    try {
-      await db.execProtocolRaw(new Uint8Array(close));
-      await db.execProtocolRaw(new Uint8Array([0x53, 0, 0, 0, 4])); // Sync
-    } catch (error) { process.stderr.write(`pglite-host: statement cleanup failed: ${errorMessage(error)}\n`); }
-    if (heldStatements.get(nameKey(backend))?.closed) heldStatements.delete(nameKey(backend));
-  }
-}
-
-/** 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 (error) {
-    if (error?.code !== '3B001' && error?.code !== '25P01') throw error;
-  }
-}
-
-/** `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 && machineNow() - 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 += machineNow() - 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 += machineNow() - 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 (machineNow() - 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
- * transaction. */
-function lastReadyStatus(response) {
-  let status = null;
-  let offset = 0;
-  while (offset + 5 <= response.length) {
-    const type = response[offset];
-    const length = (response[offset + 1] << 24) | (response[offset + 2] << 16)
-      | (response[offset + 3] << 8) | response[offset + 4];
-    if (length < 4) break; // malformed; stop scanning rather than loop
-    if (type === 0x5a /* 'Z' */ && offset + 5 < response.length) {
-      status = String.fromCharCode(response[offset + 5]);
-    }
-    offset += 1 + length;
-  }
-  return status;
+// ---- exclusive backend session ---------------------------------------------
+let activeSession = null;
+const SYNC = new Uint8Array([0x53, 0, 0, 0, 4]);
+const SESSION_GAP = 'World PGlite supports one PostgreSQL session; select the native or container backing for concurrent connections';
+function concurrentSession() {
+  return BackendError.create({ severity: 'FATAL', code: '53300', message: SESSION_GAP,
+    detail: 'PGlite has one PostgreSQL backend session; separate wire connections cannot share its transactions or session state faithfully.',
+    hint: 'Select VOLTER_WORLD_INFRA_BACKING=native with PostgreSQL installed, or use the container backing.' });
 }
 
 // ---- 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.
+// Only the declared database can be connected to. Creating another catalog
+// row would advertise a database this service cannot serve, so the statement
+// fails: 42P04 for the declared name, 0A000 for another name.
 // 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.
@@ -662,9 +193,9 @@ const raising = (errcode, message, detail, hint) => `DO ${DOLLAR_TAG} BEGIN RAIS
  * `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.';
+  const exists = name !== undefined && name === own;
+  const detail = "The World's PGlite backing serves ONE database; only its declared database can be connected to, so CREATE DATABASE cannot make a separately served one.";
+  const hint = 'Use the database named in DATABASE_URL, or select the native PostgreSQL or container backing 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);
@@ -723,7 +254,7 @@ function refuseStatements(message, own) {
 // 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
+// dropped; the Sync's own one ends the batch. 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
@@ -753,148 +284,64 @@ function withoutEarlyReady(message, response) {
   return response;
 }
 
-const server = net.createServer(async (socket) => {
-  const token = {};
-  let holding = false;
-  const session = { socket, busy: false, idleSince: machineNow(), 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(),
-    names: new Map() };
-  sessions.set(token, session);
+const server = net.createServer((socket) => {
+  const session = { closed: false, pending: Promise.resolve() };
   socket.on('close', () => {
     session.closed = true;
-    sessions.delete(token);
-    releaseStatements(session);
-    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
-    void dbReady
-      .then((db) => db.query('ROLLBACK'))
-      .catch(error => { process.stderr.write(`pglite-host: connection cleanup failed: ${errorMessage(error)}\n`); })
-      .then(() => {
-        holding = false;
-        release(token);
-      });
+    if (activeSession !== session) return;
+    // Admission stays reserved through pending messages and confirmed reset.
+    // Sync also clears a disconnected extended-protocol batch's error state.
+    void session.pending.then(async () => {
+      const db = await dbReady;
+      readWorldClock();
+      await db.execProtocolRaw(SYNC);
+      await db.exec('ROLLBACK');
+      await db.exec('DISCARD ALL');
+      await db.exec(`SET SESSION AUTHORIZATION ${quoteIdentifier(databaseUser)}`);
+      activeSession = null;
+    }).catch(error => {
+      process.stderr.write(`pglite-host: session cleanup failed: ${errorMessage(error)}\n`);
+      process.exit(1);
+    });
   });
   socket.on('error', () => { /* close handler owns cleanup */ });
-  await fromNodeSocket(socket, {
+  void fromNodeSocket(socket, {
     serverVersion: '18.3 (PGlite)',
-    auth: { method: 'trust' },
-    async onMessage(data, { isAuthenticated, clientParams }) {
+    auth: { method: 'password', getClearTextPassword: () => databasePassword,
+      validateCredentials: ({ username, password }) => username === databaseUser && password === databasePassword },
+    onStartup({ clientParams }) {
+      const requested = clientParams?.database || clientParams?.user;
+      if (requested !== databaseName) throw BackendError.create({ severity: 'FATAL', code: '3D000', message: `database "${requested}" does not exist` });
+    },
+    onAuthenticated() {
+      if (activeSession !== null) throw concurrentSession();
+      if (!session.closed) activeSession = session;
+    },
+    onMessage(data, { isAuthenticated }) {
       if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
-      const client = data;
-      const closes = closing(client);
-      // looked up, not claimed, while the turn is decided: a Parse claims its name on the connection's own turn,
-      // after the closed connections' names are released (a reconnect's `s0` is its own again)
-      data = scopeNames(session, client, false);
-      const db = await dbReady;
-      readWorldClock();
-      // 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 (activeSession !== session) throw concurrentSession();
+      // Gateway owns Terminate; sending it to the shared backend would end the
+      // backend itself. Disconnect cleanup resets its session instead.
+      if (data[0] === 0x58) return undefined;
+      const pending = session.pending.then(async () => {
         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 += machineNow() - 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; }
-        data = scopeNames(session, client, true);
-        noteStatement(session, data);
-        if (data[0] === 0x50 && text(asBuffer(data), 5) === '') session.guestUnnamed = true;
-        let raw;
-        session.guestRunning = true;
+        const db = await dbReady;
+        readWorldClock();
         try {
-          raw = await db.execProtocolRaw(refuseStatements(data, own));
+          const raw = await db.execProtocolRaw(refuseStatements(data, databaseName));
+          return withoutEarlyReady(data, raw);
         } catch (error) {
+          // SQL errors arrive as protocol bytes. A throw is a backend failure.
           process.stderr.write(`pglite-host: backend aborted: ${errorMessage(error)}\n`);
           process.exit(1);
         }
-        const response = withoutEarlyReady(data, raw);
-        settleClose(session, closes, response);
-        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;
-      session.busy = true;
-      // a turn that begins outside any transaction first closes what closed connections left
-      if (closedStatements.length && !session.midBatch && session.status !== 'T' && session.status !== 'E') await flushClosed(await dbReady);
-      data = scopeNames(session, client, 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: ${errorMessage(error)}\n`);
-        process.exit(1);
-      }
-      session.busy = false;
-      session.idleSince = machineNow();
-      const response = withoutEarlyReady(data, raw);
-      settleClose(session, closes, response);
-      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;
+      });
+      session.pending = pending;
+      return pending;
     },
+  }).catch(error => {
+    process.stderr.write(`pglite-host: wire connection failed: ${errorMessage(error)}\n`);
+    socket.destroy();
   });
 });