turbine-orm 0.62.1 → 0.64.0

package/dist/cjs/nested-write.js

@@ -237,6 +237,18 @@ function pkWhere(tableMeta, row) {
     const where = {};
     for (const col of tableMeta.primaryKey) {
         const field = tableMeta.reverseColumnMap[col] ?? col;
+        // A PARTIAL primary key here is not a filter, it is a mass mutation.
+        // `undefined` values are dropped when the where compiles, and the
+        // empty-where guard only fires when NOTHING survives, so a composite PK
+        // missing one member compiles to a predicate on the remaining member and
+        // the statement rewrites every row that shares it. The row is supposed to
+        // be one this engine just read, so a missing member is an internal fault,
+        // and the only safe response is to refuse rather than to run.
+        if (row[field] === undefined) {
+            throw new errors_js_1.ValidationError(`[turbine] Cannot address a row of "${tableMeta.name}" by primary key: "${field}" is missing from the ` +
+                'row this nested write is operating on, so the generated predicate would match more rows than intended. ' +
+                'This is a bug in turbine, please report it.');
+        }
         where[field] = row[field];
     }
     return where;

package/dist/cjs/powql.d.ts

@@ -307,6 +307,15 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
      * and returns it regardless. Untagged tables project exactly as before.
      */
+    /**
+     * Resolve one projection field name, or throw. PowQL already refused an
+     * unresolvable name here (via {@link column}), unlike the SQL engines' join
+     * path, which filtered it out silently until 0.64. What this adds is the
+     * RELATION case: naming a relation inside `select` is a Prisma habit rather
+     * than a typo, and the generic "unknown column" text sends the reader looking
+     * for a misspelling that is not there. Same message as the SQL engines.
+     */
+    private projectionColumn;
     private projectedColumns;
     /**
      * The snake_case names of this table's PII-tagged columns. Empty for a table

package/dist/cjs/powql.js

@@ -908,31 +908,56 @@ class PowqlInterface {
      * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
      * and returns it regardless. Untagged tables project exactly as before.
      */
+    /**
+     * Resolve one projection field name, or throw. PowQL already refused an
+     * unresolvable name here (via {@link column}), unlike the SQL engines' join
+     * path, which filtered it out silently until 0.64. What this adds is the
+     * RELATION case: naming a relation inside `select` is a Prisma habit rather
+     * than a typo, and the generic "unknown column" text sends the reader looking
+     * for a misspelling that is not there. Same message as the SQL engines.
+     */
+    projectionColumn(field, clause) {
+        if ((0, utils_js_1.ownLookup)(this.meta.relations, field)) {
+            throw new errors_js_1.ValidationError((0, utils_js_1.relationInProjectionMessage)(this.table, field, clause));
+        }
+        return this.column(field).name;
+    }
     projectedColumns(select, omit, includePii) {
+        const pk = new Set(this.meta.primaryKey);
         let cols = this.meta.columns.map((c) => c.name);
         const hasSelect = select && Object.keys(select).length;
         if (hasSelect) {
             const picked = new Set(Object.entries(select)
                 .filter(([, v]) => v)
-                .map(([k]) => this.column(k).name));
+                .map(([k]) => this.projectionColumn(k, 'select')));
             // Always keep the PK so reselect / relation stitching has a key to work with.
-            for (const pk of this.meta.primaryKey)
-                picked.add(pk);
+            for (const key of pk)
+                picked.add(key);
             cols = cols.filter((c) => picked.has(c));
         }
         else if (!includePii) {
             // Default / omit-only projection: drop PII columns (kept above only when a
-            // caller names them in `select`). PK is never PII in practice; if one is
-            // tagged it is still dropped here, so tag sensitive data, not keys.
+            // caller names them in `select`), EXCEPT a PK column. This used to drop a
+            // tagged PK, on the reasoning that keys should not be tagged in the first
+            // place. That is good advice and a bad guarantee: the row it returns
+            // cannot address itself, so writing it back builds a partial predicate
+            // and mutates every row sharing the rest of the key. Same rule and same
+            // reason as `piiColumns` on the SQL engines.
             const pii = this.piiColumnNames();
             if (pii.size)
-                cols = cols.filter((c) => !pii.has(c));
+                cols = cols.filter((c) => !pii.has(c) || pk.has(c));
         }
         if (omit && Object.keys(omit).length) {
             const dropped = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
-                .map(([k]) => this.column(k).name));
-            cols = cols.filter((c) => !dropped.has(c));
+                .map(([k]) => this.projectionColumn(k, 'omit')));
+            // The PK survives `omit` too. This filter ran unconditionally and after
+            // the `select` branch's force-add, so `omit: { id: true }` undid the very
+            // guarantee that force-add exists to provide: the m2m loader keys its
+            // target map on the PK (`targetByPk`), so every target collapsed onto the
+            // single bucket "undefined", no parent matched, and the relation came
+            // back `[]` for every row with no error.
+            cols = cols.filter((c) => !dropped.has(c) || pk.has(c));
         }
         return cols;
     }

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

@@ -304,6 +304,30 @@ async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0
     // A falsy `_count` opts out, exactly like a falsy relation spec.
     const countSpec = withClause._count;
     const hasCount = Boolean(countSpec);
+    // NESTED `_count` is refused here so the two strategies answer alike.
+    //
+    // The join builder emits `_count` only for the TOP-LEVEL `with`; one level
+    // down, `buildRelationSubquery` looks `_count` up as an ordinary relation
+    // name, misses, and throws E005. This loader handled it at every depth, so
+    // one query with one set of args either threw or returned populated counts
+    // depending purely on which plan ran, and under the `'auto'` default that
+    // choice is made by a cost heuristic reading index coverage and table size.
+    // The same code therefore worked on a small table and threw on a large one.
+    //
+    // That is the same non-determinism as the correlation-key bug this module was
+    // just fixed for, only louder, so it is closed the same way: by agreement.
+    // Refusing is the direction that is a no-op for anyone on the default, since
+    // there the shape already fails whenever the relation is NOT demoted. Nested
+    // `_count` is a real feature (Prisma has it) and teaching the join path is
+    // the right end state, but that means the four json_build_object emission
+    // sites, the positional encoding, SQL Server's FOR JSON override and PowDB's
+    // nested projections all learning it together, which is a feature release,
+    // not a line in a correctness fix. Until then both strategies say no.
+    if (hasCount && depth > 0) {
+        throw new errors_js_1.RelationError(`[turbine] Unknown relation "_count" on table "${ctx.parentMeta.name}". ` +
+            `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}. ` +
+            '(`_count` is supported on the top-level `with` only, on every relationLoadStrategy.)');
+    }
     // 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.
@@ -395,6 +419,7 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
     const parentKeyField = ctx.parentMeta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
     const childKeyField = targetMeta.reverseColumnMap[childKeyCol] ?? childKeyCol;
+    assertCorrelationKeyProjected(parents, parentKeyField, relName, ctx.parentMeta.name);
     const keys = uniqueKeys(parents, parentKeyField);
     const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
     if (keys.length === 0) {
@@ -404,7 +429,16 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     }
     // The follow-up must project the child correlation key even if the caller's
     // select/omit excluded it; strip it back off afterwards so the shape matches join.
-    const proj = includeKeysForBatching(options.select, options.omit, [childKeyField], defaultProjectionFields(targetMeta, ctx.includePii));
+    //
+    // AND the keys the child's OWN nested relations will correlate on. Passing
+    // only `childKeyField` here was the whole of the silent-null bug: this level
+    // stitched fine, then the recursion below asked the children for a key that
+    // this projection had just dropped. The root call sites in builder.ts have
+    // always resolved the full set through `neededParentKeyFields`; these nested
+    // ones did not, so the defect needed a `select` (or an `omit` of the FK) on a
+    // to-many with a to-one inside it, which is why `include` and `join` were both
+    // clean and seventeen rounds of parity capture missed it.
+    const proj = includeKeysForBatching(options.select, options.omit, [childKeyField, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
     const chunks = [];
     for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS)
@@ -430,6 +464,12 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     if (options.with && allChildren.length > 0) {
         await loadRelationsBatched({ ...ctx, parentMeta: targetMeta }, allChildren, options.with, timeout, depth + 1, [...path, relName]);
     }
+    // Symmetric to the parent-side assertion above. If the CHILD key were ever
+    // missing, `groupBy` would bucket every child under the string "undefined",
+    // no parent would match, and the relation would come back empty just as
+    // silently. `includeKeysForBatching` makes that unreachable, which is exactly
+    // what was true of the parent side until this week.
+    assertCorrelationKeyProjected(allChildren, childKeyField, relName, targetMeta.name);
     const byKey = groupBy(allChildren, childKeyField);
     const limit = options.limit;
     for (const parent of parents) {
@@ -468,6 +508,7 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
     const targetPkCol = targetMeta.primaryKey[0];
     const parentRefField = ctx.parentMeta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
     const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
+    assertCorrelationKeyProjected(parents, parentRefField, relName, ctx.parentMeta.name);
     const parentKeys = uniqueKeys(parents, parentRefField);
     if (parentKeys.length === 0) {
         for (const parent of parents)
@@ -506,7 +547,10 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
         }
     }
     // (2) Target rows by PK, honouring the relation's own where/select/omit/orderBy.
-    const proj = includeKeysForBatching(options.select, options.omit, [targetPkField], defaultProjectionFields(targetMeta, ctx.includePii));
+    // Plus the keys the target's own nested relations need, same rule and same
+    // reason as the to-many loader above: this level's PK is not the only key the
+    // recursion below will ask these rows for.
+    const proj = includeKeysForBatching(options.select, options.omit, [targetPkField, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
     const targetVals = [...targetValSet];
     const tChunks = [];
@@ -688,6 +732,48 @@ function mergeChildWhere(where, keyField, chunk) {
         return { AND: [where, correlation] };
     return { ...where, ...correlation };
 }
+/**
+ * Refuse to stitch a relation whose correlation key was never projected.
+ *
+ * THE FAILURE THIS EXISTS TO REMOVE. `uniqueKeys` skips a row whose key is
+ * `null` OR `undefined`, and a column the projection left out is `undefined`
+ * for exactly the same reason it is for a genuinely null FK. So a loader that
+ * has lost its key cannot tell itself apart from a page of parents that
+ * legitimately point at nothing: both produce zero keys, and the empty-key
+ * branch hands back `null` / `[]` for every parent. That is a wrong answer with
+ * an HTTP 200 on it: a reporting endpoint summed a money column across the
+ * relation, every row of it read as absent, and the total came back 0 for a
+ * large fraction of a page. Nothing in the payload, the logs or the response
+ * status distinguished it from the right answer.
+ *
+ * The two states ARE distinguishable, just not by the value: a column that was
+ * not selected is ABSENT from the parsed entity (`'fk' in row === false`),
+ * while a selected column holding SQL NULL is PRESENT with the value `null`.
+ * Verified against a live database in both directions. So the discriminator is
+ * property presence (`Object.hasOwn`, not `in`: the rest of this file uses it,
+ * and a column named `constructor` or `toString` passes an `in` check on any
+ * plain object), and it is checked over ALL parents rather than the first:
+ * every row on one level shares one projection, so a field missing from every
+ * row is a projection fault, while a field missing from some rows is not a
+ * state this loader can produce at all.
+ *
+ * After {@link neededParentKeyFields} is applied at every nesting level this is
+ * an unreachable invariant, which is the point: if it ever fires it is a bug in
+ * Turbine, not in the caller's query, and the caller gets told so along with the
+ * one-line workaround. E017 with the same remedy as the composite-key refusal a
+ * few lines up, deliberately: to the caller both are "this strategy cannot serve
+ * this shape, use 'join'", and inventing a code for an unreachable state would
+ * be a new public error nobody can trigger.
+ */
+function assertCorrelationKeyProjected(parents, field, relName, parentTable) {
+    if (parents.length === 0)
+        return;
+    if (parents.some((parent) => Object.hasOwn(parent, field)))
+        return;
+    throw new errors_js_1.UnsupportedFeatureError(`batched loading of relation "${relName}" on "${parentTable}"`, 'relationLoadStrategy: "batched"', `the correlation key "${field}" is missing from every parent row, so the relation cannot be stitched and ` +
+        'would silently come back empty. This is a bug in turbine, please report it. ' +
+        `Workaround: pass \`relationLoadStrategy: 'join'\` on this query.`);
+}
 /** Distinct, non-null values of `field` across `rows`. */
 function uniqueKeys(rows, field) {
     const seen = new Set();

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

@@ -34,8 +34,41 @@ export interface RelationShape {
     cardinality: 'many' | 'one';
 }
 /**
- * Resolve select/omit options into a list of snake_case column names.
- * Returns null if neither is provided (meaning all columns).
+ * 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
+ * projection", i.e. all columns, which keeps the `*` fast path.
+ *
+ * ## Why this is one function
+ *
+ * It used to be two, `resolveColumns` for the top level and
+ * `resolveTargetColumns` for a relation target, doing the same job against
+ * different metadata. They drifted, and the drift was invisible from either
+ * side: the top level resolved every name through a throwing lookup, while the
+ * relation side filtered unresolvable names out and emitted SQL for whatever
+ * survived. So the SAME key in the SAME query threw at the top and was silently
+ * ignored one level down, where `select: { titel: true }` returned `{}` rows
+ * and `omit: { titel: true }` returned the column it was asked to hide.
+ *
+ * It was worse than an inconsistency between depths. The batched loader runs
+ * each relation as a real query against the target table, so it went through
+ * the THROWING path, while the join plan went through the silent one. The two
+ * strategies therefore disagreed about whether the query was even valid, and
+ * under `relationLoadStrategy: 'auto'` which one runs is decided by a cost
+ * heuristic reading index coverage and table size. The same code threw on one
+ * table and quietly returned the wrong shape on another.
+ *
+ * Merging them is the fix that outlives this bug. Two functions that must agree
+ * are kept in step by whoever remembers; one function cannot disagree with
+ * itself. This mirrors `walkWhere` in where-compile.ts, which exists for the
+ * same reason after the top-level and relation-scoped WHERE walkers drifted
+ * twice, and it is why a new projection site is safe by default: PII exclusion,
+ * the `*` fast path and name resolution all live here, so reimplementing the
+ * name handling would mean reimplementing those too.
+ */
+export declare function resolveProjection(qi: BuilderCtx, table: string, meta: TableMetadata, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
+/**
+ * The query's own table. Thin wrapper over {@link resolveProjection} kept for
+ * the existing call sites in builder.ts.
  */
 export declare function resolveColumns(qi: BuilderCtx, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
 /**
@@ -254,8 +287,14 @@ export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unkno
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
  * {@link buildRelationShape} (decode key order) so they can never diverge.
+ *
+ * A relation always projects SOMETHING, so the `null` that
+ * {@link resolveProjection} uses for the top level's `SELECT *` fast path
+ * becomes the target's full column list here. That is the only difference
+ * between the two, and it is why this is a four-line wrapper rather than a
+ * second implementation.
  */
-export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean): string[];
+export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean, targetTable?: string): string[];
 /**
  * Render a single relation row's JSON: a keyed object (`'object'`) or a
  * positional array (`'positional'`). The array drops the keys but keeps the

package/dist/cjs/query/relations.js

@@ -47,6 +47,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjection = resolveProjection;
 exports.resolveColumns = resolveColumns;
 exports.withFingerprint = withFingerprint;
 exports.collectWithParams = collectWithParams;
@@ -100,10 +101,58 @@ const warn_registry_js_1 = require("./warn-registry.js");
 const whereMod = __importStar(require("./where.js"));
 const writesMod = __importStar(require("./writes.js"));
 /**
- * Resolve select/omit options into a list of snake_case column names.
- * Returns null if neither is provided (meaning all columns).
+ * Turn ONE caller-supplied projection field name into a column, or throw.
+ *
+ * The whole point of this function is that it has no third outcome. The
+ * relation-side projection used to filter unresolvable names out
+ * (`.filter((col) => allColumns.includes(col))`) instead of rejecting them, and
+ * a filter that discards is exactly how a name typed by a human becomes SQL
+ * that no longer reflects what was asked for.
  */
-function resolveColumns(qi, select, omit, includePii) {
+function projectionColumn(table, meta, field, clause) {
+    const column = (0, utils_js_1.resolveColumnName)(meta, field);
+    if (column)
+        return column;
+    // A relation named in a projection is a habit, not a typo, so it gets its own
+    // message pointing at `with`. Checked BEFORE the generic throw because the
+    // generic one degrades into "Did you mean <exactly what you typed>?".
+    if ((0, utils_js_1.ownLookup)(meta.relations, field))
+        throw new errors_js_1.ValidationError((0, utils_js_1.relationInProjectionMessage)(table, field, clause));
+    throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(table, field, meta));
+}
+/**
+ * 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
+ * projection", i.e. all columns, which keeps the `*` fast path.
+ *
+ * ## Why this is one function
+ *
+ * It used to be two, `resolveColumns` for the top level and
+ * `resolveTargetColumns` for a relation target, doing the same job against
+ * different metadata. They drifted, and the drift was invisible from either
+ * side: the top level resolved every name through a throwing lookup, while the
+ * relation side filtered unresolvable names out and emitted SQL for whatever
+ * survived. So the SAME key in the SAME query threw at the top and was silently
+ * ignored one level down, where `select: { titel: true }` returned `{}` rows
+ * and `omit: { titel: true }` returned the column it was asked to hide.
+ *
+ * It was worse than an inconsistency between depths. The batched loader runs
+ * each relation as a real query against the target table, so it went through
+ * the THROWING path, while the join plan went through the silent one. The two
+ * strategies therefore disagreed about whether the query was even valid, and
+ * under `relationLoadStrategy: 'auto'` which one runs is decided by a cost
+ * heuristic reading index coverage and table size. The same code threw on one
+ * table and quietly returned the wrong shape on another.
+ *
+ * Merging them is the fix that outlives this bug. Two functions that must agree
+ * are kept in step by whoever remembers; one function cannot disagree with
+ * itself. This mirrors `walkWhere` in where-compile.ts, which exists for the
+ * same reason after the top-level and relation-scoped WHERE walkers drifted
+ * twice, and it is why a new projection site is safe by default: PII exclusion,
+ * the `*` fast path and name resolution all live here, so reimplementing the
+ * name handling would mean reimplementing those too.
+ */
+function resolveProjection(qi, table, meta, select, omit, includePii) {
     if (select) {
         // An array here means a caller wrote `select: ['id', 'name']` (Drizzle/SQL
         // style) instead of the object shape. Object.entries() would iterate the
@@ -117,12 +166,12 @@ function resolveColumns(qi, select, omit, includePii) {
         // PII column IS the opt-in: it comes back regardless of `includePii`.
         return Object.entries(select)
             .filter(([, v]) => v)
-            .map(([k]) => qi.toColumn(k));
+            .map(([k]) => projectionColumn(table, meta, k, 'select'));
     }
     // Default / omit-only projection: PII-tagged columns are excluded unless the
     // caller opted in with `includePii: UNSAFE`. An empty set (untagged schema) keeps the
     // `null`/`*` fast path so the emitted SQL is byte-identical to before.
-    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, qi.tableMeta);
+    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, meta);
     const hasPii = piiCols !== undefined && piiCols.size > 0;
     if (omit) {
         if (Array.isArray(omit)) {
@@ -131,14 +180,21 @@ function resolveColumns(qi, select, omit, includePii) {
         // Include all columns except those where value is true (and PII columns).
         const omitCols = new Set(Object.entries(omit)
             .filter(([, v]) => v)
-            .map(([k]) => qi.toColumn(k)));
-        return qi.tableMeta.allColumns.filter((col) => !omitCols.has(col) && !(hasPii && piiCols.has(col)));
+            .map(([k]) => projectionColumn(table, meta, k, 'omit')));
+        return meta.allColumns.filter((col) => !omitCols.has(col) && !(hasPii && piiCols.has(col)));
     }
     if (hasPii) {
-        return qi.tableMeta.allColumns.filter((col) => !piiCols.has(col));
+        return meta.allColumns.filter((col) => !piiCols.has(col));
     }
     return null;
 }
+/**
+ * The query's own table. Thin wrapper over {@link resolveProjection} kept for
+ * the existing call sites in builder.ts.
+ */
+function resolveColumns(qi, select, omit, includePii) {
+    return resolveProjection(qi, qi.table, qi.tableMeta, select, omit, includePii);
+}
 /**
  * Produce a fingerprint for a `with` clause tree. Recursion mirrors
  * buildSelectWithRelations / buildRelationSubquery.
@@ -1210,30 +1266,17 @@ function parseNestedRow(qi, row, table, fromJson = false) {
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
  * {@link buildRelationShape} (decode key order) so they can never diverge.
+ *
+ * A relation always projects SOMETHING, so the `null` that
+ * {@link resolveProjection} uses for the top level's `SELECT *` fast path
+ * becomes the target's full column list here. That is the only difference
+ * between the two, and it is why this is a four-line wrapper rather than a
+ * second implementation.
  */
-function resolveTargetColumns(qi, spec, targetMeta, includePii) {
-    if (spec !== true && spec.select) {
-        // Explicit `select` names the columns: a PII column named here IS the
-        // opt-in and comes back regardless of the query's `includePii`.
-        const selectedFields = Object.entries(spec.select)
-            .filter(([, v]) => v)
-            .map(([k]) => (0, utils_js_1.ownLookup)(targetMeta.columnMap, k) ?? (0, schema_js_1.camelToSnake)(k));
-        return selectedFields.filter((col) => targetMeta.allColumns.includes(col));
-    }
-    // Default / omit-only relation projection: PII columns are excluded unless
-    // the query opted in via `includePii`.
-    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, targetMeta);
-    const hasPii = piiCols !== undefined && piiCols.size > 0;
-    if (spec !== true && spec.omit) {
-        const omittedFields = new Set(Object.entries(spec.omit)
-            .filter(([, v]) => v)
-            .map(([k]) => (0, utils_js_1.ownLookup)(targetMeta.columnMap, k) ?? (0, schema_js_1.camelToSnake)(k)));
-        return targetMeta.allColumns.filter((col) => !omittedFields.has(col) && !(hasPii && piiCols.has(col)));
-    }
-    if (hasPii) {
-        return targetMeta.allColumns.filter((col) => !piiCols.has(col));
-    }
-    return targetMeta.allColumns;
+function resolveTargetColumns(qi, spec, targetMeta, includePii, targetTable = targetMeta.name) {
+    const select = spec === true ? undefined : spec.select;
+    const omit = spec === true ? undefined : spec.omit;
+    return resolveProjection(qi, targetTable, targetMeta, select, omit, includePii) ?? targetMeta.allColumns;
 }
 /**
  * Render a single relation row's JSON: a keyed object (`'object'`) or a
@@ -1384,7 +1427,7 @@ function buildRelationShape(qi, relDef, spec, parentMeta, includePii) {
     const targetMeta = qi.schema.tables[relDef.to];
     if (!targetMeta)
         return { keys: [], nested: {}, cardinality: 'many' };
-    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     const keys = targetColumns.map((col) => targetMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col));
     const nested = {};
     if (spec !== true && spec.with) {
@@ -1642,7 +1685,7 @@ function planFlattenNode(qi, counter, relName, relDef, spec, depth, path, includ
         }
     }
     const alias = `${FLATTEN_ALIAS_PREFIX}${counter.n++}`;
-    const cols = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const cols = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     const discAlias = `${alias}__${FLATTEN_DISCRIMINATOR}`;
     const node = {
         relName,
@@ -2212,7 +2255,7 @@ function buildRelationSubquery(qi, relDef, spec, params, parentRef, aliasCounter
     // `includePii` opt-in). Shared with the positional-shape builder so the
     // emitted json_build_array column order and the decode-side key order can
     // never drift apart.
-    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     // Engine override seam (additive): a dialect whose JSON-aggregation shape does
     // not map onto buildJsonObject/buildJsonArrayAgg (SQL Server FOR JSON PATH) owns
     // the WHOLE subquery. Absent for PG/MySQL/SQLite → the native path below runs

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

@@ -451,3 +451,19 @@ export declare function unknownFieldMessage(table: string, field: string, meta:
     columnMap: Record<string, string>;
     relations?: Record<string, unknown>;
 }): string;
+/**
+ * The error text for a RELATION named inside `select` / `omit`.
+ *
+ * Separate from {@link unknownFieldMessage} because the generic text degrades
+ * into nonsense here: `closestName` matches an exactly-spelled relation name at
+ * distance zero, so the message would read `Unknown field "comments". Did you
+ * mean "comments" (a relation)?`, which answers a question nobody asked and
+ * hides the actual fix.
+ *
+ * It is worth its own message for a second reason: this is not really a typo,
+ * it is a habit. Prisma nests a relation inside `select`, so writing
+ * `select: { comments: true }` is the natural first guess, and in Turbine a
+ * relation is loaded by `with`, which sits BESIDE `select` rather than inside
+ * it. Naming the fix costs one sentence and saves a search.
+ */
+export declare function relationInProjectionMessage(table: string, field: string, clause: 'select' | 'omit'): string;

package/dist/cjs/query/utils.js

@@ -36,6 +36,7 @@ exports.coerceJsonWireValue = coerceJsonWireValue;
 exports.closestName = closestName;
 exports.suggestKey = suggestKey;
 exports.unknownFieldMessage = unknownFieldMessage;
+exports.relationInProjectionMessage = relationInProjectionMessage;
 const pg_1 = __importDefault(require("pg"));
 const schema_js_1 = require("../schema.js");
 const warn_registry_js_1 = require("./warn-registry.js");
@@ -886,3 +887,27 @@ function unknownFieldMessage(table, field, meta) {
         ` Known columns: ${columns.join(', ') || '(none)'}.` +
         (relations.length ? ` Known relations (valid in \`where\` and \`with\`): ${relations.join(', ')}.` : ''));
 }
+/**
+ * The error text for a RELATION named inside `select` / `omit`.
+ *
+ * Separate from {@link unknownFieldMessage} because the generic text degrades
+ * into nonsense here: `closestName` matches an exactly-spelled relation name at
+ * distance zero, so the message would read `Unknown field "comments". Did you
+ * mean "comments" (a relation)?`, which answers a question nobody asked and
+ * hides the actual fix.
+ *
+ * It is worth its own message for a second reason: this is not really a typo,
+ * it is a habit. Prisma nests a relation inside `select`, so writing
+ * `select: { comments: true }` is the natural first guess, and in Turbine a
+ * relation is loaded by `with`, which sits BESIDE `select` rather than inside
+ * it. Naming the fix costs one sentence and saves a search.
+ */
+function relationInProjectionMessage(table, field, clause) {
+    const head = `[turbine] "${field}" is a relation on table "${table}", not a column, so it cannot be named in \`${clause}\`.`;
+    return clause === 'select'
+        ? `${head} Load it with \`with: { ${field}: true }\`, which is a sibling of \`select\`, not a member of it.` +
+            " To narrow the relation's own columns, put a `select` inside that relation's options:" +
+            ` \`with: { ${field}: { select: { … } } }\`.`
+        : `${head} A relation is only present when you ask for it in \`with\`, so leave it out of \`with\` to leave it` +
+            ' out of the result.';
+}

package/dist/cjs/query/writes.js

@@ -706,8 +706,25 @@ function buildDeleteMany(qi, args) {
  */
 function piiColumns(_qi, meta) {
     const out = new Set();
+    const pk = new Set(meta.primaryKey);
     for (const col of meta.columns) {
-        if (col.pii)
+        // A PII-tagged PRIMARY KEY column is NEVER stripped. The exemption lives
+        // here, in the helper every projection reads, rather than at the call
+        // sites: it was written once at the write site (`|| pk.has(col)`) and no
+        // read path had it, so a table whose PK member is tagged returned rows
+        // that could not address themselves. Round-tripping such a row into an
+        // update produced a PARTIAL predicate (the missing PK member is
+        // `undefined`, which the where compiler drops, and the empty-where guard
+        // does not fire because the OTHER member is present), so `update` silently
+        // rewrote every row sharing the remaining key instead of one. Measured on
+        // a composite `(org_id, email)` PK: three rows changed where one was
+        // asked for, no error.
+        //
+        // The policy this implements is the one already stated on
+        // {@link writeReturningColumns}: tag sensitive data, not keys; a PII PK is
+        // out of scope for stripping because the returned row must stay
+        // addressable. Only the enforcement was missing.
+        if (col.pii && !pk.has(col.name))
             out.add(col.name);
     }
     return out;
@@ -721,8 +738,14 @@ function piiColumns(_qi, meta) {
  */
 function piiFields(_qi, meta) {
     const out = [];
+    const pk = new Set(meta.primaryKey);
+    // Same PK exemption as {@link piiColumns}, and it MATTERS here rather than
+    // being belt-and-braces: this strip runs on an already-fetched row, so
+    // without it the SQL kept the PK addressable and this deleted it again,
+    // which is the exact contradiction between this function's own "no-op"
+    // docstring and writeReturningColumns' "must stay addressable".
     for (const col of meta.columns) {
-        if (col.pii)
+        if (col.pii && !pk.has(col.name))
             out.push(col.field);
     }
     return out;
@@ -794,11 +817,12 @@ function namedColumns(meta, data) {
     return out;
 }
 function writeReturningColumns(qi) {
+    // The PK exemption used to be re-stated here as `|| pk.has(col)`. It now
+    // lives in `piiColumns` so every projection inherits it and none can drift.
     const piiCols = piiColumns(qi, qi.tableMeta);
     if (piiCols.size === 0)
         return '*';
-    const pk = new Set(qi.tableMeta.primaryKey);
-    return qi.tableMeta.allColumns.filter((col) => !piiCols.has(col) || pk.has(col)).map((col) => qi.q(col));
+    return qi.tableMeta.allColumns.filter((col) => !piiCols.has(col)).map((col) => qi.q(col));
 }
 /**
  * String form of {@link writeReturningColumns} for a `SELECT` list (the

package/dist/nested-write.js

@@ -229,6 +229,18 @@ function pkWhere(tableMeta, row) {
     const where = {};
     for (const col of tableMeta.primaryKey) {
         const field = tableMeta.reverseColumnMap[col] ?? col;
+        // A PARTIAL primary key here is not a filter, it is a mass mutation.
+        // `undefined` values are dropped when the where compiles, and the
+        // empty-where guard only fires when NOTHING survives, so a composite PK
+        // missing one member compiles to a predicate on the remaining member and
+        // the statement rewrites every row that shares it. The row is supposed to
+        // be one this engine just read, so a missing member is an internal fault,
+        // and the only safe response is to refuse rather than to run.
+        if (row[field] === undefined) {
+            throw new ValidationError(`[turbine] Cannot address a row of "${tableMeta.name}" by primary key: "${field}" is missing from the ` +
+                'row this nested write is operating on, so the generated predicate would match more rows than intended. ' +
+                'This is a bug in turbine, please report it.');
+        }
         where[field] = row[field];
     }
     return where;

package/dist/powql.d.ts

@@ -307,6 +307,15 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
      * and returns it regardless. Untagged tables project exactly as before.
      */
+    /**
+     * Resolve one projection field name, or throw. PowQL already refused an
+     * unresolvable name here (via {@link column}), unlike the SQL engines' join
+     * path, which filtered it out silently until 0.64. What this adds is the
+     * RELATION case: naming a relation inside `select` is a Prisma habit rather
+     * than a typo, and the generic "unknown column" text sends the reader looking
+     * for a misspelling that is not there. Same message as the SQL engines.
+     */
+    private projectionColumn;
     private projectedColumns;
     /**
      * The snake_case names of this table's PII-tagged columns. Empty for a table

package/dist/powql.js

@@ -45,7 +45,7 @@ import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/fil
 // are unlocked ONLY by the UNSAFE symbol, on this engine exactly as on the SQL
 // engines, so a spread request body cannot turn either on here either.
 import { assertDirectionToken, resolveUnsafeFlag, UNSAFE } from './query/types.js';
-import { escapeLike } from './query/utils.js';
+import { escapeLike, ownLookup, relationInProjectionMessage } from './query/utils.js';
 import { assertJsonFilterKeys, jsonStringEntries } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -872,31 +872,56 @@ export class PowqlInterface {
      * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
      * and returns it regardless. Untagged tables project exactly as before.
      */
+    /**
+     * Resolve one projection field name, or throw. PowQL already refused an
+     * unresolvable name here (via {@link column}), unlike the SQL engines' join
+     * path, which filtered it out silently until 0.64. What this adds is the
+     * RELATION case: naming a relation inside `select` is a Prisma habit rather
+     * than a typo, and the generic "unknown column" text sends the reader looking
+     * for a misspelling that is not there. Same message as the SQL engines.
+     */
+    projectionColumn(field, clause) {
+        if (ownLookup(this.meta.relations, field)) {
+            throw new ValidationError(relationInProjectionMessage(this.table, field, clause));
+        }
+        return this.column(field).name;
+    }
     projectedColumns(select, omit, includePii) {
+        const pk = new Set(this.meta.primaryKey);
         let cols = this.meta.columns.map((c) => c.name);
         const hasSelect = select && Object.keys(select).length;
         if (hasSelect) {
             const picked = new Set(Object.entries(select)
                 .filter(([, v]) => v)
-                .map(([k]) => this.column(k).name));
+                .map(([k]) => this.projectionColumn(k, 'select')));
             // Always keep the PK so reselect / relation stitching has a key to work with.
-            for (const pk of this.meta.primaryKey)
-                picked.add(pk);
+            for (const key of pk)
+                picked.add(key);
             cols = cols.filter((c) => picked.has(c));
         }
         else if (!includePii) {
             // Default / omit-only projection: drop PII columns (kept above only when a
-            // caller names them in `select`). PK is never PII in practice; if one is
-            // tagged it is still dropped here, so tag sensitive data, not keys.
+            // caller names them in `select`), EXCEPT a PK column. This used to drop a
+            // tagged PK, on the reasoning that keys should not be tagged in the first
+            // place. That is good advice and a bad guarantee: the row it returns
+            // cannot address itself, so writing it back builds a partial predicate
+            // and mutates every row sharing the rest of the key. Same rule and same
+            // reason as `piiColumns` on the SQL engines.
             const pii = this.piiColumnNames();
             if (pii.size)
-                cols = cols.filter((c) => !pii.has(c));
+                cols = cols.filter((c) => !pii.has(c) || pk.has(c));
         }
         if (omit && Object.keys(omit).length) {
             const dropped = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
-                .map(([k]) => this.column(k).name));
-            cols = cols.filter((c) => !dropped.has(c));
+                .map(([k]) => this.projectionColumn(k, 'omit')));
+            // The PK survives `omit` too. This filter ran unconditionally and after
+            // the `select` branch's force-add, so `omit: { id: true }` undid the very
+            // guarantee that force-add exists to provide: the m2m loader keys its
+            // target map on the PK (`targetByPk`), so every target collapsed onto the
+            // single bucket "undefined", no parent matched, and the relation came
+            // back `[]` for every row with no error.
+            cols = cols.filter((c) => !dropped.has(c) || pk.has(c));
         }
         return cols;
     }

package/dist/query/batched-loader.js

@@ -295,6 +295,30 @@ export async function loadRelationsBatched(ctx, parents, withClause, timeout, de
     // A falsy `_count` opts out, exactly like a falsy relation spec.
     const countSpec = withClause._count;
     const hasCount = Boolean(countSpec);
+    // NESTED `_count` is refused here so the two strategies answer alike.
+    //
+    // The join builder emits `_count` only for the TOP-LEVEL `with`; one level
+    // down, `buildRelationSubquery` looks `_count` up as an ordinary relation
+    // name, misses, and throws E005. This loader handled it at every depth, so
+    // one query with one set of args either threw or returned populated counts
+    // depending purely on which plan ran, and under the `'auto'` default that
+    // choice is made by a cost heuristic reading index coverage and table size.
+    // The same code therefore worked on a small table and threw on a large one.
+    //
+    // That is the same non-determinism as the correlation-key bug this module was
+    // just fixed for, only louder, so it is closed the same way: by agreement.
+    // Refusing is the direction that is a no-op for anyone on the default, since
+    // there the shape already fails whenever the relation is NOT demoted. Nested
+    // `_count` is a real feature (Prisma has it) and teaching the join path is
+    // the right end state, but that means the four json_build_object emission
+    // sites, the positional encoding, SQL Server's FOR JSON override and PowDB's
+    // nested projections all learning it together, which is a feature release,
+    // not a line in a correctness fix. Until then both strategies say no.
+    if (hasCount && depth > 0) {
+        throw new RelationError(`[turbine] Unknown relation "_count" on table "${ctx.parentMeta.name}". ` +
+            `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}. ` +
+            '(`_count` is supported on the top-level `with` only, on every relationLoadStrategy.)');
+    }
     // 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.
@@ -386,6 +410,7 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
     const parentKeyField = ctx.parentMeta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
     const childKeyField = targetMeta.reverseColumnMap[childKeyCol] ?? childKeyCol;
+    assertCorrelationKeyProjected(parents, parentKeyField, relName, ctx.parentMeta.name);
     const keys = uniqueKeys(parents, parentKeyField);
     const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
     if (keys.length === 0) {
@@ -395,7 +420,16 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     }
     // The follow-up must project the child correlation key even if the caller's
     // select/omit excluded it; strip it back off afterwards so the shape matches join.
-    const proj = includeKeysForBatching(options.select, options.omit, [childKeyField], defaultProjectionFields(targetMeta, ctx.includePii));
+    //
+    // AND the keys the child's OWN nested relations will correlate on. Passing
+    // only `childKeyField` here was the whole of the silent-null bug: this level
+    // stitched fine, then the recursion below asked the children for a key that
+    // this projection had just dropped. The root call sites in builder.ts have
+    // always resolved the full set through `neededParentKeyFields`; these nested
+    // ones did not, so the defect needed a `select` (or an `omit` of the FK) on a
+    // to-many with a to-one inside it, which is why `include` and `join` were both
+    // clean and seventeen rounds of parity capture missed it.
+    const proj = includeKeysForBatching(options.select, options.omit, [childKeyField, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
     const chunks = [];
     for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS)
@@ -421,6 +455,12 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     if (options.with && allChildren.length > 0) {
         await loadRelationsBatched({ ...ctx, parentMeta: targetMeta }, allChildren, options.with, timeout, depth + 1, [...path, relName]);
     }
+    // Symmetric to the parent-side assertion above. If the CHILD key were ever
+    // missing, `groupBy` would bucket every child under the string "undefined",
+    // no parent would match, and the relation would come back empty just as
+    // silently. `includeKeysForBatching` makes that unreachable, which is exactly
+    // what was true of the parent side until this week.
+    assertCorrelationKeyProjected(allChildren, childKeyField, relName, targetMeta.name);
     const byKey = groupBy(allChildren, childKeyField);
     const limit = options.limit;
     for (const parent of parents) {
@@ -459,6 +499,7 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
     const targetPkCol = targetMeta.primaryKey[0];
     const parentRefField = ctx.parentMeta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
     const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
+    assertCorrelationKeyProjected(parents, parentRefField, relName, ctx.parentMeta.name);
     const parentKeys = uniqueKeys(parents, parentRefField);
     if (parentKeys.length === 0) {
         for (const parent of parents)
@@ -497,7 +538,10 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
         }
     }
     // (2) Target rows by PK, honouring the relation's own where/select/omit/orderBy.
-    const proj = includeKeysForBatching(options.select, options.omit, [targetPkField], defaultProjectionFields(targetMeta, ctx.includePii));
+    // Plus the keys the target's own nested relations need, same rule and same
+    // reason as the to-many loader above: this level's PK is not the only key the
+    // recursion below will ask these rows for.
+    const proj = includeKeysForBatching(options.select, options.omit, [targetPkField, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
     const targetVals = [...targetValSet];
     const tChunks = [];
@@ -679,6 +723,48 @@ function mergeChildWhere(where, keyField, chunk) {
         return { AND: [where, correlation] };
     return { ...where, ...correlation };
 }
+/**
+ * Refuse to stitch a relation whose correlation key was never projected.
+ *
+ * THE FAILURE THIS EXISTS TO REMOVE. `uniqueKeys` skips a row whose key is
+ * `null` OR `undefined`, and a column the projection left out is `undefined`
+ * for exactly the same reason it is for a genuinely null FK. So a loader that
+ * has lost its key cannot tell itself apart from a page of parents that
+ * legitimately point at nothing: both produce zero keys, and the empty-key
+ * branch hands back `null` / `[]` for every parent. That is a wrong answer with
+ * an HTTP 200 on it: a reporting endpoint summed a money column across the
+ * relation, every row of it read as absent, and the total came back 0 for a
+ * large fraction of a page. Nothing in the payload, the logs or the response
+ * status distinguished it from the right answer.
+ *
+ * The two states ARE distinguishable, just not by the value: a column that was
+ * not selected is ABSENT from the parsed entity (`'fk' in row === false`),
+ * while a selected column holding SQL NULL is PRESENT with the value `null`.
+ * Verified against a live database in both directions. So the discriminator is
+ * property presence (`Object.hasOwn`, not `in`: the rest of this file uses it,
+ * and a column named `constructor` or `toString` passes an `in` check on any
+ * plain object), and it is checked over ALL parents rather than the first:
+ * every row on one level shares one projection, so a field missing from every
+ * row is a projection fault, while a field missing from some rows is not a
+ * state this loader can produce at all.
+ *
+ * After {@link neededParentKeyFields} is applied at every nesting level this is
+ * an unreachable invariant, which is the point: if it ever fires it is a bug in
+ * Turbine, not in the caller's query, and the caller gets told so along with the
+ * one-line workaround. E017 with the same remedy as the composite-key refusal a
+ * few lines up, deliberately: to the caller both are "this strategy cannot serve
+ * this shape, use 'join'", and inventing a code for an unreachable state would
+ * be a new public error nobody can trigger.
+ */
+function assertCorrelationKeyProjected(parents, field, relName, parentTable) {
+    if (parents.length === 0)
+        return;
+    if (parents.some((parent) => Object.hasOwn(parent, field)))
+        return;
+    throw new UnsupportedFeatureError(`batched loading of relation "${relName}" on "${parentTable}"`, 'relationLoadStrategy: "batched"', `the correlation key "${field}" is missing from every parent row, so the relation cannot be stitched and ` +
+        'would silently come back empty. This is a bug in turbine, please report it. ' +
+        `Workaround: pass \`relationLoadStrategy: 'join'\` on this query.`);
+}
 /** Distinct, non-null values of `field` across `rows`. */
 function uniqueKeys(rows, field) {
     const seen = new Set();

package/dist/query/relations.d.ts

@@ -34,8 +34,41 @@ export interface RelationShape {
     cardinality: 'many' | 'one';
 }
 /**
- * Resolve select/omit options into a list of snake_case column names.
- * Returns null if neither is provided (meaning all columns).
+ * 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
+ * projection", i.e. all columns, which keeps the `*` fast path.
+ *
+ * ## Why this is one function
+ *
+ * It used to be two, `resolveColumns` for the top level and
+ * `resolveTargetColumns` for a relation target, doing the same job against
+ * different metadata. They drifted, and the drift was invisible from either
+ * side: the top level resolved every name through a throwing lookup, while the
+ * relation side filtered unresolvable names out and emitted SQL for whatever
+ * survived. So the SAME key in the SAME query threw at the top and was silently
+ * ignored one level down, where `select: { titel: true }` returned `{}` rows
+ * and `omit: { titel: true }` returned the column it was asked to hide.
+ *
+ * It was worse than an inconsistency between depths. The batched loader runs
+ * each relation as a real query against the target table, so it went through
+ * the THROWING path, while the join plan went through the silent one. The two
+ * strategies therefore disagreed about whether the query was even valid, and
+ * under `relationLoadStrategy: 'auto'` which one runs is decided by a cost
+ * heuristic reading index coverage and table size. The same code threw on one
+ * table and quietly returned the wrong shape on another.
+ *
+ * Merging them is the fix that outlives this bug. Two functions that must agree
+ * are kept in step by whoever remembers; one function cannot disagree with
+ * itself. This mirrors `walkWhere` in where-compile.ts, which exists for the
+ * same reason after the top-level and relation-scoped WHERE walkers drifted
+ * twice, and it is why a new projection site is safe by default: PII exclusion,
+ * the `*` fast path and name resolution all live here, so reimplementing the
+ * name handling would mean reimplementing those too.
+ */
+export declare function resolveProjection(qi: BuilderCtx, table: string, meta: TableMetadata, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
+/**
+ * The query's own table. Thin wrapper over {@link resolveProjection} kept for
+ * the existing call sites in builder.ts.
  */
 export declare function resolveColumns(qi: BuilderCtx, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
 /**
@@ -254,8 +287,14 @@ export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unkno
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
  * {@link buildRelationShape} (decode key order) so they can never diverge.
+ *
+ * A relation always projects SOMETHING, so the `null` that
+ * {@link resolveProjection} uses for the top level's `SELECT *` fast path
+ * becomes the target's full column list here. That is the only difference
+ * between the two, and it is why this is a four-line wrapper rather than a
+ * second implementation.
  */
-export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean): string[];
+export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean, targetTable?: string): string[];
 /**
  * Render a single relation row's JSON: a keyed object (`'object'`) or a
  * positional array (`'positional'`). The array drops the keys but keeps the

package/dist/query/relations.js

@@ -18,15 +18,63 @@ import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { resolveCountRelations } from './batched-loader.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
 import { assertDirectionToken, assertOrderDirection } from './types.js';
-import { ownLookup } from './utils.js';
+import { ownLookup, relationInProjectionMessage, resolveColumnName, 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';
 /**
- * Resolve select/omit options into a list of snake_case column names.
- * Returns null if neither is provided (meaning all columns).
+ * Turn ONE caller-supplied projection field name into a column, or throw.
+ *
+ * The whole point of this function is that it has no third outcome. The
+ * relation-side projection used to filter unresolvable names out
+ * (`.filter((col) => allColumns.includes(col))`) instead of rejecting them, and
+ * a filter that discards is exactly how a name typed by a human becomes SQL
+ * that no longer reflects what was asked for.
  */
-export function resolveColumns(qi, select, omit, includePii) {
+function projectionColumn(table, meta, field, clause) {
+    const column = resolveColumnName(meta, field);
+    if (column)
+        return column;
+    // A relation named in a projection is a habit, not a typo, so it gets its own
+    // message pointing at `with`. Checked BEFORE the generic throw because the
+    // generic one degrades into "Did you mean <exactly what you typed>?".
+    if (ownLookup(meta.relations, field))
+        throw new ValidationError(relationInProjectionMessage(table, field, clause));
+    throw new ValidationError(unknownFieldMessage(table, field, meta));
+}
+/**
+ * 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
+ * projection", i.e. all columns, which keeps the `*` fast path.
+ *
+ * ## Why this is one function
+ *
+ * It used to be two, `resolveColumns` for the top level and
+ * `resolveTargetColumns` for a relation target, doing the same job against
+ * different metadata. They drifted, and the drift was invisible from either
+ * side: the top level resolved every name through a throwing lookup, while the
+ * relation side filtered unresolvable names out and emitted SQL for whatever
+ * survived. So the SAME key in the SAME query threw at the top and was silently
+ * ignored one level down, where `select: { titel: true }` returned `{}` rows
+ * and `omit: { titel: true }` returned the column it was asked to hide.
+ *
+ * It was worse than an inconsistency between depths. The batched loader runs
+ * each relation as a real query against the target table, so it went through
+ * the THROWING path, while the join plan went through the silent one. The two
+ * strategies therefore disagreed about whether the query was even valid, and
+ * under `relationLoadStrategy: 'auto'` which one runs is decided by a cost
+ * heuristic reading index coverage and table size. The same code threw on one
+ * table and quietly returned the wrong shape on another.
+ *
+ * Merging them is the fix that outlives this bug. Two functions that must agree
+ * are kept in step by whoever remembers; one function cannot disagree with
+ * itself. This mirrors `walkWhere` in where-compile.ts, which exists for the
+ * same reason after the top-level and relation-scoped WHERE walkers drifted
+ * twice, and it is why a new projection site is safe by default: PII exclusion,
+ * the `*` fast path and name resolution all live here, so reimplementing the
+ * name handling would mean reimplementing those too.
+ */
+export function resolveProjection(qi, table, meta, select, omit, includePii) {
     if (select) {
         // An array here means a caller wrote `select: ['id', 'name']` (Drizzle/SQL
         // style) instead of the object shape. Object.entries() would iterate the
@@ -40,12 +88,12 @@ export function resolveColumns(qi, select, omit, includePii) {
         // PII column IS the opt-in: it comes back regardless of `includePii`.
         return Object.entries(select)
             .filter(([, v]) => v)
-            .map(([k]) => qi.toColumn(k));
+            .map(([k]) => projectionColumn(table, meta, k, 'select'));
     }
     // Default / omit-only projection: PII-tagged columns are excluded unless the
     // caller opted in with `includePii: UNSAFE`. An empty set (untagged schema) keeps the
     // `null`/`*` fast path so the emitted SQL is byte-identical to before.
-    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, qi.tableMeta);
+    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, meta);
     const hasPii = piiCols !== undefined && piiCols.size > 0;
     if (omit) {
         if (Array.isArray(omit)) {
@@ -54,14 +102,21 @@ export function resolveColumns(qi, select, omit, includePii) {
         // Include all columns except those where value is true (and PII columns).
         const omitCols = new Set(Object.entries(omit)
             .filter(([, v]) => v)
-            .map(([k]) => qi.toColumn(k)));
-        return qi.tableMeta.allColumns.filter((col) => !omitCols.has(col) && !(hasPii && piiCols.has(col)));
+            .map(([k]) => projectionColumn(table, meta, k, 'omit')));
+        return meta.allColumns.filter((col) => !omitCols.has(col) && !(hasPii && piiCols.has(col)));
     }
     if (hasPii) {
-        return qi.tableMeta.allColumns.filter((col) => !piiCols.has(col));
+        return meta.allColumns.filter((col) => !piiCols.has(col));
     }
     return null;
 }
+/**
+ * The query's own table. Thin wrapper over {@link resolveProjection} kept for
+ * the existing call sites in builder.ts.
+ */
+export function resolveColumns(qi, select, omit, includePii) {
+    return resolveProjection(qi, qi.table, qi.tableMeta, select, omit, includePii);
+}
 /**
  * Produce a fingerprint for a `with` clause tree. Recursion mirrors
  * buildSelectWithRelations / buildRelationSubquery.
@@ -1133,30 +1188,17 @@ export function parseNestedRow(qi, row, table, fromJson = false) {
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
  * {@link buildRelationShape} (decode key order) so they can never diverge.
+ *
+ * A relation always projects SOMETHING, so the `null` that
+ * {@link resolveProjection} uses for the top level's `SELECT *` fast path
+ * becomes the target's full column list here. That is the only difference
+ * between the two, and it is why this is a four-line wrapper rather than a
+ * second implementation.
  */
-export function resolveTargetColumns(qi, spec, targetMeta, includePii) {
-    if (spec !== true && spec.select) {
-        // Explicit `select` names the columns: a PII column named here IS the
-        // opt-in and comes back regardless of the query's `includePii`.
-        const selectedFields = Object.entries(spec.select)
-            .filter(([, v]) => v)
-            .map(([k]) => ownLookup(targetMeta.columnMap, k) ?? camelToSnake(k));
-        return selectedFields.filter((col) => targetMeta.allColumns.includes(col));
-    }
-    // Default / omit-only relation projection: PII columns are excluded unless
-    // the query opted in via `includePii`.
-    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, targetMeta);
-    const hasPii = piiCols !== undefined && piiCols.size > 0;
-    if (spec !== true && spec.omit) {
-        const omittedFields = new Set(Object.entries(spec.omit)
-            .filter(([, v]) => v)
-            .map(([k]) => ownLookup(targetMeta.columnMap, k) ?? camelToSnake(k)));
-        return targetMeta.allColumns.filter((col) => !omittedFields.has(col) && !(hasPii && piiCols.has(col)));
-    }
-    if (hasPii) {
-        return targetMeta.allColumns.filter((col) => !piiCols.has(col));
-    }
-    return targetMeta.allColumns;
+export function resolveTargetColumns(qi, spec, targetMeta, includePii, targetTable = targetMeta.name) {
+    const select = spec === true ? undefined : spec.select;
+    const omit = spec === true ? undefined : spec.omit;
+    return resolveProjection(qi, targetTable, targetMeta, select, omit, includePii) ?? targetMeta.allColumns;
 }
 /**
  * Render a single relation row's JSON: a keyed object (`'object'`) or a
@@ -1307,7 +1349,7 @@ export function buildRelationShape(qi, relDef, spec, parentMeta, includePii) {
     const targetMeta = qi.schema.tables[relDef.to];
     if (!targetMeta)
         return { keys: [], nested: {}, cardinality: 'many' };
-    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     const keys = targetColumns.map((col) => targetMeta.reverseColumnMap[col] ?? snakeToCamel(col));
     const nested = {};
     if (spec !== true && spec.with) {
@@ -1565,7 +1607,7 @@ function planFlattenNode(qi, counter, relName, relDef, spec, depth, path, includ
         }
     }
     const alias = `${FLATTEN_ALIAS_PREFIX}${counter.n++}`;
-    const cols = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const cols = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     const discAlias = `${alias}__${FLATTEN_DISCRIMINATOR}`;
     const node = {
         relName,
@@ -2135,7 +2177,7 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // `includePii` opt-in). Shared with the positional-shape builder so the
     // emitted json_build_array column order and the decode-side key order can
     // never drift apart.
-    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     // Engine override seam (additive): a dialect whose JSON-aggregation shape does
     // not map onto buildJsonObject/buildJsonArrayAgg (SQL Server FOR JSON PATH) owns
     // the WHOLE subquery. Absent for PG/MySQL/SQLite → the native path below runs

package/dist/query/utils.d.ts

@@ -451,3 +451,19 @@ export declare function unknownFieldMessage(table: string, field: string, meta:
     columnMap: Record<string, string>;
     relations?: Record<string, unknown>;
 }): string;
+/**
+ * The error text for a RELATION named inside `select` / `omit`.
+ *
+ * Separate from {@link unknownFieldMessage} because the generic text degrades
+ * into nonsense here: `closestName` matches an exactly-spelled relation name at
+ * distance zero, so the message would read `Unknown field "comments". Did you
+ * mean "comments" (a relation)?`, which answers a question nobody asked and
+ * hides the actual fix.
+ *
+ * It is worth its own message for a second reason: this is not really a typo,
+ * it is a habit. Prisma nests a relation inside `select`, so writing
+ * `select: { comments: true }` is the natural first guess, and in Turbine a
+ * relation is loaded by `with`, which sits BESIDE `select` rather than inside
+ * it. Naming the fix costs one sentence and saves a search.
+ */
+export declare function relationInProjectionMessage(table: string, field: string, clause: 'select' | 'omit'): string;

package/dist/query/utils.js

@@ -852,3 +852,27 @@ export function unknownFieldMessage(table, field, meta) {
         ` Known columns: ${columns.join(', ') || '(none)'}.` +
         (relations.length ? ` Known relations (valid in \`where\` and \`with\`): ${relations.join(', ')}.` : ''));
 }
+/**
+ * The error text for a RELATION named inside `select` / `omit`.
+ *
+ * Separate from {@link unknownFieldMessage} because the generic text degrades
+ * into nonsense here: `closestName` matches an exactly-spelled relation name at
+ * distance zero, so the message would read `Unknown field "comments". Did you
+ * mean "comments" (a relation)?`, which answers a question nobody asked and
+ * hides the actual fix.
+ *
+ * It is worth its own message for a second reason: this is not really a typo,
+ * it is a habit. Prisma nests a relation inside `select`, so writing
+ * `select: { comments: true }` is the natural first guess, and in Turbine a
+ * relation is loaded by `with`, which sits BESIDE `select` rather than inside
+ * it. Naming the fix costs one sentence and saves a search.
+ */
+export function relationInProjectionMessage(table, field, clause) {
+    const head = `[turbine] "${field}" is a relation on table "${table}", not a column, so it cannot be named in \`${clause}\`.`;
+    return clause === 'select'
+        ? `${head} Load it with \`with: { ${field}: true }\`, which is a sibling of \`select\`, not a member of it.` +
+            " To narrow the relation's own columns, put a `select` inside that relation's options:" +
+            ` \`with: { ${field}: { select: { … } } }\`.`
+        : `${head} A relation is only present when you ask for it in \`with\`, so leave it out of \`with\` to leave it` +
+            ' out of the result.';
+}

package/dist/query/writes.js

@@ -649,8 +649,25 @@ export function buildDeleteMany(qi, args) {
  */
 export function piiColumns(_qi, meta) {
     const out = new Set();
+    const pk = new Set(meta.primaryKey);
     for (const col of meta.columns) {
-        if (col.pii)
+        // A PII-tagged PRIMARY KEY column is NEVER stripped. The exemption lives
+        // here, in the helper every projection reads, rather than at the call
+        // sites: it was written once at the write site (`|| pk.has(col)`) and no
+        // read path had it, so a table whose PK member is tagged returned rows
+        // that could not address themselves. Round-tripping such a row into an
+        // update produced a PARTIAL predicate (the missing PK member is
+        // `undefined`, which the where compiler drops, and the empty-where guard
+        // does not fire because the OTHER member is present), so `update` silently
+        // rewrote every row sharing the remaining key instead of one. Measured on
+        // a composite `(org_id, email)` PK: three rows changed where one was
+        // asked for, no error.
+        //
+        // The policy this implements is the one already stated on
+        // {@link writeReturningColumns}: tag sensitive data, not keys; a PII PK is
+        // out of scope for stripping because the returned row must stay
+        // addressable. Only the enforcement was missing.
+        if (col.pii && !pk.has(col.name))
             out.add(col.name);
     }
     return out;
@@ -664,8 +681,14 @@ export function piiColumns(_qi, meta) {
  */
 export function piiFields(_qi, meta) {
     const out = [];
+    const pk = new Set(meta.primaryKey);
+    // Same PK exemption as {@link piiColumns}, and it MATTERS here rather than
+    // being belt-and-braces: this strip runs on an already-fetched row, so
+    // without it the SQL kept the PK addressable and this deleted it again,
+    // which is the exact contradiction between this function's own "no-op"
+    // docstring and writeReturningColumns' "must stay addressable".
     for (const col of meta.columns) {
-        if (col.pii)
+        if (col.pii && !pk.has(col.name))
             out.push(col.field);
     }
     return out;
@@ -737,11 +760,12 @@ function namedColumns(meta, data) {
     return out;
 }
 export function writeReturningColumns(qi) {
+    // The PK exemption used to be re-stated here as `|| pk.has(col)`. It now
+    // lives in `piiColumns` so every projection inherits it and none can drift.
     const piiCols = piiColumns(qi, qi.tableMeta);
     if (piiCols.size === 0)
         return '*';
-    const pk = new Set(qi.tableMeta.primaryKey);
-    return qi.tableMeta.allColumns.filter((col) => !piiCols.has(col) || pk.has(col)).map((col) => qi.q(col));
+    return qi.tableMeta.allColumns.filter((col) => !piiCols.has(col)).map((col) => qi.q(col));
 }
 /**
  * String form of {@link writeReturningColumns} for a `SELECT` list (the

package/package.json

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