turbine-orm 0.61.0 → 0.62.0

package/dist/cjs/prisma-compat.js

@@ -41,6 +41,11 @@
  *   by this layer, and a key that is neither a Prisma arg nor a turbine option
  *   gets a dev-mode warning instead of vanishing (see
  *   {@link PRISMA_ARG_KEYS} and `warnUnknownQueryOptions`).
+ *   The three PRIVILEGE options among them (`skipGlobalFilters`, `includePii`,
+ *   `allowFullTableScan`) are forwarded VERBATIM, which is what makes them safe
+ *   here: core accepts only the `UNSAFE` sentinel, so a Prisma-shaped args
+ *   object carrying `includePii: true` reaches core and is refused there, and
+ *   this layer never needs its own copy of that rule.
  *
  * ## What it deliberately does NOT do (documented divergences)
  *
@@ -76,11 +81,16 @@
  * - **`limit` on `updateMany` / `deleteMany`** (Prisma 6.7+) throws. Turbine has
  *   no row-bounded mass mutation, and dropping a SAFETY BOUND with a warning
  *   would turn "change at most 10 rows" into "change every matching row".
- * - **Write projections** (`select` / `include` / `omit` on
- *   create/update/delete/upsert), **`select` on `count`**, and
- *   **`orderBy` / `cursor` / `take` / `skip` on `aggregate`** are accepted and
- *   IGNORED (they are legitimate Prisma, so they never warn); the full row / a
- *   plain number comes back.
+ * - **Write projections**: `select` / `omit` on create/update/delete/upsert
+ *   narrow the RETURNED OBJECT (see {@link resolveWriteProjection}); they do
+ *   NOT narrow the statement's `RETURNING` list, so the column still crosses
+ *   the wire, and `pii: true` remains the SQL-level control. A relation key in
+ *   either (or any `include` on a write) THROWS, since a write returns its own
+ *   row only. `omit` on READS is translated to core's own `omit`, see
+ *   {@link translateOmit}.
+ * - **`select` on `count`** and **`orderBy` / `cursor` / `take` / `skip` on
+ *   `aggregate`** are accepted and IGNORED (they are legitimate Prisma, so they
+ *   never warn); a plain number / the aggregate comes back.
  *
  * ## Type dependencies (0.41.0)
  *
@@ -638,16 +648,53 @@ function mapTake(take) {
     return take;
 }
 /**
- * Translate Prisma `include` / `select` into Turbine `{ select, with }`.
- * `include` keeps all scalars and adds relations; `select` narrows scalars and
- * may also pull relations + `_count`. The two are mutually exclusive.
+ * Translate a Prisma `omit` (scalar field names → true) into Turbine's `omit`.
+ *
+ * This used to be DROPPED silently, which made it a data-exposure bug rather
+ * than an ergonomics one: `omit` is the idiom for a sensitive-but-untagged
+ * column (`passwordHash`, `resetToken`), so a caller who asked for it got the
+ * column back anyway, in a response they believed was already filtered. Turbine
+ * core has supported `omit` on reads all along; only this translation was
+ * missing.
+ *
+ * A relation name is refused rather than forwarded: core's `omit` narrows the
+ * SCALAR projection, so `omit: { posts: true }` would have compiled to nothing
+ * and dropped the caller's intent a second time. Prisma rejects it too.
+ */
+function translateOmit(ctx, mm, omit) {
+    const out = {};
+    let any = false;
+    for (const [key, val] of Object.entries(omit)) {
+        if (val === false || val == null)
+            continue;
+        if (mm.relations[key]) {
+            throw new errors_js_1.ValidationError(`[turbine] prisma-compat: \`omit\` on model "${modelName(ctx, mm)}" takes scalar fields, but "${key}" ` +
+                'is a relation. Leave the relation out of `include` instead.');
+        }
+        out[renameField(mm, key)] = true;
+        any = true;
+    }
+    return any ? out : undefined;
+}
+/**
+ * Translate Prisma `include` / `select` / `omit` into Turbine
+ * `{ select, omit, with }`. `include` keeps all scalars and adds relations;
+ * `select` narrows scalars and may also pull relations + `_count`. `include`
+ * and `select` are mutually exclusive, and so are `select` and `omit` (a
+ * narrowed projection minus fields is ambiguous; Prisma refuses the pair too).
  */
 function translateProjection(ctx, mm, args) {
     const include = args.include;
     const select = args.select;
+    const omitArg = args.omit;
     if (include && select) {
         throw new errors_js_1.ValidationError('[turbine] prisma-compat: `include` and `select` are mutually exclusive.');
     }
+    if (select && omitArg) {
+        throw new errors_js_1.ValidationError('[turbine] prisma-compat: `select` and `omit` are mutually exclusive. ' +
+            'A `select` already lists exactly the fields you want.');
+    }
+    const omit = omitArg ? translateOmit(ctx, mm, omitArg) : undefined;
     const withClause = {};
     let hasWith = false;
     if (include) {
@@ -666,7 +713,7 @@ function translateProjection(ctx, mm, args) {
             withClause[rel.name] = translateWithOption(ctx, mm, rel.name, val);
             hasWith = true;
         }
-        return { with: hasWith ? withClause : undefined };
+        return { omit, with: hasWith ? withClause : undefined };
     }
     if (select) {
         const scalar = {};
@@ -690,7 +737,130 @@ function translateProjection(ctx, mm, args) {
         }
         return { select: hasScalar ? scalar : undefined, with: hasWith ? withClause : undefined };
     }
-    return {};
+    return { omit };
+}
+const NO_WRITE_PROJECTION = {};
+/**
+ * Refuse a write-projection key that names no field on the model.
+ *
+ * Unlike a READ projection, this one never reaches core: `select` / `omit` on a
+ * write are applied to the already-returned object by
+ * {@link applyWriteProjection}, so nothing downstream can notice the name is
+ * wrong. A typo therefore failed silently in BOTH directions, and the `omit`
+ * direction is the one that matters: `omit: { ssn: true }` misspelled as
+ * `snn` returned the column, and the call site that asked for it hidden had no
+ * signal at all. (`pick` failed the other way, quietly dropping the field from
+ * the result.)
+ *
+ * The read path has never had this hole: core validates every projection key
+ * and throws E003 on an unknown one, which is the behaviour a caller has
+ * already observed on `findMany` before writing the same clause on `create`.
+ * So this is not a new rule, it is the read rule reaching the one surface that
+ * bypassed it. Errors match core's shape, including the suggestion.
+ */
+function assertWriteProjectionField(ctx, mm, op, clause, key) {
+    if (Object.hasOwn(mm.fields, key))
+        return;
+    const known = Object.keys(mm.fields);
+    const suggestion = (0, utils_js_1.suggestKey)(key, new Set(known));
+    throw new errors_js_1.ValidationError(`[turbine] prisma-compat: unknown field "${key}" in \`${clause}\` on ${modelName(ctx, mm)}.${op}().` +
+        (suggestion ? ` Did you mean "${suggestion}"?` : '') +
+        ` Known fields: ${known.join(', ') || '(none)'}.`);
+}
+/**
+ * Resolve `select` / `omit` / `include` on create / update / delete / upsert.
+ *
+ * All three used to be accepted and IGNORED here. For `omit` that is the exact
+ * data-exposure bug that was fixed for reads: `omit` is the idiom for a
+ * sensitive-but-untagged column, and because it demonstrably WORKS on
+ * `findMany`, a caller has positive evidence for assuming it works on `create`
+ * too. `select` is the same class in the other spelling (the caller asked for
+ * three fields and got the whole row).
+ *
+ * SCOPE, stated exactly rather than implied: this narrows the OBJECT this
+ * adapter returns. Core's write args carry no projection, so the column is
+ * still in the statement's `RETURNING` list and still crosses the wire. The
+ * SQL-level control is `pii: true` on the column, which is enforced in core and
+ * is unaffected by any of this.
+ *
+ * A relation (or `_count`) key THROWS instead: a write returns its own row and
+ * nothing else, so serving it is impossible, and the alternative is handing
+ * back a row whose relation property is silently `undefined`, which is the
+ * failure mode this whole round exists to remove.
+ */
+function resolveWriteProjection(ctx, mm, op, args) {
+    if (!args)
+        return NO_WRITE_PROJECTION;
+    const include = args.include;
+    const select = args.select;
+    const omitArg = args.omit;
+    if (include && select) {
+        throw new errors_js_1.ValidationError('[turbine] prisma-compat: `include` and `select` are mutually exclusive.');
+    }
+    if (select && omitArg) {
+        throw new errors_js_1.ValidationError('[turbine] prisma-compat: `select` and `omit` are mutually exclusive. ' +
+            'A `select` already lists exactly the fields you want.');
+    }
+    if (include) {
+        for (const [key, val] of Object.entries(include)) {
+            if (val === false || val == null)
+                continue;
+            throw new errors_js_1.UnsupportedFeatureError(`include ("${key}") on ${op}`, 'prisma-compat', `a write on model "${modelName(ctx, mm)}" returns its own row only; read the relation back with a ` +
+                'separate findUnique inside the same $transaction.');
+        }
+    }
+    if (select) {
+        const pick = new Set();
+        for (const [key, val] of Object.entries(select)) {
+            if (val === false || val == null)
+                continue;
+            if (key === '_count' || mm.relations[key]) {
+                throw new errors_js_1.UnsupportedFeatureError(`select of "${key}" on ${op}`, 'prisma-compat', `"${key}" is a relation on model "${modelName(ctx, mm)}"; a write returns its own row only, so read ` +
+                    'it back with a separate findUnique inside the same $transaction.');
+            }
+            assertWriteProjectionField(ctx, mm, op, 'select', key);
+            pick.add(key);
+        }
+        // An all-false `select` names nothing. Reads treat that as "no projection"
+        // (translateProjection returns select: undefined), so writes do too rather
+        // than inventing a second rule for input Prisma rejects anyway.
+        return pick.size ? { pick } : NO_WRITE_PROJECTION;
+    }
+    if (omitArg) {
+        const omit = new Set();
+        for (const [key, val] of Object.entries(omitArg)) {
+            if (val === false || val == null)
+                continue;
+            if (mm.relations[key]) {
+                throw new errors_js_1.ValidationError(`[turbine] prisma-compat: \`omit\` on model "${modelName(ctx, mm)}" takes scalar fields, but "${key}" ` +
+                    'is a relation.');
+            }
+            assertWriteProjectionField(ctx, mm, op, 'omit', key);
+            omit.add(key);
+        }
+        return omit.size ? { omit } : NO_WRITE_PROJECTION;
+    }
+    return NO_WRITE_PROJECTION;
+}
+/** Apply a {@link WriteProjection} to one already-reshaped write result row. */
+function applyWriteProjection(proj, row) {
+    if (!isPlainObject(row))
+        return row;
+    if (proj.pick) {
+        const out = {};
+        for (const key of proj.pick) {
+            if (key in row)
+                out[key] = row[key];
+        }
+        return out;
+    }
+    if (proj.omit) {
+        const out = { ...row };
+        for (const key of proj.omit)
+            delete out[key];
+        return out;
+    }
+    return row;
 }
 /** Translate a Prisma relation include payload into a Turbine `WithOptions`. */
 function translateWithOption(ctx, mm, turbineRel, val) {
@@ -709,10 +879,14 @@ function translateWithOption(ctx, mm, turbineRel, val) {
     if (val.skip !== undefined) {
         throw new errors_js_1.UnsupportedFeatureError('skip (offset) on a nested relation include', 'prisma-compat', "Turbine's `with` clause has no offset, page the relation with a separate query.");
     }
-    if (target && (val.select !== undefined || val.include !== undefined)) {
+    if (target && (val.select !== undefined || val.include !== undefined || val.omit !== undefined)) {
         const proj = translateProjection(ctx, target, val);
         if (proj.select)
             opt.select = proj.select;
+        // Same silent drop as the top level: a nested `omit` names the sensitive
+        // column on the CHILD rows, which are just as exposed.
+        if (proj.omit)
+            opt.omit = proj.omit;
         if (proj.with)
             opt.with = proj.with;
     }
@@ -759,6 +933,8 @@ function translateReadArgs(ctx, mm, prismaArgs, kind) {
     const proj = translateProjection(ctx, mm, prismaArgs);
     if (proj.select)
         t.select = proj.select;
+    if (proj.omit)
+        t.omit = proj.omit;
     if (proj.with)
         t.with = proj.with;
     if (Array.isArray(prismaArgs.distinct)) {
@@ -1520,15 +1696,22 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
         findUnique: (args) => defer('findUnique', args, () => translateReadArgs(ctx, mm, requireWhere(args, 'findUnique'), 'unique'), (qi, t) => qi.findUnique(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindUnique(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
         findFirstOrThrow: (args = {}) => defer('findFirstOrThrow', args, () => translateReadArgs(ctx, mm, args, 'first'), (qi, t) => qi.findFirstOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirstOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
         findUniqueOrThrow: (args) => defer('findUniqueOrThrow', args, () => translateReadArgs(ctx, mm, requireWhere(args, 'findUniqueOrThrow'), 'unique'), (qi, t) => qi.findUniqueOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindUniqueOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
-        create: (args) => defer('create', args, () => {
-            const t = { data: translateWriteData(ctx, mm, applyCreateDefaults(mm, args.data)) };
-            (0, index_js_1.applyNativeOptions)(index_js_1.CREATE_OPTIONS, args, t);
-            return t;
-        }, (qi, t) => qi.create(t).then((r) => reshapeRow(ctx, mm, r)), {
-            build: (qi, t) => qi.buildCreate(t),
-            reshape: (raw) => reshapeRow(ctx, mm, raw),
-            nested: (t) => hasNestedKeys(ctx, mm, t.data),
-        }),
+        create: (args) => {
+            // Resolved inside the translate thunk below (so it validates before the
+            // write runs and stays deferred), read back by every result path.
+            let proj = NO_WRITE_PROJECTION;
+            const shape = (raw) => applyWriteProjection(proj, reshapeRow(ctx, mm, raw));
+            return defer('create', args, () => {
+                proj = resolveWriteProjection(ctx, mm, 'create', args);
+                const t = { data: translateWriteData(ctx, mm, applyCreateDefaults(mm, args.data)) };
+                (0, index_js_1.applyNativeOptions)(index_js_1.CREATE_OPTIONS, args, t);
+                return t;
+            }, (qi, t) => qi.create(t).then(shape), {
+                build: (qi, t) => qi.buildCreate(t),
+                reshape: shape,
+                nested: (t) => hasNestedKeys(ctx, mm, t.data),
+            });
+        },
         createMany: (args) => defer('createMany', args, () => {
             const data = args.data;
             const rows = Array.isArray(data)
@@ -1556,28 +1739,33 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
             nested: (t) => createManyRunsOf(t).length > 1,
             execInTx: (table, t) => createManyByRun(table(mm.table), t, createManyRunsOf(t)),
         }),
-        update: (args) => defer('update', args, () => {
-            const a = requireWhere(args, 'update');
-            const t = {
-                where: translateWhere(ctx, mm, a.where),
-                data: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.data)),
-            };
-            (0, index_js_1.applyNativeOptions)(index_js_1.UPDATE_OPTIONS, a, t);
-            // `optimisticLock.field` is a FIELD NAME, so it is renamed rather than
-            // copied: a blind passthrough would send the Prisma spelling into core
-            // and break on any model whose column is `@map`ped.
-            if (isPlainObject(a.optimisticLock)) {
-                t.optimisticLock = {
-                    ...a.optimisticLock,
-                    field: renameField(mm, String(a.optimisticLock.field)),
+        update: (args) => {
+            let proj = NO_WRITE_PROJECTION;
+            const shape = (raw) => applyWriteProjection(proj, reshapeRow(ctx, mm, raw));
+            return defer('update', args, () => {
+                const a = requireWhere(args, 'update');
+                proj = resolveWriteProjection(ctx, mm, 'update', a);
+                const t = {
+                    where: translateWhere(ctx, mm, a.where),
+                    data: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.data)),
                 };
-            }
-            return t;
-        }, (qi, t) => qi.update(t).then((r) => reshapeRow(ctx, mm, r)), {
-            build: (qi, t) => qi.buildUpdate(t),
-            reshape: (raw) => reshapeRow(ctx, mm, raw),
-            nested: (t) => hasNestedKeys(ctx, mm, t.data),
-        }),
+                (0, index_js_1.applyNativeOptions)(index_js_1.UPDATE_OPTIONS, a, t);
+                // `optimisticLock.field` is a FIELD NAME, so it is renamed rather than
+                // copied: a blind passthrough would send the Prisma spelling into core
+                // and break on any model whose column is `@map`ped.
+                if (isPlainObject(a.optimisticLock)) {
+                    t.optimisticLock = {
+                        ...a.optimisticLock,
+                        field: renameField(mm, String(a.optimisticLock.field)),
+                    };
+                }
+                return t;
+            }, (qi, t) => qi.update(t).then(shape), {
+                build: (qi, t) => qi.buildUpdate(t),
+                reshape: shape,
+                nested: (t) => hasNestedKeys(ctx, mm, t.data),
+            });
+        },
         updateMany: (args) => defer('updateMany', args, () => {
             const a = args;
             refuseRowLimit(modelName(ctx, mm), 'updateMany', a);
@@ -1590,15 +1778,20 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
             // row, and an explicit `allowFullTableScan: false` must not be able to
             // turn that parity into a thrown empty-where guard.
             if (a.where === undefined)
-                t.allowFullTableScan = true;
+                t.allowFullTableScan = index_js_1.UNSAFE;
             return t;
         }, (qi, t) => qi.updateMany(t), { build: (qi, t) => qi.buildUpdateMany(t), reshape: (raw) => raw }),
-        delete: (args) => defer('delete', args, () => {
-            const a = requireWhere(args, 'delete');
-            const t = { where: translateWhere(ctx, mm, a.where) };
-            (0, index_js_1.applyNativeOptions)(index_js_1.DELETE_OPTIONS, a, t);
-            return t;
-        }, (qi, t) => qi.delete(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildDelete(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
+        delete: (args) => {
+            let proj = NO_WRITE_PROJECTION;
+            const shape = (raw) => applyWriteProjection(proj, reshapeRow(ctx, mm, raw));
+            return defer('delete', args, () => {
+                const a = requireWhere(args, 'delete');
+                proj = resolveWriteProjection(ctx, mm, 'delete', a);
+                const t = { where: translateWhere(ctx, mm, a.where) };
+                (0, index_js_1.applyNativeOptions)(index_js_1.DELETE_OPTIONS, a, t);
+                return t;
+            }, (qi, t) => qi.delete(t).then(shape), { build: (qi, t) => qi.buildDelete(t), reshape: shape });
+        },
         deleteMany: (args = {}) => defer('deleteMany', args, () => {
             const a = args;
             refuseRowLimit(modelName(ctx, mm), 'deleteMany', a);
@@ -1606,40 +1799,42 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
             (0, index_js_1.applyNativeOptions)(index_js_1.DELETE_MANY_OPTIONS, a, t);
             // LAST, so it wins. See the same note on updateMany.
             if (a.where === undefined)
-                t.allowFullTableScan = true;
+                t.allowFullTableScan = index_js_1.UNSAFE;
             return t;
         }, (qi, t) => qi.deleteMany(t), { build: (qi, t) => qi.buildDeleteMany(t), reshape: (raw) => raw }),
-        upsert: (args) => defer('upsert', args, () => {
-            const a = requireWhere(args, 'upsert');
-            const t = {
-                where: translateWhere(ctx, mm, a.where),
-                create: translateWriteData(ctx, mm, applyCreateDefaults(mm, a.create)),
-                update: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.update)),
-            };
-            (0, index_js_1.applyNativeOptions)(index_js_1.UPSERT_OPTIONS, a, t);
-            return t;
-        }, (qi, t) => {
-            // Native ON CONFLICT upsert is only Prisma-equivalent when the where
-            // key values equal the create values AND no nested write data is
-            // present; otherwise emulate Prisma's lookup-first atomically.
-            if (upsertKeysMatch(t) && !hasNestedKeys(ctx, mm, t.create) && !hasNestedKeys(ctx, mm, t.update)) {
-                return qi.upsert(t).then((r) => reshapeRow(ctx, mm, r));
-            }
-            return runInTx(async (table) => {
-                const row = await upsertLookupFirst(table(mm.table), t);
-                return reshapeRow(ctx, mm, row);
-            });
-        }, {
-            build: (qi, t) => qi.buildUpsert(t),
-            reshape: (raw) => reshapeRow(ctx, mm, raw),
-            nested: (t) => !upsertKeysMatch(t) || hasNestedKeys(ctx, mm, t.create) || hasNestedKeys(ctx, mm, t.update),
-            execInTx: async (table, t) => {
+        upsert: (args) => {
+            let proj = NO_WRITE_PROJECTION;
+            const shape = (raw) => applyWriteProjection(proj, reshapeRow(ctx, mm, raw));
+            return defer('upsert', args, () => {
+                const a = requireWhere(args, 'upsert');
+                proj = resolveWriteProjection(ctx, mm, 'upsert', a);
+                const t = {
+                    where: translateWhere(ctx, mm, a.where),
+                    create: translateWriteData(ctx, mm, applyCreateDefaults(mm, a.create)),
+                    update: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.update)),
+                };
+                (0, index_js_1.applyNativeOptions)(index_js_1.UPSERT_OPTIONS, a, t);
+                return t;
+            }, (qi, t) => {
+                // Native ON CONFLICT upsert is only Prisma-equivalent when the where
+                // key values equal the create values AND no nested write data is
+                // present; otherwise emulate Prisma's lookup-first atomically.
                 if (upsertKeysMatch(t) && !hasNestedKeys(ctx, mm, t.create) && !hasNestedKeys(ctx, mm, t.update)) {
-                    return reshapeRow(ctx, mm, await table(mm.table).upsert(t));
+                    return qi.upsert(t).then(shape);
                 }
-                return reshapeRow(ctx, mm, await upsertLookupFirst(table(mm.table), t));
-            },
-        }),
+                return runInTx(async (table) => shape(await upsertLookupFirst(table(mm.table), t)));
+            }, {
+                build: (qi, t) => qi.buildUpsert(t),
+                reshape: shape,
+                nested: (t) => !upsertKeysMatch(t) || hasNestedKeys(ctx, mm, t.create) || hasNestedKeys(ctx, mm, t.update),
+                execInTx: async (table, t) => {
+                    if (upsertKeysMatch(t) && !hasNestedKeys(ctx, mm, t.create) && !hasNestedKeys(ctx, mm, t.update)) {
+                        return shape(await table(mm.table).upsert(t));
+                    }
+                    return shape(await upsertLookupFirst(table(mm.table), t));
+                },
+            });
+        },
         count: (args = {}) => defer('count', args, () => {
             const t = {};
             (0, index_js_1.applyNativeOptions)(index_js_1.COUNT_OPTIONS, args, t);

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

@@ -18,7 +18,7 @@ import type { BuilderCtx } from './where.js';
  * projection, and a value-returning aggregate is a projection by another name:
  * `groupBy({ by: ['email'] })` emits one row per distinct plaintext email, and
  * `_min`/`_max` return a stored cell verbatim. Both therefore REQUIRE the same
- * `includePii: true` opt-in reads use.
+ * `includePii` opt-in (the UNSAFE sentinel) that reads use.
  *
  * Deliberately NOT gated: `_count` (a count, never a value), `_sum` / `_avg`
  * (a computed total across many rows, not a stored cell), and `where` /

package/dist/cjs/query/aggregates.js

@@ -54,6 +54,7 @@ exports.buildAggregate = buildAggregate;
 const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
 const filters_js_1 = require("./filters.js");
+const types_js_1 = require("./types.js");
 const utils_js_1 = require("./utils.js");
 const whereMod = __importStar(require("./where.js"));
 /**
@@ -62,7 +63,7 @@ const whereMod = __importStar(require("./where.js"));
  * projection, and a value-returning aggregate is a projection by another name:
  * `groupBy({ by: ['email'] })` emits one row per distinct plaintext email, and
  * `_min`/`_max` return a stored cell verbatim. Both therefore REQUIRE the same
- * `includePii: true` opt-in reads use.
+ * `includePii` opt-in (the UNSAFE sentinel) that reads use.
  *
  * Deliberately NOT gated: `_count` (a count, never a value), `_sum` / `_avg`
  * (a computed total across many rows, not a stored cell), and `where` /
@@ -80,7 +81,8 @@ function assertAggregatePiiOptIn(table, meta, field, column, usage, includePii)
         return;
     throw new errors_js_1.ValidationError(`[turbine] ${usage} on column "${field}" of table "${table}" is refused: that column is ` +
         'PII-tagged (`pii: true`), and this aggregate returns its stored values, which are excluded ' +
-        'from every default projection. Pass `includePii: true` on this call to opt in. ' +
+        'from every default projection. Pass `includePii: UNSAFE` on this call to opt in ' +
+        "(import { UNSAFE } from 'turbine-orm'). " +
         '`_count` over a PII column (a count, not a value) and `where` / `orderBy` / `having` on PII ' +
         'columns need no opt-in.');
 }
@@ -93,7 +95,11 @@ function buildGroupBy(qi, args) {
             }
         }
     }
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
+    // Resolve the PII opt-in ONCE, here, so the sentinel check runs on every
+    // groupBy (including one whose `by` names no PII column) rather than only on
+    // the paths that happen to consult it.
+    const includePii = (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii');
     const gbWhere = whereMod.mergeGlobalFilter(qi, args.where);
     const { sql: whereSql, params } = gbWhere
         ? whereMod.buildWhere(qi, gbWhere)
@@ -143,7 +149,7 @@ function buildGroupBy(qi, args) {
     for (const entry of args.by) {
         if (typeof entry === 'string') {
             const col = qi.toColumn(entry);
-            assertAggregatePiiOptIn(qi.table, meta, entry, col, 'groupBy `by` key', args.includePii);
+            assertAggregatePiiOptIn(qi.table, meta, entry, col, 'groupBy `by` key', includePii);
             claimResultKey(entry, `column "${col}"`);
             // The emitted output column is the snake_case name; claim it too (when
             // it differs from the result key) so a JSON alias like 'created_at'
@@ -158,7 +164,7 @@ function buildGroupBy(qi, args) {
         }
         else {
             const col = resolveJsonPathTarget(qi, 'group key', entry.field, entry.path);
-            assertAggregatePiiOptIn(qi.table, meta, entry.field, col, 'groupBy JSON `by` key', args.includePii);
+            assertAggregatePiiOptIn(qi.table, meta, entry.field, col, 'groupBy JSON `by` key', includePii);
             params.push(whereMod.jsonPathParam(qi, entry.path));
             const extract = qi.dialect.buildJsonPathExtract(qi.q(col), qi.p(params.length));
             const alias = entry.alias ?? String(entry.path[entry.path.length - 1]);
@@ -226,7 +232,7 @@ function buildGroupBy(qi, args) {
             if (target === true) {
                 const col = qi.toColumn(key);
                 if (aggKey === '_min' || aggKey === '_max') {
-                    assertAggregatePiiOptIn(qi.table, meta, key, col, `groupBy ${aggKey}`, args.includePii);
+                    assertAggregatePiiOptIn(qi.table, meta, key, col, `groupBy ${aggKey}`, includePii);
                 }
                 // Aggregate output aliases share the same output-name namespace as
                 // the group keys: `_sum: { totalPrice: true, total_price: {json} }`
@@ -240,7 +246,7 @@ function buildGroupBy(qi, args) {
             }
             const col = resolveJsonPathTarget(qi, `${aggKey} target "${key}"`, target.field, target.path);
             if (aggKey === '_min' || aggKey === '_max') {
-                assertAggregatePiiOptIn(qi.table, meta, target.field, col, `groupBy ${aggKey} JSON target`, args.includePii);
+                assertAggregatePiiOptIn(qi.table, meta, target.field, col, `groupBy ${aggKey} JSON target`, includePii);
             }
             const alwaysNumeric = aggKey === '_sum' || aggKey === '_avg';
             if (alwaysNumeric && target.type === 'text') {
@@ -412,6 +418,9 @@ function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
                     throw new errors_js_1.ValidationError(`[turbine] Cannot order groupBy by "_count" on table "${qi.table}": _count is not selected. ` +
                         `Orderable keys: ${validKeys()}.`);
                 }
+                // Refuse a direction that is neither asc nor desc BEFORE normalizeOrderBy,
+                // whose `=== 'desc' ? DESC : ASC` would silently sort ascending.
+                (0, types_js_1.assertOrderDirection)(value, `groupBy orderBy "_count" on table "${qi.table}"`);
                 const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
                 parts.push(`${expr} ${dir}${qi.nullsSuffix(nulls)}`);
                 continue;
@@ -429,6 +438,7 @@ function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
                     throw new errors_js_1.ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${qi.table}": ` +
                         `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
                 }
+                (0, types_js_1.assertOrderDirection)(dirSpec, `groupBy orderBy "${key}.${field}" on table "${qi.table}"`);
                 const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(dirSpec);
                 parts.push(`${expr} ${dir}${qi.nullsSuffix(nulls)}`);
             }
@@ -440,6 +450,7 @@ function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
             throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${qi.table}". ` +
                 `Orderable keys: ${validKeys()}.`);
         }
+        (0, types_js_1.assertOrderDirection)(value, `groupBy orderBy "${key}" on table "${qi.table}"`);
         const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
         parts.push(`${expr} ${dir}${qi.nullsSuffix(nulls)}`);
     }
@@ -508,6 +519,7 @@ function buildDistinctOnSource(qi, distinctOn, whereSql, params) {
                 'sort specs, and JSON-path orderings only.');
         }
         const col = qi.resolveOrderByColumn(qi.table, qi.tableMeta, key);
+        (0, types_js_1.assertOrderDirection)(value, `groupBy distinctOn.orderBy "${key}" on table "${qi.table}"`);
         const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
         orderParts.push(`${qi.q(col)} ${dir}${qi.nullsSuffix(nulls)}`);
     }
@@ -803,7 +815,9 @@ function temporalAggValue(qi, col, value) {
     return value === '-infinity' ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY;
 }
 function buildAggregate(qi, args) {
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
+    // Resolved once, up front: see buildGroupBy.
+    const includePii = (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii');
     const aggWhere = whereMod.mergeGlobalFilter(qi, args.where);
     const { sql: whereSql, params } = aggWhere
         ? whereMod.buildWhere(qi, aggWhere)
@@ -874,7 +888,7 @@ function buildAggregate(qi, args) {
         for (const [field, enabled] of Object.entries(args._min)) {
             if (enabled) {
                 const col = qi.toColumn(field);
-                assertAggregatePiiOptIn(qi.table, meta, field, col, 'aggregate _min', args.includePii);
+                assertAggregatePiiOptIn(qi.table, meta, field, col, 'aggregate _min', includePii);
                 selectExprs.push(`MIN(${qi.q(col)}) AS ${qi.q(`_min_${col}`)}`);
             }
         }
@@ -884,7 +898,7 @@ function buildAggregate(qi, args) {
         for (const [field, enabled] of Object.entries(args._max)) {
             if (enabled) {
                 const col = qi.toColumn(field);
-                assertAggregatePiiOptIn(qi.table, meta, field, col, 'aggregate _max', args.includePii);
+                assertAggregatePiiOptIn(qi.table, meta, field, col, 'aggregate _max', includePii);
                 selectExprs.push(`MAX(${qi.q(col)}) AS ${qi.q(`_max_${col}`)}`);
             }
         }

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

@@ -56,7 +56,7 @@
 import type pg from 'pg';
 import { type RelationDef, type SchemaMetadata, type TableMetadata } from '../schema.js';
 import type { ReselectExecutor } from './builder.js';
-import type { SkipGlobalFilters, WithClause, WithCount } from './types.js';
+import type { SkipGlobalFilters, Unsafe, WithClause, WithCount } from './types.js';
 /**
  * A DeferredQuery, minimally typed for what the loader consumes. Kept local to
  * avoid a value import of builder.ts (which imports this module).
@@ -104,9 +104,14 @@ export interface RelationLoadContext {
     /**
      * The query's `includePii` opt-in, threaded onto every child `buildFindMany`
      * so a batched relation load excludes (or includes) PII-tagged columns exactly
-     * as the join strategy does at every nested level. Default `false`.
+     * as the join strategy does at every nested level. Absent by default.
+     *
+     * Typed as the SENTINEL, not a boolean, and that is a contract not a style
+     * choice: this value is copied verbatim onto child `FindManyArgs`, where a
+     * plain `true` is refused as a privilege escalation. A boolean here would
+     * type-check and then throw on the first relation follow-up.
      */
-    includePii?: boolean;
+    includePii?: Unsafe;
     /**
      * Render `table`'s global filter against `alias` for a raw follow-up query
      * (the batched `_count`), numbering its `$n` placeholders AFTER
@@ -128,7 +133,7 @@ export interface RelationLoadContext {
  * keep the `select: undefined, omit: undefined` fast path and the emitted SQL
  * stays byte-identical.
  */
-export declare function defaultProjectionFields(meta: TableMetadata, includePii: boolean | undefined): {
+export declare function defaultProjectionFields(meta: TableMetadata, includePii: boolean | Unsafe | undefined): {
     hidden: ReadonlySet<string>;
     visible: string[];
 } | undefined;

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

@@ -86,7 +86,10 @@ const MAX_DEPTH = 10;
  * keep the `select: undefined, omit: undefined` fast path and the emitted SQL
  * stays byte-identical.
  */
-function defaultProjectionFields(meta, includePii) {
+function defaultProjectionFields(meta, 
+// Either the already-resolved boolean (top-level callers) or the raw sentinel
+// (the relation-load context); both are only ever tested for truthiness.
+includePii) {
     if (includePii)
         return undefined;
     const hidden = new Set();