turbine-orm 0.29.0 → 0.31.0

package/dist/powdb.js

@@ -24,6 +24,11 @@
  *     impossible → it degrades to batched N+1 loaders (Phase B).
  *   - **Single global write lock; no savepoints/isolation** — nested
  *     transactions / isolation / vector / LISTEN-NOTIFY / RLS throw.
+ *     Independent concurrent `db.$transaction` calls do NOT throw: they queue
+ *     FIFO on a pool-level gate and run one at a time (see {@link PowdbTxGate}).
+ *     Only a *re-entrant* transaction — a `db.$transaction` opened from inside
+ *     an active transaction callback's async context, which queueing would
+ *     deadlock — fails fast with E017.
  *   - **The wire protocol pipelines** — `@zvndev/powdb-client` writes each
  *     request frame immediately and matches replies FIFO, so multiple queries
  *     may be in flight on one connection. {@link PowdbPool}'s checked-out
@@ -47,9 +52,11 @@
  *
  * @module
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { TurbineClient, } from './client.js';
 import { postgresDialect } from './dialect.js';
 import { ConnectionError, NotNullViolationError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
+import importOptionalPeer from './optional-peer-import.cjs';
 /**
  * Capability descriptor for PowDB. PowQL generation is owned by
  * {@link PowqlInterface} (not the SQL `Dialect`), so this dialect exists only to
@@ -65,9 +72,11 @@ import { ConnectionError, NotNullViolationError, TimeoutError, UniqueConstraintE
  *     {@link UnsupportedFeatureError} (E017): a nested `tx.$transaction` emits a
  *     savepoint synchronously (before any DB call) and so fails fast with a
  *     clear typed error instead of leaking PowDB's cryptic `Parse(... 'sp_1')`.
- *     The pool-level begin-while-active guard (see {@link PowdbPool}) catches the
- *     other re-entrant shape — a fresh top-level `db.$transaction` opened inside
- *     an already-open one — before it can deadlock on the write lock.
+ *     The pool-level transaction gate (see {@link PowdbTxGate}) handles the
+ *     other shapes: a fresh top-level `db.$transaction` opened inside an
+ *     already-open one throws E017 before it can deadlock on the write lock,
+ *     while INDEPENDENT concurrent `db.$transaction` calls queue FIFO and run
+ *     one at a time instead of failing.
  * Isolation levels remain Phase B.
  */
 export const powdbDialect = {
@@ -212,6 +221,125 @@ function isDateColumn(col) {
  * `auto` modifier, so PowDB assigns a monotonic id on insert and Turbine stops
  * synthesizing a client-side value for it.
  */
+/**
+ * PowQL reserved words — the v0.10 lexer keyword table from POWQL.md's
+ * "Reserved Words and Quoting" section, including the v0.10 additions
+ * `schema` and `describe`. Keyword matching is case-sensitive in the lexer,
+ * so only the exact lowercase form collides.
+ */
+export const POWQL_KEYWORDS = new Set([
+    'abs',
+    'add',
+    'alter',
+    'and',
+    'as',
+    'asc',
+    'auto',
+    'avg',
+    'begin',
+    'between',
+    'case',
+    'cast',
+    'ceil',
+    'column',
+    'commit',
+    'concat',
+    'conflict',
+    'count',
+    'cross',
+    'date_add',
+    'date_diff',
+    'default',
+    'delete',
+    'dense_rank',
+    'desc',
+    'describe',
+    'distinct',
+    'drop',
+    'else',
+    'end',
+    'exists',
+    'explain',
+    'extract',
+    'false',
+    'filter',
+    'floor',
+    'group',
+    'having',
+    'in',
+    'index',
+    'inner',
+    'insert',
+    'is',
+    'join',
+    'left',
+    'length',
+    'let',
+    'like',
+    'limit',
+    'link',
+    'lower',
+    'match',
+    'materialize',
+    'materialized',
+    'max',
+    'min',
+    'multi',
+    'not',
+    'now',
+    'null',
+    'offset',
+    'on',
+    'or',
+    'order',
+    'outer',
+    'over',
+    'partition',
+    'pow',
+    'rank',
+    'refresh',
+    'required',
+    'returning',
+    'right',
+    'rollback',
+    'round',
+    'row_number',
+    'schema',
+    'select',
+    'sqrt',
+    'substring',
+    'sum',
+    'then',
+    'transaction',
+    'trim',
+    'true',
+    'type',
+    'union',
+    'unique',
+    'update',
+    'upper',
+    'upsert',
+    'view',
+    'when',
+]);
+const POWQL_BARE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Backtick-quote an identifier when PowQL would otherwise lex it as a keyword
+ * (or when it contains characters outside the bare-identifier grammar).
+ * Applied only in bare-identifier positions — DDL type/field names, index DDL,
+ * and `insert`/`update`/`upsert` assignment targets. Dotted references
+ * (`.col` in filters/projections/ordering) bypass keyword lookup on every
+ * engine version and deliberately stay bare for ≤0.9 compatibility. Backticks
+ * parse on PowDB ≥ 0.10; on older engines these names were already parse
+ * errors when emitted bare, so quoting is strictly an improvement.
+ */
+export function quotePowqlIdent(name) {
+    if (name.includes('`')) {
+        // The lexer has no backtick escape inside a quoted identifier.
+        throw new ValidationError(`[turbine] Identifier "${name}" contains a backtick, which PowQL cannot represent.`);
+    }
+    return POWQL_KEYWORDS.has(name) || !POWQL_BARE_IDENT.test(name) ? `\`${name}\`` : name;
+}
 export function powqlSchemaDDL(schema) {
     const stmts = [];
     for (const meta of Object.values(schema.tables)) {
@@ -233,13 +361,13 @@ export function powqlSchemaDDL(schema) {
             // a plain typed column (Turbine assigns the value client-side instead).
             if (col.isGenerated && powqlColumnType(col) === 'int')
                 mods.push('auto');
-            return `  ${mods.join(' ')}${mods.length ? ' ' : ''}${col.name}: ${powqlColumnType(col)}`;
+            return `  ${mods.join(' ')}${mods.length ? ' ' : ''}${quotePowqlIdent(col.name)}: ${powqlColumnType(col)}`;
         });
-        stmts.push(`type ${meta.name} {\n${fields.join(',\n')}\n}`);
+        stmts.push(`type ${quotePowqlIdent(meta.name)} {\n${fields.join(',\n')}\n}`);
         // Secondary unique constraints (beyond the PK) become unique indexes.
         for (const uniq of meta.uniqueColumns) {
             if (uniq.length === 1 && !pkSet.has(uniq[0])) {
-                stmts.push(`alter ${meta.name} add unique .${uniq[0]}`);
+                stmts.push(`alter ${quotePowqlIdent(meta.name)} add unique .${quotePowqlIdent(uniq[0])}`);
             }
         }
     }
@@ -339,6 +467,17 @@ export function wrapPowdbError(err) {
         const m = /column ['"]?(\w+)['"]?/i.exec(msg);
         return new NotNullViolationError({ column: m?.[1], cause: err });
     }
+    // Driver pool lifecycle errors (acquire after close, acquire timeout) carry
+    // no .code — classify by message so both transports surface E004.
+    if (/pool closed|pool acquire timeout/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB connection unavailable: ${msg}`);
+    }
+    // Server-side transaction-gate wait bound (PowDB ≥ 0.10, default 5s): another
+    // connection held the single global write lock past the server's
+    // --tx-wait-timeout-ms. Retryable timeout, not a query defect.
+    if (/transaction gate timeout/i.test(msg)) {
+        return new TimeoutError(0, 'PowDB transaction gate');
+    }
     // Type mismatch / parse / execution / storage / unexpected → validation
     // (E003). On the embedded transport these are the only signal we get
     // (code is always 'GenericFailure'); on the networked path they are a
@@ -384,15 +523,161 @@ function txControl(powql) {
     return null;
 }
 /**
- * The error a pool throws when a `begin` arrives while a transaction is already
- * open. PowDB has ONE global write lock and supports neither concurrent nor
- * nested transactions: on the networked transport a second `begin` checks out a
- * fresh pooled connection and blocks forever on the lock the open transaction
- * holds. This guard converts that hang into a fast, typed error.
+ * The error a pool throws when a `begin` arrives from INSIDE an already-open
+ * transaction's async context (a re-entrant `db.$transaction`). PowDB has ONE
+ * global write lock and no savepoints: queueing a re-entrant transaction would
+ * deadlock (the outer callback awaits the inner transaction, which waits on
+ * the write lock the outer transaction holds), and on the networked transport
+ * it would block a fresh pooled connection on the lock forever. This guard
+ * converts that hang into a fast, typed error. Independent concurrent
+ * transactions do NOT hit this — they queue FIFO on {@link PowdbTxGate}.
  */
 function reentrantTransactionError() {
-    return new UnsupportedFeatureError('concurrent or nested transactions', 'powdb', 'PowDB is single-writer — it has one global write lock. A second transaction would block on it forever; ' +
-        'complete the open transaction first.');
+    return new UnsupportedFeatureError('re-entrant transactions', 'powdb', 'PowDB is single-writer — a transaction opened from inside an active transaction callback would deadlock ' +
+        'on the write lock the open transaction holds. Use the `tx` client the callback receives, or start the ' +
+        'second transaction after the first completes. (Independent concurrent transactions queue automatically.)');
+}
+// ---------------------------------------------------------------------------
+// Single-writer transaction gate — FIFO queueing + re-entrancy detection
+// ---------------------------------------------------------------------------
+/**
+ * Default cap (ms) on how long a `begin` may wait in the FIFO queue for
+ * PowDB's single global write lock before failing with a typed
+ * {@link TimeoutError} (E002). Prevents silent starvation behind a wedged
+ * transaction. Override via `transactionQueueTimeoutMs`
+ * ({@link TurbinePowdbOptions} / {@link PowdbPoolOptions}); `0` or `Infinity`
+ * waits without limit.
+ */
+export const DEFAULT_TX_QUEUE_TIMEOUT_MS = 30_000;
+/**
+ * Upper bound on the best-effort `rollback` a release-with-open-hold fires
+ * before handing the gate to the next queued transaction. Keeps a dead socket
+ * from wedging the FIFO queue while still letting the engine drop its global
+ * write lock cleanly in the normal case.
+ */
+const RELEASE_ROLLBACK_TIMEOUT_MS = 2_000;
+const powdbTxStorage = new AsyncLocalStorage();
+/**
+ * FIFO gate serializing transactions across a whole pool. PowDB holds one
+ * global write lock, so at most one transaction may be open per database:
+ * without this gate a second `begin` on the networked transport checks out a
+ * fresh connection and blocks forever on the lock the open transaction holds
+ * (and the embedded engine rejects it with a raw parse error).
+ *
+ * `acquire()` is called (synchronously, see below) for every `begin`:
+ *   - a **re-entrant** `begin` — issued from inside an active transaction's
+ *     async context, detected via {@link powdbTxStorage} — throws E017
+ *     immediately. Queueing it can never succeed: the open transaction cannot
+ *     commit while its callback awaits the queued one.
+ *   - an **independent** `begin` waits its FIFO turn, bounded by the queue
+ *     timeout, then returns a {@link PowdbTxHold} the caller finishes on
+ *     commit / rollback / connection release.
+ *
+ * Context propagation: `acquire()` only READS the async context (the
+ * chain-walking check in its prologue); it never writes it. The marker is
+ * planted by the pool's `wrapTransactionCallback` (`TurbineClient` invokes
+ * the user callback as `powdbTxStorage.run(hold.ctx, fn)`), so it exists
+ * exclusively inside the transaction CALLBACK's async subtree. Everything
+ * launched from inside the callback (table ops on the `tx` client, a
+ * fire-and-forget `db.$transaction`, nested-write implicit transactions)
+ * inherits it; the CALLER's context stays unmarked. This is load-bearing: the
+ * pre-0.31 implementation used `enterWith()` in acquire's prologue, which
+ * mutates the caller's shared context. On a cold client the FIRST same-tick
+ * burst of `db.$transaction` calls saw call #1's live marker from every
+ * sibling and falsely threw re-entrant E017 (9/10 rejected in production;
+ * one warm-up transaction masked it because its pruned `done` marker changed
+ * the propagation shape). With `run()` the sibling contexts are unmarked by
+ * construction, so they queue FIFO as intended. Markers form a chain
+ * ({@link PowdbTxContext.parent}) so transactions nested across DIFFERENT
+ * pools cannot shadow an outer marker on this gate; the re-entrancy check
+ * walks every live ancestor.
+ *
+ * **Residual limitation:** a transaction begun OUTSIDE a `$transaction`
+ * callback plants no marker (a manual raw `begin` span, or a worker loop
+ * whose continuations captured their context before the transaction opened).
+ * A deadlocking re-entrant begin from such a context cannot be told apart
+ * from a legitimate independent concurrent transaction: it queues FIFO and,
+ * because the open transaction is awaiting it, times out after
+ * `transactionQueueTimeoutMs` with a typed {@link TimeoutError} rather than
+ * throwing E017 instantly. The 30s default is the backstop for exactly this
+ * case: do not set `transactionQueueTimeoutMs: 0` (wait forever) in code
+ * paths that may start transactions from unmarked contexts.
+ */
+class PowdbTxGate {
+    queueTimeoutMs;
+    /** Tail of the FIFO queue — resolves once every earlier transaction has finished. */
+    tail = Promise.resolve();
+    constructor(queueTimeoutMs) {
+        this.queueTimeoutMs = queueTimeoutMs;
+    }
+    /**
+     * Take a place in the transaction queue. The prologue walks the caller's
+     * marker chain (planted around transaction callbacks by the pool's
+     * `wrapTransactionCallback`) and throws re-entrant E017 when any live
+     * ancestor holds THIS gate. It never marks the caller's context itself;
+     * the returned hold carries the fresh marker (`hold.ctx`) for
+     * `wrapTransactionCallback` to scope around the user callback.
+     */
+    async acquire() {
+        // Walk the WHOLE marker chain, not just the innermost marker: with two
+        // pools, dbA-tx → dbB-tx → dbA-begin leaves dbB's marker innermost, but
+        // the dbA ancestor is still open — queueing the inner dbA begin behind it
+        // would deadlock. Any live ancestor on this gate ⇒ re-entrant E017.
+        // Prune completed heads first (`done` never flips back) so sequential
+        // transactions issued from one long-lived context do not chain — and leak
+        // — unboundedly; what remains is bounded by real nesting depth.
+        let parent = powdbTxStorage.getStore();
+        while (parent?.done)
+            parent = parent.parent;
+        for (let c = parent; c !== undefined; c = c.parent) {
+            if (c.gate === this && !c.done) {
+                throw reentrantTransactionError();
+            }
+        }
+        const ctx = { gate: this, done: false, parent };
+        let handOff;
+        const finished = new Promise((resolve) => {
+            handOff = resolve;
+        });
+        const ahead = this.tail;
+        this.tail = ahead.then(() => finished);
+        const hold = {
+            ctx,
+            finish: () => {
+                if (ctx.done)
+                    return;
+                ctx.done = true;
+                handOff();
+            },
+        };
+        // --- FIFO wait (optionally bounded) ---
+        const timeoutMs = this.queueTimeoutMs;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            await ahead;
+            return hold;
+        }
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                // Give up the queue slot: finishing resolves our `finished` link, so
+                // once every transaction ahead completes, later waiters skip straight
+                // past us instead of stalling behind a slot nobody will release.
+                hold.finish();
+                reject(new TimeoutError(timeoutMs, 'PowDB transaction (queued behind the single-writer lock)'));
+            }, timeoutMs);
+            void ahead.then(() => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+        return hold;
+    }
 }
 /** Adapt a PowDB result into the pg-compat `{ rows, rowCount, fields }` shape. */
 function adaptResult(r) {
@@ -426,49 +711,87 @@ export class PowdbPool {
     toParam;
     closed = false;
     /**
-     * Pool-level single-writer guard. PowDB holds one global write lock, so at
-     * most one transaction may be open across the whole pool. A `begin` issued
-     * while this is `true` is rejected (it would otherwise check out a second
-     * connection and block on the lock forever — the networked re-entrant hang).
+     * Pool-level single-writer gate. PowDB holds one global write lock, so at
+     * most one transaction may be open across the whole pool. Concurrent
+     * `begin`s queue FIFO on the gate (instead of checking out a second
+     * connection and blocking on the lock forever — the networked hang);
+     * re-entrant `begin`s throw E017 (see {@link PowdbTxGate}).
+     */
+    txGate;
+    /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
+    poolHold = null;
+    /**
+     * Clients currently checked out via {@link connect}. The driver pool's
+     * `close()` only closes IDLE clients (checked-out ones are documented as the
+     * caller's responsibility), so {@link end} destroys these explicitly;
+     * otherwise a `disconnect()` racing an unreleased connection would leave a
+     * live socket holding the process open until the server's idle timeout.
      */
-    activeTransaction = false;
-    constructor(pool, toParam = (v) => toPowdbParam(v)) {
+    checkedOut = new Set();
+    constructor(pool, toParam = (v) => toPowdbParam(v), options = {}) {
         this.pool = pool;
         this.toParam = toParam;
+        this.txGate = new PowdbTxGate(options.transactionQueueTimeoutMs ?? DEFAULT_TX_QUEUE_TIMEOUT_MS);
     }
-    /**
-     * Enforce the single-writer model on a transaction-control statement. Throws
-     * (before any query runs) if a `begin` arrives while a transaction is open;
-     * otherwise flips the pool-level flag. Returns the control kind so the caller
-     * can decide whether it even needs to hit the engine.
-     */
-    guardTxControl(powql) {
+    // biome-ignore lint/suspicious/noExplicitAny: pg-compat query is generic over the row shape.
+    async query(text, values) {
+        this.assertOpen();
+        const { text: powql, params } = normalizeQueryArgs(text, values);
         const ctl = txControl(powql);
         if (ctl === 'begin') {
-            if (this.activeTransaction)
-                throw reentrantTransactionError();
-            this.activeTransaction = true;
+            // Gate BEFORE touching the engine: a begin from inside an active
+            // transaction callback throws re-entrant E017 fast; an independent
+            // concurrent one waits its FIFO turn.
+            this.poolHold = await this.txGate.acquire();
         }
-        else if (ctl === 'commit' || ctl === 'rollback') {
-            this.activeTransaction = false;
+        if ((ctl === 'commit' || ctl === 'rollback') && this.poolHold === null) {
+            // No gate hold → our `begin` never ran (gate timeout / re-entrant
+            // E017 / no begin at all). Never forward a stray commit/rollback to
+            // the engine — PowDB is single-writer, so it could only ever end a
+            // DIFFERENT caller's open transaction. Empty success instead.
+            return { rows: [], rowCount: 0, fields: [] };
         }
-        return ctl;
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: pg-compat query is generic over the row shape.
-    async query(text, values) {
-        const { text: powql, params } = normalizeQueryArgs(text, values);
-        this.guardTxControl(powql);
         try {
             const result = await this.pool.withClient((c) => c.query(powql, params.map(this.toParam)));
             return adaptResult(result);
         }
         catch (err) {
+            if (ctl === 'begin') {
+                this.poolHold?.finish();
+                this.poolHold = null;
+            }
             throw wrapPowdbError(err);
         }
+        finally {
+            if (ctl === 'commit' || ctl === 'rollback') {
+                this.poolHold?.finish();
+                this.poolHold = null;
+            }
+        }
+    }
+    /**
+     * Typed guard mirroring {@link PowdbEmbeddedPool}: after `end()` the driver
+     * pool throws a raw `Error('pool closed')` that {@link wrapPowdbError}
+     * cannot classify — surface the same ConnectionError on both transports.
+     */
+    assertOpen() {
+        if (this.closed) {
+            throw new ConnectionError('[turbine] The PowDB pool is closed — disconnect() was already called on this client.');
+        }
     }
     async connect() {
-        const client = await this.pool.acquire();
+        this.assertOpen();
+        let client;
+        try {
+            client = await this.pool.acquire();
+        }
+        catch (err) {
+            throw wrapPowdbError(err);
+        }
+        this.checkedOut.add(client);
         let broken = false;
+        /** The gate hold of the transaction begun through THIS connection (if any). */
+        let hold = null;
         return {
             // The networked client's query() supports concurrent in-flight calls on
             // one connection: every request frame is written to the socket
@@ -478,29 +801,100 @@ export class PowdbPool {
             // for the batch's rollback contract because a failed statement leaves
             // the engine's transaction open (no aborted state, no auto-rollback) —
             // later pipelined statements execute inside the same still-open
-            // transaction and the final `rollback` discards every effect.
+            // transaction and the final `rollback` discards every effect. (The
+            // batch path awaits `begin` before dispatching the burst, so the gate
+            // wait below never reorders statements around it.)
             supportsPipelining: true,
             // biome-ignore lint/suspicious/noExplicitAny: see query() above.
             query: async (text, values) => {
                 const { text: powql, params } = normalizeQueryArgs(text, values);
-                // Guard BEFORE acquiring the engine — a re-entrant begin throws fast
-                // instead of blocking on the global write lock the open tx holds.
-                this.guardTxControl(powql);
+                const ctl = txControl(powql);
+                if (ctl === 'begin') {
+                    // Gate BEFORE hitting the engine: a begin from inside an active
+                    // transaction callback throws re-entrant E017 fast instead of
+                    // blocking on the global write lock the open tx holds; an
+                    // independent concurrent begin queues FIFO.
+                    hold = await this.txGate.acquire();
+                }
+                if ((ctl === 'commit' || ctl === 'rollback') && hold === null) {
+                    // This connection never acquired the gate — its `begin` never ran
+                    // (gate timeout / re-entrant E017). A stray commit/rollback must
+                    // never reach the single-writer engine, where it could only end a
+                    // DIFFERENT caller's open transaction. Empty success instead.
+                    return { rows: [], rowCount: 0, fields: [] };
+                }
                 try {
                     return adaptResult(await client.query(powql, params.map(this.toParam)));
                 }
                 catch (err) {
                     broken = true;
+                    if (ctl === 'begin') {
+                        hold?.finish();
+                        hold = null;
+                    }
                     throw wrapPowdbError(err);
                 }
+                finally {
+                    if (ctl === 'commit' || ctl === 'rollback') {
+                        hold?.finish();
+                        hold = null;
+                    }
+                }
             },
-            release: () => {
-                // Releasing this connection ends its transaction scope. Clear the flag
-                // as a safety net so a tx torn down without an explicit commit/rollback
-                // (e.g. a timeout that destroys the connection) never leaves the pool
-                // permanently believing a transaction is still open.
-                this.activeTransaction = false;
-                return broken ? this.pool.destroy(client) : this.pool.release(client);
+            // Single-writer re-entrancy scoping: TurbineClient runs the user's
+            // transaction callback through this, so the gate's marker lives ONLY
+            // in the callback's async subtree (everything inside it, tx table ops
+            // and fire-and-forget db.$transaction alike, inherits it; the caller's
+            // context stays unmarked). `hold.ctx` is the same object `finish()` flips, so
+            // done-pruning keeps working for contexts that outlive the callback.
+            wrapTransactionCallback: (fn) => {
+                const ctx = hold?.ctx;
+                return ctx ? powdbTxStorage.run(ctx, fn) : fn();
+            },
+            release: (err) => {
+                // Releasing this connection ends its transaction scope. pg semantics:
+                // a truthy `err` means "destroy, don't re-idle" — client.ts's
+                // $transaction timeout path relies on that to keep an abandoned
+                // callback's connection out of the pool. Additionally, an OPEN hold
+                // here means the tx begun on this connection never saw commit/rollback
+                // (timeout teardown or caller bug): fire a best-effort bounded
+                // `rollback` FIRST so the engine drops its global write lock and the
+                // server-side transaction ends (destroying the socket alone leaves it
+                // open until the server's idle timeout), THEN hand the gate to the
+                // next queued transaction. If the rollback fails or times out the
+                // connection is treated as broken and destroyed. Never throws — a
+                // teardown error must not mask the transaction's real outcome.
+                const openHold = hold;
+                hold = null;
+                this.checkedOut.delete(client);
+                const teardown = async () => {
+                    let rolledBack = false;
+                    if (openHold) {
+                        try {
+                            await Promise.race([
+                                client.query('rollback', []).then(() => {
+                                    rolledBack = true;
+                                }),
+                                new Promise((resolve) => {
+                                    const t = setTimeout(resolve, RELEASE_ROLLBACK_TIMEOUT_MS);
+                                    t.unref?.();
+                                }),
+                            ]);
+                        }
+                        catch {
+                            /* best-effort */
+                        }
+                        openHold.finish();
+                    }
+                    const mustDestroy = broken || Boolean(err) || (openHold !== null && !rolledBack);
+                    try {
+                        await (mustDestroy ? this.pool.destroy(client) : this.pool.release(client));
+                    }
+                    catch {
+                        /* the pool may already be closed */
+                    }
+                };
+                void teardown();
             },
         };
     }
@@ -508,7 +902,16 @@ export class PowdbPool {
         if (this.closed)
             return;
         this.closed = true;
+        // close() rejects pending waiters and closes every IDLE client…
         await this.pool.close();
+        // …but NOT checked-out ones (documented in @zvndev/powdb-client: "callers
+        // that still hold one when close() is called are responsible for closing
+        // it themselves"). Destroy any stragglers so end() never leaves a live
+        // socket keeping the process alive until the server's idle timeout.
+        for (const client of this.checkedOut) {
+            this.pool.destroy(client);
+        }
+        this.checkedOut.clear();
     }
 }
 /** Normalize the embedded addon's loosely-typed result into a {@link PowdbResult}. */
@@ -612,57 +1015,112 @@ export class PowdbEmbeddedPool {
     db;
     closed = false;
     /**
-     * Single-writer guard. The embedded engine is one handle with one global
+     * Single-writer gate. The embedded engine is one handle with one global
      * write lock — only one transaction may be open at a time. A re-entrant
-     * `begin` (a fresh top-level `db.$transaction` opened inside an open one)
-     * would otherwise hit PowDB's raw "already in a transaction" parse error;
-     * this surfaces a typed error instead. (Nested `tx.$transaction` is caught
-     * earlier still, by the savepoint override in {@link powdbDialect}.)
+     * `begin` (a fresh top-level `db.$transaction` opened inside an open one's
+     * callback) would otherwise hit PowDB's raw "already in a transaction"
+     * parse error; the gate surfaces a typed E017 instead, while INDEPENDENT
+     * concurrent transactions queue FIFO and run one at a time. (Nested
+     * `tx.$transaction` is caught earlier still, by the savepoint override in
+     * {@link powdbDialect}.)
      */
-    activeTransaction = false;
-    constructor(db) {
+    txGate;
+    /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
+    poolHoldRef = { hold: null };
+    constructor(db, options = {}) {
         this.db = db;
+        this.txGate = new PowdbTxGate(options.transactionQueueTimeoutMs ?? DEFAULT_TX_QUEUE_TIMEOUT_MS);
+    }
+    /** Materialize `$N` params and hand the PowQL to the in-process engine. */
+    exec(powql, params) {
+        const materialized = materializePowql(powql, params);
+        return adaptResult(normalizeEmbeddedResult(this.db.query(materialized)));
     }
-    /** Enforce the single-writer model on a transaction-control statement. */
-    guardTxControl(powql) {
+    /**
+     * Run one statement, gating transaction control. `holdRef` scopes the gate
+     * hold to whoever issued the `begin` (the pool itself or one checked-out
+     * client), so finishing a transaction can never release a slot a different
+     * transaction is holding.
+     */
+    async run(powql, params, holdRef) {
+        if (this.closed) {
+            throw new ConnectionError('[turbine] The PowDB embedded pool is closed: disconnect() was already called on this client.');
+        }
         const ctl = txControl(powql);
         if (ctl === 'begin') {
-            if (this.activeTransaction)
-                throw reentrantTransactionError();
-            this.activeTransaction = true;
+            // Gate BEFORE hitting the engine: a begin from inside an active
+            // transaction callback throws re-entrant E017 fast; independent
+            // concurrent ones wait their FIFO turn.
+            holdRef.hold = await this.txGate.acquire();
         }
-        else if (ctl === 'commit' || ctl === 'rollback') {
-            this.activeTransaction = false;
+        if ((ctl === 'commit' || ctl === 'rollback') && holdRef.hold === null) {
+            // This context never acquired the gate — its `begin` never ran (the
+            // gate timed out / threw re-entrant E017, or no begin was issued at
+            // all). The engine is ONE shared handle: forwarding this stray
+            // commit/rollback would hit whatever transaction ANOTHER caller has
+            // open on it (live-reproduced: a best-effort ROLLBACK after a failed
+            // begin silently discarded a concurrent transaction's writes). Swallow
+            // it as an empty success instead — there is nothing of ours to end.
+            return { rows: [], rowCount: 0, fields: [] };
         }
-    }
-    run(powql, params) {
-        this.guardTxControl(powql);
         try {
-            const materialized = materializePowql(powql, params);
-            return adaptResult(normalizeEmbeddedResult(this.db.query(materialized)));
+            return this.exec(powql, params);
         }
         catch (err) {
+            if (ctl === 'begin') {
+                holdRef.hold?.finish();
+                holdRef.hold = null;
+            }
             throw wrapPowdbError(err);
         }
+        finally {
+            if (ctl === 'commit' || ctl === 'rollback') {
+                holdRef.hold?.finish();
+                holdRef.hold = null;
+            }
+        }
     }
     // biome-ignore lint/suspicious/noExplicitAny: pg-compat query is generic over the row shape.
     async query(text, values) {
         const { text: powql, params } = normalizeQueryArgs(text, values);
-        return this.run(powql, params);
+        return this.run(powql, params, this.poolHoldRef);
     }
     async connect() {
         // Single in-process handle — the "client" shares the one Database; tx
-        // keywords run serially on it.
+        // keywords run serially on it. Each checked-out client scopes its own
+        // gate hold so release() only ever finishes ITS transaction.
+        const holdRef = { hold: null };
         return {
             // biome-ignore lint/suspicious/noExplicitAny: see query() above.
             query: async (text, values) => {
                 const { text: powql, params } = normalizeQueryArgs(text, values);
-                return this.run(powql, params);
+                return this.run(powql, params, holdRef);
+            },
+            // Scope the gate's re-entrancy marker to the user callback's async
+            // subtree (see PowdbPool.connect(), identical contract).
+            wrapTransactionCallback: (fn) => {
+                const ctx = holdRef.hold?.ctx;
+                return ctx ? powdbTxStorage.run(ctx, fn) : fn();
             },
             release: () => {
                 // End-of-scope safety net (see PowdbPool.connect()): a tx torn down
-                // without an explicit commit/rollback must not wedge the handle.
-                this.activeTransaction = false;
+                // without an explicit commit/rollback must not wedge the queue — and
+                // on the ONE shared embedded handle its open engine transaction must
+                // actually be rolled back before the gate moves on, or the next
+                // transaction's work interleaves into it. run() owns the
+                // finish/null-out in its commit/rollback finally; the .finally here
+                // is the fallback when run() itself rejects.
+                const h = holdRef.hold;
+                if (!h)
+                    return;
+                void this.run('rollback', [], holdRef)
+                    .catch(() => {
+                    /* best-effort */
+                })
+                    .finally(() => {
+                    h.finish();
+                    holdRef.hold = null;
+                });
             },
         };
     }
@@ -670,8 +1128,11 @@ export class PowdbEmbeddedPool {
         if (this.closed)
             return;
         // The addon exposes no explicit close — drop the reference and let GC /
-        // the engine's checkpoint flush. Caveat: durability is checkpoint-bound, so
-        // hold the process open long enough for the final WAL flush in short scripts.
+        // the engine's checkpoint flush. Marking the pool closed makes later
+        // queries fail with a typed ConnectionError instead of silently running
+        // against a handle the caller believes is gone. Caveat: durability is
+        // checkpoint-bound, so hold the process open long enough for the final
+        // WAL flush in short scripts.
         this.closed = true;
     }
 }
@@ -685,10 +1146,14 @@ export { PowqlInterface } from './powql.js';
  */
 async function loadPowdb() {
     try {
-        return (await import('@zvndev/powdb-client'));
+        // Via the .cts helper so the CJS build keeps a path to a REAL dynamic
+        // import() — @zvndev/powdb-client ≥ 0.9 is ESM-only, and the CommonJS
+        // pass transpiles a plain `import()` here into an unusable `require()`.
+        return (await importOptionalPeer('@zvndev/powdb-client'));
     }
     catch (err) {
-        throw new ConnectionError("[turbine] turbine-orm/powdb requires the optional peer dependency '@zvndev/powdb-client'. Install it: npm i @zvndev/powdb-client. " +
+        throw new ConnectionError("[turbine] turbine-orm/powdb requires the optional peer dependency '@zvndev/powdb-client'. Install it: npm i @zvndev/powdb-client — " +
+            'or construct the PowDB pool yourself and inject it: turbinePowDB(pool, schema). ' +
             `(${err.message})`);
     }
 }
@@ -702,13 +1167,16 @@ async function loadPowdb() {
 async function loadPowdbEmbedded() {
     let mod;
     try {
-        mod = (await import('@zvndev/powdb-embedded'));
+        // Via the .cts helper — keeps a real dynamic import() available to the
+        // CJS build in case a future addon version ships ESM-only (see loadPowdb).
+        mod = (await importOptionalPeer('@zvndev/powdb-embedded'));
     }
     catch (err) {
         throw new ConnectionError("[turbine] turbine-orm/powdb embedded mode requires the optional peer '@zvndev/powdb-embedded'. " +
             'Install it: npm i @zvndev/powdb-embedded. If install succeeded but loading failed, your platform has no ' +
             'prebuilt binary (prebuilts ship for macOS arm64/x64 and Linux glibc x64/arm64; Intel-mac/musl/Windows ' +
-            'build from source) — build it with `npm run build` in the addon, then retry. ' +
+            'build from source) — build it with `npm run build` in the addon, then retry. You can also construct the ' +
+            'pool yourself and inject it: turbinePowDB(pool, schema). ' +
             `(${err.message})`);
     }
     if (!mod || typeof mod.Database?.open !== 'function') {
@@ -718,7 +1186,7 @@ async function loadPowdbEmbedded() {
     return mod;
 }
 /** Open an embedded database handle, wrapping engine open failures (corrupt dir, etc.). */
-async function openEmbeddedPool(target) {
+async function openEmbeddedPool(target, poolOptions = {}) {
     const mod = await loadPowdbEmbedded();
     const { embedded: dir, syncMode, memoryLimit } = target;
     let db;
@@ -744,7 +1212,7 @@ async function openEmbeddedPool(target) {
         }
         db.setSyncMode(syncMode);
     }
-    return new PowdbEmbeddedPool(db);
+    return new PowdbEmbeddedPool(db, poolOptions);
 }
 /**
  * Bind Turbine to PowDB. `target` is one of:
@@ -767,28 +1235,30 @@ async function openEmbeddedPool(target) {
 export async function turbinePowDB(target, schema, options = {}) {
     let pool;
     let owns = false;
+    const poolOptions = { transactionQueueTimeoutMs: options.transactionQueueTimeoutMs };
     if (typeof target === 'string') {
-        const mod = await loadPowdb();
+        const mod = options.powdbClientModule ?? (await loadPowdb());
         const clientPool = new mod.Pool({ ...parsePowdbUrl(target), max: options.connectionLimit ?? 10 });
         await assertNetworkedVersion(clientPool);
-        pool = new PowdbPool(clientPool);
+        pool = new PowdbPool(clientPool, undefined, poolOptions);
         owns = true;
     }
     else if (target instanceof PowdbPool) {
+        // An injected PowdbPool carries its own PowdbPoolOptions.
         pool = target;
     }
     else if (isEmbeddedTarget(target)) {
-        pool = await openEmbeddedPool(target);
+        pool = await openEmbeddedPool(target, poolOptions);
         owns = true;
     }
     else if (isPowdbClientPool(target)) {
-        pool = new PowdbPool(target);
+        pool = new PowdbPool(target, undefined, poolOptions);
     }
     else {
-        const mod = await loadPowdb();
+        const mod = options.powdbClientModule ?? (await loadPowdb());
         const clientPool = new mod.Pool({ ...target, max: options.connectionLimit ?? 10 });
         await assertNetworkedVersion(clientPool);
-        pool = new PowdbPool(clientPool);
+        pool = new PowdbPool(clientPool, undefined, poolOptions);
         owns = true;
     }
     // The PowQL generator is loaded here to keep client.ts free of any PowDB import.
@@ -803,7 +1273,23 @@ export async function turbinePowDB(target, schema, options = {}) {
         warnOnUnlimited: options.warnOnUnlimited,
         queryInterfaceFactory,
     }, schema);
-    if (!owns) {
+    if (owns) {
+        // Turbine built this pool / embedded handle, so disconnect()/end() must
+        // close it. client.ts sees TurbineConfig.pool as EXTERNAL (ownsPool =
+        // false) and skips pool.end(); before this patch an owned networked
+        // client leaked its live socket(s) on disconnect(), holding the process
+        // open until powdb-server's idle timeout (~300s) closed them. Consistent
+        // with turbineMssql's owned-pool patch.
+        const baseDisconnect = client.disconnect.bind(client);
+        const close = async () => {
+            await baseDisconnect();
+            await pool.end();
+        };
+        const patch = client;
+        patch.disconnect = close;
+        patch.end = close;
+    }
+    else {
         // Injected pool — the caller owns its lifecycle.
         client.disconnect = async () => { };
     }