turbine-orm 0.30.0 → 0.32.0

package/dist/cjs/client.js

@@ -783,7 +783,12 @@ 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;
         }
@@ -876,6 +881,12 @@ 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
@@ -897,14 +908,14 @@ 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/cjs/mssql.js

@@ -756,11 +756,32 @@ function buildForJsonSubquery(dialect, ctx) {
         if (hasOrder) {
             const orderBy = orderEntries
                 .map(([k, dir]) => {
-                const col = (0, schema_js_1.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 errors_js_1.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 errors_js_1.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] ?? (0, schema_js_1.camelToSnake)(k);
                 if (!targetMeta.allColumns.includes(col)) {
-                    throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
+                    throw new errors_js_1.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/cjs/powdb.js

@@ -518,6 +518,11 @@ function wrapPowdbError(err) {
         const m = /column ['"]?(\w+)['"]?/i.exec(msg);
         return new errors_js_1.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 errors_js_1.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.
@@ -595,6 +600,13 @@ function reentrantTransactionError() {
  * waits without limit.
  */
 exports.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 node_async_hooks_1.AsyncLocalStorage();
 /**
  * FIFO gate serializing transactions across a whole pool. PowDB holds one
@@ -612,25 +624,35 @@ const powdbTxStorage = new node_async_hooks_1.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;
@@ -640,12 +662,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
@@ -662,7 +686,6 @@ class PowdbTxGate {
             }
         }
         const ctx = { gate: this, done: false, parent };
-        powdbTxStorage.enterWith(ctx);
         let handOff;
         const finished = new Promise((resolve) => {
             handOff = resolve;
@@ -670,6 +693,7 @@ class PowdbTxGate {
         const ahead = this.tail;
         this.tail = ahead.then(() => finished);
         const hold = {
+            ctx,
             finish: () => {
                 if (ctx.done)
                     return;
@@ -747,6 +771,14 @@ 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;
@@ -754,12 +786,13 @@ 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) {
@@ -787,8 +820,26 @@ 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 errors_js_1.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;
@@ -810,9 +861,10 @@ 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) {
@@ -840,16 +892,60 @@ 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();
             },
         };
     }
@@ -857,7 +953,16 @@ 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();
     }
 }
 exports.PowdbPool = PowdbPool;
@@ -990,11 +1095,14 @@ class PowdbEmbeddedPool {
      * transaction is holding.
      */
     async run(powql, params, holdRef) {
+        if (this.closed) {
+            throw new errors_js_1.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) {
@@ -1040,11 +1148,31 @@ 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;
+                });
             },
         };
     }
@@ -1052,8 +1180,11 @@ 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;
     }
 }
@@ -1160,7 +1291,7 @@ 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);
@@ -1178,7 +1309,7 @@ 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);
@@ -1196,7 +1327,23 @@ 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 () => { };
     }

package/dist/cjs/powql.js

@@ -74,6 +74,7 @@ const node_crypto_1 = require("node:crypto");
 const errors_js_1 = require("./errors.js");
 const nested_write_js_1 = require("./nested-write.js");
 const powdb_js_1 = require("./powdb.js");
+const filters_js_1 = require("./query/filters.js");
 const utils_js_1 = require("./query/utils.js");
 const schema_js_1 = require("./schema.js");
 /**
@@ -511,7 +512,22 @@ class PowqlInterface {
             return '';
         const parts = keys.map(([field, dir]) => {
             if (dir && typeof dir === 'object') {
-                throw new errors_js_1.UnsupportedFeatureError('vector / distance ordering', 'PowDB', `field "${field}"`);
+                // Name the actual feature in the refusal — a pick-row ordering
+                // reported as "vector / distance ordering" sends users hunting for
+                // pgvector docs. All object-valued orderings stay E017 on PowDB.
+                const o = dir;
+                const feature = (0, filters_js_1.isRelationPickOrderBy)(dir)
+                    ? 'relation pick-row ordering'
+                    : 'distance' in o
+                        ? 'vector / distance ordering'
+                        : Array.isArray(o.path)
+                            ? 'JSON-path ordering'
+                            : '_count' in o
+                                ? 'relation _count ordering'
+                                : 'sort' in o || 'nulls' in o
+                                    ? 'NULLS placement / sort-spec ordering'
+                                    : 'object-valued ordering';
+                throw new errors_js_1.UnsupportedFeatureError(feature, 'PowDB', `field "${field}"`);
             }
             return `${this.ref(field)} ${dir === 'desc' ? 'desc' : 'asc'}`;
         });
@@ -985,7 +1001,13 @@ class PowqlInterface {
             const { TransactionClient } = await Promise.resolve().then(() => __importStar(require('./client.js')));
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
             const ctx = { schema: this.schema, tx: tx };
-            const result = await fn(ctx);
+            // Plant the single-writer re-entrancy marker for the implicit tx's
+            // subtree (same seam TurbineClient.$transaction uses) — user code that
+            // fires db.$transaction from inside (e.g. $use middleware around a
+            // nested-write child op) must fast-fail E017, not queue into deadlock.
+            const wrap = client
+                .wrapTransactionCallback;
+            const result = await (wrap ? wrap(() => fn(ctx)) : fn(ctx));
             await client.query(d?.commitStatement?.() ?? 'commit');
             return result;
         }
@@ -1149,6 +1171,27 @@ class PowqlInterface {
     }
     async groupBy(args) {
         return this.withMiddleware('groupBy', args, async () => {
+            // The SQL-only groupBy extensions (DISTINCT ON row source, JSON-path
+            // group keys / aggregate targets) have no PowQL equivalent: refuse
+            // clearly instead of emitting broken PowQL.
+            if (args.distinctOn) {
+                throw new errors_js_1.UnsupportedFeatureError('groupBy distinctOn row source', 'PowDB');
+            }
+            for (const entry of args.by) {
+                if (typeof entry !== 'string') {
+                    throw new errors_js_1.UnsupportedFeatureError('JSON-path groupBy keys', 'PowDB');
+                }
+            }
+            for (const fn of ['_sum', '_avg', '_min', '_max']) {
+                const spec = args[fn];
+                if (!spec)
+                    continue;
+                for (const value of Object.values(spec)) {
+                    if (value !== undefined && typeof value !== 'boolean') {
+                        throw new errors_js_1.UnsupportedFeatureError(`JSON-path ${fn} aggregate targets`, 'PowDB');
+                    }
+                }
+            }
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
             const where = this.buildWhere(resolvedWhere, params);

package/dist/cjs/query/batched-loader.js

@@ -52,9 +52,11 @@ exports.includeKeysForBatching = includeKeysForBatching;
 exports.stripFields = stripFields;
 exports.neededParentKeyFields = neededParentKeyFields;
 exports.resolveCountRelations = resolveCountRelations;
+exports.rejectNestedPickOrder = rejectNestedPickOrder;
 exports.loadRelationsBatched = loadRelationsBatched;
 const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
+const filters_js_1 = require("./filters.js");
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
  * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit — it
@@ -184,6 +186,34 @@ function resolveCountRelations(parentMeta, countSpec) {
 function keyOf(value) {
     return String(value);
 }
+/**
+ * Reject pick-row relation ordering anywhere inside a `with` tree's orderBy —
+ * strategy parity with the join path, which throws this exact E003 at SQL
+ * build time (`pickOrderNestedError` in builder.ts). Without this guard the
+ * loaders would forward `options.orderBy` as the child reader's TOP-LEVEL
+ * findMany orderBy, where the pick shape compiles fine — so the same query
+ * would execute on 'batched' but throw on 'join'. Walks the whole tree up
+ * front so acceptance never depends on which levels have rows — the batched
+ * runners in builder.ts call this BEFORE the base query (a zero-row base
+ * result must still reject, exactly like the join strategy's build-time throw).
+ */
+function rejectNestedPickOrder(withClause) {
+    for (const spec of Object.values(withClause)) {
+        if (!spec || spec === true)
+            continue;
+        const options = spec;
+        if (options.orderBy) {
+            for (const [key, value] of Object.entries(options.orderBy)) {
+                if ((0, filters_js_1.isRelationPickOrderBy)(value)) {
+                    throw new errors_js_1.ValidationError(`[turbine] Pick-row ordering on relation "${key}" is only supported in a top-level ` +
+                        'findMany orderBy: nested `with` orderBy does not support it.');
+                }
+            }
+        }
+        if (options.with)
+            rejectNestedPickOrder(options.with);
+    }
+}
 /**
  * Load every relation in `withClause` for `parents` and attach it onto each row
  * in place. Mirrors the join strategy's output shape exactly. Recurses for nested
@@ -192,6 +222,10 @@ function keyOf(value) {
 async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0, path = [ctx.parentMeta.name]) {
     if (depth >= MAX_DEPTH)
         throw new errors_js_1.CircularRelationError([...path, '…']);
+    // Scope-rule parity with the join strategy: validate the whole tree BEFORE
+    // the empty-parents early return, so accept/reject never depends on data.
+    if (depth === 0)
+        rejectNestedPickOrder(withClause);
     if (parents.length === 0)
         return;
     // Sibling relations are independent (each writes only its own parent[relName]