turbine-orm 0.62.1 → 0.63.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.js

@@ -909,6 +909,7 @@ class PowqlInterface {
      * and returns it regardless. Untagged tables project exactly as before.
      */
     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) {
@@ -916,23 +917,33 @@ class PowqlInterface {
                 .filter(([, v]) => v)
                 .map(([k]) => this.column(k).name));
             // 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));
+            // 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/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.js

@@ -873,6 +873,7 @@ export class PowqlInterface {
      * and returns it regardless. Untagged tables project exactly as before.
      */
     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) {
@@ -880,23 +881,33 @@ export class PowqlInterface {
                 .filter(([, v]) => v)
                 .map(([k]) => this.column(k).name));
             // 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));
+            // 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/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.63.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).",