turbine-orm 0.61.0 → 0.62.0

package/dist/query/types.d.ts

@@ -1,8 +1,122 @@
 /**
  * turbine-orm, Query builder types
  *
- * All exported type and interface definitions for the query builder module.
+ * All exported type and interface definitions for the query builder module,
+ * plus the small runtime guards that police the values those types describe
+ * (the {@link UNSAFE} sentinel and the orderBy-direction check). Those guards
+ * live here, next to the declarations they enforce, so a new privilege option
+ * or direction-bearing shape has one obvious place to be wired in.
  */
+/**
+ * The value that unlocks a PRIVILEGE option: `skipGlobalFilters`,
+ * `includePii`, `allowFullTableScan`.
+ *
+ * ## The bug this closes
+ *
+ * All three of those options are ordinary siblings of `where` on the query-args
+ * object, so a handler written the idiomatic way,
+ *
+ * ```ts
+ * app.get('/users', (req, res) => db.users.findMany({ ...req.body }));
+ * ```
+ *
+ * used to let the REQUEST BODY turn them on. `{"where":{"name":"x"},
+ * "skipGlobalFilters":true}` compiled to the same statement minus the tenant
+ * predicate: the documented multi-tenancy mechanism, removed by an attacker
+ * over the wire. `includePii: true` unlocked the PII projection the same way,
+ * and `allowFullTableScan: true` disarmed the empty-`where` guard that stops a
+ * mass update or delete.
+ *
+ * Typing the options `boolean` and writing "be careful" in the docs is not a
+ * fix: the escalation is a mass-assignment shape, and mass assignment happens
+ * because nobody enumerated the keys.
+ *
+ * ## Why a symbol
+ *
+ * `JSON.parse` cannot produce a symbol. There is no JSON document, no query
+ * string, no form body and no `structuredClone` of untrusted input that yields
+ * this value, so an attacker cannot put it on an args object at all. The
+ * escalation stops being "discouraged" and becomes STRUCTURALLY impossible,
+ * which is the only property that survives a refactor.
+ *
+ * Registered via `Symbol.for` rather than `Symbol()` on purpose: this package
+ * ships dual ESM + CJS builds, and a consumer can easily import `UNSAFE` from
+ * one copy while the query interface it calls came from the other. A plain
+ * `Symbol()` would be a different value in each copy and every privileged call
+ * would throw. The global registry makes the two copies agree. (Reachability of
+ * `Symbol.for` from application code is irrelevant to the threat model here:
+ * the attacker's channel is parsed data, which cannot carry a symbol either
+ * way.)
+ *
+ * @example
+ * ```ts
+ * import { UNSAFE } from 'turbine-orm';
+ *
+ * // Deliberate, in a background job that legitimately crosses tenants:
+ * await db.users.findMany({ where: { active: true }, skipGlobalFilters: UNSAFE });
+ *
+ * // Skip the global filter on named tables only (the head element is the opt-in):
+ * await db.users.findMany({ with: { posts: true }, skipGlobalFilters: [UNSAFE, 'posts'] });
+ * ```
+ */
+export declare const UNSAFE: unique symbol;
+/** The type of the {@link UNSAFE} sentinel. */
+export type Unsafe = typeof UNSAFE;
+/** Every privilege option, for the diagnostic below and for tests to enumerate. */
+export type PrivilegeOption = 'skipGlobalFilters' | 'includePii' | 'allowFullTableScan';
+/**
+ * Resolve a boolean-shaped privilege option (`includePii`,
+ * `allowFullTableScan`) into the boolean the builders use.
+ *
+ * - absent / `undefined` / `null` / `false` → `false`. These are unambiguously
+ *   NOT a request for the privilege, and throwing on them would break the
+ *   ordinary `allowFullTableScan: someFlag` call whose flag is off (prisma-compat
+ *   relies on `allowFullTableScan: false` staying a no-op, see its updateMany).
+ * - {@link UNSAFE} → `true`.
+ * - ANYTHING else, `true` included → throws {@link ValidationError} (E003).
+ *
+ * The literal `true` throws rather than being ignored ON PURPOSE. Ignoring it
+ * would swap an escalation bug for a silent-failure bug: a legitimate caller
+ * who has not migrated would keep reading rows with the PII columns quietly
+ * missing, or keep expecting a cross-tenant read that no longer happens, with
+ * no signal anywhere. Throwing turns the attacker's spread into a 500 and the
+ * legitimate caller's stale code into an immediate, self-describing error.
+ */
+export declare function resolveUnsafeFlag(value: unknown, option: PrivilegeOption): boolean;
+/**
+ * The internal form of {@link SkipGlobalFilters}: `true` (skip every table) or
+ * the list of table accessors to skip. This is what the global-filter resolver
+ * consumes, and it is produced ONLY by {@link resolveSkipGlobalFilters}.
+ */
+export type ResolvedSkipGlobalFilters = true | readonly string[];
+/**
+ * Validate and normalize {@link SkipGlobalFilters}.
+ *
+ * The array form is policed exactly as hard as the bare form: an attacker who
+ * can post `{"skipGlobalFilters":["users"]}` drops the tenant predicate on the
+ * table they care about, which is the same breach with an extra step. So the
+ * array must LEAD with the sentinel (`[UNSAFE, 'posts']`) and the rest must be
+ * table-name strings.
+ */
+export declare function resolveSkipGlobalFilters(value: unknown): ResolvedSkipGlobalFilters | undefined;
+/**
+ * Refuse an orderBy direction that is neither `asc` nor `desc`.
+ *
+ * Every direction consumer used to be spelled `String(v).toLowerCase() ===
+ * 'desc' ? 'DESC' : 'ASC'`, so `'descending'`, `''`, `null`, `1` and every
+ * other typo all emitted `ASC`. TypeScript rejects them, but the value that
+ * reaches this code in practice is `orderBy: { [field]: req.query.dir }`, which
+ * is `any` at the boundary, and the failure is SILENT: the caller gets a
+ * correct-looking page sorted the exact opposite way, which is worse than an
+ * error and identical to a successful response.
+ *
+ * Accepts any casing (`'DESC'` already worked) and leaves `undefined` alone
+ * (every consumer treats an undefined entry as absent). Recursive/compound
+ * orderBy shapes are validated one node at a time by their own consumers.
+ */
+export declare function assertOrderDirection(value: unknown, context: string): void;
+/** One direction token. `undefined` means "not specified", which defaults to asc. */
+export declare function assertDirectionToken(value: unknown, context: string): void;
 export type OrderDirection = 'asc' | 'desc';
 /**
  * How a query resolves its `with` relations.
@@ -186,13 +300,18 @@ export type GlobalFilters = {
     [tableAccessor: string]: WhereClause<any> | (() => WhereClause<any>);
 };
 /**
- * Per-query opt-out of the configured {@link GlobalFilters}. `true` skips the
- * global filter on the query's own table AND on every relation target it
- * touches; an array skips only the named table accessors (own table and/or
- * relation targets). Global filters never satisfy the empty-`where` guard for
- * `update`/`delete`, that guard always checks the user-supplied `where`.
+ * Per-query opt-out of the configured {@link GlobalFilters}. {@link UNSAFE}
+ * skips the global filter on the query's own table AND on every relation target
+ * it touches; `[UNSAFE, ...names]` skips only the named table accessors (own
+ * table and/or relation targets). Global filters never satisfy the empty-`where`
+ * guard for `update`/`delete`, that guard always checks the user-supplied
+ * `where`.
+ *
+ * PRIVILEGE OPTION: it removes the documented multi-tenancy boundary, so it is
+ * unlocked by the {@link UNSAFE} sentinel only. `true` / `['users']` throw
+ * (E003). See {@link UNSAFE} for why.
  */
-export type SkipGlobalFilters = true | readonly string[];
+export type SkipGlobalFilters = Unsafe | readonly [Unsafe, ...string[]];
 /**
  * Reserved key in a `with` clause that requests correlated relation counts.
  * `_count: true` counts every to-many relation of the table; a record form
@@ -463,8 +582,8 @@ export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithCla
     stableRelationOrder?: boolean;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
-    /** Include PII-tagged columns in the result. See {@link FindManyArgs.includePii}. */
-    includePii?: boolean;
+    /** Include PII-tagged columns (`includePii: UNSAFE`). See {@link FindManyArgs.includePii}. */
+    includePii?: Unsafe;
     /** Plan this query with its real parameter values. See {@link FindManyArgs.forceCustomPlan}. */
     forceCustomPlan?: boolean;
 }
@@ -518,8 +637,12 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
      *
      * Referencing a PII column in `where` / `orderBy` / `groupBy` / aggregates is
      * always allowed regardless of this flag (the reference is explicit).
+     *
+     * PRIVILEGE OPTION: unlocked by the {@link UNSAFE} sentinel only
+     * (`includePii: UNSAFE`). A literal `true` throws (E003), because a request
+     * body spread into these args must not be able to unlock the PII projection.
      */
-    includePii?: boolean;
+    includePii?: Unsafe;
     /**
      * Plan THIS query with its actual parameter values, every execution.
      * PostgreSQL only (see the refusal below).
@@ -728,10 +851,15 @@ export interface UpdateArgs<T, R extends object = {}> {
      * Opt in to running this mutation when `where` resolves to an empty
      * predicate (e.g. `{}` or `{ id: undefined }`). Default `false`, an
      * empty predicate throws `ValidationError` to catch the common case of
-     * a filter value accidentally being `undefined`. Set this to `true` only
-     * when an unconditional mutation is the intended behaviour.
+     * a filter value accidentally being `undefined`.
+     *
+     * PRIVILEGE OPTION: unlocked by the {@link UNSAFE} sentinel only
+     * (`allowFullTableScan: UNSAFE`), and only when an unconditional mutation is
+     * genuinely the intent. A literal `true` throws (E003): this guard is the
+     * last thing standing between a spread request body and an unconditional
+     * `UPDATE` / `DELETE` over the whole table.
      */
-    allowFullTableScan?: boolean;
+    allowFullTableScan?: Unsafe;
     /**
      * Optimistic locking, prevents lost updates in concurrent scenarios.
      * Specify the version field and its expected value. The update adds a
@@ -762,7 +890,7 @@ export interface UpdateManyArgs<T, R extends object = {}> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
+    allowFullTableScan?: Unsafe;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
@@ -771,7 +899,7 @@ export interface DeleteArgs<T, R extends object = {}> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
+    allowFullTableScan?: Unsafe;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
@@ -780,7 +908,7 @@ export interface DeleteManyArgs<T, R extends object = {}> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
+    allowFullTableScan?: Unsafe;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
@@ -1085,8 +1213,11 @@ export interface GroupByArgs<T, R extends object = {}> {
      * STORED VALUES, so without this they throw `ValidationError` (E003).
      * `_count` (a count, not a value), `_sum` / `_avg`, and `where` / `orderBy` /
      * `having` on PII columns stay allowed.
+     *
+     * PRIVILEGE OPTION: unlocked by the {@link UNSAFE} sentinel only. See
+     * {@link FindManyArgs.includePii}.
      */
-    includePii?: boolean;
+    includePii?: Unsafe;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
@@ -1187,8 +1318,11 @@ export interface AggregateArgs<T, R extends object = {}> {
      * `ValidationError` (E003) on a PII column. `_count` (a count, not a value)
      * and `_sum` / `_avg` (a computed total over many rows) stay allowed, as do
      * `where` filters on PII columns.
+     *
+     * PRIVILEGE OPTION: unlocked by the {@link UNSAFE} sentinel only. See
+     * {@link FindManyArgs.includePii}.
      */
-    includePii?: boolean;
+    includePii?: Unsafe;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */

package/dist/query/types.js

@@ -1,6 +1,211 @@
 /**
  * turbine-orm, Query builder types
  *
- * All exported type and interface definitions for the query builder module.
+ * All exported type and interface definitions for the query builder module,
+ * plus the small runtime guards that police the values those types describe
+ * (the {@link UNSAFE} sentinel and the orderBy-direction check). Those guards
+ * live here, next to the declarations they enforce, so a new privilege option
+ * or direction-bearing shape has one obvious place to be wired in.
  */
-export {};
+import { ValidationError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// The privilege sentinel
+// ---------------------------------------------------------------------------
+/**
+ * The value that unlocks a PRIVILEGE option: `skipGlobalFilters`,
+ * `includePii`, `allowFullTableScan`.
+ *
+ * ## The bug this closes
+ *
+ * All three of those options are ordinary siblings of `where` on the query-args
+ * object, so a handler written the idiomatic way,
+ *
+ * ```ts
+ * app.get('/users', (req, res) => db.users.findMany({ ...req.body }));
+ * ```
+ *
+ * used to let the REQUEST BODY turn them on. `{"where":{"name":"x"},
+ * "skipGlobalFilters":true}` compiled to the same statement minus the tenant
+ * predicate: the documented multi-tenancy mechanism, removed by an attacker
+ * over the wire. `includePii: true` unlocked the PII projection the same way,
+ * and `allowFullTableScan: true` disarmed the empty-`where` guard that stops a
+ * mass update or delete.
+ *
+ * Typing the options `boolean` and writing "be careful" in the docs is not a
+ * fix: the escalation is a mass-assignment shape, and mass assignment happens
+ * because nobody enumerated the keys.
+ *
+ * ## Why a symbol
+ *
+ * `JSON.parse` cannot produce a symbol. There is no JSON document, no query
+ * string, no form body and no `structuredClone` of untrusted input that yields
+ * this value, so an attacker cannot put it on an args object at all. The
+ * escalation stops being "discouraged" and becomes STRUCTURALLY impossible,
+ * which is the only property that survives a refactor.
+ *
+ * Registered via `Symbol.for` rather than `Symbol()` on purpose: this package
+ * ships dual ESM + CJS builds, and a consumer can easily import `UNSAFE` from
+ * one copy while the query interface it calls came from the other. A plain
+ * `Symbol()` would be a different value in each copy and every privileged call
+ * would throw. The global registry makes the two copies agree. (Reachability of
+ * `Symbol.for` from application code is irrelevant to the threat model here:
+ * the attacker's channel is parsed data, which cannot carry a symbol either
+ * way.)
+ *
+ * @example
+ * ```ts
+ * import { UNSAFE } from 'turbine-orm';
+ *
+ * // Deliberate, in a background job that legitimately crosses tenants:
+ * await db.users.findMany({ where: { active: true }, skipGlobalFilters: UNSAFE });
+ *
+ * // Skip the global filter on named tables only (the head element is the opt-in):
+ * await db.users.findMany({ with: { posts: true }, skipGlobalFilters: [UNSAFE, 'posts'] });
+ * ```
+ */
+export const UNSAFE = Symbol.for('turbine-orm.UNSAFE');
+/** The one message shape every privilege refusal uses. */
+function privilegeRefusal(option, received, extra = '') {
+    return new ValidationError(`[turbine] \`${option}\` must be the \`UNSAFE\` symbol, received ${describeValue(received)}. ` +
+        `${option} is a privilege option: it removes a safety boundary (a tenant filter, the PII ` +
+        'projection, or the empty-`where` guard), so it cannot be enabled by a plain value that ' +
+        'JSON.parse can produce. Import the sentinel and pass it explicitly: ' +
+        `import { UNSAFE } from 'turbine-orm';  →  { ${option}: UNSAFE }.${extra ? ` ${extra}` : ''} ` +
+        'If you did not write this option, an untrusted object was spread into these query args.');
+}
+/** Short, non-leaking rendering of a rejected value for the diagnostic. */
+function describeValue(value) {
+    if (typeof value === 'symbol')
+        return 'a different symbol';
+    if (Array.isArray(value))
+        return 'an array';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'object')
+        return 'an object';
+    if (typeof value === 'string')
+        return `the string ${JSON.stringify(value)}`;
+    return String(value);
+}
+/**
+ * Resolve a boolean-shaped privilege option (`includePii`,
+ * `allowFullTableScan`) into the boolean the builders use.
+ *
+ * - absent / `undefined` / `null` / `false` → `false`. These are unambiguously
+ *   NOT a request for the privilege, and throwing on them would break the
+ *   ordinary `allowFullTableScan: someFlag` call whose flag is off (prisma-compat
+ *   relies on `allowFullTableScan: false` staying a no-op, see its updateMany).
+ * - {@link UNSAFE} → `true`.
+ * - ANYTHING else, `true` included → throws {@link ValidationError} (E003).
+ *
+ * The literal `true` throws rather than being ignored ON PURPOSE. Ignoring it
+ * would swap an escalation bug for a silent-failure bug: a legitimate caller
+ * who has not migrated would keep reading rows with the PII columns quietly
+ * missing, or keep expecting a cross-tenant read that no longer happens, with
+ * no signal anywhere. Throwing turns the attacker's spread into a 500 and the
+ * legitimate caller's stale code into an immediate, self-describing error.
+ */
+export function resolveUnsafeFlag(value, option) {
+    if (value === undefined || value === null || value === false)
+        return false;
+    if (value === UNSAFE)
+        return true;
+    throw privilegeRefusal(option, value);
+}
+/**
+ * Validate and normalize {@link SkipGlobalFilters}.
+ *
+ * The array form is policed exactly as hard as the bare form: an attacker who
+ * can post `{"skipGlobalFilters":["users"]}` drops the tenant predicate on the
+ * table they care about, which is the same breach with an extra step. So the
+ * array must LEAD with the sentinel (`[UNSAFE, 'posts']`) and the rest must be
+ * table-name strings.
+ */
+export function resolveSkipGlobalFilters(value) {
+    if (value === undefined || value === null || value === false)
+        return undefined;
+    if (value === UNSAFE)
+        return true;
+    if (Array.isArray(value)) {
+        if (value[0] !== UNSAFE) {
+            throw privilegeRefusal('skipGlobalFilters', value, 'The array form skips the named tables and must lead with the sentinel: [UNSAFE, "posts"].');
+        }
+        const tables = value.slice(1);
+        // `[UNSAFE]` names no table. It used to resolve to `[]`, which every
+        // consumer reads as "skip nothing", so the one shape that is an explicit,
+        // correctly-imported privilege request was ALSO the one shape that was
+        // silently a no-op. It is not read as "skip all" on purpose: that would let
+        // `[UNSAFE, ...tables]` ESCALATE to a global skip whenever `tables` happens
+        // to come back empty, which is the same accident with a much worse outcome.
+        if (tables.length === 0) {
+            throw new ValidationError('[turbine] `skipGlobalFilters: [UNSAFE]` names no table, so it would skip nothing. ' +
+                'Pass the tables to skip (`[UNSAFE, "posts"]`), or the bare sentinel (`UNSAFE`) to skip every table.');
+        }
+        for (const t of tables) {
+            if (typeof t !== 'string') {
+                throw new ValidationError('[turbine] `skipGlobalFilters: [UNSAFE, ...]` takes table accessor NAMES after the sentinel, ' +
+                    `received ${describeValue(t)}.`);
+            }
+        }
+        return tables;
+    }
+    throw privilegeRefusal('skipGlobalFilters', value);
+}
+// ---------------------------------------------------------------------------
+// orderBy direction validation
+// ---------------------------------------------------------------------------
+/**
+ * Refuse an orderBy direction that is neither `asc` nor `desc`.
+ *
+ * Every direction consumer used to be spelled `String(v).toLowerCase() ===
+ * 'desc' ? 'DESC' : 'ASC'`, so `'descending'`, `''`, `null`, `1` and every
+ * other typo all emitted `ASC`. TypeScript rejects them, but the value that
+ * reaches this code in practice is `orderBy: { [field]: req.query.dir }`, which
+ * is `any` at the boundary, and the failure is SILENT: the caller gets a
+ * correct-looking page sorted the exact opposite way, which is worse than an
+ * error and identical to a successful response.
+ *
+ * Accepts any casing (`'DESC'` already worked) and leaves `undefined` alone
+ * (every consumer treats an undefined entry as absent). Recursive/compound
+ * orderBy shapes are validated one node at a time by their own consumers.
+ */
+export function assertOrderDirection(value, context) {
+    // `undefined` alone means "this entry carries no ordering" (every consumer
+    // skips it). `null` is a VALUE, and a measured silent-ASC case, so it is
+    // refused like any other bad token.
+    if (value === undefined)
+        return;
+    if (typeof value === 'string') {
+        assertDirectionToken(value, context);
+        return;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const v = value;
+        // `{ sort, nulls }` (OrderBySpec), `{ direction }` (JSON-path / pick-row),
+        // `{ distance: { metric, direction } }` (vector KNN).
+        if ('sort' in v)
+            assertDirectionToken(v.sort, context);
+        if ('direction' in v)
+            assertDirectionToken(v.direction, context);
+        const distance = v.distance;
+        if (distance !== null && typeof distance === 'object' && 'direction' in distance) {
+            assertDirectionToken(distance.direction, context);
+        }
+        return;
+    }
+    // A number or boolean is never a direction.
+    assertDirectionToken(value, context);
+}
+/** One direction token. `undefined` means "not specified", which defaults to asc. */
+export function assertDirectionToken(value, context) {
+    if (value === undefined)
+        return;
+    if (typeof value === 'string') {
+        const lowered = value.toLowerCase();
+        if (lowered === 'asc' || lowered === 'desc')
+            return;
+    }
+    throw new ValidationError(`[turbine] Invalid orderBy direction ${describeValue(value)} for ${context}. ` +
+        "Use 'asc' or 'desc'. An unrecognized direction used to sort ASCENDING silently, " +
+        'which returns a correct-looking page in the wrong order.');
+}

package/dist/query/where.d.ts

@@ -15,7 +15,7 @@ import type { Dialect } from '../dialect.js';
 import { ValidationError } from '../errors.js';
 import type { RelationDef, SchemaMetadata, TableMetadata } from '../schema.js';
 import type { TemporalInfinityReading } from './deferred.js';
-import type { ArrayFilter, ColumnRef, GlobalFilters, JsonFilter, JsonPathOrderBy, SkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
+import type { ArrayFilter, ColumnRef, GlobalFilters, JsonFilter, JsonPathOrderBy, ResolvedSkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
 import { type SqlCacheEntry } from './utils.js';
 import { type WhereHost, type WhereRecord } from './where-compile.js';
 /**
@@ -58,7 +58,7 @@ export interface BuilderCtx {
      * synchronous SQL-build + param-collect tree reads it deep inside
      * `resolveGlobalFilter`.
      */
-    currentSkip: SkipGlobalFilters | undefined;
+    currentSkip: ResolvedSkipGlobalFilters | undefined;
     q(name: string): string;
     p(index: number): string;
     inParam(values: unknown): unknown;
@@ -216,7 +216,7 @@ export declare function buildWhere<T extends object>(qi: BuilderCtx, where: Wher
  * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
  * no filter applies, the query opted out, or the filter is empty.
  */
-export declare function resolveGlobalFilter(qi: BuilderCtx, table: string, skip?: SkipGlobalFilters | undefined): Record<string, unknown> | null;
+export declare function resolveGlobalFilter(qi: BuilderCtx, table: string, skip?: ResolvedSkipGlobalFilters | undefined): Record<string, unknown> | null;
 /**
  * AND-merge this table's resolved global filter into a user `where`. Either
  * side may be absent. When no filter applies the user where is returned by

package/dist/query/where.js

@@ -464,13 +464,19 @@ export function userPredicateIsEmpty(qi, userWhere) {
     const throwaway = [];
     return buildWhereClause(qi, userWhere, throwaway) === null;
 }
-export function assertMutationHasPredicate(qi, operation, whereSql, allowFullTableScan) {
+export function assertMutationHasPredicate(qi, operation, whereSql, 
+// Already RESOLVED by the caller (writes.ts) through `resolveUnsafeFlag`, so
+// the sentinel check happens on every mutation, not only the guarded ones: a
+// literal `allowFullTableScan: true` must throw even when the `where` is
+// non-empty, or the escalation attempt goes unreported on most calls.
+allowFullTableScan) {
     if (whereSql.length > 0)
         return;
     if (allowFullTableScan === true)
         return;
     throw new ValidationError(`[turbine] ${operation} on "${qi.table}" refused: the \`where\` clause is empty. ` +
-        `Pass \`allowFullTableScan: true\` to opt in, or check that your filter values are defined.`);
+        "Pass `allowFullTableScan: UNSAFE` to opt in (import { UNSAFE } from 'turbine-orm'), " +
+        'or check that your filter values are defined.');
 }
 /**
  * Build the inner WHERE expression (without the WHERE keyword).

package/dist/query/writes.js

@@ -14,6 +14,7 @@ import { NotFoundError, OptimisticLockError, UnsupportedFeatureError, Validation
 import { camelToSnake, snakeToCamel } from '../schema.js';
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isUnmatchedPlainObject, UPDATE_OPERATOR_KEYS } from './filters.js';
+import { resolveSkipGlobalFilters, resolveUnsafeFlag } from './types.js';
 import { coerceTemporalValue, resolveColumnName } from './utils.js';
 import * as whereMod from './where.js';
 /**
@@ -308,7 +309,7 @@ export function buildCreateMany(qi, args) {
 }
 export function buildUpdate(qi, args) {
     assertWritable(qi, 'update');
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
     // `updatedAt`-tagged columns are filled in before anything reads `data`, so
     // the SET list, the fingerprint and the param collector all see one object.
     const dataObj = applyUpdatedAtColumns(qi, args.data);
@@ -321,7 +322,7 @@ export function buildUpdate(qi, args) {
     // The empty-`where` guard checks the USER predicate only, a global filter
     // must never turn an unguarded mass update into an allowed one.
     const userHasPredicate = !whereMod.userPredicateIsEmpty(qi, userWhere) || !!lock;
-    whereMod.assertMutationHasPredicate(qi, 'update', userHasPredicate ? ' WHERE x' : '', args.allowFullTableScan);
+    whereMod.assertMutationHasPredicate(qi, 'update', userHasPredicate ? ' WHERE x' : '', resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'));
     // The SQL is built from the global-filter-merged where (soft-delete keeps an
     // update from touching already-deleted rows).
     const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
@@ -450,11 +451,11 @@ export function buildUpdate(qi, args) {
 }
 export function buildDelete(qi, args) {
     assertWritable(qi, 'delete');
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
     // Prisma compound-unique selector → the column conjunction (before the guard).
     const userWhere = expandCompoundUniqueWhere(qi.tableMeta, args.where);
     // Guard the USER predicate (a global filter must not satisfy the guard).
-    whereMod.assertMutationHasPredicate(qi, 'delete', whereMod.userPredicateIsEmpty(qi, userWhere) ? '' : ' WHERE x', args.allowFullTableScan);
+    whereMod.assertMutationHasPredicate(qi, 'delete', whereMod.userPredicateIsEmpty(qi, userWhere) ? '' : ' WHERE x', resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'));
     const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
     const ck = `d:${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
@@ -505,7 +506,7 @@ export function buildUpsert(qi, args) {
     assertWritable(qi, 'upsert');
     assertNoGeneratedColumns(qi, args.create, 'upsert');
     assertNoGeneratedColumns(qi, args.update, 'upsert');
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
     // Prisma compound-unique selector on the conflict target → its member columns.
     const upsertWhere = expandCompoundUniqueWhere(qi.tableMeta, args.where);
     // Build the INSERT part from create data
@@ -574,10 +575,10 @@ export function buildUpsert(qi, args) {
 }
 export function buildUpdateMany(qi, args) {
     assertWritable(qi, 'updateMany');
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
     const dataObj = applyUpdatedAtColumns(qi, args.data);
     assertNoGeneratedColumns(qi, dataObj, 'updateMany');
-    whereMod.assertMutationHasPredicate(qi, 'updateMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', args.allowFullTableScan);
+    whereMod.assertMutationHasPredicate(qi, 'updateMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'));
     const whereObj = (whereMod.mergeGlobalFilter(qi, args.where) ?? {});
     // Nothing to SET: a no-op, for the same reason as `update` above (that path
     // has the full rationale). Reports `count: 0` because zero rows were
@@ -616,8 +617,8 @@ export function buildUpdateMany(qi, args) {
 }
 export function buildDeleteMany(qi, args) {
     assertWritable(qi, 'deleteMany');
-    qi.currentSkip = args.skipGlobalFilters;
-    whereMod.assertMutationHasPredicate(qi, 'deleteMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', args.allowFullTableScan);
+    qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
+    whereMod.assertMutationHasPredicate(qi, 'deleteMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'));
     const whereObj = (whereMod.mergeGlobalFilter(qi, args.where) ?? {});
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
     const ck = `dm:${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.61.0",
+  "version": "0.62.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).",
@@ -111,6 +111,7 @@
     "README.md"
   ],
   "sideEffects": false,
+  "//prepublishOnly": "The gate for a MANUAL LOCAL `npm publish`, which is the normal release flow here, so it is the ONLY gate on that path (release.yml runs on a pushed tag, and a local publish never triggers it). `check:package` joined it 2026-07-28: publint --strict + attw --pack, the two checks that catch a broken exports map or CJS declarations that resolve to ESM, which is a class of bug that shipped once already and is invisible to every other script here. `test:coverage:cli` joined at the same time (~3s) so a local publish cannot ship a Studio/migrate coverage regression. Still deliberately absent, because they need a live database or minutes of packing: the Postgres integration suite, the engine containers, and the tarball install smoke, all of which release.yml + ci.yml run.",
   "scripts": {
     "prebuild": "npm run gen:studio",
     "build": "rm -rf dist && tsc && tsc --project tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
@@ -122,13 +123,21 @@
     "test": "tsx --test --test-concurrency=1 src/test/*.test.ts",
     "test:unit": "DATABASE_URL= tsx --test src/test/*.test.ts",
     "test:coverage": "c8 tsx --test --test-concurrency=1 src/test/*.test.ts",
+    "//coverage:cli": "The CLI coverage gate, split into ONE collection run plus FOUR threshold checks. c8 enforces a single threshold set per invocation and its --per-file applies the SAME numbers to every file, neither of which can express 'destructive.ts holds 100 while migrate.ts holds 70'. An aggregate-only floor lets the least-covered file spend the whole slack the best-covered file earned: at the measured 3623/2951 lines, migrate.ts could fall from 70.3% to 66.6% with the aggregate still green. So each file gets its OWN floor, checked by re-reporting the coverage already on disk (c8 report re-reads ./coverage/tmp, so this costs no extra test run). The aggregate check is kept as well: it catches all three sagging together inside their individual margins. Per-file gates run FIRST because their failure names the file. DATABASE_URL is neutralized on the collection run: these test files include live migration tests that create and drop tables, and this script runs from prepublishOnly.",
+    "test:coverage:cli": "npm run coverage:cli:collect && npm run coverage:cli:gate:destructive && npm run coverage:cli:gate:studio && npm run coverage:cli:gate:migrate && npm run coverage:cli:gate:aggregate",
+    "coverage:cli:collect": "DATABASE_URL= c8 --all --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts tsx --test src/test/studio-write.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts",
+    "coverage:cli:gate": "c8 report --all --exclude 'src/test/**' --reporter text --check-coverage",
+    "coverage:cli:gate:destructive": "npm run coverage:cli:gate -- --include src/cli/destructive.ts --lines 98 --statements 98 --branches 84 --functions 98",
+    "coverage:cli:gate:studio": "npm run coverage:cli:gate -- --include src/cli/studio.ts --lines 82 --statements 82 --branches 81 --functions 86",
+    "coverage:cli:gate:migrate": "npm run coverage:cli:gate -- --include src/cli/migrate.ts --lines 69 --statements 69 --branches 91 --functions 73",
+    "coverage:cli:gate:aggregate": "npm run coverage:cli:gate -- --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --lines 78 --statements 78 --branches 84 --functions 82",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",
     "check:error-codes": "tsx scripts/check-error-codes.ts",
     "check:changelog": "node scripts/check-changelog-headings.mjs",
     "check:package": "publint --strict && attw --pack . --profile node16",
-    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit && npm run check:error-codes && npm run check:changelog && npm run size",
+    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit && npm run test:coverage:cli && npm run check:error-codes && npm run check:changelog && npm run check:package && npm run size",
     "prepack": "node scripts/strip-prepare.mjs",
     "postpack": "node scripts/restore-prepare.mjs",
     "size": "size-limit",
@@ -143,7 +152,8 @@
     "pretypecheck": "npm run gen:studio",
     "pretest": "npm run gen:studio",
     "pretest:unit": "npm run gen:studio",
-    "pretest:coverage": "npm run gen:studio"
+    "pretest:coverage": "npm run gen:studio",
+    "pretest:coverage:cli": "npm run gen:studio"
   },
   "engines": {
     "node": ">=20.0.0"