turbine-orm 0.28.3 → 0.30.0

package/dist/powdb.js

@@ -22,8 +22,19 @@
  *     `string` PKs hold UUID strings.
  *   - **No JSON aggregation / link navigation** — single-query nested `with` is
  *     impossible → it degrades to batched N+1 loaders (Phase B).
- *   - **Single global write lock; no savepoints/isolation/pipelining** — nested
+ *   - **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
+ *     clients advertise `supportsPipelining`, which lets the batch
+ *     `$transaction([...])` overload dispatch all statements in one write
+ *     burst (~1 round trip) instead of one round trip per statement.
  *
  * `@zvndev/powdb-client` is an **optional peer dependency** loaded by dynamic
  * import; `npm i turbine-orm` still pulls only `pg`.
@@ -41,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
@@ -59,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 = {
@@ -206,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)) {
@@ -227,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])}`);
             }
         }
     }
@@ -333,6 +467,12 @@ export function wrapPowdbError(err) {
         const m = /column ['"]?(\w+)['"]?/i.exec(msg);
         return new NotNullViolationError({ column: m?.[1], cause: err });
     }
+    // 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
@@ -378,15 +518,142 @@ 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;
+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 relies on `AsyncLocalStorage.enterWith()` running in the
+ * caller's *synchronous* execution: the pools call `acquire()` from the
+ * synchronous prologue of `query('begin')`, so when `TurbineClient.$transaction`
+ * awaits that begin, its continuation — and therefore the user callback — runs
+ * with the marker set, while sibling contexts (concurrent transactions, the
+ * caller after `$transaction` resolves) captured their snapshots earlier and
+ * never see it. 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 re-entrant begin issued from an async context
+ * created BEFORE the transaction opened (e.g. a job-queue worker loop whose
+ * continuations captured their ALS snapshot up front) carries no marker, so it
+ * 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 pre-existing async 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. MUST be invoked in the same
+     * synchronous execution as the caller's `begin` (no `await` before it) so
+     * the re-entrancy marker propagates into the transaction's async scope.
+     */
+    async acquire() {
+        // --- synchronous section (runs before the caller's first await) ---
+        // 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 };
+        powdbTxStorage.enterWith(ctx);
+        let handOff;
+        const finished = new Promise((resolve) => {
+            handOff = resolve;
+        });
+        const ahead = this.tail;
+        this.tail = ahead.then(() => finished);
+        const hold = {
+            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) {
@@ -420,70 +687,117 @@ 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}).
      */
-    activeTransaction = false;
-    constructor(pool, toParam = (v) => toPowdbParam(v)) {
+    txGate;
+    /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
+    poolHold = null;
+    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) {
+        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 re-entrant begin throws fast, an
+            // independent concurrent one waits its FIFO turn. (acquire()'s
+            // re-entrancy check + context mark run synchronously right here.)
+            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;
+            }
+        }
     }
     async connect() {
         const client = await this.pool.acquire();
         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
+            // immediately and replies are matched to callers in FIFO order. That
+            // lets the batch `$transaction([...])` path dispatch all statements in
+            // one write burst instead of paying a round trip per statement. Safe
+            // 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. (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 re-entrant begin throws 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;
+                // Releasing this connection ends its transaction scope. Finish the
+                // hold as a safety net so a tx torn down without an explicit
+                // commit/rollback (e.g. a timeout that destroys the connection) hands
+                // the gate to the next queued transaction instead of wedging the
+                // queue. Only THIS connection's hold — releasing an unrelated (read)
+                // connection never touches another transaction's slot.
+                hold?.finish();
+                hold = null;
                 return broken ? this.pool.destroy(client) : this.pool.release(client);
             },
         };
@@ -596,57 +910,89 @@ 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) {
         const ctl = txControl(powql);
         if (ctl === 'begin') {
-            if (this.activeTransaction)
-                throw reentrantTransactionError();
-            this.activeTransaction = true;
+            // Gate BEFORE hitting the engine — re-entrant begins throw fast,
+            // independent concurrent ones wait their FIFO turn. (acquire()'s
+            // re-entrancy check + context mark run synchronously right here.)
+            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);
             },
             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.
+                holdRef.hold?.finish();
+                holdRef.hold = null;
             },
         };
     }
@@ -669,10 +1015,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})`);
     }
 }
@@ -686,13 +1036,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') {
@@ -702,7 +1055,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;
@@ -728,7 +1081,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:
@@ -751,28 +1104,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 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 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.