turbine-orm 0.29.0 → 0.31.0

package/dist/mssql.js

@@ -92,7 +92,9 @@
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
 import { ConnectionError, RelationError, UnsupportedFeatureError, ValidationError } from './errors.js';
-import { camelToSnake, isDateType, normalizeKeyColumns, singularize, snakeToCamel, } from './schema.js';
+import { deriveEngineRelations } from './introspect.js';
+import importOptionalPeer from './optional-peer-import.cjs';
+import { camelToSnake, isDateType, normalizeKeyColumns, snakeToCamel, } from './schema.js';
 // ---------------------------------------------------------------------------
 // SQL Server / connection limits
 // ---------------------------------------------------------------------------
@@ -743,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(', ');
@@ -853,103 +876,15 @@ function buildForJsonManyToMany(dialect, ctx, h) {
 }
 const num = (v) => (typeof v === 'string' ? Number(v) : (v ?? 0));
 /**
- * Derive belongsTo + hasMany relations (and conservatively-detected manyToMany
- * junctions) from a flat foreign-key list. Mirrors the PostgreSQL / MySQL / SQLite
- * introspectors so the produced {@link SchemaMetadata} has an identical relation
- * shape across engines.
+ * Derive relations from the FK list via the SHARED introspection pipeline
+ * (`deriveEngineRelations` → `buildRelationsFromForeignKeys` +
+ * `addAutoManyToManyRelations` in introspect.ts), so this engine derives
+ * IDENTICAL relation names to `turbine generate` against Postgres for the
+ * same logical schema — legacy-first naming, per-column disambiguation, and
+ * collision resolution against scalar column fields included.
  */
 function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, columnsByTable) {
-    const tableSet = new Set(tableNames);
-    const fkCounts = new Map();
-    for (const fk of foreignKeys) {
-        const key = `${fk.sourceTable}->${fk.targetTable}`;
-        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-    }
-    const relationsByTable = new Map();
-    for (const fk of foreignKeys) {
-        if (!tableSet.has(fk.targetTable))
-            continue;
-        const needsDisambiguation = (fkCounts.get(`${fk.sourceTable}->${fk.targetTable}`) ?? 0) > 1;
-        const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
-        const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-        const belongsToName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
-            : singularize(snakeToCamel(fk.targetTable));
-        if (!relationsByTable.has(fk.sourceTable))
-            relationsByTable.set(fk.sourceTable, {});
-        relationsByTable.get(fk.sourceTable)[belongsToName] = {
-            type: 'belongsTo',
-            name: belongsToName,
-            from: fk.sourceTable,
-            to: fk.targetTable,
-            foreignKey,
-            referenceKey,
-        };
-        const hasManyName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-            : snakeToCamel(fk.sourceTable);
-        if (!relationsByTable.has(fk.targetTable))
-            relationsByTable.set(fk.targetTable, {});
-        relationsByTable.get(fk.targetTable)[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
-            from: fk.targetTable,
-            to: fk.sourceTable,
-            foreignKey,
-            referenceKey,
-        };
-    }
-    // Conservative many-to-many auto-detection (additive): a table J is a pure
-    // junction iff PK is exactly two columns, exactly two single-column FKs whose
-    // source columns ARE the PK, two distinct target tables, and no payload columns.
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2)
-            continue;
-        if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((c) => pkSet.has(c)))
-            continue;
-        if (new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
-        if (jCols.length !== 2)
-            continue;
-        const addM2M = (self, other) => {
-            const sourceTbl = self.targetTable;
-            const targetTbl = other.targetTable;
-            const relName = snakeToCamel(targetTbl);
-            if (!relationsByTable.has(sourceTbl))
-                relationsByTable.set(sourceTbl, {});
-            const existing = relationsByTable.get(sourceTbl);
-            if (existing[relName])
-                return;
-            existing[relName] = {
-                type: 'manyToMany',
-                name: relName,
-                from: sourceTbl,
-                to: targetTbl,
-                referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                through: {
-                    table: tableName,
-                    sourceKey: self.sourceColumns[0],
-                    targetKey: other.sourceColumns[0],
-                },
-            };
-        };
-        addM2M(fkA, fkB);
-        addM2M(fkB, fkA);
-    }
-    return relationsByTable;
+    return deriveEngineRelations(tableNames, foreignKeys, pkByTable, columnsByTable);
 }
 /**
  * Introspect a SQL Server database into the same {@link SchemaMetadata} shape the
@@ -1196,11 +1131,12 @@ async function loadMssql() {
     let mod;
     try {
         // `mssql` ships no bundled type declarations (it needs @types/mssql, which
-        // Turbine deliberately does not depend on) — the structural MssqlModule above
-        // is our typed surface. Import through a widened specifier so tsc treats the
-        // typeless module as `any` instead of erroring (TS7016).
-        const specifier = 'mssql';
-        mod = (await import(specifier));
+        // Turbine deliberately does not depend on) — the structural MssqlModule
+        // above is our typed surface; the helper returns `unknown` so no TS7016.
+        // Via the .cts helper so the CJS build keeps a path to a REAL dynamic
+        // import() even if a future mssql major goes ESM-only (the CommonJS pass
+        // transpiles a plain `import()` here into `require()`).
+        mod = (await importOptionalPeer('mssql'));
     }
     catch (err) {
         throw new ConnectionError("[turbine] turbine-orm/mssql requires the optional peer dependency 'mssql'. Install it: npm i mssql. " +

package/dist/mysql.js

@@ -65,7 +65,9 @@
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
 import { ConnectionError, UnsupportedFeatureError } from './errors.js';
-import { isDateType, singularize, snakeToCamel, } from './schema.js';
+import { deriveEngineRelations } from './introspect.js';
+import importOptionalPeer from './optional-peer-import.cjs';
+import { isDateType, snakeToCamel, } from './schema.js';
 // ---------------------------------------------------------------------------
 // Value coercion (params in)
 // ---------------------------------------------------------------------------
@@ -555,103 +557,15 @@ export const mysqlDialect = {
 };
 const num = (v) => (typeof v === 'string' ? Number(v) : (v ?? 0));
 /**
- * Derive belongsTo + hasMany relations (and conservatively-detected manyToMany
- * junctions) from a flat foreign-key list. Mirrors the PostgreSQL / SQLite
- * introspectors so the produced {@link SchemaMetadata} has an identical relation
- * shape across engines.
+ * Derive relations from the FK list via the SHARED introspection pipeline
+ * (`deriveEngineRelations` → `buildRelationsFromForeignKeys` +
+ * `addAutoManyToManyRelations` in introspect.ts), so this engine derives
+ * IDENTICAL relation names to `turbine generate` against Postgres for the
+ * same logical schema — legacy-first naming, per-column disambiguation, and
+ * collision resolution against scalar column fields included.
  */
 function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, columnsByTable) {
-    const tableSet = new Set(tableNames);
-    const fkCounts = new Map();
-    for (const fk of foreignKeys) {
-        const key = `${fk.sourceTable}->${fk.targetTable}`;
-        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-    }
-    const relationsByTable = new Map();
-    for (const fk of foreignKeys) {
-        if (!tableSet.has(fk.targetTable))
-            continue;
-        const needsDisambiguation = (fkCounts.get(`${fk.sourceTable}->${fk.targetTable}`) ?? 0) > 1;
-        const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
-        const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-        const belongsToName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
-            : singularize(snakeToCamel(fk.targetTable));
-        if (!relationsByTable.has(fk.sourceTable))
-            relationsByTable.set(fk.sourceTable, {});
-        relationsByTable.get(fk.sourceTable)[belongsToName] = {
-            type: 'belongsTo',
-            name: belongsToName,
-            from: fk.sourceTable,
-            to: fk.targetTable,
-            foreignKey,
-            referenceKey,
-        };
-        const hasManyName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-            : snakeToCamel(fk.sourceTable);
-        if (!relationsByTable.has(fk.targetTable))
-            relationsByTable.set(fk.targetTable, {});
-        relationsByTable.get(fk.targetTable)[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
-            from: fk.targetTable,
-            to: fk.sourceTable,
-            foreignKey,
-            referenceKey,
-        };
-    }
-    // Conservative many-to-many auto-detection (additive): a table J is a pure
-    // junction iff PK is exactly two columns, exactly two single-column FKs whose
-    // source columns ARE the PK, two distinct target tables, and no payload columns.
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2)
-            continue;
-        if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((c) => pkSet.has(c)))
-            continue;
-        if (new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
-        if (jCols.length !== 2)
-            continue;
-        const addM2M = (self, other) => {
-            const sourceTbl = self.targetTable;
-            const targetTbl = other.targetTable;
-            const relName = snakeToCamel(targetTbl);
-            if (!relationsByTable.has(sourceTbl))
-                relationsByTable.set(sourceTbl, {});
-            const existing = relationsByTable.get(sourceTbl);
-            if (existing[relName])
-                return;
-            existing[relName] = {
-                type: 'manyToMany',
-                name: relName,
-                from: sourceTbl,
-                to: targetTbl,
-                referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                through: {
-                    table: tableName,
-                    sourceKey: self.sourceColumns[0],
-                    targetKey: other.sourceColumns[0],
-                },
-            };
-        };
-        addM2M(fkA, fkB);
-        addM2M(fkB, fkA);
-    }
-    return relationsByTable;
+    return deriveEngineRelations(tableNames, foreignKeys, pkByTable, columnsByTable);
 }
 /**
  * Introspect a MySQL database into the same {@link SchemaMetadata} shape the
@@ -898,7 +812,10 @@ function parseMysqlConfig(connectionString) {
 async function loadCreatePool() {
     let mod;
     try {
-        mod = (await import('mysql2/promise'));
+        // Via the .cts helper so the CJS build keeps a path to a REAL dynamic
+        // import() even if a future mysql2 major goes ESM-only (the CommonJS pass
+        // transpiles a plain `import()` here into `require()`).
+        mod = (await importOptionalPeer('mysql2/promise'));
     }
     catch (err) {
         throw new ConnectionError("[turbine] turbine-orm/mysql requires the optional peer dependency 'mysql2'. Install it: npm i mysql2. " +

package/dist/optional-peer-import.cjs

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * True dynamic `import()` for the optional peer dependencies (`mysql2`,
+ * `mssql`, `@zvndev/powdb-client`, `@zvndev/powdb-embedded`) — safe in BOTH
+ * build outputs, including for peers that are ESM-only.
+ *
+ * THE PROBLEM THIS FILE SOLVES (the `@zvndev/powdb-client` ≥ 0.9 CJS break):
+ * the engine subpaths load their optional peers with dynamic `import()` so the
+ * peers stay out of the static graph. The ESM build (`tsconfig.json`, module
+ * NodeNext) emits that `import()` verbatim. The CJS build (`tsconfig.cjs.json`,
+ * module CommonJS) however TRANSPILES `import()` into
+ * `Promise.resolve().then(() => require(...))` — and `require()` of an
+ * ESM-only package (no `require` export condition, e.g. powdb-client ≥ 0.9)
+ * throws `ERR_PACKAGE_PATH_NOT_EXPORTED`, breaking every CJS consumer.
+ *
+ * TypeScript offers no way to preserve `import()` under `module: CommonJS`,
+ * and the CJS pass cannot switch to `module: NodeNext` (the root package.json
+ * says `"type": "module"`, so NodeNext would classify every `.ts` source as
+ * ESM and emit ESM into dist/cjs). A `.cts` file is the escape hatch: it is
+ * CommonJS-format by extension regardless of package `type`, so under the ESM
+ * pass (NodeNext) it compiles to `dist/optional-peer-import.cjs` — a CommonJS
+ * file whose `import()` SURVIVES transpilation (NodeNext preserves dynamic
+ * import in CJS files precisely because it is the only way CJS can load ESM).
+ *
+ * That gives the published package two copies of this module:
+ *   - `dist/optional-peer-import.cjs`      (ESM pass, NodeNext)  — real `import()`
+ *   - `dist/cjs/optional-peer-import.cjs`  (CJS pass, CommonJS)  — lowered to `require()`
+ *
+ * The lowered copy works fine for CJS-loadable peers (`mysql2`, `mssql`, older
+ * powdb peers). When it hits an ESM-only peer, the `require()` fails with a
+ * recognizable code and this function falls back to delegating the load to the
+ * sibling NodeNext copy one directory up (`../optional-peer-import.cjs`) —
+ * which is a plain CommonJS file (loadable by `require()` on every supported
+ * Node) whose real `import()` then loads the ESM peer. The ESM-pass copy has
+ * no such sibling; its lazy `require` throws and the original error surfaces,
+ * so the fallback can never recurse.
+ *
+ * Keep this module dependency-free and side-effect-free: it must be loadable
+ * from both module systems on every supported Node (≥ 20) without pulling in
+ * anything else.
+ */
+/**
+ * Does this error mean "the module exists but cannot be loaded via
+ * `require()` because it is ESM-only"? These are the only failures worth
+ * retrying through a real `import()`; anything else (not installed, throw on
+ * init, …) is rethrown untouched so callers keep the original diagnostics.
+ */
+function isEsmOnlyLoadError(err) {
+    const code = err?.code;
+    return (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED' || // exports map has no `require` condition
+        code === 'ERR_REQUIRE_ESM' || // require() of an ES module (pre-require(esm) Node)
+        code === 'ERR_REQUIRE_ASYNC_MODULE' // require(esm) of a module with top-level await
+    );
+}
+/**
+ * Dynamically import an optional peer dependency. In the ESM build this is a
+ * plain `import()`. In the CJS build the first attempt is a transpiled
+ * `require()`; if the peer turns out to be ESM-only, the load is retried
+ * through the ESM-build sibling copy of this file, whose `import()` survived
+ * transpilation (see the module doc comment).
+ *
+ * @param specifier bare package specifier (e.g. `'@zvndev/powdb-client'`).
+ * @param allowEsmFallback internal recursion guard — the delegated call passes
+ *   `false` so a failure in the sibling copy can never bounce back.
+ */
+async function importOptionalPeer(specifier, allowEsmFallback = true) {
+    try {
+        return await import(specifier);
+    }
+    catch (err) {
+        if (!allowEsmFallback || !isEsmOnlyLoadError(err))
+            throw err;
+        let esmCapableCopy;
+        try {
+            // Only resolvable from dist/cjs/, where it lands on the NodeNext-built
+            // dist/optional-peer-import.cjs. From anywhere else (the ESM copy
+            // itself, or running the TypeScript source directly) the file does not
+            // exist and the original error is rethrown below.
+            esmCapableCopy = require('../optional-peer-import.cjs');
+        }
+        catch {
+            esmCapableCopy = undefined;
+        }
+        if (typeof esmCapableCopy !== 'function')
+            throw err;
+        return esmCapableCopy(specifier, false);
+    }
+}
+module.exports = importOptionalPeer;

package/dist/optional-peer-import.d.cts

@@ -0,0 +1,53 @@
+/**
+ * True dynamic `import()` for the optional peer dependencies (`mysql2`,
+ * `mssql`, `@zvndev/powdb-client`, `@zvndev/powdb-embedded`) — safe in BOTH
+ * build outputs, including for peers that are ESM-only.
+ *
+ * THE PROBLEM THIS FILE SOLVES (the `@zvndev/powdb-client` ≥ 0.9 CJS break):
+ * the engine subpaths load their optional peers with dynamic `import()` so the
+ * peers stay out of the static graph. The ESM build (`tsconfig.json`, module
+ * NodeNext) emits that `import()` verbatim. The CJS build (`tsconfig.cjs.json`,
+ * module CommonJS) however TRANSPILES `import()` into
+ * `Promise.resolve().then(() => require(...))` — and `require()` of an
+ * ESM-only package (no `require` export condition, e.g. powdb-client ≥ 0.9)
+ * throws `ERR_PACKAGE_PATH_NOT_EXPORTED`, breaking every CJS consumer.
+ *
+ * TypeScript offers no way to preserve `import()` under `module: CommonJS`,
+ * and the CJS pass cannot switch to `module: NodeNext` (the root package.json
+ * says `"type": "module"`, so NodeNext would classify every `.ts` source as
+ * ESM and emit ESM into dist/cjs). A `.cts` file is the escape hatch: it is
+ * CommonJS-format by extension regardless of package `type`, so under the ESM
+ * pass (NodeNext) it compiles to `dist/optional-peer-import.cjs` — a CommonJS
+ * file whose `import()` SURVIVES transpilation (NodeNext preserves dynamic
+ * import in CJS files precisely because it is the only way CJS can load ESM).
+ *
+ * That gives the published package two copies of this module:
+ *   - `dist/optional-peer-import.cjs`      (ESM pass, NodeNext)  — real `import()`
+ *   - `dist/cjs/optional-peer-import.cjs`  (CJS pass, CommonJS)  — lowered to `require()`
+ *
+ * The lowered copy works fine for CJS-loadable peers (`mysql2`, `mssql`, older
+ * powdb peers). When it hits an ESM-only peer, the `require()` fails with a
+ * recognizable code and this function falls back to delegating the load to the
+ * sibling NodeNext copy one directory up (`../optional-peer-import.cjs`) —
+ * which is a plain CommonJS file (loadable by `require()` on every supported
+ * Node) whose real `import()` then loads the ESM peer. The ESM-pass copy has
+ * no such sibling; its lazy `require` throws and the original error surfaces,
+ * so the fallback can never recurse.
+ *
+ * Keep this module dependency-free and side-effect-free: it must be loadable
+ * from both module systems on every supported Node (≥ 20) without pulling in
+ * anything else.
+ */
+/**
+ * Dynamically import an optional peer dependency. In the ESM build this is a
+ * plain `import()`. In the CJS build the first attempt is a transpiled
+ * `require()`; if the peer turns out to be ESM-only, the load is retried
+ * through the ESM-build sibling copy of this file, whose `import()` survived
+ * transpilation (see the module doc comment).
+ *
+ * @param specifier bare package specifier (e.g. `'@zvndev/powdb-client'`).
+ * @param allowEsmFallback internal recursion guard — the delegated call passes
+ *   `false` so a failure in the sibling copy can never bounce back.
+ */
+declare function importOptionalPeer(specifier: string, allowEsmFallback?: boolean): Promise<unknown>;
+export = importOptionalPeer;

package/dist/powdb.d.ts

@@ -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
@@ -65,9 +70,11 @@ import type { ColumnMetadata, SchemaMetadata, TableMetadata } from './schema.js'
  *     {@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 declare const powdbDialect: Dialect;
@@ -113,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;
@@ -161,6 +180,24 @@ export declare function powqlColumnType(col: ColumnMetadata): PowqlType;
  * `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 declare const POWQL_KEYWORDS: ReadonlySet<string>;
+/**
+ * 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 declare function quotePowqlIdent(name: string): string;
 export declare function powqlSchemaDDL(schema: SchemaMetadata): string[];
 /**
  * Coerce a single PowDB wire string into the JS value its column type implies.
@@ -194,6 +231,27 @@ type QueryArg = string | {
     text: string;
     values?: unknown[];
 };
+/**
+ * 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 declare const DEFAULT_TX_QUEUE_TIMEOUT_MS = 30000;
+/** Tuning options shared by {@link PowdbPool} and {@link PowdbEmbeddedPool}. */
+export interface PowdbPoolOptions {
+    /**
+     * Max time (ms) a concurrent transaction's `begin` may wait in the FIFO
+     * queue for the single-writer lock before failing with a
+     * {@link TimeoutError}. Default {@link DEFAULT_TX_QUEUE_TIMEOUT_MS};
+     * `0` / `Infinity` = wait without limit. Note this is a separate surface
+     * from `$transaction`'s `timeout` option, which only covers the callback
+     * *after* the transaction has begun.
+     */
+    transactionQueueTimeoutMs?: number;
+}
 /**
  * A {@link PgCompatPool} backed by a `@zvndev/powdb-client` `Pool`. The query
  * `text` is **PowQL**, not SQL — {@link PowqlInterface} generates it. Rows come
@@ -205,21 +263,31 @@ export declare class PowdbPool implements PgCompatPool {
     private readonly toParam;
     private closed;
     /**
-     * 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}).
      */
-    private activeTransaction;
-    constructor(pool: PowdbClientPool, toParam?: (v: unknown, i: number) => PowdbParam);
+    private readonly txGate;
+    /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
+    private poolHold;
     /**
-     * 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.
+     * 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 guardTxControl;
+    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>;
 }
@@ -278,17 +346,27 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
     private readonly db;
     private closed;
     /**
-     * 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}.)
+     */
+    private readonly txGate;
+    /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
+    private readonly poolHoldRef;
+    constructor(db: EmbeddedDatabase, options?: PowdbPoolOptions);
+    /** Materialize `$N` params and hand the PowQL to the in-process engine. */
+    private exec;
+    /**
+     * 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.
      */
-    private activeTransaction;
-    constructor(db: EmbeddedDatabase);
-    /** Enforce the single-writer model on a transaction-control statement. */
-    private guardTxControl;
     private run;
     query(text: QueryArg, values?: unknown[]): Promise<any>;
     connect(): Promise<PgCompatPoolClient>;
@@ -299,6 +377,23 @@ export { PowqlInterface } from './powql.js';
 export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
     /** Max pooled connections (default 10). Networked transport only. */
     connectionLimit?: number;
+    /**
+     * Max time (ms) a concurrent `$transaction` waits in the FIFO queue for
+     * PowDB's single global write lock before failing with a typed
+     * `TimeoutError` (default {@link DEFAULT_TX_QUEUE_TIMEOUT_MS} = 30 000;
+     * `0` / `Infinity` = wait without limit). Independent concurrent
+     * transactions queue and run one at a time; only a re-entrant
+     * `db.$transaction` (opened inside an active transaction callback) throws
+     * 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`