turbine-orm 0.73.1 → 0.74.0

package/dist/cjs/powql.d.ts

@@ -196,7 +196,25 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * makes a core rule arrive on its own, and an engine that reads `take` but
      * not `skip` pages differently from one that reads both.
      */
+    /**
+     * Fill in the deterministic per-relation ordering `stableRelationOrder` asks
+     * for, through the shared transform the SQL engines use.
+     *
+     * PowDB accepted this option and did nothing with it before 0.74.0, so
+     * relation rows came back in whatever order the engine produced, from the one
+     * option whose entire purpose is that they do not. Same resolution as
+     * QueryInterface: a per-query flag wins, else the client-level default.
+     */
+    private withStableRelationOrder;
     private normalizeArgs;
+    /**
+     * `jsonEncoding` selects between PostgreSQL's `json_build_object` and
+     * `json_build_array` row encodings for relation subqueries. PowQL emits no
+     * JSON row encoding at all, so there is nothing for the option to select and
+     * it was simply dropped: the caller asked for a wire format and got silence.
+     * Refused for the same reason `forceCustomPlan` is.
+     */
+    private assertNoJsonEncoding;
     private assertNoForceCustomPlan;
     /** See query/compound-unique.ts: one rule and one message across engines. */
     private assertIdentifiesOneRow;
@@ -883,5 +901,25 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * `{ OR: [{ f: undefined }] }`, compiles to the empty string and is refused,
      * because emitting a filter-less write would hit every row.
      */
+    /**
+     * AND this table's configured global filter (soft-delete / multi-tenancy)
+     * onto an ALREADY-COMPILED user filter, pushing its params after the user's.
+     *
+     * Before 0.74.0 `PowqlInterface` did not read `globalFilters` at all, so a
+     * client configured for multi-tenancy applied its tenant predicate on every
+     * SQL engine and NONE on PowDB, silently, and `skipGlobalFilters` was
+     * accepted and inert. The rule itself is shared
+     * ({@link resolveGlobalFilterFrom}) rather than restated here.
+     *
+     * It takes a COMPILED user filter, and that ordering is the contract, not an
+     * implementation detail: the empty-`where` guard must see the USER filter
+     * alone, or a configured global filter would silently satisfy it and turn a
+     * refused mass mutation into an accepted one. Every write call site therefore
+     * calls {@link assertCompiledWhere} first and this second.
+     *
+     * `alias` is forwarded so the nested/native-join paths qualify the filter's
+     * column references the same way they qualify the user's.
+     */
+    private applyGlobalFilter;
     private assertCompiledWhere;
 }

package/dist/cjs/powql.js

@@ -430,8 +430,38 @@ class PowqlInterface {
      * makes a core rule arrive on its own, and an engine that reads `take` but
      * not `skip` pages differently from one that reads both.
      */
+    /**
+     * Fill in the deterministic per-relation ordering `stableRelationOrder` asks
+     * for, through the shared transform the SQL engines use.
+     *
+     * PowDB accepted this option and did nothing with it before 0.74.0, so
+     * relation rows came back in whatever order the engine produced, from the one
+     * option whose entire purpose is that they do not. Same resolution as
+     * QueryInterface: a per-query flag wins, else the client-level default.
+     */
+    withStableRelationOrder(args) {
+        if (!args?.with)
+            return args;
+        const on = args.stableRelationOrder ?? this.options.stableRelationOrder === true;
+        if (!on)
+            return args;
+        const ordered = (0, relation_names_js_1.applyStableRelationOrderTo)(this.schema, args.with, this.table);
+        return ordered === args.with ? args : { ...args, with: ordered };
+    }
     normalizeArgs(args) {
-        return (0, utils_js_1.normalizePagination)(this.withDeclaredRelationNames(args));
+        return (0, utils_js_1.normalizePagination)(this.withStableRelationOrder(this.withDeclaredRelationNames(args)));
+    }
+    /**
+     * `jsonEncoding` selects between PostgreSQL's `json_build_object` and
+     * `json_build_array` row encodings for relation subqueries. PowQL emits no
+     * JSON row encoding at all, so there is nothing for the option to select and
+     * it was simply dropped: the caller asked for a wire format and got silence.
+     * Refused for the same reason `forceCustomPlan` is.
+     */
+    assertNoJsonEncoding(args) {
+        if (args?.jsonEncoding === undefined)
+            return;
+        throw new errors_js_1.UnsupportedFeatureError('jsonEncoding', 'PowDB', 'PowQL emits no JSON row encoding for relations, so there is nothing to select; omit the option');
     }
     assertNoForceCustomPlan(args) {
         if (args?.forceCustomPlan !== true)
@@ -1386,6 +1416,7 @@ class PowqlInterface {
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
         this.assertNoForceCustomPlan(args);
+        this.assertNoJsonEncoding(args);
         args = this.normalizeArgs(args);
         return this.withMiddleware('findMany', args, async () => {
             // `limit: 0` means "no rows" (SQL `LIMIT 0`), and answering it client-side
@@ -1467,7 +1498,8 @@ class PowqlInterface {
         }
         const nest = nestedPlans.length > 0 || linkPlans.length > 0;
         const alias = nest ? 't0' : undefined;
-        const where = this.buildWhere(resolvedWhere, params, alias);
+        let where = this.buildWhere(resolvedWhere, params, alias);
+        where = this.applyGlobalFilter(where, params, args.skipGlobalFilters, alias);
         // PowQL's `distinct` is row-wide, so these names never reach the emitted
         // statement. They are still caller-supplied names, and a name resolves or
         // throws: reading the array for its LENGTH alone let `distinct: ['nope']`
@@ -1544,6 +1576,7 @@ class PowqlInterface {
     }
     async findUnique(args) {
         this.assertNoForceCustomPlan(args);
+        this.assertNoJsonEncoding(args);
         args = this.normalizeArgs(args);
         // Prisma compound-unique selector → column conjunction (engine parity with
         // the SQL findUnique family; pure metadata, so this is a one-line adoption).
@@ -2638,14 +2671,41 @@ class PowqlInterface {
             }
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
-            this.assertCompiledWhere(where, false, 'update');
-            const setClause = this.buildUpdateAssignments(args.data, params);
+            let where = this.buildWhere(resolvedWhere, params);
+            // `false` here refused an empty where even WITH the opt-in, while every
+            // SQL engine accepted it: verified by probe on buildUpdate/buildDelete.
+            this.assertCompiledWhere(where, (0, types_js_1.resolveUnsafeFlag)(args.allowFullTableScan, 'allowFullTableScan'), 'update');
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
+            let setClause = this.buildUpdateAssignments(args.data, params);
+            // Optimistic locking, matching the SQL engines exactly: bump the version
+            // column in the SET, add `version = expected` to the filter, and treat
+            // "matched no row" as a lost race rather than a missing row.
+            //
+            // PowqlInterface ignored `optimisticLock` outright before 0.74.0, which is
+            // worse than not supporting it: the update applied, the caller's version
+            // check never happened, and a concurrent writer's change was overwritten
+            // by a caller who believed they held the lock.
+            const lock = args.optimisticLock;
+            if (lock) {
+                const versionCol = (0, powdb_js_1.quotePowqlIdent)(this.column(lock.field).name);
+                setClause += `, ${versionCol} := ${this.ref(lock.field)} + 1`;
+                params.push(lock.expected);
+                const check = `${this.ref(lock.field)} = $${params.length}`;
+                where = where ? `(${where}) and (${check})` : check;
+            }
             // `returning` hands back the post-update row(s); take the first (single-row contract).
             const { rows, native } = await this.exec(`${this.qt} filter ${where} update { ${setClause} } returning`, params, args.timeout, 'update');
             const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
-            if (!row)
+            if (!row) {
+                if (lock) {
+                    throw new errors_js_1.OptimisticLockError({
+                        table: this.table,
+                        versionField: lock.field,
+                        expectedVersion: lock.expected,
+                    });
+                }
                 throw new errors_js_1.NotFoundError({ table: this.table, where: args.where });
+            }
             return row;
         });
     }
@@ -2653,8 +2713,9 @@ class PowqlInterface {
         return this.withMiddleware('updateMany', args, async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
+            let where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, (0, types_js_1.resolveUnsafeFlag)(args.allowFullTableScan, 'allowFullTableScan'), 'updateMany');
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             const setClause = this.buildUpdateAssignments(args.data, params);
             const filter = where ? ` filter ${where}` : '';
             const { rowCount } = await this.exec(`${this.qt}${filter} update { ${setClause} }`, params, args.timeout, 'updateMany');
@@ -2789,8 +2850,9 @@ class PowqlInterface {
         return this.withMiddleware('delete', args, async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
-            this.assertCompiledWhere(where, false, 'delete');
+            let where = this.buildWhere(resolvedWhere, params);
+            this.assertCompiledWhere(where, (0, types_js_1.resolveUnsafeFlag)(args.allowFullTableScan, 'allowFullTableScan'), 'delete');
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             // `returning` hands back the deleted row(s), no separate pre-image reselect needed.
             const { rows, native } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout, 'delete');
             const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
@@ -2803,8 +2865,9 @@ class PowqlInterface {
         return this.withMiddleware('deleteMany', args, async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
+            let where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, (0, types_js_1.resolveUnsafeFlag)(args.allowFullTableScan, 'allowFullTableScan'), 'deleteMany');
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
             const { rowCount } = await this.exec(`${this.qt}${filter} delete`, params, args.timeout, 'deleteMany');
             return { count: rowCount };
@@ -2875,7 +2938,8 @@ class PowqlInterface {
         return this.withMiddleware('count', (args ?? {}), async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
+            let where = this.buildWhere(resolvedWhere, params);
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
             const { rows } = await this.exec(`count(${this.qt}${filter})`, params, args.timeout, 'count');
             return Number((rows[0]?.value ?? rows[0]?.count ?? 0));
@@ -2916,7 +2980,8 @@ class PowqlInterface {
             const result = {};
             const filterParams = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, filterParams);
+            let where = this.buildWhere(resolvedWhere, filterParams);
+            where = this.applyGlobalFilter(where, filterParams, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
             const scalar = async (expr) => {
                 const params = [...filterParams];
@@ -2978,7 +3043,8 @@ class PowqlInterface {
             const emitNative = Boolean(this.capabilities.nativeRaw);
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
+            let where = this.buildWhere(resolvedWhere, params);
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
             // Result-key namespace, mirroring the SQL builder's `claimResultKey`
             // (query/builder.ts): a group-key / aggregate output-name collision (with
@@ -3331,6 +3397,36 @@ class PowqlInterface {
      * `{ OR: [{ f: undefined }] }`, compiles to the empty string and is refused,
      * because emitting a filter-less write would hit every row.
      */
+    /**
+     * AND this table's configured global filter (soft-delete / multi-tenancy)
+     * onto an ALREADY-COMPILED user filter, pushing its params after the user's.
+     *
+     * Before 0.74.0 `PowqlInterface` did not read `globalFilters` at all, so a
+     * client configured for multi-tenancy applied its tenant predicate on every
+     * SQL engine and NONE on PowDB, silently, and `skipGlobalFilters` was
+     * accepted and inert. The rule itself is shared
+     * ({@link resolveGlobalFilterFrom}) rather than restated here.
+     *
+     * It takes a COMPILED user filter, and that ordering is the contract, not an
+     * implementation detail: the empty-`where` guard must see the USER filter
+     * alone, or a configured global filter would silently satisfy it and turn a
+     * refused mass mutation into an accepted one. Every write call site therefore
+     * calls {@link assertCompiledWhere} first and this second.
+     *
+     * `alias` is forwarded so the nested/native-join paths qualify the filter's
+     * column references the same way they qualify the user's.
+     */
+    applyGlobalFilter(compiledUserWhere, params, skip, alias) {
+        const gf = (0, where_js_1.resolveGlobalFilterFrom)(this.options.globalFilters, this.table, (0, types_js_1.resolveSkipGlobalFilters)(skip));
+        if (!gf)
+            return compiledUserWhere;
+        const gfWhere = this.buildWhere(gf, params, alias);
+        if (!gfWhere)
+            return compiledUserWhere;
+        if (!compiledUserWhere)
+            return gfWhere;
+        return `(${compiledUserWhere}) and (${gfWhere})`;
+    }
     assertCompiledWhere(compiledWhere, allow, action) {
         if (allow === true)
             return;

package/dist/cjs/query/builder.js

@@ -444,14 +444,8 @@ function unlockNestedWriteTx(tx) {
  * orderBy is never overwritten while an empty `{}` / `[]` still gets the
  * synthesized PK order.
  */
-function isEmptyOrderBy(orderBy) {
-    if (Array.isArray(orderBy))
-        return orderBy.length === 0;
-    if (orderBy && typeof orderBy === 'object') {
-        return Object.values(orderBy).every((v) => v === undefined);
-    }
-    return orderBy === undefined || orderBy === null;
-}
+// Moved to ./filters.ts in 0.74.0 so PowqlInterface consumes the SAME
+// predicate rather than a second copy of it. See applyStableRelationOrderTo.
 /** The two accepted {@link JsonEncoding} values, frozen so the check is total. */
 const JSON_ENCODINGS = Object.freeze(['object', 'positional']);
 /**
@@ -1155,46 +1149,10 @@ class QueryInterface {
      * nothing stable to order by, so both are left untouched.
      */
     applyStableRelationOrder(withClause, table, depth = 0) {
-        if (depth >= 10)
-            return withClause; // parity with the build depth cap
-        const meta = this.schema.tables[table];
-        if (!meta)
-            return withClause;
-        let out;
-        for (const [relName, spec] of Object.entries(withClause)) {
-            if (relName === '_count' || !spec)
-                continue; // `_count` is a count, not a row load
-            const rel = (0, utils_js_1.resolveRelationDef)(meta.relations, relName);
-            if (!rel)
-                continue; // unknown relation, let the build path surface E005
-            const options = spec === true ? {} : spec;
-            // Recurse first so a nested change alone still clones this level.
-            const nestedWith = options.with;
-            const newNested = nestedWith ? this.applyStableRelationOrder(nestedWith, rel.to, depth + 1) : undefined;
-            const nestedChanged = newNested !== undefined && newNested !== nestedWith;
-            const isToMany = rel.type === 'hasMany' || rel.type === 'manyToMany';
-            const hasOrder = options.orderBy !== undefined && !isEmptyOrderBy(options.orderBy);
-            let synthOrder;
-            if (isToMany && !hasOrder) {
-                const targetMeta = this.schema.tables[rel.to];
-                const pk = targetMeta?.primaryKey ?? [];
-                if (targetMeta && pk.length > 0) {
-                    const pkFields = pk.map((c) => targetMeta.reverseColumnMap[c] ?? c);
-                    synthOrder =
-                        pkFields.length === 1 ? { [pkFields[0]]: 'asc' } : pkFields.map((f) => ({ [f]: 'asc' }));
-                }
-            }
-            if (!synthOrder && !nestedChanged)
-                continue; // nothing to change, keep the ref
-            out ??= { ...withClause };
-            const clonedSpec = { ...options };
-            if (synthOrder)
-                clonedSpec.orderBy = synthOrder;
-            if (nestedChanged)
-                clonedSpec.with = newNested;
-            out[relName] = clonedSpec;
-        }
-        return out ?? withClause;
+        // The transform itself lives in ./relation-names.ts as of 0.74.0, so PowDB
+        // runs the SAME rule instead of a second copy that accepted the option and
+        // did nothing.
+        return (0, relation_names_js_1.applyStableRelationOrderTo)(this.schema, withClause, table, depth);
     }
     // -------------------------------------------------------------------------
     // Deterministic pagination (unordered LIMIT/OFFSET)
@@ -1281,7 +1239,7 @@ class QueryInterface {
             return false;
         if (args.distinct !== undefined)
             return false;
-        if (!isEmptyOrderBy(args.orderBy))
+        if (!(0, filters_js_1.isEmptyOrderBy)(args.orderBy))
             return false;
         if (args.limit !== undefined || args.offset !== undefined)
             return true;
@@ -2672,7 +2630,7 @@ class QueryInterface {
         // array conditionally end up passing `[]`. Normalized here, before the
         // implicit-ordering and fingerprinting steps, so every downstream path sees
         // one shape.
-        if (args?.orderBy !== undefined && isEmptyOrderBy(args.orderBy)) {
+        if (args?.orderBy !== undefined && (0, filters_js_1.isEmptyOrderBy)(args.orderBy)) {
             args = { ...args, orderBy: undefined };
         }
         // Drop `orderBy` terms that sort by an expression an earlier term already

package/dist/cjs/query/filters.d.ts

@@ -387,3 +387,11 @@ export declare function normalizeOrderBy(value: OrderDirection | OrderBySpec): {
     dir: 'ASC' | 'DESC';
     nulls?: 'first' | 'last';
 };
+/**
+ * Is this `orderBy` effectively absent?
+ *
+ * `{}` and `[]` and `{ id: undefined }` all mean "no ordering asked for". Used
+ * by the stable-relation-order transform so an explicit (non-empty) orderBy is
+ * never overwritten while an empty one still gets the synthesized PK order.
+ */
+export declare function isEmptyOrderBy(orderBy: unknown): boolean;

package/dist/cjs/query/filters.js

@@ -33,6 +33,7 @@ exports.orderKeyIdentity = orderKeyIdentity;
 exports.dedupeOrderEntries = dedupeOrderEntries;
 exports.dedupeColumnList = dedupeColumnList;
 exports.normalizeOrderBy = normalizeOrderBy;
+exports.isEmptyOrderBy = isEmptyOrderBy;
 const errors_js_1 = require("../errors.js");
 const types_js_1 = require("./types.js");
 const utils_js_1 = require("./utils.js");
@@ -701,3 +702,18 @@ function normalizeOrderBy(value) {
     }
     return { dir: String(value).toLowerCase() === 'desc' ? 'DESC' : 'ASC' };
 }
+/**
+ * Is this `orderBy` effectively absent?
+ *
+ * `{}` and `[]` and `{ id: undefined }` all mean "no ordering asked for". Used
+ * by the stable-relation-order transform so an explicit (non-empty) orderBy is
+ * never overwritten while an empty one still gets the synthesized PK order.
+ */
+function isEmptyOrderBy(orderBy) {
+    if (Array.isArray(orderBy))
+        return orderBy.length === 0;
+    if (orderBy && typeof orderBy === 'object') {
+        return Object.values(orderBy).every((v) => v === undefined);
+    }
+    return orderBy === undefined || orderBy === null;
+}

package/dist/cjs/query/relation-names.d.ts

@@ -50,3 +50,21 @@ import type { WithClause } from './types.js';
  * Returns the input by reference when no key changed.
  */
 export declare function normalizeWithClause(schema: SchemaMetadata, table: string, withClause: WithClause | undefined, depth?: number): WithClause | undefined;
+/**
+ * Fill in a deterministic `orderBy` for every to-many relation in a `with`
+ * clause that did not ask for one, using the target table's primary key.
+ *
+ * THE single authority for `stableRelationOrder`, on every engine. It was a
+ * private method on `QueryInterface` until 0.74.0, which meant PowDB accepted
+ * the option and did nothing with it: relation rows came back in whatever order
+ * the engine produced, from the option whose entire purpose is that they do
+ * not. Restating the rule in `powql.ts` would have been the 0.64 projection
+ * resolver again, so it moved here instead, into the same "normalize the whole
+ * `with` tree once, before anything reads it" slot as
+ * {@link normalizeWithClause}.
+ *
+ * Returns the input BY REFERENCE when nothing changed, so a query that already
+ * orders every relation allocates nothing and its SQL/fingerprint stay
+ * byte-identical.
+ */
+export declare function applyStableRelationOrderTo(schema: SchemaMetadata, withClause: WithClause, table: string, depth?: number): WithClause;

package/dist/cjs/query/relation-names.js

@@ -44,6 +44,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeWithClause = normalizeWithClause;
+exports.applyStableRelationOrderTo = applyStableRelationOrderTo;
+const filters_js_1 = require("./filters.js");
 const utils_js_1 = require("./utils.js");
 /** Depth cap mirroring the builder's own, so a cyclic `with` cannot spin here. */
 const MAX_DEPTH = 12;
@@ -118,3 +120,61 @@ function normalizeCount(meta, count) {
  * already a documented single authority; wrapping them here would add a second
  * name for the same rule without removing a caller.
  */
+/**
+ * Fill in a deterministic `orderBy` for every to-many relation in a `with`
+ * clause that did not ask for one, using the target table's primary key.
+ *
+ * THE single authority for `stableRelationOrder`, on every engine. It was a
+ * private method on `QueryInterface` until 0.74.0, which meant PowDB accepted
+ * the option and did nothing with it: relation rows came back in whatever order
+ * the engine produced, from the option whose entire purpose is that they do
+ * not. Restating the rule in `powql.ts` would have been the 0.64 projection
+ * resolver again, so it moved here instead, into the same "normalize the whole
+ * `with` tree once, before anything reads it" slot as
+ * {@link normalizeWithClause}.
+ *
+ * Returns the input BY REFERENCE when nothing changed, so a query that already
+ * orders every relation allocates nothing and its SQL/fingerprint stay
+ * byte-identical.
+ */
+function applyStableRelationOrderTo(schema, withClause, table, depth = 0) {
+    if (depth >= 10)
+        return withClause; // parity with the build depth cap
+    const meta = schema.tables[table];
+    if (!meta)
+        return withClause;
+    let out;
+    for (const [relName, spec] of Object.entries(withClause)) {
+        if (relName === '_count' || !spec)
+            continue; // `_count` is a count, not a row load
+        const rel = (0, utils_js_1.resolveRelationDef)(meta.relations, relName);
+        if (!rel)
+            continue; // unknown relation, let the build path surface E005
+        const options = spec === true ? {} : spec;
+        // Recurse first so a nested change alone still clones this level.
+        const nestedWith = options.with;
+        const newNested = nestedWith ? applyStableRelationOrderTo(schema, nestedWith, rel.to, depth + 1) : undefined;
+        const nestedChanged = newNested !== undefined && newNested !== nestedWith;
+        const isToMany = rel.type === 'hasMany' || rel.type === 'manyToMany';
+        const hasOrder = options.orderBy !== undefined && !(0, filters_js_1.isEmptyOrderBy)(options.orderBy);
+        let synthOrder;
+        if (isToMany && !hasOrder) {
+            const targetMeta = schema.tables[rel.to];
+            const pk = targetMeta?.primaryKey ?? [];
+            if (targetMeta && pk.length > 0) {
+                const pkFields = pk.map((c) => targetMeta.reverseColumnMap[c] ?? c);
+                synthOrder = pkFields.length === 1 ? { [pkFields[0]]: 'asc' } : pkFields.map((f) => ({ [f]: 'asc' }));
+            }
+        }
+        if (!synthOrder && !nestedChanged)
+            continue; // nothing to change, keep the ref
+        out ??= { ...withClause };
+        const clonedSpec = { ...options };
+        if (synthOrder)
+            clonedSpec.orderBy = synthOrder;
+        if (nestedChanged)
+            clonedSpec.with = newNested;
+        out[relName] = clonedSpec;
+    }
+    return out ?? withClause;
+}

package/dist/cjs/query/where.d.ts

@@ -285,6 +285,20 @@ export declare function buildWhere<T extends object>(qi: BuilderCtx, where: Wher
     sql: string;
     params: unknown[];
 };
+/**
+ * THE global-filter resolution rule, with no dependency on a `BuilderCtx`.
+ *
+ * Split out from {@link resolveGlobalFilter} so `PowqlInterface` can consume
+ * the SAME rule rather than a transcription of it. It is a parallel
+ * implementation of the public surface, and this repository's history is
+ * unambiguous that a rule written twice is how two engines come to disagree
+ * (the 0.64 projection resolver, the 0.73 findUnique guard). Every clause here
+ * is load-bearing on both engines: a function filter is evaluated PER BUILD so
+ * per-request tenancy works, an all-undefined filter is treated as absent so it
+ * cannot emit a dangling clause, and `skip` is honoured in both its whole-query
+ * and per-table forms.
+ */
+export declare function resolveGlobalFilterFrom(filters: GlobalFilters | undefined, table: string, skip: ResolvedSkipGlobalFilters | undefined): Record<string, unknown> | null;
 /**
  * Resolve the configured global filter for `table`, evaluating a function
  * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when

package/dist/cjs/query/where.js

@@ -24,6 +24,7 @@ exports.collectJsonFilterParams = collectJsonFilterParams;
 exports.collectArrayFilterParams = collectArrayFilterParams;
 exports.collectVectorFilterParams = collectVectorFilterParams;
 exports.buildWhere = buildWhere;
+exports.resolveGlobalFilterFrom = resolveGlobalFilterFrom;
 exports.resolveGlobalFilter = resolveGlobalFilter;
 exports.mergeGlobalFilter = mergeGlobalFilter;
 exports.targetGlobalFilterAlias = targetGlobalFilterAlias;
@@ -436,12 +437,19 @@ function buildWhere(qi, where) {
     return { sql: ` WHERE ${clause}`, params };
 }
 /**
- * Resolve the configured global filter for `table`, evaluating a function
- * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
- * no filter applies, the query opted out, or the filter is empty.
+ * THE global-filter resolution rule, with no dependency on a `BuilderCtx`.
+ *
+ * Split out from {@link resolveGlobalFilter} so `PowqlInterface` can consume
+ * the SAME rule rather than a transcription of it. It is a parallel
+ * implementation of the public surface, and this repository's history is
+ * unambiguous that a rule written twice is how two engines come to disagree
+ * (the 0.64 projection resolver, the 0.73 findUnique guard). Every clause here
+ * is load-bearing on both engines: a function filter is evaluated PER BUILD so
+ * per-request tenancy works, an all-undefined filter is treated as absent so it
+ * cannot emit a dangling clause, and `skip` is honoured in both its whole-query
+ * and per-table forms.
  */
-function resolveGlobalFilter(qi, table, skip = qi.currentSkip) {
-    const filters = qi.globalFilters;
+function resolveGlobalFilterFrom(filters, table, skip) {
     if (!filters)
         return null;
     if (skip === true)
@@ -461,6 +469,14 @@ function resolveGlobalFilter(qi, table, skip = qi.currentSkip) {
         return null;
     return obj;
 }
+/**
+ * Resolve the configured global filter for `table`, evaluating a function
+ * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
+ * no filter applies, the query opted out, or the filter is empty.
+ */
+function resolveGlobalFilter(qi, table, skip = qi.currentSkip) {
+    return resolveGlobalFilterFrom(qi.globalFilters, table, skip);
+}
 /**
  * AND-merge this table's resolved global filter into a user `where`. Either
  * side may be absent. When no filter applies the user where is returned by

package/dist/powql.d.ts

@@ -196,7 +196,25 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * makes a core rule arrive on its own, and an engine that reads `take` but
      * not `skip` pages differently from one that reads both.
      */
+    /**
+     * Fill in the deterministic per-relation ordering `stableRelationOrder` asks
+     * for, through the shared transform the SQL engines use.
+     *
+     * PowDB accepted this option and did nothing with it before 0.74.0, so
+     * relation rows came back in whatever order the engine produced, from the one
+     * option whose entire purpose is that they do not. Same resolution as
+     * QueryInterface: a per-query flag wins, else the client-level default.
+     */
+    private withStableRelationOrder;
     private normalizeArgs;
+    /**
+     * `jsonEncoding` selects between PostgreSQL's `json_build_object` and
+     * `json_build_array` row encodings for relation subqueries. PowQL emits no
+     * JSON row encoding at all, so there is nothing for the option to select and
+     * it was simply dropped: the caller asked for a wire format and got silence.
+     * Refused for the same reason `forceCustomPlan` is.
+     */
+    private assertNoJsonEncoding;
     private assertNoForceCustomPlan;
     /** See query/compound-unique.ts: one rule and one message across engines. */
     private assertIdentifiesOneRow;
@@ -883,5 +901,25 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * `{ OR: [{ f: undefined }] }`, compiles to the empty string and is refused,
      * because emitting a filter-less write would hit every row.
      */
+    /**
+     * AND this table's configured global filter (soft-delete / multi-tenancy)
+     * onto an ALREADY-COMPILED user filter, pushing its params after the user's.
+     *
+     * Before 0.74.0 `PowqlInterface` did not read `globalFilters` at all, so a
+     * client configured for multi-tenancy applied its tenant predicate on every
+     * SQL engine and NONE on PowDB, silently, and `skipGlobalFilters` was
+     * accepted and inert. The rule itself is shared
+     * ({@link resolveGlobalFilterFrom}) rather than restated here.
+     *
+     * It takes a COMPILED user filter, and that ordering is the contract, not an
+     * implementation detail: the empty-`where` guard must see the USER filter
+     * alone, or a configured global filter would silently satisfy it and turn a
+     * refused mass mutation into an accepted one. Every write call site therefore
+     * calls {@link assertCompiledWhere} first and this second.
+     *
+     * `alias` is forwarded so the nested/native-join paths qualify the filter's
+     * column references the same way they qualify the user's.
+     */
+    private applyGlobalFilter;
     private assertCompiledWhere;
 }

package/dist/powql.js

@@ -35,20 +35,20 @@
  * @module
  */
 import { randomUUID } from 'node:crypto';
-import { NotFoundError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
+import { NotFoundError, OptimisticLockError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isPowdbDatetimeColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlDotted, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb.js';
 import { assertAggregatePiiOptIn } from './query/aggregates.js';
 import { assertWhereIdentifiesOneRow, expandCompoundUniqueWhere } from './query/compound-unique.js';
 import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
 import { warnUnknownQueryOptions } from './query/option-surface.js';
-import { normalizeWithClause } from './query/relation-names.js';
+import { applyStableRelationOrderTo, normalizeWithClause } from './query/relation-names.js';
 // The privilege sentinel and its resolver: `includePii` / `allowFullTableScan`
 // are unlocked ONLY by the UNSAFE symbol, on this engine exactly as on the SQL
 // engines, so a spread request body cannot turn either on here either.
-import { assertDirectionToken, resolveUnsafeFlag, UNSAFE } from './query/types.js';
+import { assertDirectionToken, resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './query/types.js';
 import { escapeLike, normalizePagination, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, } from './query/utils.js';
-import { assertJsonFilterKeys, jsonStringEntries } from './query/where.js';
+import { assertJsonFilterKeys, jsonStringEntries, resolveGlobalFilterFrom } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
  * Max parent keys per relation-loader `in (…)` query. A `with` over a large
@@ -394,8 +394,38 @@ export class PowqlInterface {
      * makes a core rule arrive on its own, and an engine that reads `take` but
      * not `skip` pages differently from one that reads both.
      */
+    /**
+     * Fill in the deterministic per-relation ordering `stableRelationOrder` asks
+     * for, through the shared transform the SQL engines use.
+     *
+     * PowDB accepted this option and did nothing with it before 0.74.0, so
+     * relation rows came back in whatever order the engine produced, from the one
+     * option whose entire purpose is that they do not. Same resolution as
+     * QueryInterface: a per-query flag wins, else the client-level default.
+     */
+    withStableRelationOrder(args) {
+        if (!args?.with)
+            return args;
+        const on = args.stableRelationOrder ?? this.options.stableRelationOrder === true;
+        if (!on)
+            return args;
+        const ordered = applyStableRelationOrderTo(this.schema, args.with, this.table);
+        return ordered === args.with ? args : { ...args, with: ordered };
+    }
     normalizeArgs(args) {
-        return normalizePagination(this.withDeclaredRelationNames(args));
+        return normalizePagination(this.withStableRelationOrder(this.withDeclaredRelationNames(args)));
+    }
+    /**
+     * `jsonEncoding` selects between PostgreSQL's `json_build_object` and
+     * `json_build_array` row encodings for relation subqueries. PowQL emits no
+     * JSON row encoding at all, so there is nothing for the option to select and
+     * it was simply dropped: the caller asked for a wire format and got silence.
+     * Refused for the same reason `forceCustomPlan` is.
+     */
+    assertNoJsonEncoding(args) {
+        if (args?.jsonEncoding === undefined)
+            return;
+        throw new UnsupportedFeatureError('jsonEncoding', 'PowDB', 'PowQL emits no JSON row encoding for relations, so there is nothing to select; omit the option');
     }
     assertNoForceCustomPlan(args) {
         if (args?.forceCustomPlan !== true)
@@ -1350,6 +1380,7 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
         this.assertNoForceCustomPlan(args);
+        this.assertNoJsonEncoding(args);
         args = this.normalizeArgs(args);
         return this.withMiddleware('findMany', args, async () => {
             // `limit: 0` means "no rows" (SQL `LIMIT 0`), and answering it client-side
@@ -1431,7 +1462,8 @@ export class PowqlInterface {
         }
         const nest = nestedPlans.length > 0 || linkPlans.length > 0;
         const alias = nest ? 't0' : undefined;
-        const where = this.buildWhere(resolvedWhere, params, alias);
+        let where = this.buildWhere(resolvedWhere, params, alias);
+        where = this.applyGlobalFilter(where, params, args.skipGlobalFilters, alias);
         // PowQL's `distinct` is row-wide, so these names never reach the emitted
         // statement. They are still caller-supplied names, and a name resolves or
         // throws: reading the array for its LENGTH alone let `distinct: ['nope']`
@@ -1508,6 +1540,7 @@ export class PowqlInterface {
     }
     async findUnique(args) {
         this.assertNoForceCustomPlan(args);
+        this.assertNoJsonEncoding(args);
         args = this.normalizeArgs(args);
         // Prisma compound-unique selector → column conjunction (engine parity with
         // the SQL findUnique family; pure metadata, so this is a one-line adoption).
@@ -2602,14 +2635,41 @@ export class PowqlInterface {
             }
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
-            this.assertCompiledWhere(where, false, 'update');
-            const setClause = this.buildUpdateAssignments(args.data, params);
+            let where = this.buildWhere(resolvedWhere, params);
+            // `false` here refused an empty where even WITH the opt-in, while every
+            // SQL engine accepted it: verified by probe on buildUpdate/buildDelete.
+            this.assertCompiledWhere(where, resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'), 'update');
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
+            let setClause = this.buildUpdateAssignments(args.data, params);
+            // Optimistic locking, matching the SQL engines exactly: bump the version
+            // column in the SET, add `version = expected` to the filter, and treat
+            // "matched no row" as a lost race rather than a missing row.
+            //
+            // PowqlInterface ignored `optimisticLock` outright before 0.74.0, which is
+            // worse than not supporting it: the update applied, the caller's version
+            // check never happened, and a concurrent writer's change was overwritten
+            // by a caller who believed they held the lock.
+            const lock = args.optimisticLock;
+            if (lock) {
+                const versionCol = quotePowqlIdent(this.column(lock.field).name);
+                setClause += `, ${versionCol} := ${this.ref(lock.field)} + 1`;
+                params.push(lock.expected);
+                const check = `${this.ref(lock.field)} = $${params.length}`;
+                where = where ? `(${where}) and (${check})` : check;
+            }
             // `returning` hands back the post-update row(s); take the first (single-row contract).
             const { rows, native } = await this.exec(`${this.qt} filter ${where} update { ${setClause} } returning`, params, args.timeout, 'update');
             const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
-            if (!row)
+            if (!row) {
+                if (lock) {
+                    throw new OptimisticLockError({
+                        table: this.table,
+                        versionField: lock.field,
+                        expectedVersion: lock.expected,
+                    });
+                }
                 throw new NotFoundError({ table: this.table, where: args.where });
+            }
             return row;
         });
     }
@@ -2617,8 +2677,9 @@ export class PowqlInterface {
         return this.withMiddleware('updateMany', args, async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
+            let where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'), 'updateMany');
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             const setClause = this.buildUpdateAssignments(args.data, params);
             const filter = where ? ` filter ${where}` : '';
             const { rowCount } = await this.exec(`${this.qt}${filter} update { ${setClause} }`, params, args.timeout, 'updateMany');
@@ -2753,8 +2814,9 @@ export class PowqlInterface {
         return this.withMiddleware('delete', args, async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
-            this.assertCompiledWhere(where, false, 'delete');
+            let where = this.buildWhere(resolvedWhere, params);
+            this.assertCompiledWhere(where, resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'), 'delete');
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             // `returning` hands back the deleted row(s), no separate pre-image reselect needed.
             const { rows, native } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout, 'delete');
             const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
@@ -2767,8 +2829,9 @@ export class PowqlInterface {
         return this.withMiddleware('deleteMany', args, async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
+            let where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'), 'deleteMany');
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
             const { rowCount } = await this.exec(`${this.qt}${filter} delete`, params, args.timeout, 'deleteMany');
             return { count: rowCount };
@@ -2839,7 +2902,8 @@ export class PowqlInterface {
         return this.withMiddleware('count', (args ?? {}), async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
+            let where = this.buildWhere(resolvedWhere, params);
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
             const { rows } = await this.exec(`count(${this.qt}${filter})`, params, args.timeout, 'count');
             return Number((rows[0]?.value ?? rows[0]?.count ?? 0));
@@ -2880,7 +2944,8 @@ export class PowqlInterface {
             const result = {};
             const filterParams = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, filterParams);
+            let where = this.buildWhere(resolvedWhere, filterParams);
+            where = this.applyGlobalFilter(where, filterParams, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
             const scalar = async (expr) => {
                 const params = [...filterParams];
@@ -2942,7 +3007,8 @@ export class PowqlInterface {
             const emitNative = Boolean(this.capabilities.nativeRaw);
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-            const where = this.buildWhere(resolvedWhere, params);
+            let where = this.buildWhere(resolvedWhere, params);
+            where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
             // Result-key namespace, mirroring the SQL builder's `claimResultKey`
             // (query/builder.ts): a group-key / aggregate output-name collision (with
@@ -3295,6 +3361,36 @@ export class PowqlInterface {
      * `{ OR: [{ f: undefined }] }`, compiles to the empty string and is refused,
      * because emitting a filter-less write would hit every row.
      */
+    /**
+     * AND this table's configured global filter (soft-delete / multi-tenancy)
+     * onto an ALREADY-COMPILED user filter, pushing its params after the user's.
+     *
+     * Before 0.74.0 `PowqlInterface` did not read `globalFilters` at all, so a
+     * client configured for multi-tenancy applied its tenant predicate on every
+     * SQL engine and NONE on PowDB, silently, and `skipGlobalFilters` was
+     * accepted and inert. The rule itself is shared
+     * ({@link resolveGlobalFilterFrom}) rather than restated here.
+     *
+     * It takes a COMPILED user filter, and that ordering is the contract, not an
+     * implementation detail: the empty-`where` guard must see the USER filter
+     * alone, or a configured global filter would silently satisfy it and turn a
+     * refused mass mutation into an accepted one. Every write call site therefore
+     * calls {@link assertCompiledWhere} first and this second.
+     *
+     * `alias` is forwarded so the nested/native-join paths qualify the filter's
+     * column references the same way they qualify the user's.
+     */
+    applyGlobalFilter(compiledUserWhere, params, skip, alias) {
+        const gf = resolveGlobalFilterFrom(this.options.globalFilters, this.table, resolveSkipGlobalFilters(skip));
+        if (!gf)
+            return compiledUserWhere;
+        const gfWhere = this.buildWhere(gf, params, alias);
+        if (!gfWhere)
+            return compiledUserWhere;
+        if (!compiledUserWhere)
+            return gfWhere;
+        return `(${compiledUserWhere}) and (${gfWhere})`;
+    }
     assertCompiledWhere(compiledWhere, allow, action) {
         if (allow === true)
             return;

package/dist/query/builder.js

@@ -18,9 +18,9 @@ import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
 import { assertProjectionShape, defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
 import { assertWhereIdentifiesOneRow, expandCompoundUniqueWhere } from './compound-unique.js';
-import { dedupeColumnList, dedupeOrderEntries, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
+import { dedupeColumnList, dedupeOrderEntries, isEmptyOrderBy, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import { warnUnknownQueryOptions } from './option-surface.js';
-import { normalizeWithClause } from './relation-names.js';
+import { applyStableRelationOrderTo, normalizeWithClause } from './relation-names.js';
 import * as relationsMod from './relations.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
 import { isTemporalInfinity, LRUCache, normalizePagination, ownLookup, parseDbDate, resolveColumnName, resolveRelation, resolveRelationDef, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
@@ -406,14 +406,8 @@ export function unlockNestedWriteTx(tx) {
  * orderBy is never overwritten while an empty `{}` / `[]` still gets the
  * synthesized PK order.
  */
-function isEmptyOrderBy(orderBy) {
-    if (Array.isArray(orderBy))
-        return orderBy.length === 0;
-    if (orderBy && typeof orderBy === 'object') {
-        return Object.values(orderBy).every((v) => v === undefined);
-    }
-    return orderBy === undefined || orderBy === null;
-}
+// Moved to ./filters.ts in 0.74.0 so PowqlInterface consumes the SAME
+// predicate rather than a second copy of it. See applyStableRelationOrderTo.
 /** The two accepted {@link JsonEncoding} values, frozen so the check is total. */
 const JSON_ENCODINGS = Object.freeze(['object', 'positional']);
 /**
@@ -1117,46 +1111,10 @@ export class QueryInterface {
      * nothing stable to order by, so both are left untouched.
      */
     applyStableRelationOrder(withClause, table, depth = 0) {
-        if (depth >= 10)
-            return withClause; // parity with the build depth cap
-        const meta = this.schema.tables[table];
-        if (!meta)
-            return withClause;
-        let out;
-        for (const [relName, spec] of Object.entries(withClause)) {
-            if (relName === '_count' || !spec)
-                continue; // `_count` is a count, not a row load
-            const rel = resolveRelationDef(meta.relations, relName);
-            if (!rel)
-                continue; // unknown relation, let the build path surface E005
-            const options = spec === true ? {} : spec;
-            // Recurse first so a nested change alone still clones this level.
-            const nestedWith = options.with;
-            const newNested = nestedWith ? this.applyStableRelationOrder(nestedWith, rel.to, depth + 1) : undefined;
-            const nestedChanged = newNested !== undefined && newNested !== nestedWith;
-            const isToMany = rel.type === 'hasMany' || rel.type === 'manyToMany';
-            const hasOrder = options.orderBy !== undefined && !isEmptyOrderBy(options.orderBy);
-            let synthOrder;
-            if (isToMany && !hasOrder) {
-                const targetMeta = this.schema.tables[rel.to];
-                const pk = targetMeta?.primaryKey ?? [];
-                if (targetMeta && pk.length > 0) {
-                    const pkFields = pk.map((c) => targetMeta.reverseColumnMap[c] ?? c);
-                    synthOrder =
-                        pkFields.length === 1 ? { [pkFields[0]]: 'asc' } : pkFields.map((f) => ({ [f]: 'asc' }));
-                }
-            }
-            if (!synthOrder && !nestedChanged)
-                continue; // nothing to change, keep the ref
-            out ??= { ...withClause };
-            const clonedSpec = { ...options };
-            if (synthOrder)
-                clonedSpec.orderBy = synthOrder;
-            if (nestedChanged)
-                clonedSpec.with = newNested;
-            out[relName] = clonedSpec;
-        }
-        return out ?? withClause;
+        // The transform itself lives in ./relation-names.ts as of 0.74.0, so PowDB
+        // runs the SAME rule instead of a second copy that accepted the option and
+        // did nothing.
+        return applyStableRelationOrderTo(this.schema, withClause, table, depth);
     }
     // -------------------------------------------------------------------------
     // Deterministic pagination (unordered LIMIT/OFFSET)

package/dist/query/filters.d.ts

@@ -387,3 +387,11 @@ export declare function normalizeOrderBy(value: OrderDirection | OrderBySpec): {
     dir: 'ASC' | 'DESC';
     nulls?: 'first' | 'last';
 };
+/**
+ * Is this `orderBy` effectively absent?
+ *
+ * `{}` and `[]` and `{ id: undefined }` all mean "no ordering asked for". Used
+ * by the stable-relation-order transform so an explicit (non-empty) orderBy is
+ * never overwritten while an empty one still gets the synthesized PK order.
+ */
+export declare function isEmptyOrderBy(orderBy: unknown): boolean;

package/dist/query/filters.js

@@ -673,3 +673,18 @@ export function normalizeOrderBy(value) {
     }
     return { dir: String(value).toLowerCase() === 'desc' ? 'DESC' : 'ASC' };
 }
+/**
+ * Is this `orderBy` effectively absent?
+ *
+ * `{}` and `[]` and `{ id: undefined }` all mean "no ordering asked for". Used
+ * by the stable-relation-order transform so an explicit (non-empty) orderBy is
+ * never overwritten while an empty one still gets the synthesized PK order.
+ */
+export function isEmptyOrderBy(orderBy) {
+    if (Array.isArray(orderBy))
+        return orderBy.length === 0;
+    if (orderBy && typeof orderBy === 'object') {
+        return Object.values(orderBy).every((v) => v === undefined);
+    }
+    return orderBy === undefined || orderBy === null;
+}

package/dist/query/relation-names.d.ts

@@ -50,3 +50,21 @@ import type { WithClause } from './types.js';
  * Returns the input by reference when no key changed.
  */
 export declare function normalizeWithClause(schema: SchemaMetadata, table: string, withClause: WithClause | undefined, depth?: number): WithClause | undefined;
+/**
+ * Fill in a deterministic `orderBy` for every to-many relation in a `with`
+ * clause that did not ask for one, using the target table's primary key.
+ *
+ * THE single authority for `stableRelationOrder`, on every engine. It was a
+ * private method on `QueryInterface` until 0.74.0, which meant PowDB accepted
+ * the option and did nothing with it: relation rows came back in whatever order
+ * the engine produced, from the option whose entire purpose is that they do
+ * not. Restating the rule in `powql.ts` would have been the 0.64 projection
+ * resolver again, so it moved here instead, into the same "normalize the whole
+ * `with` tree once, before anything reads it" slot as
+ * {@link normalizeWithClause}.
+ *
+ * Returns the input BY REFERENCE when nothing changed, so a query that already
+ * orders every relation allocates nothing and its SQL/fingerprint stay
+ * byte-identical.
+ */
+export declare function applyStableRelationOrderTo(schema: SchemaMetadata, withClause: WithClause, table: string, depth?: number): WithClause;

package/dist/query/relation-names.js

@@ -41,7 +41,8 @@
  * available relations; rejecting it here would move that error away from its
  * context and change which error type callers see.
  */
-import { resolveRelation } from './utils.js';
+import { isEmptyOrderBy } from './filters.js';
+import { resolveRelation, resolveRelationDef } from './utils.js';
 /** Depth cap mirroring the builder's own, so a cyclic `with` cannot spin here. */
 const MAX_DEPTH = 12;
 /**
@@ -115,3 +116,61 @@ function normalizeCount(meta, count) {
  * already a documented single authority; wrapping them here would add a second
  * name for the same rule without removing a caller.
  */
+/**
+ * Fill in a deterministic `orderBy` for every to-many relation in a `with`
+ * clause that did not ask for one, using the target table's primary key.
+ *
+ * THE single authority for `stableRelationOrder`, on every engine. It was a
+ * private method on `QueryInterface` until 0.74.0, which meant PowDB accepted
+ * the option and did nothing with it: relation rows came back in whatever order
+ * the engine produced, from the option whose entire purpose is that they do
+ * not. Restating the rule in `powql.ts` would have been the 0.64 projection
+ * resolver again, so it moved here instead, into the same "normalize the whole
+ * `with` tree once, before anything reads it" slot as
+ * {@link normalizeWithClause}.
+ *
+ * Returns the input BY REFERENCE when nothing changed, so a query that already
+ * orders every relation allocates nothing and its SQL/fingerprint stay
+ * byte-identical.
+ */
+export function applyStableRelationOrderTo(schema, withClause, table, depth = 0) {
+    if (depth >= 10)
+        return withClause; // parity with the build depth cap
+    const meta = schema.tables[table];
+    if (!meta)
+        return withClause;
+    let out;
+    for (const [relName, spec] of Object.entries(withClause)) {
+        if (relName === '_count' || !spec)
+            continue; // `_count` is a count, not a row load
+        const rel = resolveRelationDef(meta.relations, relName);
+        if (!rel)
+            continue; // unknown relation, let the build path surface E005
+        const options = spec === true ? {} : spec;
+        // Recurse first so a nested change alone still clones this level.
+        const nestedWith = options.with;
+        const newNested = nestedWith ? applyStableRelationOrderTo(schema, nestedWith, rel.to, depth + 1) : undefined;
+        const nestedChanged = newNested !== undefined && newNested !== nestedWith;
+        const isToMany = rel.type === 'hasMany' || rel.type === 'manyToMany';
+        const hasOrder = options.orderBy !== undefined && !isEmptyOrderBy(options.orderBy);
+        let synthOrder;
+        if (isToMany && !hasOrder) {
+            const targetMeta = schema.tables[rel.to];
+            const pk = targetMeta?.primaryKey ?? [];
+            if (targetMeta && pk.length > 0) {
+                const pkFields = pk.map((c) => targetMeta.reverseColumnMap[c] ?? c);
+                synthOrder = pkFields.length === 1 ? { [pkFields[0]]: 'asc' } : pkFields.map((f) => ({ [f]: 'asc' }));
+            }
+        }
+        if (!synthOrder && !nestedChanged)
+            continue; // nothing to change, keep the ref
+        out ??= { ...withClause };
+        const clonedSpec = { ...options };
+        if (synthOrder)
+            clonedSpec.orderBy = synthOrder;
+        if (nestedChanged)
+            clonedSpec.with = newNested;
+        out[relName] = clonedSpec;
+    }
+    return out ?? withClause;
+}

package/dist/query/where.d.ts

@@ -285,6 +285,20 @@ export declare function buildWhere<T extends object>(qi: BuilderCtx, where: Wher
     sql: string;
     params: unknown[];
 };
+/**
+ * THE global-filter resolution rule, with no dependency on a `BuilderCtx`.
+ *
+ * Split out from {@link resolveGlobalFilter} so `PowqlInterface` can consume
+ * the SAME rule rather than a transcription of it. It is a parallel
+ * implementation of the public surface, and this repository's history is
+ * unambiguous that a rule written twice is how two engines come to disagree
+ * (the 0.64 projection resolver, the 0.73 findUnique guard). Every clause here
+ * is load-bearing on both engines: a function filter is evaluated PER BUILD so
+ * per-request tenancy works, an all-undefined filter is treated as absent so it
+ * cannot emit a dangling clause, and `skip` is honoured in both its whole-query
+ * and per-table forms.
+ */
+export declare function resolveGlobalFilterFrom(filters: GlobalFilters | undefined, table: string, skip: ResolvedSkipGlobalFilters | undefined): Record<string, unknown> | null;
 /**
  * Resolve the configured global filter for `table`, evaluating a function
  * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when

package/dist/query/where.js

@@ -369,12 +369,19 @@ export function buildWhere(qi, where) {
     return { sql: ` WHERE ${clause}`, params };
 }
 /**
- * Resolve the configured global filter for `table`, evaluating a function
- * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
- * no filter applies, the query opted out, or the filter is empty.
+ * THE global-filter resolution rule, with no dependency on a `BuilderCtx`.
+ *
+ * Split out from {@link resolveGlobalFilter} so `PowqlInterface` can consume
+ * the SAME rule rather than a transcription of it. It is a parallel
+ * implementation of the public surface, and this repository's history is
+ * unambiguous that a rule written twice is how two engines come to disagree
+ * (the 0.64 projection resolver, the 0.73 findUnique guard). Every clause here
+ * is load-bearing on both engines: a function filter is evaluated PER BUILD so
+ * per-request tenancy works, an all-undefined filter is treated as absent so it
+ * cannot emit a dangling clause, and `skip` is honoured in both its whole-query
+ * and per-table forms.
  */
-export function resolveGlobalFilter(qi, table, skip = qi.currentSkip) {
-    const filters = qi.globalFilters;
+export function resolveGlobalFilterFrom(filters, table, skip) {
     if (!filters)
         return null;
     if (skip === true)
@@ -394,6 +401,14 @@ export function resolveGlobalFilter(qi, table, skip = qi.currentSkip) {
         return null;
     return obj;
 }
+/**
+ * Resolve the configured global filter for `table`, evaluating a function
+ * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
+ * no filter applies, the query opted out, or the filter is empty.
+ */
+export function resolveGlobalFilter(qi, table, skip = qi.currentSkip) {
+    return resolveGlobalFilterFrom(qi.globalFilters, table, skip);
+}
 /**
  * AND-merge this table's resolved global filter into a user `where`. Either
  * side may be absent. When no filter applies the user where is returned by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.73.1",
+  "version": "0.74.0",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",