turbine-orm 0.51.0 → 0.52.0

package/dist/prisma-compat.js

@@ -25,7 +25,10 @@
  *  , the un-awaited delegate calls defer to Turbine's `build*()` methods and
  *   run atomically through the core batch `$transaction([...])` path.
  * - **Raw SQL**: `$queryRaw` / `$executeRaw` tagged templates (with
- *   `Prisma.sql`-style nested-fragment flattening) and the `*Unsafe` variants.
+ *   `Prisma.sql`-style nested-fragment flattening) and the `*Unsafe` variants,
+ *   on the client AND on the transaction client, where they run on the
+ *   transaction's own connection so a mixed raw + delegate `$transaction` stays
+ *   atomic.
  * - **Result reshaping**: `_count` objects keyed back to Prisma relation names,
  *   and to-one relations surfaced as `object | null`.
  *
@@ -82,11 +85,27 @@
  * ```
  */
 import { TurbineError, TurbineErrorCode, UnsupportedFeatureError, ValidationError, wrapPgError } from './errors.js';
+import { createManyShapeRuns } from './nested-write.js';
 import { shouldWarnOnce } from './query/warn-registry.js';
 // ---------------------------------------------------------------------------
 // Prisma.sql-style raw fragments (local, minimal, never imports @prisma/client)
 // ---------------------------------------------------------------------------
-const SQL_FRAGMENT = Symbol.for('turbine.prismaCompat.sqlFragment');
+/**
+ * Brand marking an object as a raw-SQL fragment whose `strings` are spliced
+ * VERBATIM into the emitted statement (see `flattenTemplate`). Deliberately a
+ * module-private `Symbol()` and NOT `Symbol.for(...)`: a registry symbol is
+ * reachable by name from anywhere in the process, so any dependency could mint
+ * an object that flattens as trusted SQL. With a private symbol the only way to
+ * obtain a fragment is to call `Prisma.sql` / `Prisma.join` / `Prisma.raw` from
+ * this module.
+ *
+ * The fragment check is fail-CLOSED: an object that does not carry this exact
+ * symbol is bound as a `$N` parameter, never spliced. That is also what makes
+ * the (contrived) dual-package case safe rather than dangerous, a fragment
+ * built by the ESM copy of this module and executed by the CJS copy binds as a
+ * parameter instead of composing.
+ */
+const SQL_FRAGMENT = Symbol('turbine.prismaCompat.sqlFragment');
 function isSqlFragment(x) {
     return typeof x === 'object' && x !== null && x[SQL_FRAGMENT] === true;
 }
@@ -1065,6 +1084,40 @@ async function upsertLookupFirst(qi, t) {
         return qi.update({ where: t.where, data: t.update });
     return qi.create({ data: t.create });
 }
+/**
+ * The row shapes a translated `createMany` has to insert, as contiguous runs
+ * that each name the same fields (see {@link createManyShapeRuns}).
+ *
+ * Prisma accepts rows of DIFFERENT shapes in one `createMany` and emits a single
+ * INSERT over the UNION of the named columns, binding its own schema-level
+ * `@default` for a field a row omits and `null` for one it has no default for
+ * (verified against @prisma/client 7.9.0 on PostgreSQL 16). Core `createMany`
+ * refuses a mixed batch instead, because it has no per-cell DEFAULT form on
+ * every engine and would otherwise write NULL over the column's default. Runs
+ * bridge the two: one core `createMany` per run, all of them inside one
+ * transaction, so a ported call site keeps working and the `{ count }` it gets
+ * back is the number of rows actually inserted.
+ *
+ * The one place this is not byte-for-byte Prisma is a column whose DEFAULT lives
+ * in the DATABASE and not in the Prisma schema: Prisma binds null there and
+ * loses the default, a run lets the column default apply. Prisma's own answer is
+ * the lossy one, so the divergence only ever adds back a value the caller never
+ * asked to overwrite.
+ */
+function createManyRunsOf(t) {
+    return createManyShapeRuns((Array.isArray(t.data) ? t.data : []));
+}
+/** One core `createMany` per run, in order, summing Prisma's `{ count }`. */
+async function createManyByRun(qi, t, runs) {
+    let count = 0;
+    for (const run of runs) {
+        const args = { data: run };
+        if (t.skipDuplicates)
+            args.skipDuplicates = true;
+        count += (await qi.createMany(args)).length;
+    }
+    return { count };
+}
 function makeDelegate(ctx, mm, getQI, runInTx) {
     const pe = ctx.options.prismaErrorCodes;
     // Build a lazy Prisma-style promise for one delegate call. Crucially, the
@@ -1140,7 +1193,23 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
             if (args.skipDuplicates)
                 t.skipDuplicates = true;
             return t;
-        }, (qi, t) => qi.createMany(t).then((r) => ({ count: r.length })), { build: (qi, t) => qi.buildCreateMany(t), reshape: (raw) => ({ count: raw.length }) }),
+        }, (qi, t) => {
+            // Rows that all name the same fields are one statement, exactly as
+            // before. A mixed batch, which Prisma accepts, becomes one createMany
+            // per contiguous same-shape run inside ONE transaction, so the call
+            // stays all-or-nothing and the count is the total actually inserted.
+            const runs = createManyRunsOf(t);
+            if (runs.length <= 1)
+                return qi.createMany(t).then((r) => ({ count: r.length }));
+            return runInTx((table) => createManyByRun(table(mm.table), t, runs));
+        }, {
+            build: (qi, t) => qi.buildCreateMany(t),
+            reshape: (raw) => ({ count: raw.length }),
+            // A mixed batch is more than one statement, so the array
+            // $transaction([...]) form runs the whole array sequentially in a tx.
+            nested: (t) => createManyRunsOf(t).length > 1,
+            execInTx: (table, t) => createManyByRun(table(mm.table), t, createManyRunsOf(t)),
+        }),
         update: (args) => defer(() => {
             const a = requireWhere(args, 'update');
             return {
@@ -1255,6 +1324,31 @@ function flattenTemplate(strings, values, ph) {
     append(strings, values);
     return { text, params };
 }
+/**
+ * Build the four Prisma raw methods over ONE executor. Both the client-level and
+ * the transaction-scoped surfaces come from this function, so they cannot drift:
+ * same fragment flattening, same placeholder generation, same return shapes
+ * (`$queryRaw` → rows, `$executeRaw` → affected-row count). The only difference
+ * is which connection the executor runs on.
+ */
+function makeRawSurface(exec, ph) {
+    return {
+        $queryRaw: async (strings, ...values) => {
+            const { text, params } = flattenTemplate(strings, values, ph);
+            return (await exec(text, params)).rows;
+        },
+        $queryRawUnsafe: async (sql, ...params) => {
+            return (await exec(sql, params)).rows;
+        },
+        $executeRaw: async (strings, ...values) => {
+            const { text, params } = flattenTemplate(strings, values, ph);
+            return (await exec(text, params)).rowCount ?? 0;
+        },
+        $executeRawUnsafe: async (sql, ...params) => {
+            return (await exec(sql, params)).rowCount ?? 0;
+        },
+    };
+}
 // ---------------------------------------------------------------------------
 // createPrismaCompatClient
 // ---------------------------------------------------------------------------
@@ -1310,6 +1404,11 @@ function junctionModels(ctx, map, tableToModel) {
         if (alias)
             seen.add(alias);
     }
+    // Junction names already registered by an earlier relation. A many-to-many
+    // pair is normally DECLARED ON BOTH SIDES, so the same junction table is
+    // reached twice; the second visit must be a silent no-op, not a collision (it
+    // would be colliding with its own registration).
+    const registered = new Set();
     for (const table of Object.values(ctx.schema.tables)) {
         for (const rel of Object.values(table.relations ?? {})) {
             if (rel.type !== 'manyToMany')
@@ -1317,15 +1416,18 @@ function junctionModels(ctx, map, tableToModel) {
             const name = rel.through?.table;
             if (!name || !ctx.schema.tables[name] || tableToModel.has(name))
                 continue;
+            if (registered.has(name))
+                continue;
             if (seen.has(name)) {
                 if (process.env.NODE_ENV !== 'production' && shouldWarnOnce(JUNCTION_WARN_NS, name)) {
                     console.warn(`[turbine] prisma-compat: the many-to-many junction table "${name}" collides with an ` +
                         'existing client member of the same name, so no junction accessor was created for it. ' +
-                        'Reach its rows through $queryRaw / $executeRaw, or through the owning model relation.');
+                        'Reach its rows through the owning model relation (a nested connect / disconnect / set on the ' +
+                        'related model), or through $queryRaw / $executeRaw.');
                 }
                 continue;
             }
-            seen.add(name);
+            registered.add(name);
             out.push([name, { table: name, accessor: name, fields: {}, relations: {}, compoundUniques: {} }]);
         }
     }
@@ -1388,6 +1490,27 @@ export function createPrismaCompatClient(client, map, options = {}) {
             throw decorate(wrapPgError(err), ctx.options.prismaErrorCodes);
         }
     };
+    /**
+     * The same executor bound to a transaction's OWN connection. A raw statement
+     * that quietly ran on a pool connection would leave the caller unable to tell
+     * that its writes were outside the transaction, so a transaction client that
+     * cannot execute raw SQL refuses rather than falling back to the pool.
+     * `wrapPgError` is idempotent (it returns an already-typed TurbineError
+     * untouched), so the error shape matches the pool path exactly.
+     */
+    const txRunRaw = (tx) => async (text, params) => {
+        if (typeof tx.rawQuery !== 'function') {
+            throw decorate(new ValidationError('[turbine] prisma-compat: raw SQL inside $transaction needs a transaction client that can execute it ' +
+                '(core TransactionClient.rawQuery). Refusing to run the statement on a pool connection, which would ' +
+                'silently place it outside the transaction.'), ctx.options.prismaErrorCodes);
+        }
+        try {
+            return await tx.rawQuery(text, params);
+        }
+        catch (err) {
+            throw decorate(wrapPgError(err), ctx.options.prismaErrorCodes);
+        }
+    };
     const base = {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         $transaction: ((arg, txOptions) => {
@@ -1436,23 +1559,16 @@ export function createPrismaCompatClient(client, map, options = {}) {
                         txDelegates[alias] = txDelegates[prismaModel];
                     }
                 }
-                return fn(txDelegates);
+                // Raw SQL on the transaction's own connection. Prisma's tx client
+                // carries these four, and code that mixes `$transaction` with raw SQL is
+                // the common case in a migrated codebase. No model can shadow them: a
+                // Prisma model name cannot start with `$`, and junction accessors skip
+                // every CLIENT_RESERVED_KEYS name.
+                const txClient = { ...txDelegates, ...makeRawSurface(txRunRaw(tx), ph) };
+                return fn(txClient);
             }, txOptions);
         }),
-        $queryRaw: async (strings, ...values) => {
-            const { text, params } = flattenTemplate(strings, values, ph);
-            return (await runRaw(text, params)).rows;
-        },
-        $queryRawUnsafe: async (sql, ...params) => {
-            return (await runRaw(sql, params)).rows;
-        },
-        $executeRaw: async (strings, ...values) => {
-            const { text, params } = flattenTemplate(strings, values, ph);
-            return (await runRaw(text, params)).rowCount ?? 0;
-        },
-        $executeRawUnsafe: async (sql, ...params) => {
-            return (await runRaw(sql, params)).rowCount ?? 0;
-        },
+        ...makeRawSurface(runRaw, ph),
         $connect: async () => { },
         $disconnect: async () => { },
     };

package/dist/query/batched-loader.d.ts

@@ -36,6 +36,13 @@
  *     (`[]` when empty), single-or-null for hasOne/belongsTo, with the same
  *     camelCase keys and Date coercion, because the child rows are parsed by the
  *     very same `parseRow`/`buildFindMany` machinery via a child QueryInterface.
+ *   - **Identical KEY ORDER.** Object key order is observable output: callers
+ *     `JSON.stringify` results into HTTP bodies, ETags and cache keys. The
+ *     follow-up queries run concurrently, so the completion order of two sibling
+ *     relations is a race; every relation key (and every `_count` entry) is
+ *     therefore SEEDED up front in the order the join plan emits it, and the
+ *     concurrent loads only overwrite already-existing keys. See
+ *     {@link seedRelationKeys}.
  *   - **Stitch keys never leak.** To stitch, the follow-up query must select the
  *     FK/PK it joins on even when the caller's `select`/`omit` excluded it; the
  *     loader adds those columns for the query and strips them from the returned

package/dist/query/batched-loader.js

@@ -36,6 +36,13 @@
  *     (`[]` when empty), single-or-null for hasOne/belongsTo, with the same
  *     camelCase keys and Date coercion, because the child rows are parsed by the
  *     very same `parseRow`/`buildFindMany` machinery via a child QueryInterface.
+ *   - **Identical KEY ORDER.** Object key order is observable output: callers
+ *     `JSON.stringify` results into HTTP bodies, ETags and cache keys. The
+ *     follow-up queries run concurrently, so the completion order of two sibling
+ *     relations is a race; every relation key (and every `_count` entry) is
+ *     therefore SEEDED up front in the order the join plan emits it, and the
+ *     concurrent loads only overwrite already-existing keys. See
+ *     {@link seedRelationKeys}.
  *   - **Stitch keys never leak.** To stitch, the follow-up query must select the
  *     FK/PK it joins on even when the caller's `select`/`omit` excluded it; the
  *     loader adds those columns for the query and strips them from the returned
@@ -48,7 +55,7 @@
  */
 import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { normalizeKeyColumns } from '../schema.js';
-import { isRelationPickOrderBy } from './filters.js';
+import { isRelationPickOrderBy, sortedEntries } from './filters.js';
 import { ownLookup } from './utils.js';
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
@@ -268,30 +275,96 @@ export async function loadRelationsBatched(ctx, parents, withClause, timeout, de
         rejectNestedPickOrder(withClause);
     if (parents.length === 0)
         return;
-    // Sibling relations are independent (each writes only its own parent[relName]
-    // and reads only parent keys), so load them concurrently, on a pool that's
-    // real parallelism, inside a transaction pg queues them on the one connection.
-    const loads = [];
-    for (const [relName, spec] of Object.entries(withClause)) {
-        if (!spec)
-            continue;
-        // Reserved `_count` key, one grouped COUNT(*) follow-up per counted relation.
-        if (relName === '_count') {
-            loads.push(loadCounts(ctx, parents, spec));
+    // Resolve the relations to load in the SAME order the join plan emits their
+    // columns (`sortedEntries` in buildSelectWithRelations), with the reserved
+    // `_count` key last.
+    const resolved = [];
+    for (const [relName, spec] of sortedEntries(withClause)) {
+        if (!spec || relName === '_count')
             continue;
-        }
         const rel = ownLookup(ctx.parentMeta.relations, relName);
         if (!rel) {
             throw new ValidationError(`[turbine] Unknown relation "${relName}" on table "${ctx.parentMeta.name}". ` +
                 `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}`);
         }
-        const options = spec === true ? {} : spec;
+        resolved.push({ relName, rel, options: spec === true ? {} : spec });
+    }
+    // A falsy `_count` opts out, exactly like a falsy relation spec.
+    const countSpec = withClause._count;
+    const hasCount = Boolean(countSpec);
+    // Fix key order BEFORE anything is awaited: the loads below all write their
+    // key on completion, and completion order is a race between concurrent
+    // statements.
+    seedRelationKeys(parents, ctx.parentMeta, resolved, hasCount);
+    // Sibling relations are independent (each writes only its own parent[relName]
+    // and reads only parent keys), so load them concurrently, on a pool that's
+    // real parallelism, inside a transaction pg queues them on the one connection.
+    const loads = [];
+    for (const { relName, rel, options } of resolved) {
         loads.push(rel.type === 'manyToMany'
             ? loadManyToMany(ctx, parents, rel, relName, options, timeout, depth, path)
             : loadToOneOrMany(ctx, parents, rel, relName, options, timeout, depth, path));
     }
+    // Reserved `_count` key, one grouped COUNT(*) follow-up per counted relation.
+    if (hasCount)
+        loads.push(loadCounts(ctx, parents, countSpec));
     await Promise.all(loads);
 }
+/**
+ * Give every relation key its final POSITION on each parent row before the
+ * concurrent follow-up queries start, so the stitched object serializes to the
+ * same bytes on every run and matches the join strategy.
+ *
+ * The reference order is the join plan's SELECT list: base columns, then the
+ * relation columns in sorted `with` order, then the `_count__<rel>` scalars
+ * (which `parseNestedRow` folds into a `_count` object appended last). A key
+ * that is already present is re-inserted rather than seeded: under the `'auto'`
+ * split some relations arrive resolved by the join plan and the rest are loaded
+ * here, and only a re-insert can interleave the two sets into one canonical
+ * order. Base (non-relation) columns are never touched.
+ */
+function seedRelationKeys(parents, parentMeta, resolved, hasCount) {
+    // Placeholder per relation: the value an empty load produces, so a seeded key
+    // is never a shape the caller could not otherwise see.
+    const seeds = new Map();
+    for (const { relName, rel } of resolved) {
+        seeds.set(relName, rel.type === 'belongsTo' || rel.type === 'hasOne' ? 'one' : 'many');
+    }
+    // Relations the join plan already resolved onto these rows (the `'auto'`
+    // split's residual join). Rows all come from one query, so one row's shape
+    // answers for the batch.
+    const sample = parents[0];
+    if (sample) {
+        for (const relName of Object.keys(parentMeta.relations)) {
+            // Already resolved by the join plan: it needs a position, never a
+            // placeholder, so it is re-inserted rather than overwritten.
+            if (!seeds.has(relName) && Object.hasOwn(sample, relName))
+                seeds.set(relName, 'present');
+        }
+    }
+    const ordered = [...seeds.keys()].sort();
+    const countPresent = hasCount || (sample !== undefined && Object.hasOwn(sample, '_count'));
+    if (ordered.length === 0 && !countPresent)
+        return;
+    for (const parent of parents) {
+        for (const relName of ordered) {
+            if (Object.hasOwn(parent, relName)) {
+                // Re-insert so this key sits in canonical order, value untouched.
+                const existing = parent[relName];
+                delete parent[relName];
+                parent[relName] = existing;
+            }
+            else {
+                parent[relName] = seeds.get(relName) === 'many' ? [] : null;
+            }
+        }
+        if (!countPresent)
+            continue;
+        const existingCount = Object.hasOwn(parent, '_count') ? parent._count : undefined;
+        delete parent._count;
+        parent._count = existingCount ?? {};
+    }
+}
 /**
  * hasMany / hasOne / belongsTo: one follow-up `SELECT ... WHERE childKey = ANY($1)`
  * (chunked), grouped by the correlation key and attached (array vs single-or-null).
@@ -474,15 +547,24 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
  * Load correlated `_count` values for the counted relations. One grouped
  * follow-up per relation (`SELECT key, COUNT(*) … WHERE key = ANY($1) GROUP BY
  * key`), attached onto each parent's `_count` object (0 when a parent has no
- * matching rows), byte-identical to the join strategy's `_count` output.
+ * matching rows), byte-identical to the join strategy's `_count` output,
+ * INCLUDING key order: the join plan emits its `_count__<rel>` columns in
+ * `resolveCountRelations` order, so every key is seeded here in that same order
+ * before the concurrent counts run and can only be overwritten in place.
  */
 async function loadCounts(ctx, parents, countSpec) {
     const rels = resolveCountRelations(ctx.parentMeta, countSpec);
-    // Initialise every parent's `_count` up-front so the concurrent per-relation
-    // loads below (each writing its own key) never race on the object creation.
+    // Initialise every parent's `_count` up-front, and seed every counted
+    // relation's key in `resolveCountRelations` order, so the concurrent
+    // per-relation loads below only ever overwrite a key that already exists.
+    // Without the seeded keys, insertion order is whichever COUNT statement
+    // finishes first and the same query serializes differently run to run.
     for (const parent of parents) {
         if (parent._count === undefined)
             parent._count = {};
+        const counts = parent._count;
+        for (const rel of rels)
+            counts[rel.name] = 0;
     }
     await Promise.all(rels.map((rel) => loadOneCount(ctx, parents, rel)));
 }

package/dist/query/builder.d.ts

@@ -78,6 +78,82 @@ export declare const AUTO_TO_ONE_JOIN_MAX_ROWS: number;
  */
 export declare const AUTO_TO_ONE_JOIN_ROWS_MIN = 100;
 export declare const AUTO_TO_ONE_JOIN_ROWS_MAX = 100000;
+/**
+ * WHY THIS IS A CONFIGURED LATENCY AND NOT A MEASURED ONE.
+ *
+ * The obvious next step from the formula above is to have the client measure
+ * its own round-trip time and derive the threshold at runtime. That was built
+ * and benchmarked, and it is NOT what ships, for a reason worth recording so it
+ * is not re-litigated blind:
+ *
+ * Every query's wall time is `roundTrip + serverWork`, and nothing in a
+ * duration distinguishes the two. An all-time MINIMUM reads a lucky packet
+ * (1.489ms on a link whose real per-statement cost was 2.862ms) and lands the
+ * threshold at half the true break-even. A MEDIAN over recent durations is
+ * accurate when the workload is cheap queries, but the workload being planned
+ * for here is precisely the expensive one: in the verification sweep the ring
+ * filled with 10-17ms relation queries, the estimate inflated, and `'auto'`
+ * held an 8,000-row query on the join plan, 1.30x slower than the better plan,
+ * WORSE than the fixed constant it replaced. Capping the median against a
+ * multiple of the floor mitigates it but turns the whole thing into a pair of
+ * magic numbers tuned against two synthetic links, which is the same mistake as
+ * a socket-tuned row count wearing a different hat.
+ *
+ * Round-trip time is a deployment fact, not a runtime discovery: it is fixed by
+ * where the app runs relative to the database, the operator knows it (or gets
+ * it from one `ping`), and it does not change between queries. So it is
+ * configuration. That also keeps plan selection deterministic, which matters
+ * for a library whose documented guarantee is that the strategy changes the
+ * plan and never the result.
+ */
+/**
+ * The smallest plan-time parent-row bound at which `'auto'` moves a relation
+ * `_count` on a PROVEN-UNINDEXED probe to the grouped follow-up. Deliberately
+ * 2, i.e. "everything except a parent set provably bounded at one row".
+ *
+ * `_count` does NOT share the to-one break-even formula above, because its two
+ * plans do not differ by a small per-row penalty. Writing S for one scan of the
+ * child table and RTT for a round trip:
+ *
+ *     inline(N)  = N x S        (a correlated COUNT(*) per parent row; see
+ *                                buildRelationCountExpr in relations.ts, the
+ *                                inline form is NOT a grouped scan)
+ *     batched(N) = S + RTT      (one `COUNT(*) ... GROUP BY fk` follow-up)
+ *
+ * so the crossover sits at `N = 1 + RTT/S` and, decisively, the two regrets are
+ * not comparable in kind:
+ *
+ *   - choosing batched when inline would have won costs at most RTT, once, and
+ *     ONLY at N = 1 (at N = 1 the difference is exactly RTT, and it shrinks to
+ *     zero immediately after);
+ *   - choosing inline when batched would have won costs (N - 1) x S, which is
+ *     unbounded in the parent count.
+ *
+ * Measured on an UNINDEXED FK (PostgreSQL 16, 200K-row child table, 10K-row
+ * parent table, median of 11 interleaved reps per point, loopback;
+ * benchmarks/bench-count-strategy.ts):
+ *
+ *   parents      1      2      3      5     20     100     1000    10000
+ *   inline    4.3ms  8.3ms 12.3ms 20.1ms 79.2ms 417.5ms   3.06s   31.06s
+ *   batched   5.2ms  4.8ms  4.8ms  5.2ms  6.1ms  11.5ms   9.9ms   28.4ms
+ *   winner   inline batched batched batched batched batched batched batched
+ *   ratio     1.22x  1.73x  2.54x  3.84x 13.05x  36.42x 310.92x 1093.35x
+ *
+ * Inline wins exactly one cell, by 0.9ms, then loses the next by 1.73x and the
+ * last by 1093x. A skewed child distribution (half the rows on ten parents)
+ * moves nothing: same crossover at 2, same 1179x at 10,000. So the useful
+ * threshold is not a tunable row count, it is the one row where inline provably
+ * cannot lose. There is deliberately no config knob: the entire regret this rule
+ * can produce is one round trip, which is less than any knob would be worth, and
+ * `relationLoadStrategy: 'join'` already forces the single-statement plan.
+ *
+ * This applies ONLY to a probe the introspected index metadata PROVES unindexed.
+ * An INDEXED `_count` stays inline at every size measured (inline wins 1.30x to
+ * 2.06x from 1 to 10,000 parents, because the per-parent subquery collapses to
+ * an index-only scan costing ~0.001ms), and the partition below never demotes
+ * it.
+ */
+export declare const AUTO_COUNT_BATCH_MIN_PARENT_ROWS = 2;
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './deferred.js';
 import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
 export declare class QueryInterface<T extends object, R extends object = {}> {
@@ -225,6 +301,46 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private readonly ctx;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /**
+     * Dev-only, once per table: the columns whose database type is absent from
+     * BOTH the column entry and the table-level type maps, the residual case
+     * after the two-source resolution above.
+     *
+     * The set is deliberately every untyped column, not the `dateColumns`
+     * members. An unresolved type is precisely the state in which Turbine cannot
+     * say WHICH kind of column it is, so restricting the scan to `dateColumns`
+     * got it wrong in both directions: that set carries `timestamptz` (whose
+     * bind was never affected, since binding the `Date` is the correct thing to
+     * do for it) and omits `time` / `timetz` entirely (deliberately, see
+     * `timeOfDayKind` in schema.ts), which is the one kind that fails LOUDLY
+     * rather than silently. The message therefore names the columns and states
+     * what each kind does, rather than asserting a kind it cannot know.
+     *
+     * What is actually at stake per kind, all of it `coerceWriteValue` returning
+     * the bound `Date` by identity for want of a type:
+     *   - zone-less `date` / `timestamp`: the driver serializes with the
+     *     PROCESS's offset, so the column stores local calendar fields. Nothing
+     *     surfaces at runtime, and a turbine-only round trip reads the same value
+     *     back (the read path shifts by the same offset), so only an outside
+     *     reader sees the drift.
+     *   - `time` / `timetz`: the driver serializes a full ISO timestamp, which
+     *     Postgres rejects with `22007 invalid input syntax for type time`.
+     *   - `timestamptz` and every non-temporal type: unaffected.
+     *
+     * PostgreSQL only: the UTC bind rewrite is Postgres-gated (see
+     * `utcDateTimeWrites` in writes.ts), so on the other engines a missing type
+     * changes nothing about how a `Date` is bound. Suppressed under
+     * `NODE_ENV=production` like the other dev diagnostics and deduped through
+     * the shared registry, so a hot table logs one line for the process.
+     *
+     * Cannot throw on odd metadata: it walks `tableMeta.columns`, the array the
+     * constructor loop above has already iterated (and that client.ts validates
+     * as an array), never `dateColumns`, which is a `Set` in every first-party
+     * metadata path but arrives as a plain object from JSON-round-tripped
+     * metadata. A dev-only diagnostic that crashes a shape production would serve
+     * is worse than the bug it reports.
+     */
+    private warnUntypedColumns;
     /** Quote an identifier through the active SQL dialect. */
     private q;
     /** Return the active dialect's placeholder for a 1-indexed parameter position. */
@@ -427,6 +543,16 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * `findFirst` pass `false` explicitly (their parent set is one row).
      */
     private autoParentSetLarge;
+    /**
+     * The plan-time UPPER BOUND on the parent-row count, or `undefined` when the
+     * query is unbounded. This is the raw number behind
+     * {@link autoParentSetLarge}; the `_count` rule needs the number itself
+     * because its threshold ({@link AUTO_COUNT_BATCH_MIN_PARENT_ROWS}) is two
+     * rows rather than the to-one break-even. `findUnique` / `findFirst` pass `1`
+     * directly: their parent set is one row as a matter of the statement's shape,
+     * not an estimate.
+     */
+    private autoParentBound;
     /**
      * The parent-row count at which `'auto'` stops preferring the single-statement
      * join for a to-one relation.
@@ -465,11 +591,11 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *
      * Everything else (indexed to-many, composite-key, unknown) stays in `joinWith`
      * (byte-identical join). The reserved `_count` key falls back on rule 1 only,
-     * and only for a large parent set: an inline `_count` is one correlated
-     * `COUNT(*)` per parent row, so the grouped follow-up wins exactly when there
-     * are many parents, while for a handful of parents the extra round-trip costs
-     * more than the repeated (small) scans. Also returns the engaged relations for
-     * the dev note.
+     * and on its OWN size rule: an inline `_count` is one correlated `COUNT(*)`
+     * per parent row over an unindexed child table, so the grouped follow-up wins
+     * from {@link AUTO_COUNT_BATCH_MIN_PARENT_ROWS} parent rows upward and inline
+     * is preferred only when the parent set is provably bounded below that. Also
+     * returns the engaged relations for the dev note.
      */
     private partitionWithForAuto;
     /**