turbine-orm 0.40.1 → 0.41.0

package/dist/cjs/query/aggregates.js

@@ -134,15 +134,37 @@ function buildGroupBy(qi, args) {
         }
     }
     // _count
-    const countSelected = args._count === true || args._count === undefined;
-    if (countSelected) {
-        // default: always include count
+    //   - `true` / omitted → scalar `_count` column (COUNT(*)), result `_count: number`.
+    //   - record form → one column per selection: `_all` → COUNT(*) AS "_count__all"
+    //     (double underscore, collision-proof against a real column named `all`),
+    //     each field → COUNT(col) AS "_count_<col>", result `_count: { _all, field }`.
+    const countArg = args._count;
+    const countIsRecord = countArg !== true && countArg !== undefined && typeof countArg === 'object';
+    const scalarCount = countArg === true || countArg === undefined;
+    if (scalarCount) {
+        // default: always include the scalar count
         selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS _count`);
     }
+    else if (countIsRecord) {
+        for (const [field, enabled] of Object.entries(countArg)) {
+            if (!enabled)
+                continue;
+            if (field === '_all') {
+                selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS ${qi.q('_count__all')}`);
+            }
+            else {
+                const col = qi.toColumn(field);
+                selectExprs.push(`${qi.castAgg(`COUNT(${qi.q(col)})`, 'int')} AS ${qi.q(`_count_${col}`)}`);
+            }
+        }
+    }
     // ORDER BY aggregate expressions, keyed `${aggKey}:${field}` (plus a bare
     // `_count`). Populated alongside the SELECT list below so `orderBy` can only
     // reference an aggregate that is actually requested. `COUNT(*)` (uncast) is
     // the ordering expression (the SELECT cast is only for the returned value).
+    // COUNT(*) is orderable whenever it is selected: scalar `_count`, OR the
+    // record form containing `_all`.
+    const countSelected = scalarCount || (countIsRecord && countArg._all === true);
     const aggOrderExprs = new Map();
     if (countSelected)
         aggOrderExprs.set('_count', 'COUNT(*)');
@@ -234,12 +256,34 @@ function buildGroupBy(qi, args) {
                 restructured[reader.resultKey] = reader.raw ? row[reader.rowKey] : parsed[reader.resultKey];
             }
             // _count
+            //   scalar form → the plain `_count` (or driver-lowercased `count`) column.
+            //   record form → assemble `{ _all, field, ... }` from the `_count__all`
+            //   and `_count_<col>` columns. `_count__all` MUST be matched before the
+            //   generic `_count_` prefix (its slice(7) would map through snakeToCamel).
             if ('_count' in row) {
                 restructured._count = row._count;
             }
             else if ('count' in row) {
                 restructured._count = row.count;
             }
+            else {
+                const countObj = {};
+                let hasCount = false;
+                for (const [rawKey, rawValue] of Object.entries(row)) {
+                    if (rawKey === '_count__all') {
+                        countObj._all = rawValue;
+                        hasCount = true;
+                    }
+                    else if (rawKey.startsWith('_count_')) {
+                        const col = rawKey.slice(7);
+                        const field = qi.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
+                        countObj[field] = rawValue;
+                        hasCount = true;
+                    }
+                }
+                if (hasCount)
+                    restructured._count = countObj;
+            }
             // Collect aggregates into nested objects
             const sumObj = {};
             const avgObj = {};
@@ -562,6 +606,9 @@ function buildAggregate(qi, args) {
         }
         if (args._count && typeof args._count === 'object') {
             for (const key of Object.keys(args._count)) {
+                // `_all` is the reserved COUNT(*) selector, not a column.
+                if (key === '_all')
+                    continue;
                 if (!(key in meta.columnMap)) {
                     throw new errors_js_1.ValidationError(`Unknown column "${key}" in aggregate for table "${qi.table}"`);
                 }
@@ -569,13 +616,20 @@ function buildAggregate(qi, args) {
         }
     }
     const selectExprs = [];
-    // _count
+    // _count. `true` → scalar COUNT(*). Record form: reserved `_all` → COUNT(*) AS
+    // "_count__all" (double underscore, collision-proof against a real column named
+    // `all`); each field → COUNT(col) AS "_count_<col>".
     if (args._count === true) {
         selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS _count`);
     }
     else if (args._count && typeof args._count === 'object') {
         for (const [field, enabled] of Object.entries(args._count)) {
-            if (enabled) {
+            if (!enabled)
+                continue;
+            if (field === '_all') {
+                selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS ${qi.q('_count__all')}`);
+            }
+            else {
                 const col = qi.toColumn(field);
                 selectExprs.push(`${qi.castAgg(`COUNT(${qi.q(col)})`, 'int')} AS ${qi.q(`_count_${col}`)}`);
             }
@@ -632,11 +686,17 @@ function buildAggregate(qi, args) {
                 aggResult._count = row._count;
             }
             else {
-                // Check for per-column counts
+                // Check for per-column counts. `_count__all` MUST be matched before the
+                // generic `_count_` prefix (its slice(7) is `_all`, which snakeToCamel
+                // would mangle to `All`).
                 const countObj = {};
                 let hasCountFields = false;
                 for (const [key, val] of Object.entries(row)) {
-                    if (key.startsWith('_count_')) {
+                    if (key === '_count__all') {
+                        countObj._all = val;
+                        hasCountFields = true;
+                    }
+                    else if (key.startsWith('_count_')) {
                         const col = key.slice(7);
                         const field = qi.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
                         countObj[field] = val;

package/dist/cjs/query/builder.js

@@ -48,13 +48,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryInterface = void 0;
 const dialect_js_1 = require("../dialect.js");
 const errors_js_1 = require("../errors.js");
+const index_advisor_js_1 = require("../index-advisor.js");
 const nested_write_js_1 = require("../nested-write.js");
 const schema_js_1 = require("../schema.js");
 const aggMod = __importStar(require("./aggregates.js"));
 const batched_loader_js_1 = require("./batched-loader.js");
+const compound_unique_js_1 = require("./compound-unique.js");
 const filters_js_1 = require("./filters.js");
 const relationsMod = __importStar(require("./relations.js"));
 const utils_js_1 = require("./utils.js");
+const warn_registry_js_1 = require("./warn-registry.js");
 const whereMod = __importStar(require("./where.js"));
 const writesMod = __importStar(require("./writes.js"));
 /**
@@ -179,6 +182,34 @@ function cacheParamsEqual(a, b) {
     }
     return true;
 }
+/**
+ * Return `args` with any Prisma compound-unique selector in `args.where`
+ * expanded to its column conjunction (see {@link expandCompoundUniqueWhere}).
+ * Returns the same `args` reference when nothing expands, so untouched queries
+ * are byte-identical. Generic so it serves every unique-`where` arg shape.
+ */
+function maybeExpandCompoundUnique(meta, args) {
+    const where = args.where;
+    if (!where)
+        return args;
+    const expanded = (0, compound_unique_js_1.expandCompoundUniqueWhere)(meta, where);
+    return expanded === where ? args : { ...args, where: expanded };
+}
+/**
+ * Whether a relation `with`-clause `orderBy` carries no actual ordering: an
+ * empty array, or an object with no non-`undefined` own keys. Used by
+ * {@link QueryInterface.applyStableRelationOrder} so an explicit (non-empty)
+ * 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;
+}
 // biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 class QueryInterface {
     pool;
@@ -212,8 +243,16 @@ class QueryInterface {
      */
     sqlCacheEnabled;
     dialect;
-    /** Client-level default relation-loading strategy ('join' unless configured). */
+    /**
+     * Client-level default relation-loading strategy. When nothing is configured
+     * this is `'auto'` (the implicit default): per-relation, keep the single-
+     * statement join unless the introspected metadata proves a probe is unindexed,
+     * in which case that relation falls back to the batched loader. An explicit
+     * `'join'`/`'batched'` (client or query level) always wins.
+     */
     relationLoadStrategy;
+    /** Client-level default for {@link applyStableRelationOrder} (off unless configured). */
+    stableRelationOrder;
     /** Nested-relation JSON encoding: 'object' (default) or 'positional'. */
     jsonEncoding;
     /**
@@ -244,8 +283,6 @@ class QueryInterface {
      * must never receive this schema's `::"enum"` cast (see enumTypeForColumn).
      */
     crossSchemaTypeColumns;
-    /** Tracks tables that have already triggered a deep-with warning (one-time) */
-    deepWithWarned = new Set();
     /**
      * Per-table memo of date columns keyed by their camelCase FIELD name.
      * `meta.dateColumns` is keyed by raw snake_case column name, which matches
@@ -260,6 +297,15 @@ class QueryInterface {
     options;
     /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
     currentAction = 'raw';
+    /**
+     * Tags the query events of an in-flight `relationLoadStrategy: 'auto'` query
+     * that engaged the batched fallback (`'auto-batched'`), so observability sees
+     * which queries the auto default re-planned. Same transient-instance-state
+     * caveat as {@link currentAction}: set for the whole auto-split operation and
+     * cleared afterward; a concurrent unrelated query on the same accessor during
+     * that window could read it (a best-effort diagnostic tag, not load-bearing).
+     */
+    currentStrategyTag;
     /**
      * The active query's `skipGlobalFilters` opt-out, set at the top of each
      * `build*` method and read deep in the (synchronous) SQL-build + param-collect
@@ -326,7 +372,8 @@ class QueryInterface {
         this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
         this.sqlTemplateCache = new utils_js_1.LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? dialect_js_1.postgresDialect;
-        this.relationLoadStrategy = options?.relationLoadStrategy ?? 'join';
+        this.relationLoadStrategy = options?.relationLoadStrategy ?? 'auto';
+        this.stableRelationOrder = options?.stableRelationOrder === true;
         this.jsonEncoding = options?.jsonEncoding ?? 'object';
         // Only retain the map when it has at least one entry, so `globalFilters`
         // stays `undefined` (and every merge path a no-op) for the common case.
@@ -492,12 +539,277 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     /**
      * Resolve the effective relation-loading strategy for a query: the per-query
-     * arg wins, then the client-level default, then `'join'`. Only meaningful when
+     * arg wins, then the client-level default, then `'auto'`. Only meaningful when
      * a `with` clause is present; the callers gate on that.
      */
     resolveLoadStrategy(argStrategy) {
         return argStrategy ?? this.relationLoadStrategy;
     }
+    /**
+     * The effective {@link QueryInterfaceOptions.stableRelationOrder} for a query:
+     * the per-query arg wins, then the client-level default (off).
+     */
+    resolveStableOrder(argFlag) {
+        return argFlag ?? this.stableRelationOrder;
+    }
+    /**
+     * Fill a PK-ascending `orderBy` into every to-many `with` relation that has no
+     * explicit one, recursing into nested `with`. Returns a CLONED clause (user
+     * args are never mutated); when nothing needs filling it returns the input
+     * object unchanged, so the byte-identical fast path stays free. Only called
+     * when {@link resolveStableOrder} is true; runs BEFORE `withFingerprint`, so
+     * the two orderings get distinct SQL-cache entries automatically. To-one
+     * relations are single rows (no array to order) and PK-less targets have
+     * 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.ownLookup)(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;
+    }
+    // -------------------------------------------------------------------------
+    // relationLoadStrategy: 'auto', per-relation batched fallback when the
+    // introspected metadata proves a probe is unindexed (finding 13).
+    // -------------------------------------------------------------------------
+    /**
+     * Whether a relation can be served by the batched loader, i.e. all its
+     * correlation keys are single-column (the loader throws E017 on composite
+     * keys). Composite-key relations therefore always stay on the join plan under
+     * `'auto'` (and keep the existing unindexed-probe dev warning).
+     */
+    relationBatchEligible(rel) {
+        if (rel.type === 'manyToMany') {
+            const through = rel.through;
+            if (!through)
+                return false;
+            const pkLen = this.schema.tables[rel.to]?.primaryKey.length ?? 0;
+            return ((0, schema_js_1.normalizeKeyColumns)(through.sourceKey).length === 1 &&
+                (0, schema_js_1.normalizeKeyColumns)(through.targetKey).length === 1 &&
+                (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey).length === 1 &&
+                pkLen === 1);
+        }
+        return (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey).length === 1 && (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey).length === 1;
+    }
+    /**
+     * The verdict for one relation SUBTREE under `'auto'`: is any probe in the
+     * subtree unindexed, is EVERY relation in the subtree batched-eligible, and
+     * the first unindexed probe found (for the dev note). Subtree-atomic: a whole
+     * top-level relation falls back only when its entire subtree is eligible,
+     * mirroring the batched loader recursing the same tree.
+     */
+    autoSubtreeVerdict(rel, spec, depth) {
+        let eligible = this.relationBatchEligible(rel);
+        const ownMiss = (0, index_advisor_js_1.missingIndexForRelation)(this.schema, rel);
+        let unindexed = ownMiss !== null;
+        let miss = ownMiss ?? undefined;
+        const options = spec === true ? {} : spec;
+        const nested = options.with;
+        if (nested && depth < 10) {
+            const targetMeta = this.schema.tables[rel.to];
+            for (const [childName, childSpec] of Object.entries(nested)) {
+                if (!childSpec)
+                    continue;
+                if (childName === '_count') {
+                    const cv = this.autoCountVerdict(childSpec, targetMeta);
+                    eligible = eligible && cv.eligible;
+                    unindexed = unindexed || cv.unindexed;
+                    if (!miss && cv.miss)
+                        miss = cv.miss;
+                    continue;
+                }
+                const childRel = (0, utils_js_1.ownLookup)(targetMeta?.relations ?? {}, childName);
+                if (!childRel)
+                    continue; // unknown nested relation, let the build path surface it
+                const v = this.autoSubtreeVerdict(childRel, childSpec, depth + 1);
+                eligible = eligible && v.eligible;
+                unindexed = unindexed || v.unindexed;
+                if (!miss && v.miss)
+                    miss = v.miss;
+            }
+        }
+        return { unindexed, eligible, miss };
+    }
+    /** The `_count` verdict under `'auto'`: any counted probe unindexed + all single-key. */
+    autoCountVerdict(countSpec, parentMeta) {
+        if (!parentMeta)
+            return { unindexed: false, eligible: true };
+        let rels;
+        try {
+            rels = (0, batched_loader_js_1.resolveCountRelations)(parentMeta, countSpec);
+        }
+        catch {
+            return { unindexed: false, eligible: true }; // let the join/loader path surface the error
+        }
+        let unindexed = false;
+        let eligible = true;
+        let miss;
+        for (const rel of rels) {
+            if (!this.relationBatchEligible(rel))
+                eligible = false;
+            const m = (0, index_advisor_js_1.missingIndexForRelation)(this.schema, rel);
+            if (m) {
+                unindexed = true;
+                miss ??= m;
+            }
+        }
+        return { unindexed, eligible, miss };
+    }
+    /**
+     * Partition a top-level `with` clause under `'auto'`: each relation whose
+     * subtree has a PROVEN unindexed probe AND is fully batched-eligible routes to
+     * `batchedWith`; everything else (indexed, composite-key, unknown) stays in
+     * `joinWith` (byte-identical join). The reserved `_count` key partitions the
+     * same way. Also returns the engaged relations for the dev note.
+     */
+    partitionWithForAuto(withClause) {
+        const joinWith = {};
+        const batchedWith = {};
+        const engaged = [];
+        for (const [key, spec] of Object.entries(withClause)) {
+            if (!spec)
+                continue;
+            if (key === '_count') {
+                const cv = this.autoCountVerdict(spec, this.tableMeta);
+                if (cv.unindexed && cv.eligible) {
+                    batchedWith[key] = spec;
+                    engaged.push({ relation: '_count', miss: cv.miss });
+                }
+                else {
+                    joinWith[key] = spec;
+                }
+                continue;
+            }
+            const rel = (0, utils_js_1.ownLookup)(this.tableMeta.relations, key);
+            if (!rel) {
+                joinWith[key] = spec; // unknown relation, let the join path surface E005
+                continue;
+            }
+            const v = this.autoSubtreeVerdict(rel, spec, 0);
+            if (v.unindexed && v.eligible) {
+                batchedWith[key] = spec;
+                engaged.push({ relation: key, miss: v.miss });
+            }
+            else {
+                joinWith[key] = spec;
+            }
+        }
+        return { joinWith, batchedWith, engaged };
+    }
+    /**
+     * Plan the `'auto'` split for a query's `with` clause: normalize stable order,
+     * partition, and return the split ONLY when at least one relation falls back
+     * to batched. Returns `null` (→ run the plain join path, byte-identical, same
+     * cache keys) when there is no DB-backed index metadata or nothing qualifies.
+     */
+    planAuto(withArg, stableFlag) {
+        // No DB-backed index info (code-first / defineSchema-only) → cannot PROVE any
+        // probe is unindexed, so 'auto' behaves exactly like 'join'.
+        if (!(0, index_advisor_js_1.schemaHasIndexInfo)(this.schema))
+            return null;
+        const withClause = this.resolveStableOrder(stableFlag)
+            ? this.applyStableRelationOrder(withArg, this.table)
+            : withArg;
+        const split = this.partitionWithForAuto(withClause);
+        if (Object.keys(split.batchedWith).length === 0)
+            return null;
+        return split;
+    }
+    /** Dev-only once-per-relation note that `'auto'` engaged the batched fallback. */
+    emitAutoNotes(engaged) {
+        if (process.env.NODE_ENV === 'production')
+            return;
+        for (const e of engaged) {
+            if (!(0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.autoStrategy, `${this.table}.${e.relation}`))
+                continue;
+            const probe = e.miss
+                ? `probe "${e.miss.table}"(${e.miss.columns.join(', ')}) has no covering index`
+                : 'a probe in its subtree has no covering index';
+            console.warn(`[turbine] auto strategy: relation "${e.relation}" on "${this.table}" loads batched (${probe}). ` +
+                "Create the covering index (or set `relationLoadStrategy: 'join'` to force the single-statement " +
+                'plan); run `npx turbine doctor` for the exact CREATE INDEX SQL.');
+        }
+    }
+    /**
+     * Execute a findMany/findUnique `'auto'` split: run the base query with the
+     * residual `joinWith` (plus any parent stitch keys the batched subset needs),
+     * then load `batchedWith` via the batched loader and stitch. `single` returns
+     * the first entity (findUnique) instead of the array. Output is identical in
+     * shape to the pure join plan.
+     */
+    async runAutoSplit(args, split, single) {
+        this.emitAutoNotes(split.engaged);
+        const { joinWith, batchedWith } = split;
+        // Scope-rule parity with the batched strategy: reject nested pick ordering
+        // on the batched subset up front.
+        (0, batched_loader_js_1.rejectNestedPickOrder)(batchedWith);
+        const skip = args.skipGlobalFilters;
+        const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, batchedWith);
+        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed);
+        const hasJoin = Object.keys(joinWith).length > 0;
+        // Force the residual `with` onto the join plan so the base query never
+        // re-enters this auto planning.
+        const baseArgs = {
+            ...args,
+            with: hasJoin ? joinWith : undefined,
+            select: proj.select,
+            omit: proj.omit,
+            relationLoadStrategy: 'join',
+        };
+        this.currentStrategyTag = 'auto-batched';
+        try {
+            const deferred = single
+                ? this.buildFindUnique(baseArgs)
+                : this.buildFindMany(baseArgs);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const rows = deferred.transform(result);
+            const entities = single ? (rows ? [rows] : []) : rows;
+            if (entities.length > 0) {
+                await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true), entities, batchedWith, args.timeout);
+            }
+            (0, batched_loader_js_1.stripFields)(entities, proj.strip);
+            return single ? (entities[0] ?? null) : entities;
+        }
+        finally {
+            this.currentStrategyTag = undefined;
+        }
+    }
     /**
      * Build the {@link RelationLoadContext} the batched loader needs, closing over
      * this interface's pool/dialect/executor. Child readers are constructed on the
@@ -549,7 +861,12 @@ class QueryInterface {
      * from the returned rows, so the shape matches the join strategy exactly.
      */
     async runFindManyBatched(args) {
-        const withClause = args.with;
+        // Stable relation order (opt-in): the batched loader forwards each relation's
+        // orderBy into its follow-up query, so filling the synthesized PK order here
+        // makes the batched output deterministic exactly like the join path.
+        const withClause = this.resolveStableOrder(args.stableRelationOrder)
+            ? this.applyStableRelationOrder(args.with, this.table)
+            : args.with;
         // Scope-rule parity with the join strategy (which throws at SQL build):
         // reject nested pick-row ordering BEFORE the base query so acceptance
         // never depends on how many rows come back.
@@ -705,7 +1022,17 @@ class QueryInterface {
         if (!onQuery)
             return;
         try {
-            onQuery({ sql, params, duration, model: this.table, action, rows, timestamp: new Date(), error });
+            onQuery({
+                sql,
+                params,
+                duration,
+                model: this.table,
+                action,
+                rows,
+                timestamp: new Date(),
+                error,
+                strategy: this.currentStrategyTag,
+            });
         }
         catch {
             // Listener errors must never crash a query
@@ -844,8 +1171,15 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     async findUnique(args) {
         return this.executeWithMiddleware('findUnique', args, async () => {
-            if (args.with && this.resolveLoadStrategy(args.relationLoadStrategy) === 'batched') {
-                return this.runFindUniqueBatched(args);
+            if (args.with) {
+                const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
+                if (strategy === 'batched')
+                    return this.runFindUniqueBatched(args);
+                if (strategy === 'auto') {
+                    const split = this.planAuto(args.with, args.stableRelationOrder);
+                    if (split)
+                        return this.runAutoSplit(args, split, true);
+                }
             }
             const deferred = this.buildFindUnique(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
@@ -859,7 +1193,10 @@ class QueryInterface {
      * strategy's shape for the one row.
      */
     async runFindUniqueBatched(args) {
-        const withClause = args.with;
+        // Stable relation order (opt-in), see runFindManyBatched.
+        const withClause = this.resolveStableOrder(args.stableRelationOrder)
+            ? this.applyStableRelationOrder(args.with, this.table)
+            : args.with;
         // Same scope-rule parity as runFindManyBatched: reject before querying.
         (0, batched_loader_js_1.rejectNestedPickOrder)(withClause);
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, withClause);
@@ -877,6 +1214,16 @@ class QueryInterface {
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindUnique(args) {
         this.currentSkip = args.skipGlobalFilters;
+        // Prisma compound-unique selector expansion (before global-filter merge and
+        // fingerprinting, so the cache only ever sees the canonical expanded where).
+        args = maybeExpandCompoundUnique(this.tableMeta, args);
+        // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
+        // relations before fingerprinting (see buildFindMany).
+        if (args.with && this.resolveStableOrder(args.stableRelationOrder)) {
+            const normalized = this.applyStableRelationOrder(args.with, this.table);
+            if (normalized !== args.with)
+                args = { ...args, with: normalized };
+        }
         const includePii = args.includePii === true;
         const columnsList = this.resolveColumns(args.select, args.omit, includePii);
         // A global filter turns the where into `{ AND: [...] }`, which the
@@ -994,16 +1341,22 @@ class QueryInterface {
         if (process.env.NODE_ENV !== 'production') {
             if (args?.with) {
                 const depth = this.measureWithDepth(args.with);
-                if (depth > 5 && !this.deepWithWarned.has(this.table)) {
-                    this.deepWithWarned.add(this.table);
+                if (depth > 5 && (0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.deepWith, this.table)) {
                     console.warn(`[turbine] Deep with clause (depth ${depth}) on "${this.tableMeta.name}" — ` +
                         'consider splitting into separate queries for better performance.');
                 }
             }
         }
         return this.executeWithMiddleware('findMany', (args ?? {}), async () => {
-            if (args?.with && this.resolveLoadStrategy(args.relationLoadStrategy) === 'batched') {
-                return this.runFindManyBatched(args);
+            if (args?.with) {
+                const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
+                if (strategy === 'batched')
+                    return this.runFindManyBatched(args);
+                if (strategy === 'auto') {
+                    const split = this.planAuto(args.with, args.stableRelationOrder);
+                    if (split)
+                        return this.runAutoSplit(args, split, false);
+                }
             }
             const deferred = this.buildFindMany(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
@@ -1112,6 +1465,14 @@ class QueryInterface {
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindMany(args) {
         this.currentSkip = args?.skipGlobalFilters;
+        // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
+        // relations BEFORE fingerprinting, so the two orderings get distinct cache
+        // entries and every downstream path (SQL build, collect, parser) inherits it.
+        if (args?.with && this.resolveStableOrder(args.stableRelationOrder)) {
+            const normalized = this.applyStableRelationOrder(args.with, this.table);
+            if (normalized !== args.with)
+                args = { ...args, with: normalized };
+        }
         // `distinct` + relation orderBy is refused up front (E003): the distinct
         // path re-orders in an outer wrapper (`... AS "<table>_distinct" ORDER BY
         // <userOrder>`) where a correlated relation subquery (pick-row, `_count`,
@@ -1393,10 +1754,20 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     async findFirst(args) {
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
-            if (args?.with && this.resolveLoadStrategy(args.relationLoadStrategy) === 'batched') {
+            if (args?.with) {
+                const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
                 // findFirst is findMany + LIMIT 1: batch the single base row, then load.
-                const rows = await this.runFindManyBatched({ ...args, limit: 1 });
-                return (rows[0] ?? null);
+                if (strategy === 'batched') {
+                    const rows = await this.runFindManyBatched({ ...args, limit: 1 });
+                    return (rows[0] ?? null);
+                }
+                if (strategy === 'auto') {
+                    const split = this.planAuto(args.with, args.stableRelationOrder);
+                    if (split) {
+                        const rows = (await this.runAutoSplit({ ...args, limit: 1 }, split, false));
+                        return (rows[0] ?? null);
+                    }
+                }
             }
             const deferred = this.buildFindFirst(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);