turbine-orm 0.81.0 → 0.90.0

package/dist/query/relations.js

@@ -12,13 +12,14 @@
  * reached through the ctx. See builder.ts for the thin delegating methods and
  * the findMany/findUnique execute assembly.
  */
-import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
+import { CircularRelationError, InvariantError, RelationError, UnsupportedFeatureError, ValidationError, } from '../errors.js';
 import { missingIndexForRelation } from '../index-advisor.js';
+import { logTo } from '../logger.js';
 import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
-import { resolveCountRelations } from './batched-loader.js';
-import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, MAX_NAMED_ORDER_KEYS, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
+import { resolveCountRelations, stitchOnlyFields } from './batched-loader.js';
+import { describeOperand, isJsonPathOrderBy, isOrderBySpec, isPlainRecord, isRelationPickOrderBy, isVectorOrderBy, MAX_NAMED_ORDER_KEYS, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
 import { assertDirectionToken, assertOrderDirection } from './types.js';
-import { availableClause, canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelation, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, unknownFieldMessage, } from './utils.js';
+import { availableClause, canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelation, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, suggestKey, unknownFieldMessage, } from './utils.js';
 import { hasWarnedOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -45,6 +46,19 @@ function projectionColumn(table, meta, field, clause) {
         throw new ValidationError(relationInProjectionMessage(table, field, clause));
     throw new ValidationError(unknownFieldMessage(table, field, meta));
 }
+/**
+ * The E003 text for a PII-tagged column named in `select` without
+ * `includePii: UNSAFE`. Shared by every projection path through
+ * {@link resolveProjection}, so a top-level read, a `with` relation (join,
+ * batched, flatten and positional alike) and a single-row write refuse in the
+ * same words. The write path is named because it cannot pass the opt-in at all.
+ */
+export function piiSelectRefusedMessage(table, field) {
+    return (`\`select\` on "${table}" names "${field}", which is tagged PII. A PII column is returned only by a read that ` +
+        'passes `includePii: UNSAFE` (import { UNSAFE } from "turbine-orm"); naming it in `select` does not unlock it, ' +
+        'because `select` can arrive in request data and must not be able to. A write never returns a PII column, so ' +
+        `read the row back with \`includePii: UNSAFE\`, or remove "${field}" from \`select\`.`);
+}
 /**
  * Resolve `select` / `omit` into a list of snake_case column names, for the
  * query's own table and for a relation target alike. `null` means "no
@@ -114,8 +128,15 @@ export function resolveProjection(qi, table, meta, select, omit, includePii) {
         if (Array.isArray(select)) {
             throw new ValidationError(`"select" must be an object mapping field names to true ` + `(e.g. { id: true, name: true }), not an array.`);
         }
-        // Only include columns where value is true. An explicit `select` naming a
-        // PII column IS the opt-in: it comes back regardless of `includePii`.
+        // Only include columns where value is true.
+        //
+        // A PII-tagged column named here needs `includePii: UNSAFE`, exactly like
+        // the default-projection path below. `select` is ordinary request data (a
+        // parsed query string is a `select` object), and the `UNSAFE` symbol is the
+        // one thing a request cannot produce, so letting a bare `select: { ssn: true }`
+        // unlock the column would make the privilege option decorative. The one
+        // exemption is a key the batched loader added to stitch rows together
+        // (STITCH_ONLY_FIELDS), which it strips before the caller sees any entity.
         //
         // Emitted in the TABLE's column order, not the caller's key order, which is
         // the same order the `omit` and default branches below produce. Two reasons,
@@ -143,9 +164,17 @@ export function resolveProjection(qi, table, meta, select, omit, includePii) {
         // keys are all derived from it, so they move together. The one observable
         // consequence is that a projected row's KEY INSERTION order now follows the
         // table rather than the `select` literal.
+        const piiCols = includePii ? undefined : writesMod.piiColumns(qi, meta);
+        const stitchOnly = piiCols && piiCols.size > 0 ? stitchOnlyFields(select) : undefined;
         return canonicalColumnOrder(meta, Object.entries(select)
             .filter(([, v]) => v)
-            .map(([k]) => projectionColumn(table, meta, k, 'select')));
+            .map(([k]) => {
+            const column = projectionColumn(table, meta, k, 'select');
+            if (piiCols?.has(column) && !stitchOnly?.has(k)) {
+                throw new ValidationError(piiSelectRefusedMessage(table, meta.reverseColumnMap[column] ?? column));
+            }
+            return column;
+        }));
     }
     // Default / omit-only projection: PII-tagged columns are excluded unless the
     // caller opted in with `includePii: UNSAFE`. An empty set (untagged schema) keeps the
@@ -214,6 +243,88 @@ const EMPTY_WITH_OPTIONS = Object.freeze({});
 export function relationOptions(spec) {
     return spec === true ? EMPTY_WITH_OPTIONS : spec;
 }
+/** The options a relation in `with` reads; any other key is ignored by every relation strategy. */
+const WITH_OPTION_KEYS = new Set([
+    'with',
+    'where',
+    'orderBy',
+    'limit',
+    'offset',
+    'take',
+    'skip',
+    'select',
+    'omit',
+]);
+/**
+ * Check one relation's `with` options. The fingerprint walk reads every level
+ * of every `with` on every call, whichever strategy then loads it, so this is
+ * the one place that sees them all. `lock` is refused: the row lock compiles to
+ * `FOR <mode> OF "<table>"` on the query's own table, so a lock written on a
+ * relation locked nothing and said nothing. Any other key no relation reads
+ * (`wehre`, `cursor`, `distinct`) is named once in the advice log.
+ */
+function checkWithOptions(qi, table, relName, opts) {
+    for (const key in opts) {
+        if (WITH_OPTION_KEYS.has(key))
+            continue;
+        const value = opts[key];
+        if (value === undefined)
+            continue;
+        if (key === 'lock') {
+            throw new ValidationError(`\`lock\` is not an option of a relation in \`with\` (\`${relName}\` on "${table}"): a row lock applies to ` +
+                "the rows of the query's own table only, so the related rows would not be locked. Lock them with a " +
+                'locking read on their own table, in the same transaction.');
+        }
+        const advice = whereMod.adviceLogger(qi);
+        if (!advice || !shouldWarnOnce(WARN_NS.unknownQueryOption, `${table}.with.${relName}.${key}`))
+            continue;
+        const suggestion = suggestKey(key, WITH_OPTION_KEYS);
+        logTo(advice, 'warn', `unknown option "${key}" on relation "${relName}" in \`with\` on ${table}, it is ignored.` +
+            (suggestion ? ` Did you mean "${suggestion}"?` : ''), { code: 'unknown-query-option', table, operation: 'with', key });
+    }
+}
+/**
+ * `_count` in `with` takes `true` (every relation) or an object naming
+ * relations with `true`. Anything else under a relation, `{ where }` in
+ * particular, was read as `true` and counted every related row.
+ */
+function assertWithCount(table, count) {
+    if (count === true)
+        return;
+    if (!isPlainRecord(count)) {
+        throw new ValidationError(`\`_count\` in \`with\` on "${table}" takes true or an object naming relations, for example ` +
+            `\`_count: { posts: true }\`; received ${describeOperand(count)}.`);
+    }
+    for (const rel of Object.keys(count)) {
+        const value = count[rel];
+        if (value === undefined || typeof value === 'boolean')
+            continue;
+        throw new ValidationError(`\`_count.${rel}\` in \`with\` on "${table}" takes true; received ${describeOperand(value)}. ` +
+            '`_count` counts every related row. To count only the rows that match a filter, use ' +
+            `\`count({ where })\` on the related table.`);
+    }
+}
+/**
+ * A to-many relation's `offset` (`skip` is folded into it at the args seam by
+ * `normalizeWithPagination`, which also refuses it on a to-one relation).
+ */
+export function relationOffset(opts) {
+    return opts.offset;
+}
+/**
+ * The LIMIT / OFFSET tail of a to-many relation's inner row query. Binds the
+ * limit, then the offset, the order {@link collectRelationSubqueryParams}
+ * mirrors. Without an offset the tail is the plain ` LIMIT $n` it has always
+ * been; with one it goes through the dialect's pagination hook, which knows
+ * how to write an offset with no limit.
+ */
+function relationPagination(qi, limit, offset, params, hasOrder) {
+    const limitRef = limit === undefined ? undefined : qi.paginationRef(limit, params, 'relation limit');
+    if (offset === undefined)
+        return limitRef === undefined ? '' : ` LIMIT ${limitRef}`;
+    const offsetRef = qi.paginationRef(offset, params, 'relation offset');
+    return qi.buildPagination(limitRef, offsetRef, hasOrder);
+}
 /**
  * Produce a fingerprint for a `with` clause tree. Recursion mirrors
  * buildSelectWithRelations / buildRelationSubquery.
@@ -235,6 +346,7 @@ export function withFingerprint(qi, withClause, table, depth = 0) {
         // Reserved `_count` key, fingerprint by the selected relation set so
         // `_count: true` and `_count: { posts: true }` never share a cache entry.
         if (relName === '_count') {
+            assertWithCount(meta.name, spec);
             const c = spec;
             parts.push(c === true
                 ? '_count(*)'
@@ -251,6 +363,8 @@ export function withFingerprint(qi, withClause, table, depth = 0) {
             continue;
         }
         const opts = relationOptions(spec);
+        if (opts !== EMPTY_WITH_OPTIONS)
+            checkWithOptions(qi, meta.name, relName, opts);
         const subParts = [];
         // select/omit shape
         if (opts.select) {
@@ -285,6 +399,10 @@ export function withFingerprint(qi, withClause, table, depth = 0) {
         if (opts.limit !== undefined) {
             subParts.push(qi.dialect.inlineLimitOffset ? `l=${opts.limit}` : 'l=1');
         }
+        const offset = relationOffset(opts);
+        if (offset !== undefined) {
+            subParts.push(qi.dialect.inlineLimitOffset ? `off=${offset}` : 'off=1');
+        }
         // nested with (recurse)
         if (opts.with) {
             const nested = withFingerprint(qi, opts.with, relDef.to, depth + 1);
@@ -357,6 +475,10 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
         if (opts.limit !== undefined && !qi.dialect.inlineLimitOffset) {
             params.push(qi.paginationValue(opts.limit, 'relation limit'));
         }
+        const m2mOffset = relationOffset(opts);
+        if (m2mOffset !== undefined && !qi.dialect.inlineLimitOffset) {
+            params.push(qi.paginationValue(m2mOffset, 'relation offset'));
+        }
         if (opts.with) {
             for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
                 const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
@@ -370,7 +492,8 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
     // Mirrors buildRelationSubquery's willWrap: `orderBy: {}` is treated as absent.
     const relOrderEntries = opts.orderBy ? orderByEntries(opts.orderBy).filter(([, dir]) => dir !== undefined) : [];
     const hasOrder = relOrderEntries.length > 0;
-    const willWrap = relDef.type === 'hasMany' && (opts.limit !== undefined || hasOrder);
+    const offset = relationOffset(opts);
+    const willWrap = relDef.type === 'hasMany' && (opts.limit !== undefined || offset !== undefined || hasOrder);
     // Non-wrapped path: nested relations BEFORE where/limit
     if (!willWrap && opts.with) {
         for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
@@ -400,6 +523,9 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
     if (relDef.type === 'hasMany' && opts.limit !== undefined && !qi.dialect.inlineLimitOffset) {
         params.push(qi.paginationValue(opts.limit, 'relation limit'));
     }
+    if (relDef.type === 'hasMany' && offset !== undefined && !qi.dialect.inlineLimitOffset) {
+        params.push(qi.paginationValue(offset, 'relation offset'));
+    }
     // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
     if (willWrap && opts.with) {
         for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
@@ -557,14 +683,14 @@ export function isRelationOrderByValue(_qi, value) {
 }
 /**
  * Render the ` NULLS FIRST` / ` NULLS LAST` suffix for a column ordering.
- * Only PostgreSQL and SQLite support the `NULLS FIRST/LAST` grammar, on any
- * other engine a caller asking for explicit nulls placement gets a clear
- * {@link UnsupportedFeatureError} (E017) instead of broken SQL.
+ * On an engine without the `NULLS FIRST/LAST` grammar (`nullsOrderingClause`:
+ * PostgreSQL and SQLite have it) a caller asking for explicit nulls placement
+ * gets a clear {@link UnsupportedFeatureError} (E017) instead of broken SQL.
  */
 export function nullsSuffix(qi, nulls) {
     if (!nulls)
         return '';
-    if (qi.dialect.name !== 'postgresql' && qi.dialect.name !== 'sqlite') {
+    if (!qi.dialect.capabilities.nullsOrderingClause) {
         throw new UnsupportedFeatureError('NULLS FIRST/LAST ordering', qi.dialect.name, 'Explicit nulls placement in orderBy is only available on PostgreSQL and SQLite.');
     }
     return nulls === 'first' ? ' NULLS FIRST' : ' NULLS LAST';
@@ -638,7 +764,7 @@ export function buildJsonPathOrderEntry(qi, table, meta, field, spec, prefix, pa
     // the grammar gate matches nullsSuffix.
     const nullsSql = spec.nulls
         ? nullsSuffix(qi, spec.nulls)
-        : qi.dialect.name === 'postgresql' || qi.dialect.name === 'sqlite'
+        : qi.dialect.capabilities.nullsOrderingClause
             ? ' NULLS LAST'
             : '';
     return `${lhs} ${dir}${nullsSql}`;
@@ -847,6 +973,18 @@ export function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lat
     })
         .join(', ');
 }
+/**
+ * Param-collect mirror of a TO-ONE relation orderBy entry, done by running
+ * {@link buildRelationOrderBy} and discarding its SQL. The build pushes the
+ * target's global filter once per ordered column and, for a chained
+ * `{ author: { org: { name } } }` ordering, once more per hop table, in hop
+ * order. A hand-written mirror that pushed one filter per column bound too few
+ * params (and in the wrong order) as soon as a hop table had a filter, so this
+ * mirror is the build itself and cannot drift from it.
+ */
+export function collectToOneRelationOrderParams(qi, relName, value, params, ctx) {
+    buildRelationOrderBy(qi, relName, value, 'ord0', params, ctx);
+}
 /**
  * Validate a {@link RelationPickOrderBy} entry's scope and shape. Shared by
  * the SQL-build path ({@link buildRelationPickOrderBy}) and the cache-hit
@@ -946,7 +1084,7 @@ export function buildRelationPickOrderBy(qi, relName, relDef, spec, alias, paren
     // the caller set `nulls` explicitly; the grammar gate matches nullsSuffix.
     const nullsSql = spec.nulls
         ? nullsSuffix(qi, spec.nulls)
-        : qi.dialect.name === 'postgresql' || qi.dialect.name === 'sqlite'
+        : qi.dialect.capabilities.nullsOrderingClause
             ? ' NULLS LAST'
             : '';
     // Lateral plan: splice a `LEFT JOIN LATERAL (... LIMIT 1) ON true` into the
@@ -1109,14 +1247,18 @@ export function collectRelationOrderParams(qi, targetTable, targetMeta, orderEnt
             if (isRelationPickOrderBy(dirValue)) {
                 throw pickOrderNestedError(qi, key);
             }
-            const relDef = ownLookup(targetMeta.relations, key);
+            // resolveRelationDef, as buildRelationOrderBy resolves it, so a relation
+            // written in its table spelling binds its params on a cache hit too.
+            const relDef = resolveRelationDef(targetMeta.relations, key);
             if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
                 collectRelationCountParams(qi, relDef, params);
             }
             else if (relDef) {
-                for (const _col of Object.keys(dirValue)) {
-                    whereMod.collectTargetGlobalFilterAlias(qi, relDef.to, params);
-                }
+                collectToOneRelationOrderParams(qi, key, dirValue, params, {
+                    meta: targetMeta,
+                    table: targetTable,
+                    parentRef: targetTable,
+                });
             }
             continue;
         }
@@ -1171,26 +1313,27 @@ export function buildRelationCountExpr(qi, relDef, parentRef, alias, params) {
  * {@link collectManyToManyTargetGlobalFilter}.
  */
 export function manyToManyTargetGlobalFilterExists(qi, relDef, alias, jalias, params) {
-    const gf = whereMod.resolveGlobalFilter(qi, relDef.to);
-    if (!gf || !relDef.through)
+    const through = relDef.through;
+    if (!through)
         return '';
     const tMeta = qi.schema.tables[relDef.to];
     if (!tMeta || tMeta.primaryKey.length === 0)
         return '';
-    const talias = `${alias}t`;
-    const targetKeys = normalizeKeyColumns(relDef.through.targetKey);
+    const targetKeys = normalizeKeyColumns(through.targetKey);
     const pk = tMeta.primaryKey;
     if (targetKeys.length !== pk.length)
         return '';
-    const join = targetKeys.map((jc, i) => `${talias}.${qi.q(pk[i])} = ${jalias}.${qi.q(jc)}`).join(' AND ');
-    const gfClause = whereMod.buildAliasWhere(qi, relDef.to, tMeta, talias, gf, params);
-    const gfAnd = gfClause ? ` AND ${gfClause}` : '';
-    return `EXISTS (SELECT 1 FROM ${qi.q(relDef.to)} ${talias} WHERE ${join}${gfAnd})`;
+    return whereMod.withTargetGlobalFilter(qi, relDef.to, '', (gf) => {
+        const talias = `${alias}t`;
+        const join = targetKeys.map((jc, i) => `${talias}.${qi.q(pk[i])} = ${jalias}.${qi.q(jc)}`).join(' AND ');
+        const gfClause = whereMod.buildAliasWhere(qi, relDef.to, tMeta, talias, gf, params);
+        const gfAnd = gfClause ? ` AND ${gfClause}` : '';
+        return `EXISTS (SELECT 1 FROM ${qi.q(relDef.to)} ${talias} WHERE ${join}${gfAnd})`;
+    });
 }
 /** Param-collect mirror of {@link manyToManyTargetGlobalFilterExists}. */
 export function collectManyToManyTargetGlobalFilter(qi, relDef, params) {
-    const gf = whereMod.resolveGlobalFilter(qi, relDef.to);
-    if (!gf || !relDef.through)
+    if (!relDef.through)
         return;
     const tMeta = qi.schema.tables[relDef.to];
     if (!tMeta || tMeta.primaryKey.length === 0)
@@ -1198,7 +1341,7 @@ export function collectManyToManyTargetGlobalFilter(qi, relDef, params) {
     const targetKeys = normalizeKeyColumns(relDef.through.targetKey);
     if (targetKeys.length !== tMeta.primaryKey.length)
         return;
-    whereMod.collectAliasWhereParams(qi, relDef.to, tMeta, gf, params);
+    whereMod.withTargetGlobalFilter(qi, relDef.to, false, (gf) => whereMod.collectAliasWhereParams(qi, relDef.to, tMeta, gf, params));
 }
 /**
  * Param-collect mirror of {@link buildRelationCountExpr}'s global-filter
@@ -1333,13 +1476,15 @@ export function parseNestedRow(qi, row, table, fromJson = false) {
                 // find it.
                 //
                 // The warn is gated and deduped because this sits in parseNestedRow's
-                // per-relation loop: one 10,000-row page was 10,000 console.warn calls.
-                if (process.env.NODE_ENV !== 'production' &&
-                    shouldWarnOnce(WARN_NS.relationParseFailure, `${qi.table}.${relName}`)) {
-                    console.warn(`[turbine] Relation "${relName}" on "${qi.table}" returned a payload that is not valid JSON. ` +
-                        `This is a bug; please report it with the emitted SQL.`);
+                // per-relation loop: one 10,000-row page was 10,000 warnings. The
+                // parse error stays out of the entry: its message quotes the payload,
+                // which is row data.
+                const log = whereMod.adviceLogger(qi);
+                if (log && shouldWarnOnce(WARN_NS.relationParseFailure, `${qi.table}.${relName}`)) {
+                    logTo(log, 'warn', `Relation "${relName}" on "${qi.table}" returned a payload that is not valid JSON. ` +
+                        `This is a bug; please report it with the emitted SQL.`, { code: 'relation-payload-json', table: qi.table, relation: relName });
                 }
-                throw new ValidationError(`Relation "${relName}" on table "${qi.table}" returned a payload that could not be parsed as JSON.`, { cause: err });
+                throw new InvariantError('relation-payload-json', `Relation "${relName}" on table "${qi.table}" returned a payload that could not be parsed as JSON.`, { cause: err });
             }
         }
         else if (Array.isArray(rawValue)) {
@@ -1834,7 +1979,7 @@ function flattenNodeSignature(node) {
     return `${node.relName}@${node.alias}(${node.cols.map(([col]) => col).join(',')})${slots}`;
 }
 /**
- * Dev-only, once-per-(table, relation, reason) note that an explicitly
+ * Per-query advice, once per (table, relation, reason): an explicitly
  * requested `relationLoadStrategy: 'flatten'` did NOT engage for a relation.
  *
  * Worth its own warning because the fallback is otherwise INVISIBLE: the query
@@ -1843,21 +1988,23 @@ function flattenNodeSignature(node) {
  * Silence there is indistinguishable from the strategy being a no-op, which is
  * exactly the shape of thing that gets filed as a bug.
  *
- * Suppressed in production like the other planner notes, and deduped through
- * the shared registry so a hot query logs once rather than per call. Note that
- * a flatten plan is recomputed on the build, param-collect and row-assembly
- * paths for the same query; the registry is what keeps that to one line.
+ * Off when `diagnostics` turn advice off, like the other planner notes, and
+ * deduped through the shared registry so a hot query logs once rather than per
+ * call. Note that a flatten plan is recomputed on the build, param-collect and
+ * row-assembly paths for the same query; the registry is what keeps that to
+ * one line.
  */
-function warnFlattenFallback(table, rejects) {
+function warnFlattenFallback(qi, table, rejects) {
     if (rejects.length === 0)
         return;
-    if (process.env.NODE_ENV === 'production')
+    const log = whereMod.adviceLogger(qi);
+    if (!log)
         return;
     for (const { relation, reason } of rejects) {
         if (!shouldWarnOnce(WARN_NS.flattenFallback, `${table}.${relation}|${reason}`))
             continue;
-        console.warn(`[turbine] relationLoadStrategy: 'flatten' did not engage for relation "${relation}" on "${table}": ` +
-            `${reason}. It loads via the correlated subquery instead (same rows, same values, different plan).`);
+        logTo(log, 'warn', `relationLoadStrategy: 'flatten' did not engage for relation "${relation}" on "${table}": ` +
+            `${reason}. It loads via the correlated subquery instead (same rows, same values, different plan).`, { code: 'flatten-fallback', table, relation, reason });
     }
 }
 /**
@@ -1888,7 +2035,7 @@ export function planFlattenWith(qi, table, withClause, includePii) {
         if (node)
             nodes[relName] = node;
     }
-    warnFlattenFallback(table, rejects);
+    warnFlattenFallback(qi, table, rejects);
     if (Object.keys(nodes).length === 0)
         return null;
     // Flat rows carry the root table's own columns, one column per non-flattened
@@ -1898,7 +2045,7 @@ export function planFlattenWith(qi, table, withClause, includePii) {
     const reserved = new Set([...meta.allColumns, ...Object.keys(withClause)]);
     for (const alias of aliases) {
         if (reserved.has(alias)) {
-            warnFlattenFallback(table, [
+            warnFlattenFallback(qi, table, [
                 {
                     relation: Object.keys(nodes).join(', '),
                     reason: `the projected alias "${alias}" collides with a column or relation name on "${table}"`,
@@ -2171,11 +2318,12 @@ export function buildSelectWithRelations(qi, table, withClause, params, columnsL
     const meta = qi.schema.tables[table];
     if (!meta)
         throw new ValidationError(`Unknown table "${table}"`);
-    // Positional JSON encoding is Postgres-only in v1. Gate here, the single
-    // entry point for every `with` clause, so no engine ever emits the
-    // json_build_array shape its dialect can't produce (and mssql's FOR JSON
-    // override path is never reached with positional active).
-    if (qi.jsonEncoding === 'positional' && qi.dialect.name !== 'postgresql') {
+    // Positional JSON encoding needs `positionalJson`, the flag the default in
+    // builder.ts reads too, so the default never picks an encoding refused here.
+    // Gate here, the single entry point for every `with` clause, so no engine
+    // ever emits the json_build_array shape its dialect can't produce (and
+    // mssql's FOR JSON override path is never reached with positional active).
+    if (qi.jsonEncoding === 'positional' && !qi.dialect.capabilities.positionalJson) {
         throw new UnsupportedFeatureError("jsonEncoding: 'positional'", qi.dialect.name, 'Positional relation encoding is only available on PostgreSQL in this version.');
     }
     const cols = columnsList ?? meta.allColumns;
@@ -2329,12 +2477,13 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // The raw `spec` is still what crosses the dialect seam below, since
     // RelationSubqueryContext is a published contract.
     const opts = relationOptions(spec);
-    // Dev-only: correlated relation loading probes the child table once per parent
-    // row, so a missing FK index multiplies into per-parent full-table scans (a
-    // batched-loader ORM pays the same missing index only once, which is why
-    // schemas migrated from one often lack these). Name the exact index to create
-    // instead of letting the slowness look like an ORM problem.
-    if (process.env.NODE_ENV !== 'production') {
+    // Per-query advice: correlated relation loading probes the child table once
+    // per parent row, so a missing FK index multiplies into per-parent full-table
+    // scans (a batched-loader ORM pays the same missing index only once, which is
+    // why schemas migrated from one often lack these). Name the exact index to
+    // create instead of letting the slowness look like an ORM problem.
+    const log = whereMod.adviceLogger(qi);
+    if (log) {
         const warnKey = `${relDef.from}.${relDef.name}`;
         // Compute the (potentially costly) probe only for a key not yet warned, and
         // claim the key through the process-wide registry ONLY when we actually warn,
@@ -2343,10 +2492,16 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
         if (!hasWarnedOnce(WARN_NS.unindexedRelation, warnKey)) {
             const miss = missingIndexForRelation(qi.schema, relDef);
             if (miss && shouldWarnOnce(WARN_NS.unindexedRelation, warnKey)) {
-                console.warn(`[turbine] Relation "${relDef.name}" on "${relDef.from}" probes ` +
+                logTo(log, 'warn', `Relation "${relDef.name}" on "${relDef.from}" probes ` +
                     `"${miss.table}"(${miss.columns.join(', ')}) which has no covering index, ` +
                     `each parent row scans the full table. Fix: ${miss.createSql}; ` +
-                    'or run `npx turbine doctor` for a full report.');
+                    'or run `npx turbine doctor` for a full report.', {
+                    code: 'unindexed-relation',
+                    table: relDef.from,
+                    relation: relDef.name,
+                    probeTable: miss.table,
+                    columns: miss.columns,
+                });
             }
         }
     }
@@ -2416,7 +2571,8 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // it must neither trigger the wrap (dropping nested relations) nor render a
     // dangling `ORDER BY `. `limit: 0` is meaningful (LIMIT 0) and DOES wrap.
     const relOrderEntries = opts.orderBy ? orderByEntries(opts.orderBy).filter(([, dir]) => dir !== undefined) : [];
-    const willWrap = relDef.type === 'hasMany' && (opts.limit !== undefined || relOrderEntries.length > 0);
+    const offset = relationOffset(opts);
+    const willWrap = relDef.type === 'hasMany' && (opts.limit !== undefined || offset !== undefined || relOrderEntries.length > 0);
     // manyToMany takes a dedicated JOIN-through-junction path. Nested relations,
     // where, orderBy, and select/omit are handled there (the target alias is the
     // row source, exactly like hasMany), so short-circuit before the hasMany logic.
@@ -2484,8 +2640,8 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // (and shifts every later placeholder by one). To-one relations ignore limit.
     // `limit: 0` is honored (LIMIT 0 → empty array), so check !== undefined.
     let limitClause = '';
-    if (relDef.type === 'hasMany' && opts.limit !== undefined) {
-        limitClause = ` LIMIT ${qi.paginationRef(opts.limit, params, 'relation limit')}`;
+    if (relDef.type === 'hasMany') {
+        limitClause = relationPagination(qi, opts.limit, offset, params, relOrderEntries.length > 0);
     }
     if (relDef.type === 'hasMany') {
         // When LIMIT or ORDER BY is used, wrap in a subquery so LIMIT applies to rows
@@ -2603,11 +2759,8 @@ export function buildManyToManySubquery(qi, relDef, spec, params, parentRef, ali
     const gfExtra = whereMod.targetGlobalFilterAlias(qi, targetTable, talias, params);
     if (gfExtra)
         whereClause += ` AND ${gfExtra}`;
-    // LIMIT, `limit: 0` is honored (LIMIT 0 → empty array)
-    let limitClause = '';
-    if (opts.limit !== undefined) {
-        limitClause = ` LIMIT ${qi.paginationRef(opts.limit, params, 'relation limit')}`;
-    }
+    // LIMIT / OFFSET, `limit: 0` is honored (LIMIT 0 → empty array)
+    const limitClause = relationPagination(qi, opts.limit, relationOffset(opts), params, relOrderEntries.length > 0);
     const fromJoin = `FROM ${qTarget} ${talias} JOIN ${qJunction} ${jalias} ON ${joinOn}`;
     // When LIMIT or ORDER BY is present, wrap the joined rows in an inner subquery
     // so the LIMIT applies to rows BEFORE aggregation (same approach as hasMany).

package/dist/query/row-lock.d.ts

@@ -0,0 +1,49 @@
+/**
+ * turbine-orm: the `lock` read option (`SELECT ... FOR UPDATE OF "t"`).
+ *
+ * {@link resolveRowLock} is the one place a `lock` value is validated and
+ * rendered. The SQL build and the cache key both read its result, so the two
+ * cannot disagree about which lock a statement carries.
+ *
+ * The clause always names the queried table (`OF "t"`). That keeps the lock on
+ * the returned rows of that table and nothing else, on every relation
+ * strategy: correlated `with` subqueries are never locked anyway, and without
+ * `OF` PostgreSQL refuses the `flatten` and lateral-pick plans (their outer
+ * joins would put a table on the nullable side of the lock).
+ */
+import type { Dialect } from '../dialect.js';
+/** A validated `lock`: the clause to append after pagination, and its cache-key segment. */
+export interface ResolvedRowLock {
+    /** e.g. ` FOR UPDATE OF "jobs" SKIP LOCKED` */
+    readonly sql: string;
+    /** e.g. `u.sl`; one value per distinct clause, never empty. */
+    readonly fp: string;
+}
+/**
+ * Validate `lock` for a read on `table` and render its clause.
+ *
+ * `undefined` means no lock. Anything that is not a mode string or a
+ * `{ mode, noWait?, skipLocked? }` object is `ValidationError` (E003), and so
+ * is asking for both wait policies at once. A mode the dialect does not list in
+ * {@link Dialect.rowLockModes} is `UnsupportedFeatureError` (E017).
+ */
+export declare function resolveRowLock(lock: unknown, dialect: Dialect, table: string): ResolvedRowLock | undefined;
+/**
+ * The refusal for a locking read outside a transaction. In autocommit the lock
+ * is released when the statement ends, before the caller sees the rows, so a
+ * `skipLocked` queue claim outside a transaction claims nothing, silently.
+ */
+export declare function lockOutsideTransactionMessage(table: string, operation: string): string;
+/** The refusal for `lock` on a streaming read. */
+export declare function lockOnStreamMessage(table: string, operation: string): string;
+/** The refusal for `lock` together with `distinct`. */
+export declare function lockWithDistinctMessage(table: string): string;
+/**
+ * Refuse a locking read in a pipeline that runs each statement in autocommit
+ * (`pipeline(..., { transactional: false })`). A transactional pipeline, and
+ * `$transaction([...])`, keep the lock for the rest of the batch.
+ */
+export declare function assertNoLockInAutocommitPipeline(queries: readonly {
+    rowLock?: true;
+    tag?: string;
+}[]): void;