turbine-orm 0.30.0 → 0.31.0

package/dist/cjs/query/filters.js

@@ -7,9 +7,10 @@
  * and execution rather than filter-shape bookkeeping.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSON_RANGE_OPERATORS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = void 0;
+exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSON_RANGE_OPERATORS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = exports.COLUMN_REF_OPERATORS = void 0;
 exports.isWhereOperator = isWhereOperator;
 exports.isUnmatchedPlainObject = isUnmatchedPlainObject;
+exports.isColumnRef = isColumnRef;
 exports.fingerprintOperatorShape = fingerprintOperatorShape;
 exports.assertBindableEqualsOperand = assertBindableEqualsOperand;
 exports.sortedKeys = sortedKeys;
@@ -24,6 +25,7 @@ exports.validateTextSearchConfig = validateTextSearchConfig;
 exports.isVectorFilter = isVectorFilter;
 exports.isVectorOrderBy = isVectorOrderBy;
 exports.isOrderBySpec = isOrderBySpec;
+exports.isJsonPathOrderBy = isJsonPathOrderBy;
 exports.normalizeOrderBy = normalizeOrderBy;
 const errors_js_1 = require("../errors.js");
 const utils_js_1 = require("./utils.js");
@@ -56,17 +58,48 @@ function isUnmatchedPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Operator keys that accept a {@link ColumnRef} (`{ col: 'otherField' }`)
+ * value for column-to-column comparison. `in`/`notIn` and the LIKE operators
+ * take values only.
+ */
+exports.COLUMN_REF_OPERATORS = new Set(['equals', 'not', 'gt', 'gte', 'lt', 'lte']);
+/**
+ * Check if an operator value is a column reference: a plain object whose ONLY
+ * key is `col` with a string value. Anything else (extra keys, non-string
+ * `col`) is treated as a plain value so JSON payloads that merely contain a
+ * `col` property keep their equality meaning.
+ */
+function isColumnRef(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === 'col' && typeof value.col === 'string';
+}
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
  * param pushed), so null-ness is part of the shape — without it a cache entry
  * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ *
+ * Column references ({@link ColumnRef}) compile the referenced column into the
+ * SQL TEXT (no param bound), so the referenced field name is part of the shape
+ *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
+ * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * with other fingerprint tokens.
  */
 function fingerprintOperatorShape(value) {
     const obj = value;
     const opKeys = Object.keys(obj)
         .filter((k) => k !== 'mode')
-        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .map((k) => {
+        const v = obj[k];
+        if ((k === 'equals' || k === 'not') && v === null)
+            return `${k}:null`;
+        if (exports.COLUMN_REF_OPERATORS.has(k) && isColumnRef(v))
+            return `${k}:col(${JSON.stringify(v.col)})`;
+        return k;
+    })
         .sort();
     const modeStr = value.mode === 'insensitive' ? ':i' : '';
     return `op(${opKeys.join(',')}${modeStr})`;
@@ -269,6 +302,20 @@ function isVectorOrderBy(value) {
 function isOrderBySpec(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && 'sort' in value;
 }
+/**
+ * Check if an orderBy value is a JSON-path ordering: `{ path: [...] }` with an
+ * ARRAY path. The array requirement disambiguates from relation orderBy values
+ * (whose entries are directions/specs keyed by target column: a target column
+ * literally named `path` maps to a string direction, never an array), and the
+ * `distance`/`sort` exclusions keep vector and spec shapes out.
+ */
+function isJsonPathOrderBy(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    if ('distance' in value || 'sort' in value)
+        return false;
+    return Array.isArray(value.path);
+}
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

package/dist/client.d.ts

@@ -68,6 +68,19 @@ export interface PgCompatPoolClient {
      * sequential.
      */
     readonly supportsPipelining?: boolean;
+    /**
+     * Optional engine seam: scope a transaction's user callback to its own
+     * async subtree. When present, `TurbineClient.transaction` / `$transaction`
+     * invoke the callback as `wrapTransactionCallback(() => fn(tx))` instead of
+     * `fn(tx)` directly. Single-writer engines (PowDB) implement it with
+     * `AsyncLocalStorage.run()` to plant their re-entrancy marker so that it
+     * exists ONLY inside the callback's async subtree: a transaction opened
+     * from inside the callback is detected as re-entrant (typed E017), while
+     * the CALLER's context stays unmarked, so same-tick sibling transactions
+     * queue FIFO instead of being falsely flagged. Absent on pg and every other
+     * engine, in which case the callback runs unwrapped (zero behavior change).
+     */
+    wrapTransactionCallback?<R>(fn: () => Promise<R>): Promise<R>;
 }
 /**
  * Minimal pg-compatible pool. Pass any driver that satisfies this interface

package/dist/client.js

@@ -775,7 +775,12 @@ export class TurbineClient {
         try {
             await client.query(this.dialect.beginStatement());
             began = true;
-            const result = await fn(client);
+            // Engine seam: single-writer engines scope their transaction re-entrancy
+            // marker to the callback's async subtree (see
+            // PgCompatPoolClient.wrapTransactionCallback). Absent everywhere else.
+            const wrap = client.wrapTransactionCallback;
+            // `.call` erases the generic, so the callback's Promise<T> is re-asserted.
+            const result = wrap ? (await wrap.call(client, () => fn(client))) : await fn(client);
             await client.query(this.dialect.commitStatement());
             return result;
         }
@@ -868,6 +873,12 @@ export class TurbineClient {
                 }
             }
             let result;
+            // Engine seam: when the checked-out connection exposes
+            // wrapTransactionCallback (single-writer engines such as PowDB), run the user
+            // callback through it so the engine can scope its re-entrancy marker to
+            // the callback's async subtree. All other drivers: plain fn(tx).
+            const wrap = client.wrapTransactionCallback;
+            const runCallback = () => (wrap ? wrap.call(client, () => fn(tx)) : fn(tx));
             if (timeout) {
                 // Race between the function and a timeout. If the timeout fires we
                 // need to actually abort the in-flight query — otherwise the backend
@@ -889,14 +900,14 @@ export class TurbineClient {
                     }, timeout);
                 });
                 try {
-                    result = await Promise.race([fn(tx), timeoutPromise]);
+                    result = await Promise.race([runCallback(), timeoutPromise]);
                 }
                 finally {
                     clearTimeout(timer);
                 }
             }
             else {
-                result = await fn(tx);
+                result = await runCallback();
             }
             await client.query(this.dialect.commitStatement());
             if (this.logging) {

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByArgs, type HavingClause, type JsonFilter, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';

package/dist/mssql.js

@@ -745,11 +745,32 @@ function buildForJsonSubquery(dialect, ctx) {
         if (hasOrder) {
             const orderBy = orderEntries
                 .map(([k, dir]) => {
-                const col = camelToSnake(k);
+                // FOR JSON nested ordering supports plain directions and { sort }
+                // specs only. Object shapes the core builder compiles with params
+                // (JSON-path / vector / relation ordering) must throw here: the
+                // shared param-collect mirror is gated on the native path, so a
+                // silently-ignored object would desync SQL text from params.
+                let rawDir = dir;
+                if (typeof dir === 'object' && dir !== null) {
+                    const sortValue = dir.sort;
+                    if (typeof sortValue !== 'string') {
+                        throw new ValidationError(`[turbine] Nested orderBy on "${k}" (table "${targetTable}"): only plain directions and ` +
+                            `{ sort } specs are supported inside a relation orderBy on SQL Server.`);
+                    }
+                    if (dir.nulls !== undefined) {
+                        throw new UnsupportedFeatureError('NULLS FIRST/LAST ordering', 'sqlserver', 'Explicit nulls placement in orderBy is only available on PostgreSQL and SQLite.');
+                    }
+                    rawDir = sortValue;
+                }
+                // columnMap-first resolution (camelToSnake fallback): matches the
+                // core builder's nested orderBy path so camelCase-named DB columns
+                // resolve on SQL Server too.
+                const col = targetMeta.columnMap[k] ?? camelToSnake(k);
                 if (!targetMeta.allColumns.includes(col)) {
-                    throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
+                    throw new ValidationError(`[turbine] Unknown field "${k}" in orderBy on table "${targetTable}". ` +
+                        `Known fields: ${Object.keys(targetMeta.columnMap).join(', ') || '(none)'}.`);
                 }
-                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+                const safeDir = String(rawDir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${a}.${q(col)} ${safeDir}`;
             })
                 .join(', ');

package/dist/powdb.d.ts

@@ -120,6 +120,18 @@ interface PowdbClientPool {
     withClient<T>(fn: (c: PowdbClient) => Promise<T>): Promise<T>;
     close(): Promise<void>;
 }
+interface PowdbModule {
+    Client: {
+        connect(opts: PowdbConnOptions): Promise<PowdbClient>;
+    };
+    Pool: new (opts: PowdbConnOptions & {
+        max?: number;
+    }) => PowdbClientPool;
+    isPowDBError?(err: unknown): err is {
+        code: string;
+        message: string;
+    };
+}
 /** Connection options for {@link turbinePowDB} — host/port, not a connection string. */
 export interface PowdbConnOptions {
     host: string;
@@ -260,8 +272,22 @@ export declare class PowdbPool implements PgCompatPool {
     private readonly txGate;
     /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
     private poolHold;
+    /**
+     * 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.
+     */
+    private readonly checkedOut;
     constructor(pool: PowdbClientPool, toParam?: (v: unknown, i: number) => PowdbParam, options?: PowdbPoolOptions);
     query(text: QueryArg, values?: unknown[]): Promise<any>;
+    /**
+     * 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.
+     */
+    private assertOpen;
     connect(): Promise<PgCompatPoolClient>;
     end(): Promise<void>;
 }
@@ -361,6 +387,13 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * E017 — queueing that shape would deadlock.
      */
     transactionQueueTimeoutMs?: number;
+    /**
+     * Driver-module injection for the networked target forms (URL / host+port):
+     * bypasses the dynamic `import('@zvndev/powdb-client')` and uses this object
+     * as the driver module instead. Intended for tests (a fake pool that counts
+     * connections) and advanced embedding; everyday callers never set it.
+     */
+    powdbClientModule?: PowdbModule;
 }
 /**
  * Selects the **embedded** transport — an in-process `@zvndev/powdb-embedded`

package/dist/powdb.js

@@ -467,6 +467,11 @@ 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.
@@ -544,6 +549,13 @@ function reentrantTransactionError() {
  * 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
@@ -561,25 +573,35 @@ const powdbTxStorage = new AsyncLocalStorage();
  *     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.
+ * 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 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.
+ * **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;
@@ -589,12 +611,14 @@ class PowdbTxGate {
         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.
+     * 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() {
-        // --- 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
@@ -611,7 +635,6 @@ class PowdbTxGate {
             }
         }
         const ctx = { gate: this, done: false, parent };
-        powdbTxStorage.enterWith(ctx);
         let handOff;
         const finished = new Promise((resolve) => {
             handOff = resolve;
@@ -619,6 +642,7 @@ class PowdbTxGate {
         const ahead = this.tail;
         this.tail = ahead.then(() => finished);
         const hold = {
+            ctx,
             finish: () => {
                 if (ctx.done)
                     return;
@@ -696,6 +720,14 @@ export class PowdbPool {
     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.
+     */
+    checkedOut = new Set();
     constructor(pool, toParam = (v) => toPowdbParam(v), options = {}) {
         this.pool = pool;
         this.toParam = toParam;
@@ -703,12 +735,13 @@ export class PowdbPool {
     }
     // 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') {
-            // 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.)
+            // 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();
         }
         if ((ctl === 'commit' || ctl === 'rollback') && this.poolHold === null) {
@@ -736,8 +769,26 @@ export class PowdbPool {
             }
         }
     }
+    /**
+     * 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;
@@ -759,9 +810,10 @@ export class PowdbPool {
                 const { text: powql, params } = normalizeQueryArgs(text, values);
                 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.
+                    // 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) {
@@ -789,16 +841,60 @@ export class PowdbPool {
                     }
                 }
             },
-            release: () => {
-                // 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();
+            // 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;
-                return broken ? this.pool.destroy(client) : this.pool.release(client);
+                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();
             },
         };
     }
@@ -806,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}. */
@@ -938,11 +1043,14 @@ export class PowdbEmbeddedPool {
      * 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') {
-            // 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.)
+            // 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();
         }
         if ((ctl === 'commit' || ctl === 'rollback') && holdRef.hold === null) {
@@ -988,11 +1096,31 @@ export class PowdbEmbeddedPool {
                 const { text: powql, params } = normalizeQueryArgs(text, values);
                 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 queue.
-                holdRef.hold?.finish();
-                holdRef.hold = null;
+                // 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;
+                });
             },
         };
     }
@@ -1000,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;
     }
 }
@@ -1106,7 +1237,7 @@ export async function turbinePowDB(target, schema, options = {}) {
     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, undefined, poolOptions);
@@ -1124,7 +1255,7 @@ export async function turbinePowDB(target, schema, options = {}) {
         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, undefined, poolOptions);
@@ -1142,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 () => { };
     }