@volter/world-runtime 3.0.49 → 3.0.51

package/dist/src/pglite-host.mjs

@@ -10,11 +10,13 @@
 // server starts listening only once the backend is ready, so a port that
 // answers is a port that serves.
 //
-// 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.
+// 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.
 //
 // Extensions: every contrib extension PGlite 0.5.8 ships (CONTRIB below) plus
 // pgvector (`vector`, from @electric-sql/pglite-pgvector, pinned to the
@@ -38,11 +40,20 @@
 //   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 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.
+// - ONE backend session, with concurrent wire connections and driver pools.
+//   A complete implicit statement or explicit transaction owns it until the
+//   backend reports idle; other connections' reads and writes wait their turn.
+//   No reader borrows another connection's open transaction. An idle holder
+//   is not terminated to admit a waiter. Cross-connection work awaited inside
+//   a transaction must wait for that transaction to finish.
+//   Session SET, temp tables and session advisory locks remain shared across
+//   transactions and outlive their connection; pg_try_advisory_lock on a key
+//   another connection holds sees the same session and returns true. NOTIFY
+//   answers its sender, not an independent listener, and pg_backend_pid is
+//   shared. Existing prepared-name scoping supports pooled Prisma clients;
+//   SQL spellings outside its handled forms remain shared. Select native or
+//   container PostgreSQL for independent sessions; no gateway emulation of
+//   locks, isolation or session state supplies those semantics.
 //
 // Database timestamps use the World clock: PGlite reads Date.now() for now(),
 // CURRENT_TIMESTAMP, clock_timestamp() and transaction starts. Refresh the file
@@ -152,14 +163,272 @@ dbReady.catch((error) => {
   process.exit(1);
 });
 
-// ---- 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.' });
+// ---- transaction-affinity lock ---------------------------------------------
+let holder = null;
+const waiters = [];
+const sessions = new Map();
+/** Reserve the next complete protocol cycle/transaction in arrival order. */
+function enter(token, session) {
+  if (session.closed) return Promise.resolve(false);
+  if (holder === token) return Promise.resolve(true);
+  if (holder === null && !waiters.length) {
+    holder = token;
+    return Promise.resolve(true);
+  }
+  return new Promise(resolve => waiters.push({ token, session, resolve }));
+}
+function release(token) {
+  if (holder !== token) return;
+  holder = null;
+  while (waiters.length) {
+    const next = waiters.shift();
+    if (next.session.closed) { next.resolve(false); continue; }
+    holder = next.token;
+    next.resolve(true);
+    break;
+  }
+}
+function cancelWait(token) {
+  const index = waiters.findIndex(waiter => waiter.token === token);
+  if (index < 0) return;
+  waiters.splice(index, 1)[0].resolve(false);
+}
+
+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));
+  }
+}
+
+/** 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;
 }
 
 // ---- CREATE DATABASE refusal -----------------------------------------------
@@ -254,7 +523,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. Messages
+// 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
@@ -285,22 +554,25 @@ function withoutEarlyReady(message, response) {
 }
 
 const server = net.createServer((socket) => {
-  const session = { closed: false, pending: Promise.resolve() };
+  const token = {};
+  const session = { closed: false, status: null, midBatch: false, names: new Map(), work: Promise.resolve() };
+  sessions.set(token, session);
   socket.on('close', () => {
     session.closed = true;
-    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 () => {
+    sessions.delete(token);
+    releaseStatements(session);
+    cancelWait(token);
+    if (holder !== token) return;
+    // Keep ownership while any in-flight message finishes. Sync clears a
+    // disconnected extended-protocol error state, then the real backend rolls
+    // back the holder before another connection can enter its transaction.
+    void session.work.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;
+      await db.execProtocolRaw(new Uint8Array([0x53, 0, 0, 0, 4]));
+      await db.query('ROLLBACK');
+      release(token);
     }).catch(error => {
-      process.stderr.write(`pglite-host: session cleanup failed: ${errorMessage(error)}\n`);
+      process.stderr.write(`pglite-host: connection cleanup failed: ${errorMessage(error)}\n`);
       process.exit(1);
     });
   });
@@ -313,31 +585,40 @@ const server = net.createServer((socket) => {
       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 }) {
+    async onMessage(data, { isAuthenticated, clientParams }) {
       if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
-      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.
+      // Gateway owns Terminate; it must neither wait for a turn nor terminate
+      // the shared PostgreSQL backend. The close handler owns rollback.
       if (data[0] === 0x58) return undefined;
-      const pending = session.pending.then(async () => {
+      if (!await enter(token, session)) return undefined;
+      const work = (async () => {
         if (session.closed) return undefined;
         const db = await dbReady;
         readWorldClock();
+        if (closedStatements.length && !session.midBatch && session.status !== 'T' && session.status !== 'E') await flushClosed(db);
+        if (session.closed) return undefined;
+        const closes = closing(data);
+        data = scopeNames(session, data, true);
+        let raw;
         try {
-          const raw = await db.execProtocolRaw(refuseStatements(data, databaseName));
-          return withoutEarlyReady(data, raw);
+          raw = await db.execProtocolRaw(refuseStatements(data, clientParams?.database || clientParams?.user));
         } 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);
         }
-      });
-      session.pending = pending;
-      return pending;
+        const response = withoutEarlyReady(data, raw);
+        settleClose(session, closes, response);
+        const status = lastReadyStatus(response);
+        session.midBatch = status === null;
+        if (status !== null) session.status = status;
+        // A closed holder retains admission until its close handler confirms
+        // rollback, even if its in-flight message reported idle.
+        if (status === 'I' && !session.closed) release(token);
+        return response;
+      })();
+      session.work = work;
+      return work;
     },
   }).catch(error => {
     process.stderr.write(`pglite-host: wire connection failed: ${errorMessage(error)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.49",
+  "version": "3.0.51",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -69,14 +69,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.49",
-    "@volter/world-console": "3.0.44"
+    "@volter/world-core": "3.0.51",
+    "@volter/world-console": "3.0.46"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.49",
+    "@volter/world-core": "3.0.51",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/pglite-host.mjs

@@ -10,11 +10,13 @@
 // server starts listening only once the backend is ready, so a port that
 // answers is a port that serves.
 //
-// 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.
+// 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.
 //
 // Extensions: every contrib extension PGlite 0.5.8 ships (CONTRIB below) plus
 // pgvector (`vector`, from @electric-sql/pglite-pgvector, pinned to the
@@ -38,11 +40,20 @@
 //   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 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.
+// - ONE backend session, with concurrent wire connections and driver pools.
+//   A complete implicit statement or explicit transaction owns it until the
+//   backend reports idle; other connections' reads and writes wait their turn.
+//   No reader borrows another connection's open transaction. An idle holder
+//   is not terminated to admit a waiter. Cross-connection work awaited inside
+//   a transaction must wait for that transaction to finish.
+//   Session SET, temp tables and session advisory locks remain shared across
+//   transactions and outlive their connection; pg_try_advisory_lock on a key
+//   another connection holds sees the same session and returns true. NOTIFY
+//   answers its sender, not an independent listener, and pg_backend_pid is
+//   shared. Existing prepared-name scoping supports pooled Prisma clients;
+//   SQL spellings outside its handled forms remain shared. Select native or
+//   container PostgreSQL for independent sessions; no gateway emulation of
+//   locks, isolation or session state supplies those semantics.
 //
 // Database timestamps use the World clock: PGlite reads Date.now() for now(),
 // CURRENT_TIMESTAMP, clock_timestamp() and transaction starts. Refresh the file
@@ -152,14 +163,272 @@ dbReady.catch((error) => {
   process.exit(1);
 });
 
-// ---- 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.' });
+// ---- transaction-affinity lock ---------------------------------------------
+let holder = null;
+const waiters = [];
+const sessions = new Map();
+/** Reserve the next complete protocol cycle/transaction in arrival order. */
+function enter(token, session) {
+  if (session.closed) return Promise.resolve(false);
+  if (holder === token) return Promise.resolve(true);
+  if (holder === null && !waiters.length) {
+    holder = token;
+    return Promise.resolve(true);
+  }
+  return new Promise(resolve => waiters.push({ token, session, resolve }));
+}
+function release(token) {
+  if (holder !== token) return;
+  holder = null;
+  while (waiters.length) {
+    const next = waiters.shift();
+    if (next.session.closed) { next.resolve(false); continue; }
+    holder = next.token;
+    next.resolve(true);
+    break;
+  }
+}
+function cancelWait(token) {
+  const index = waiters.findIndex(waiter => waiter.token === token);
+  if (index < 0) return;
+  waiters.splice(index, 1)[0].resolve(false);
+}
+
+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));
+  }
+}
+
+/** 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;
 }
 
 // ---- CREATE DATABASE refusal -----------------------------------------------
@@ -254,7 +523,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. Messages
+// 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
@@ -285,22 +554,25 @@ function withoutEarlyReady(message, response) {
 }
 
 const server = net.createServer((socket) => {
-  const session = { closed: false, pending: Promise.resolve() };
+  const token = {};
+  const session = { closed: false, status: null, midBatch: false, names: new Map(), work: Promise.resolve() };
+  sessions.set(token, session);
   socket.on('close', () => {
     session.closed = true;
-    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 () => {
+    sessions.delete(token);
+    releaseStatements(session);
+    cancelWait(token);
+    if (holder !== token) return;
+    // Keep ownership while any in-flight message finishes. Sync clears a
+    // disconnected extended-protocol error state, then the real backend rolls
+    // back the holder before another connection can enter its transaction.
+    void session.work.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;
+      await db.execProtocolRaw(new Uint8Array([0x53, 0, 0, 0, 4]));
+      await db.query('ROLLBACK');
+      release(token);
     }).catch(error => {
-      process.stderr.write(`pglite-host: session cleanup failed: ${errorMessage(error)}\n`);
+      process.stderr.write(`pglite-host: connection cleanup failed: ${errorMessage(error)}\n`);
       process.exit(1);
     });
   });
@@ -313,31 +585,40 @@ const server = net.createServer((socket) => {
       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 }) {
+    async onMessage(data, { isAuthenticated, clientParams }) {
       if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
-      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.
+      // Gateway owns Terminate; it must neither wait for a turn nor terminate
+      // the shared PostgreSQL backend. The close handler owns rollback.
       if (data[0] === 0x58) return undefined;
-      const pending = session.pending.then(async () => {
+      if (!await enter(token, session)) return undefined;
+      const work = (async () => {
         if (session.closed) return undefined;
         const db = await dbReady;
         readWorldClock();
+        if (closedStatements.length && !session.midBatch && session.status !== 'T' && session.status !== 'E') await flushClosed(db);
+        if (session.closed) return undefined;
+        const closes = closing(data);
+        data = scopeNames(session, data, true);
+        let raw;
         try {
-          const raw = await db.execProtocolRaw(refuseStatements(data, databaseName));
-          return withoutEarlyReady(data, raw);
+          raw = await db.execProtocolRaw(refuseStatements(data, clientParams?.database || clientParams?.user));
         } 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);
         }
-      });
-      session.pending = pending;
-      return pending;
+        const response = withoutEarlyReady(data, raw);
+        settleClose(session, closes, response);
+        const status = lastReadyStatus(response);
+        session.midBatch = status === null;
+        if (status !== null) session.status = status;
+        // A closed holder retains admission until its close handler confirms
+        // rollback, even if its in-flight message reported idle.
+        if (status === 'I' && !session.closed) release(token);
+        return response;
+      })();
+      session.work = work;
+      return work;
     },
   }).catch(error => {
     process.stderr.write(`pglite-host: wire connection failed: ${errorMessage(error)}\n`);