turbine-orm 0.27.0 → 0.28.0

package/dist/query/builder.js

@@ -15,7 +15,7 @@ import { CircularRelationError, NotFoundError, OptimisticLockError, RelationErro
 import { missingIndexForRelation } from '../index-advisor.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
-import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, stripFields, } from './batched-loader.js';
+import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, resolveCountRelations, stripFields, } from './batched-loader.js';
 import { escapeLike, LRUCache, OPERATOR_KEYS, parseDbDate, sqlToPreparedName } from './utils.js';
 // ---------------------------------------------------------------------------
 // Internal detection helpers — used by QueryInterface
@@ -224,6 +224,21 @@ function isVectorFilter(value) {
 function isVectorOrderBy(value) {
     return isVectorFilter(value);
 }
+/** Check if an orderBy value is an explicit `{ sort, nulls? }` spec. */
+function isOrderBySpec(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && 'sort' in value;
+}
+/**
+ * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
+ * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile
+ * path (findMany, groupBy, relation inner subqueries).
+ */
+function normalizeOrderBy(value) {
+    if (isOrderBySpec(value)) {
+        return { dir: value.sort.toLowerCase() === 'desc' ? 'DESC' : 'ASC', nulls: value.nulls };
+    }
+    return { dir: String(value).toLowerCase() === 'desc' ? 'DESC' : 'ASC' };
+}
 // biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 export class QueryInterface {
     pool;
@@ -243,6 +258,13 @@ export class QueryInterface {
     relationLoadStrategy;
     /** Nested-relation JSON encoding: 'object' (default) or 'positional'. */
     jsonEncoding;
+    /**
+     * Client-level automatic WHERE filters keyed by table accessor (soft-delete /
+     * multi-tenancy). AND-merged into every query on the keyed table and every
+     * relation subquery targeting it. Undefined when none are configured, in
+     * which case every path is byte-identical to the pre-0.28 behavior.
+     */
+    globalFilters;
     /**
      * Tracks tables that have already triggered an unlimited-query warning so
      * the user is not spammed once per row. Per-instance state — each
@@ -274,6 +296,15 @@ export class QueryInterface {
     options;
     /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
     currentAction = 'raw';
+    /**
+     * The active query's `skipGlobalFilters` opt-out, set at the top of each
+     * `build*` method and read deep in the (synchronous) SQL-build + param-collect
+     * tree — so relation subqueries, relation filters, `_count`, and relation
+     * `orderBy` all see it without threading it through dozens of signatures.
+     * Only load-bearing when {@link globalFilters} is configured; build+collect are
+     * synchronous per call, so this transient is never observed across an await.
+     */
+    currentSkip;
     constructor(pool, table, schema, middlewares, options) {
         this.pool = pool;
         this.table = table;
@@ -295,6 +326,10 @@ export class QueryInterface {
         this.dialect = options?.dialect ?? postgresDialect;
         this.relationLoadStrategy = options?.relationLoadStrategy ?? 'join';
         this.jsonEncoding = options?.jsonEncoding ?? 'object';
+        // Only retain the map when it has at least one entry, so `globalFilters`
+        // stays `undefined` (and every merge path a no-op) for the common case.
+        this.globalFilters =
+            options?.globalFilters && Object.keys(options.globalFilters).length > 0 ? options.globalFilters : undefined;
         this.txScoped = options?._txScoped ?? false;
         this.options = options;
         // Pre-compute column type lookup maps (TASK-26)
@@ -414,7 +449,7 @@ export class QueryInterface {
      * and unlimited-warnings silenced — a relation load must fetch every matching
      * child, and the per-relation `limit` is applied client-side by the loader.
      */
-    batchedContext(timeout) {
+    batchedContext(timeout, skip) {
         const childOptions = {
             ...this.options,
             defaultLimit: undefined,
@@ -429,6 +464,22 @@ export class QueryInterface {
             buildInClause: (expr, paramRef, negated) => this.inClause(expr, paramRef, negated),
             inClauseParam: (values) => this.inParam(values),
             paramPlaceholder: (index) => this.p(index),
+            skipGlobalFilters: skip,
+            tableGlobalFilter: (table, alias, precedingParams) => {
+                const gf = this.resolveGlobalFilter(table, skip);
+                if (!gf)
+                    return null;
+                const meta = this.schema.tables[table];
+                if (!meta)
+                    return null;
+                // Seed the param array with `precedingParams` placeholders so
+                // buildAliasWhere numbers the gf params after the already-bound ones.
+                const seeded = new Array(precedingParams).fill(undefined);
+                const clause = this.buildAliasWhere(table, meta, alias, gf, seeded);
+                if (!clause)
+                    return null;
+                return { clause, params: seeded.slice(precedingParams) };
+            },
         };
     }
     /**
@@ -440,13 +491,18 @@ export class QueryInterface {
      */
     async runFindManyBatched(args) {
         const withClause = args.with;
+        // Capture the opt-out from the ARGS before any await: this.currentSkip is
+        // instance state on a cached accessor, so a concurrent build during the
+        // base-query await would overwrite it (tenant query loading relations with
+        // another query's skipGlobalFilters).
+        const skip = args.skipGlobalFilters;
         const { baseArgs, strip } = this.prepareBatchedBase(args, withClause);
         // baseArgs.with is always undefined here; the cast just bridges the R generic.
         const deferred = this.buildFindMany(baseArgs);
         const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
         const entities = deferred.transform(result);
         if (entities.length > 0) {
-            await loadRelationsBatched(this.batchedContext(args.timeout), entities, withClause, args.timeout);
+            await loadRelationsBatched(this.batchedContext(args.timeout, skip), entities, withClause, args.timeout);
         }
         stripFields(entities, strip);
         return entities;
@@ -668,18 +724,22 @@ export class QueryInterface {
         const entity = deferred.transform(result);
         if (!entity)
             return null;
-        await loadRelationsBatched(this.batchedContext(args.timeout), [entity], withClause, args.timeout);
+        await loadRelationsBatched(this.batchedContext(args.timeout, args.skipGlobalFilters), [entity], withClause, args.timeout);
         stripFields([entity], proj.strip);
         return entity;
     }
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindUnique(args) {
+        this.currentSkip = args.skipGlobalFilters;
         const columnsList = this.resolveColumns(args.select, args.omit);
-        const whereObj = args.where;
+        // A global filter turns the where into `{ AND: [...] }`, which the
+        // `isSimpleWhere` test below rejects → the general (buildWhereClause) path
+        // handles the merge and its params uniformly.
+        const whereObj = (this.mergeGlobalFilter(args.where) ?? {});
         const colKey = columnsList ? columnsList.join(',') : '*';
         const whereFingerprint = this.fingerprintWhere(whereObj);
         const withFp = args.with ? this.withFingerprint(args.with) : '';
-        const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}`;
+        const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}${this.globalFilterCacheSegment()}`;
         const params = [];
         // Check if all where values are simple (plain equality, no operators/null/OR).
         // Keys are sorted to match fingerprintWhere — insertion order here would let
@@ -835,24 +895,21 @@ export class QueryInterface {
     }
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindMany(args) {
+        this.currentSkip = args?.skipGlobalFilters;
         const columnsList = this.resolveColumns(args?.select, args?.omit);
         const colKey = columnsList ? columnsList.join(',') : '*';
-        const whereObj = (args?.where ?? {});
+        // AND-merge this table's global filter into the user where; `hasWhere` gates
+        // the build/collect just like `args?.where` did (a merged filter can make
+        // an otherwise-absent where present).
+        const effWhere = this.mergeGlobalFilter(args?.where);
+        const hasWhere = effWhere !== undefined;
+        const whereObj = (effWhere ?? {});
         // Build fingerprint for cache lookup
-        const whereFp = args?.where ? this.fingerprintWhere(whereObj) : '';
+        const whereFp = hasWhere ? this.fingerprintWhere(whereObj) : '';
         const withFp = args?.with ? this.withFingerprint(args.with) : '';
         const orderFp = args?.orderBy
             ? Object.entries(args.orderBy)
-                .map(([k, d]) => {
-                // Vector KNN ordering changes the emitted SQL operator by metric and
-                // adds a `::vector` param, so the metric + direction must be part of
-                // the cache key — otherwise two KNN queries differing only in metric
-                // would collide on a single cached SQL string.
-                if (isVectorOrderBy(d)) {
-                    return `${k}:vec(${d.distance.metric},${d.distance.direction ?? 'asc'})`;
-                }
-                return `${k}:${d}`;
-            })
+                .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d)}`)
                 .join(',')
             : '';
         const cursorFp = args?.cursor
@@ -865,12 +922,12 @@ export class QueryInterface {
         const effectiveLimit = args?.take ?? args?.limit ?? this.defaultLimit;
         const limitFp = effectiveLimit !== undefined ? '1' : '0';
         const offsetFp = args?.offset !== undefined ? '1' : '0';
-        const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}`;
+        const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}${this.globalFilterCacheSegment()}`;
         const params = [];
         const entry = this.acquireSql(ck, () => {
             // Fresh build — generates SQL and populates freshParams
             const freshParams = [];
-            const { sql: freshWhereSql } = args?.where
+            const { sql: freshWhereSql } = hasWhere
                 ? (() => {
                     const clause = this.buildWhereClause(whereObj, freshParams);
                     return { sql: clause ? ` WHERE ${clause}` : '' };
@@ -900,8 +957,11 @@ export class QueryInterface {
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
-                        const dir = args.orderBy?.[k] ?? 'asc';
-                        const op = dir === 'desc' ? '<' : '>';
+                        // orderBy values can be the { sort, nulls } spec form — normalize
+                        // before comparing, or a desc spec would seek the ascending side.
+                        const dir = args.orderBy?.[k];
+                        const desc = isOrderBySpec(dir) ? dir.sort === 'desc' : dir === 'desc';
+                        const op = desc ? '<' : '>';
                         freshParams.push(v);
                         return `${qt}.${col} ${op} ${this.p(freshParams.length)}`;
                     });
@@ -948,8 +1008,8 @@ export class QueryInterface {
             return sql;
         });
         // Collect params in exact build order:
-        // 1. WHERE params
-        if (args?.where) {
+        // 1. WHERE params (includes the AND-merged global filter, if any)
+        if (hasWhere) {
             this.collectWhereParams(whereObj, params);
         }
         // 2. WITH relation params
@@ -1161,6 +1221,8 @@ export class QueryInterface {
         });
     }
     buildCreate(args) {
+        this.assertWritable('create');
+        this.assertNoGeneratedColumns(args.data, 'create');
         const entries = Object.entries(args.data).filter(([, v]) => v !== undefined);
         const columns = entries.map(([k]) => this.toSqlColumn(k));
         const params = entries.map(([, v]) => v);
@@ -1235,6 +1297,10 @@ export class QueryInterface {
                 tag: `${this.table}.createMany`,
             };
         }
+        this.assertWritable('createMany');
+        for (const row of args.data) {
+            this.assertNoGeneratedColumns(row, 'createMany');
+        }
         const keys = Object.keys(args.data[0]).filter((k) => args.data[0][k] !== undefined);
         const columns = keys.map((k) => this.toColumn(k));
         const rowValues = args.data.map((row) => {
@@ -1272,12 +1338,22 @@ export class QueryInterface {
         });
     }
     buildUpdate(args) {
+        this.assertWritable('update');
+        this.currentSkip = args.skipGlobalFilters;
         const dataObj = args.data;
-        const whereObj = args.where;
+        this.assertNoGeneratedColumns(dataObj, 'update');
+        const userWhere = args.where;
         const lock = args.optimisticLock;
+        // 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 = !this.userPredicateIsEmpty(userWhere) || !!lock;
+        this.assertMutationHasPredicate('update', userHasPredicate ? ' WHERE x' : '', args.allowFullTableScan);
+        // The SQL is built from the global-filter-merged where (soft-delete keeps an
+        // update from touching already-deleted rows).
+        const whereObj = (this.mergeGlobalFilter(userWhere) ?? {});
         const setFp = this.fingerprintSet(dataObj);
         const whereFp = this.fingerprintWhere(whereObj);
-        const ck = lock ? null : `u:${setFp}|${whereFp}`;
+        const ck = lock ? null : `u:${setFp}|${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
         const buildSql = () => {
             const freshParams = [];
@@ -1295,7 +1371,6 @@ export class QueryInterface {
                 const versionCheck = `${versionCol} = ${this.p(freshParams.length)}`;
                 whereSql = whereSql ? `${whereSql} AND ${versionCheck}` : ` WHERE ${versionCheck}`;
             }
-            this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
             // Engines that inject their returning shape MID-statement (SQL Server
             // `OUTPUT INSERTED.*` between SET and WHERE) override buildUpdateStatement;
             // absent → the trailing-clause PG/SQLite/MySQL form (byte-identical).
@@ -1309,9 +1384,6 @@ export class QueryInterface {
             const entry = this.acquireSql(ck, buildSql);
             sql = entry.sql;
             preparedName = entry.name;
-            if (whereFp === '') {
-                this.assertMutationHasPredicate('update', '', args.allowFullTableScan);
-            }
         }
         else {
             sql = buildSql();
@@ -1445,27 +1517,24 @@ export class QueryInterface {
         });
     }
     buildDelete(args) {
-        const whereObj = args.where;
+        this.assertWritable('delete');
+        this.currentSkip = args.skipGlobalFilters;
+        // Guard the USER predicate (a global filter must not satisfy the guard).
+        this.assertMutationHasPredicate('delete', this.userPredicateIsEmpty(args.where) ? '' : ' WHERE x', args.allowFullTableScan);
+        const whereObj = (this.mergeGlobalFilter(args.where) ?? {});
         const whereFp = this.fingerprintWhere(whereObj);
-        const ck = `d:${whereFp}`;
+        const ck = `d:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
-        // We need to check the mutation predicate. Build the whereSql to test it.
-        // On cache hit we still need to validate (the shape may be empty).
         const entry = this.acquireSql(ck, () => {
             const freshParams = [];
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
-            this.assertMutationHasPredicate('delete', whereSql, args.allowFullTableScan);
             // SQL Server injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and WHERE;
             // absent override → the trailing-clause PG/SQLite/MySQL form (byte-identical).
             return this.dialect.buildDeleteStatement
                 ? this.dialect.buildDeleteStatement({ table: this.q(this.table), whereSql, returning: '*' })
                 : `DELETE FROM ${this.q(this.table)}${whereSql}${this.dialect.buildReturningClause('*')}`;
         });
-        // On cache hit, still validate the predicate
-        if (whereFp === '') {
-            this.assertMutationHasPredicate('delete', '', args.allowFullTableScan);
-        }
         this.collectWhereParams(whereObj, params);
         return {
             sql: entry.sql,
@@ -1505,6 +1574,10 @@ export class QueryInterface {
         });
     }
     buildUpsert(args) {
+        this.assertWritable('upsert');
+        this.assertNoGeneratedColumns(args.create, 'upsert');
+        this.assertNoGeneratedColumns(args.update, 'upsert');
+        this.currentSkip = args.skipGlobalFilters;
         // Build the INSERT part from create data
         const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
         const columns = createEntries.map(([k]) => this.toSqlColumn(k));
@@ -1523,12 +1596,23 @@ export class QueryInterface {
         });
         const updateParams = updateEntries.map(([, v]) => v);
         const params = [...createParams, ...updateParams];
+        // Global filter → restrict the conflict-UPDATE (soft-delete / tenancy) so an
+        // upsert never resurrects a soft-deleted row or writes across tenants. Only
+        // on engines whose upsert can carry a predicate (Postgres); the gf params
+        // continue the placeholder numbering after create+update params.
+        let updateWhere;
+        if (this.dialect.supportsUpsertUpdateWhere) {
+            const gf = this.resolveGlobalFilter(this.table);
+            if (gf)
+                updateWhere = this.buildWhereClause(gf, params) ?? undefined;
+        }
         const sql = this.dialect.buildUpsertStatement({
             table: this.q(this.table),
             insertColumns: columns,
             valuePlaceholders: placeholders,
             conflictColumns,
             updateSetClauses: setClauses,
+            updateWhere,
             returning: '*',
         });
         return {
@@ -1551,7 +1635,7 @@ export class QueryInterface {
             reselect: this.dialect.resultStrategy === 'reselect'
                 ? async (exec) => {
                     await exec(sql, params);
-                    const sel = this.buildReselectByWhere(args.where);
+                    const sel = this.buildReselectByWhere((this.mergeGlobalFilter(args.where) ?? {}));
                     return exec(sel.sql, sel.params);
                 }
                 : undefined,
@@ -1568,11 +1652,15 @@ export class QueryInterface {
         });
     }
     buildUpdateMany(args) {
+        this.assertWritable('updateMany');
+        this.currentSkip = args.skipGlobalFilters;
         const dataObj = args.data;
-        const whereObj = args.where;
+        this.assertNoGeneratedColumns(dataObj, 'updateMany');
+        this.assertMutationHasPredicate('updateMany', this.userPredicateIsEmpty(args.where) ? '' : ' WHERE x', args.allowFullTableScan);
+        const whereObj = (this.mergeGlobalFilter(args.where) ?? {});
         const setFp = this.fingerprintSet(dataObj);
         const whereFp = this.fingerprintWhere(whereObj);
-        const ck = `um:${setFp}|${whereFp}`;
+        const ck = `um:${setFp}|${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
         const entry = this.acquireSql(ck, () => {
             const freshParams = [];
@@ -1580,12 +1668,8 @@ export class QueryInterface {
             const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
             const whereClause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
-            this.assertMutationHasPredicate('updateMany', whereSql, args.allowFullTableScan);
             return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
         });
-        if (whereFp === '') {
-            this.assertMutationHasPredicate('updateMany', '', args.allowFullTableScan);
-        }
         this.collectSetParams(dataObj, params);
         this.collectWhereParams(whereObj, params);
         return {
@@ -1607,20 +1691,19 @@ export class QueryInterface {
         });
     }
     buildDeleteMany(args) {
-        const whereObj = args.where;
+        this.assertWritable('deleteMany');
+        this.currentSkip = args.skipGlobalFilters;
+        this.assertMutationHasPredicate('deleteMany', this.userPredicateIsEmpty(args.where) ? '' : ' WHERE x', args.allowFullTableScan);
+        const whereObj = (this.mergeGlobalFilter(args.where) ?? {});
         const whereFp = this.fingerprintWhere(whereObj);
-        const ck = `dm:${whereFp}`;
+        const ck = `dm:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
         const entry = this.acquireSql(ck, () => {
             const freshParams = [];
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
-            this.assertMutationHasPredicate('deleteMany', whereSql, args.allowFullTableScan);
             return `DELETE FROM ${this.q(this.table)}${whereSql}`;
         });
-        if (whereFp === '') {
-            this.assertMutationHasPredicate('deleteMany', '', args.allowFullTableScan);
-        }
         this.collectWhereParams(whereObj, params);
         return {
             sql: entry.sql,
@@ -1641,17 +1724,20 @@ export class QueryInterface {
         });
     }
     buildCount(args) {
-        const whereObj = (args?.where ?? {});
-        const whereFp = args?.where ? this.fingerprintWhere(whereObj) : '';
-        const ck = `cnt:${whereFp}`;
+        this.currentSkip = args?.skipGlobalFilters;
+        const effWhere = this.mergeGlobalFilter(args?.where);
+        const hasWhere = effWhere !== undefined;
+        const whereObj = (effWhere ?? {});
+        const whereFp = hasWhere ? this.fingerprintWhere(whereObj) : '';
+        const ck = `cnt:${whereFp}${this.globalFilterCacheSegment()}`;
         const params = [];
         const entry = this.acquireSql(ck, () => {
             const freshParams = [];
-            const clause = args?.where ? this.buildWhereClause(whereObj, freshParams) : null;
+            const clause = hasWhere ? this.buildWhereClause(whereObj, freshParams) : null;
             const whereSql = clause ? ` WHERE ${clause}` : '';
             return `SELECT ${this.castAgg('COUNT(*)', 'int')} AS count FROM ${this.q(this.table)}${whereSql}`;
         });
-        if (args?.where) {
+        if (hasWhere) {
             this.collectWhereParams(whereObj, params);
         }
         return {
@@ -1681,9 +1767,13 @@ export class QueryInterface {
                 }
             }
         }
+        this.currentSkip = args.skipGlobalFilters;
         const groupColsRaw = args.by.map((k) => this.toColumn(k));
         const groupCols = groupColsRaw.map((c) => this.q(c));
-        const { sql: whereSql, params } = args.where ? this.buildWhere(args.where) : { sql: '', params: [] };
+        const gbWhere = this.mergeGlobalFilter(args.where);
+        const { sql: whereSql, params } = gbWhere
+            ? this.buildWhere(gbWhere)
+            : { sql: '', params: [] };
         // Build SELECT expressions: group-by columns + aggregate functions
         const selectExprs = [...groupCols];
         // _count
@@ -1926,7 +2016,11 @@ export class QueryInterface {
         });
     }
     buildAggregate(args) {
-        const { sql: whereSql, params } = args.where ? this.buildWhere(args.where) : { sql: '', params: [] };
+        this.currentSkip = args.skipGlobalFilters;
+        const aggWhere = this.mergeGlobalFilter(args.where);
+        const { sql: whereSql, params } = aggWhere
+            ? this.buildWhere(aggWhere)
+            : { sql: '', params: [] };
         const meta = this.schema.tables[this.table];
         if (meta) {
             for (const group of [args._sum, args._avg, args._min, args._max]) {
@@ -2104,6 +2198,36 @@ export class QueryInterface {
         }
         return null;
     }
+    /**
+     * Reject any write against a view (H4). Views are introspected with
+     * `isView: true` and are read-only in every engine; a write raises a
+     * {@link ValidationError} (E003) rather than emitting SQL Postgres would
+     * reject (or, worse, silently applying to an updatable view).
+     */
+    assertWritable(operation) {
+        if (this.tableMeta.isView) {
+            throw new ValidationError(`[turbine] Cannot ${operation} "${this.table}": it is a view (read-only). ` +
+                'Views support reads (findMany/findFirst/…) but not writes.');
+        }
+    }
+    /**
+     * Reject a write whose `data` names a `GENERATED ALWAYS AS (...) STORED`
+     * column (H3). Postgres computes these from other columns and errors if you
+     * try to write them; we fail early with a clear {@link ValidationError} (E003)
+     * instead of surfacing a cryptic driver error. Undefined values are ignored
+     * (they're stripped from the statement anyway).
+     */
+    assertNoGeneratedColumns(data, operation) {
+        for (const [key, value] of Object.entries(data)) {
+            if (value === undefined)
+                continue;
+            const col = this.tableMeta.columns.find((c) => c.field === key || c.name === key || c.name === camelToSnake(key));
+            if (col?.isGeneratedStored) {
+                throw new ValidationError(`[turbine] Cannot ${operation} "${this.table}": column "${key}" is a GENERATED ALWAYS AS (…) STORED ` +
+                    'column whose value the database computes — remove it from your data.');
+            }
+        }
+    }
     /** Convert camelCase field name to snake_case column name (unquoted, for non-SQL uses) */
     toColumn(field) {
         const mapped = this.tableMeta.columnMap[field];
@@ -2433,16 +2557,7 @@ export class QueryInterface {
                     'none' in filterObj ||
                     'is' in filterObj ||
                     'isNot' in filterObj) {
-                    if (filterObj.some !== undefined && filterObj.some !== null)
-                        this.collectRelFilterParams(relationDef.to, filterObj.some, params);
-                    if (filterObj.none !== undefined && filterObj.none !== null)
-                        this.collectRelFilterParams(relationDef.to, filterObj.none, params);
-                    if (filterObj.every !== undefined && filterObj.every !== null)
-                        this.collectRelFilterParams(relationDef.to, filterObj.every, params);
-                    if (filterObj.is !== undefined && filterObj.is !== null)
-                        this.collectRelFilterParams(relationDef.to, filterObj.is, params);
-                    if (filterObj.isNot !== undefined && filterObj.isNot !== null)
-                        this.collectRelFilterParams(relationDef.to, filterObj.isNot, params);
+                    this.collectRelationFilterParams(relationDef, filterObj, params);
                     continue;
                 }
             }
@@ -2490,7 +2605,45 @@ export class QueryInterface {
             params.push(value);
         }
     }
-    /** Collect params from a relation filter sub-where. Mirrors buildSubWhereForRelation. */
+    /**
+     * Param-collect mirror of {@link buildRelationFilter} for one relation-filter
+     * object (`{ some/every/none/is/isNot }`, already normalized). Pushes, per
+     * present branch and in the canonical order some→none→every→is→isNot, the
+     * branch's sub-where params THEN the target table's global-filter params —
+     * exactly the order buildRelationFilter emits. When no global filter applies
+     * the gf calls are no-ops, so this stays byte-identical to the pre-0.28 path.
+     * Shared by every collect site that mirrors buildRelationFilter
+     * (collectWhereParams, collectRelFilterParams, collectAliasWhereParams).
+     */
+    collectRelationFilterParams(relDef, filterObj, params) {
+        const target = relDef.to;
+        if (filterObj.some !== undefined && filterObj.some !== null) {
+            this.collectRelFilterParams(target, filterObj.some, params);
+            this.collectTargetGlobalFilterExists(target, params);
+        }
+        if (filterObj.none !== undefined && filterObj.none !== null) {
+            this.collectRelFilterParams(target, filterObj.none, params);
+            this.collectTargetGlobalFilterExists(target, params);
+        }
+        if (filterObj.every !== undefined && filterObj.every !== null) {
+            // gf is only emitted (build) when the `every` sub-where compiles to a
+            // filter — otherwise `every` is trivially true and no subquery is built.
+            if (this.buildSubWhereForRelation(target, filterObj.every, []) !== null) {
+                this.collectRelFilterParams(target, filterObj.every, params);
+                this.collectTargetGlobalFilterExists(target, params);
+            }
+        }
+        if (filterObj.is !== undefined) {
+            if (filterObj.is !== null)
+                this.collectRelFilterParams(target, filterObj.is, params);
+            this.collectTargetGlobalFilterExists(target, params);
+        }
+        if (filterObj.isNot !== undefined) {
+            if (filterObj.isNot !== null)
+                this.collectRelFilterParams(target, filterObj.isNot, params);
+            this.collectTargetGlobalFilterExists(target, params);
+        }
+    }
     collectRelFilterParams(targetTable, subWhere, params) {
         const meta = this.schema.tables[targetTable];
         if (!meta)
@@ -2518,17 +2671,9 @@ export class QueryInterface {
             if (nestedRel && typeof value === 'object' && !Array.isArray(value)) {
                 const norm = this.normalizeRelationFilter(nestedRel, value);
                 if ('some' in norm || 'every' in norm || 'none' in norm || 'is' in norm || 'isNot' in norm) {
-                    // Same order as buildRelationFilter pushes params: some, none, every, is, isNot.
-                    if (norm.some != null)
-                        this.collectRelFilterParams(nestedRel.to, norm.some, params);
-                    if (norm.none != null)
-                        this.collectRelFilterParams(nestedRel.to, norm.none, params);
-                    if (norm.every != null)
-                        this.collectRelFilterParams(nestedRel.to, norm.every, params);
-                    if (norm.is != null)
-                        this.collectRelFilterParams(nestedRel.to, norm.is, params);
-                    if (norm.isNot != null)
-                        this.collectRelFilterParams(nestedRel.to, norm.isNot, params);
+                    // Mirrors buildRelationFilter (some→none→every→is→isNot, each: sub-where
+                    // params then target global-filter params).
+                    this.collectRelationFilterParams(nestedRel, norm, params);
                     continue;
                 }
             }
@@ -2608,6 +2753,21 @@ export class QueryInterface {
                 // never push a param that the build path rejected (or vice versa).
                 this.vectorOperator(key, rawColumn, dir.distance.metric);
                 this.pushVectorParam(key, rawColumn, dir.distance.to, params);
+                continue;
+            }
+            // To-many relation orderBy (`{ posts: { _count } }`) uses the same count
+            // subquery as `_count` — mirror its global-filter params. To-one relation
+            // orderBy carries the target's global filter once per ordered column.
+            if (this.isRelationOrderByValue(dir)) {
+                const relDef = this.tableMeta.relations[key];
+                if (relDef && (relDef.type === 'hasMany' || relDef.type === 'manyToMany')) {
+                    this.collectRelationCountParams(relDef, params);
+                }
+                else if (relDef) {
+                    for (const _col of Object.keys(dir)) {
+                        this.collectTargetGlobalFilterAlias(relDef.to, params);
+                    }
+                }
             }
         }
     }
@@ -2643,6 +2803,19 @@ export class QueryInterface {
             const spec = withClause[relName];
             if (!spec)
                 continue;
+            // Reserved `_count` key — fingerprint by the selected relation set so
+            // `_count: true` and `_count: { posts: true }` never share a cache entry.
+            if (relName === '_count') {
+                const c = spec;
+                parts.push(c === true
+                    ? '_count(*)'
+                    : `_count(${Object.entries(c)
+                        .filter(([, v]) => v)
+                        .map(([k]) => k)
+                        .sort()
+                        .join(',')})`);
+                continue;
+            }
             const relDef = meta.relations[relName];
             if (!relDef) {
                 parts.push(`unknown:${relName}`);
@@ -2675,9 +2848,9 @@ export class QueryInterface {
             if (opts.where) {
                 subParts.push(`w=${this.fingerprintAliasWhere(opts.where, meta.relations[relName]?.to)}`);
             }
-            // orderBy shape
+            // orderBy shape (OrderBySpec nulls placement changes the SQL, so fingerprint it)
             if (opts.orderBy) {
-                const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${d}`);
+                const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d)}`);
                 subParts.push(`o=${oEntries.join(',')}`);
             }
             // limit presence
@@ -2708,6 +2881,15 @@ export class QueryInterface {
                 continue;
             this.collectRelationSubqueryParams(relDef, relSpec, params, table ?? this.table);
         }
+        // `_count` global-filter params — mirror buildSelectWithRelations, which
+        // appends the count subqueries (and any target-filter params) AFTER every
+        // relation subquery, in resolveCountRelations order.
+        const countSpec = withClause._count;
+        if (countSpec !== undefined) {
+            for (const rel of resolveCountRelations(meta, countSpec)) {
+                this.collectRelationCountParams(rel, params);
+            }
+        }
     }
     /**
      * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
@@ -2725,6 +2907,7 @@ export class QueryInterface {
             if (spec.where) {
                 this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
             }
+            this.collectTargetGlobalFilterAlias(targetTable, params);
             if (spec.limit !== undefined && !this.dialect.inlineLimitOffset) {
                 params.push(Number(spec.limit));
             }
@@ -2754,6 +2937,9 @@ export class QueryInterface {
         if (spec.where) {
             this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
         }
+        // Global filter on the target — mirrors targetGlobalFilterAlias in
+        // buildRelationSubquery (pushed after spec.where, before limit).
+        this.collectTargetGlobalFilterAlias(targetTable, params);
         // limit param — only hasMany parameterizes its limit (mirrors
         // buildRelationSubquery). belongsTo/hasOne ignore limit (always LIMIT 1), so
         // pushing one here would orphan a param and desync the collect path.
@@ -2823,14 +3009,148 @@ export class QueryInterface {
             return { sql: '', params: [] };
         return { sql: ` WHERE ${clause}`, params };
     }
+    // -------------------------------------------------------------------------
+    // Global filters (soft-delete / multi-tenancy — WS-G)
+    //
+    // A configured global filter for a table is AND-merged into the compiled WHERE
+    // of every query on that table (via {@link mergeGlobalFilter}, so the merge is
+    // captured in the where fingerprint/collect for free) and into every relation
+    // subquery targeting it (rendered at build time against the subquery's alias/
+    // table by the `*GlobalFilterAlias`/`*GlobalFilterExists` helpers, with the
+    // shape folded into the SQL-cache key via {@link globalFilterCacheSegment}).
+    // Function filters are evaluated per resolve — at query-build time — enabling
+    // per-request tenancy via a closure. They must return a STABLE shape (same
+    // keys/operators); only values may vary between calls.
+    // -------------------------------------------------------------------------
     /**
-     * Refuse mutations with an empty predicate unless explicitly opted in.
-     *
-     * An empty `where` (e.g. `{}` or `{ id: undefined }`) resolves to a
-     * mutation with no filter — a common footgun when a caller's filter
-     * value accidentally resolves to `undefined`. This guard throws
-     * `ValidationError` in that case unless `allowFullTableScan: true`.
+     * Resolve the configured global filter for `table`, evaluating a function
+     * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
+     * no filter applies, the query opted out, or the filter is empty.
+     */
+    resolveGlobalFilter(table, skip = this.currentSkip) {
+        const filters = this.globalFilters;
+        if (!filters)
+            return null;
+        if (skip === true)
+            return null;
+        if (Array.isArray(skip) && skip.includes(table))
+            return null;
+        const raw = filters[table];
+        if (raw === undefined)
+            return null;
+        const resolved = typeof raw === 'function' ? raw() : raw;
+        if (resolved === null || resolved === undefined)
+            return null;
+        const obj = resolved;
+        // An all-undefined filter (e.g. `{ tenantId: undefined }`) contributes
+        // nothing — treat it as absent so it never emits a dangling clause.
+        if (Object.keys(obj).every((k) => obj[k] === undefined))
+            return null;
+        return obj;
+    }
+    /**
+     * 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
+     * reference, so fingerprints/SQL stay byte-identical to the pre-0.28 path.
+     */
+    mergeGlobalFilter(userWhere) {
+        const gf = this.resolveGlobalFilter(this.table);
+        if (!gf)
+            return userWhere;
+        if (userWhere === undefined)
+            return gf;
+        return { AND: [userWhere, gf] };
+    }
+    /**
+     * SQL clause for `targetTable`'s global filter rendered against `alias`
+     * (relation subqueries, `_count`, relation `orderBy`). Pushes its params to
+     * `params`; returns `''` when no filter applies. Mirror:
+     * {@link collectTargetGlobalFilterAlias}.
+     */
+    targetGlobalFilterAlias(targetTable, alias, params) {
+        const gf = this.resolveGlobalFilter(targetTable);
+        if (!gf)
+            return '';
+        const meta = this.schema.tables[targetTable];
+        if (!meta)
+            return '';
+        return this.buildAliasWhere(targetTable, meta, alias, gf, params) ?? '';
+    }
+    /** Param-collect mirror of {@link targetGlobalFilterAlias}. */
+    collectTargetGlobalFilterAlias(targetTable, params) {
+        const gf = this.resolveGlobalFilter(targetTable);
+        if (!gf)
+            return;
+        const meta = this.schema.tables[targetTable];
+        if (!meta)
+            return;
+        this.collectAliasWhereParams(targetTable, meta, gf, params);
+    }
+    /**
+     * SQL clause for `targetTable`'s global filter rendered against the bare
+     * (unaliased) table name — the form used inside relation-filter `EXISTS`
+     * subqueries. Pushes its params; `''` when none. Mirror:
+     * {@link collectTargetGlobalFilterExists}.
      */
+    targetGlobalFilterExists(targetTable, params) {
+        const gf = this.resolveGlobalFilter(targetTable);
+        if (!gf)
+            return '';
+        return this.buildSubWhereForRelation(targetTable, gf, params) ?? '';
+    }
+    /** Param-collect mirror of {@link targetGlobalFilterExists}. */
+    collectTargetGlobalFilterExists(targetTable, params) {
+        const gf = this.resolveGlobalFilter(targetTable);
+        if (!gf)
+            return;
+        this.collectRelFilterParams(targetTable, gf, params);
+    }
+    /**
+     * Value-invariant SQL-cache-key segment for the active global-filter
+     * environment. Relation-subquery / relation-filter / `_count` / relation-
+     * `orderBy` global filters are rendered at build time but their SHAPE is not
+     * otherwise in the where/with fingerprint, so this segment guards the cache:
+     * two different filter shapes never collide on one cached SQL text, while two
+     * function-filter results of the SAME shape (differing only in values) share
+     * the entry and bind their own params. Empty (`''`) when no filter applies, so
+     * cache keys stay byte-identical when the feature is unused.
+     */
+    globalFilterCacheSegment() {
+        const filters = this.globalFilters;
+        if (!filters)
+            return '';
+        const parts = [];
+        for (const table of Object.keys(filters).sort()) {
+            // Function filters for OTHER tables may be request-scoped closures that
+            // throw outside their own context; a query on an unrelated table must not
+            // break on them. A throwing filter can't have contributed SQL to this
+            // query either (merging it would have thrown first), so a constant
+            // marker keeps the key shape-distinct without evaluating it.
+            let gf;
+            try {
+                gf = this.resolveGlobalFilter(table);
+            }
+            catch {
+                parts.push(`${table}:!`);
+                continue;
+            }
+            if (gf)
+                parts.push(`${table}:${this.fingerprintWhere(gf)}`);
+        }
+        return parts.length ? `|gf=${parts.join(';')}` : '';
+    }
+    /**
+     * True when the USER-supplied `where` compiles to no predicate (`{}`,
+     * `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …). This is the exact
+     * signal the empty-`where` guard needs — the compiled emptiness, NOT the
+     * fingerprint (which is non-empty for an all-undefined `OR`/`AND`). It ignores
+     * any configured global filter, so a global filter never lets an unguarded
+     * mass mutation through.
+     */
+    userPredicateIsEmpty(userWhere) {
+        const throwaway = [];
+        return this.buildWhereClause(userWhere, throwaway) === null;
+    }
     assertMutationHasPredicate(operation, whereSql, allowFullTableScan) {
         if (whereSql.length > 0)
             return;
@@ -3002,55 +3322,69 @@ export class QueryInterface {
             // belongsTo: parent.fk = child.pk
             correlation = this.dialect.buildCorrelation(qt, relDef.referenceKey, qSelf, relDef.foreignKey);
         }
-        // "some": EXISTS (SELECT 1 FROM target WHERE correlation AND filter)
+        // The target table's global filter (soft-delete / tenancy) restricts the
+        // DOMAIN of correlated rows in EVERY branch: `some`/`none`/`is`/`isNot`
+        // ignore filtered-out rows, and `every` quantifies over only the surviving
+        // rows ("every NON-deleted related row matches P"). It is ANDed into the
+        // correlation and its params pushed AFTER the per-branch filter — mirrored
+        // exactly in collectWhereParams' relation-filter branch. `qt` is the bare
+        // target table, matching the `FROM ${qt}` here (see targetGlobalFilterExists).
+        const gfAnd = () => {
+            const gf = this.targetGlobalFilterExists(targetTable, params);
+            return gf ? ` AND ${gf}` : '';
+        };
+        // "some": EXISTS (SELECT 1 FROM target WHERE correlation AND filter AND gf)
         if (filterObj.some !== undefined) {
             const subWhere = filterObj.some;
             const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
-            const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
-            clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
+            const filterAnd = filterClause ? ` AND ${filterClause}` : '';
+            clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
         }
-        // "none": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND filter)
+        // "none": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND filter AND gf)
         if (filterObj.none !== undefined) {
             const subWhere = filterObj.none;
             const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
-            const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
-            clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
+            const filterAnd = filterClause ? ` AND ${filterClause}` : '';
+            clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
         }
-        // "every": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND NOT (filter))
+        // "every": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND gf AND NOT (filter))
         if (filterObj.every !== undefined) {
             const subWhere = filterObj.every;
             const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
             if (filterClause) {
-                clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation} AND NOT (${filterClause}))`);
+                // gf params pushed AFTER filter params (collect mirrors this order), but
+                // placed textually inside the domain so it restricts which rows count.
+                const gf = gfAnd();
+                clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${gf} AND NOT (${filterClause}))`);
             }
             else {
-                // "every" with empty filter = true (all match trivially)
+                // "every" with empty filter = true (all match trivially) — gf irrelevant.
             }
         }
         // "is": EXISTS — for to-one relations (same SQL as "some").
         // `is: null` = "no related row" (Prisma semantics) → NOT EXISTS.
         if (filterObj.is !== undefined) {
             if (filterObj.is === null) {
-                clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation})`);
+                clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${gfAnd()})`);
             }
             else {
                 const subWhere = filterObj.is;
                 const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
-                const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
-                clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
+                const filterAnd = filterClause ? ` AND ${filterClause}` : '';
+                clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
             }
         }
         // "isNot": NOT EXISTS — for to-one relations (same SQL as "none").
         // `isNot: null` = "a related row exists" → EXISTS.
         if (filterObj.isNot !== undefined) {
             if (filterObj.isNot === null) {
-                clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation})`);
+                clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${gfAnd()})`);
             }
             else {
                 const subWhere = filterObj.isNot;
                 const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
-                const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
-                clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
+                const filterAnd = filterClause ? ` AND ${filterClause}` : '';
+                clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
             }
         }
         return clauses.length > 0 ? clauses.join(' AND ') : null;
@@ -3245,17 +3579,9 @@ export class QueryInterface {
             if (aliasRel && typeof value === 'object' && !Array.isArray(value)) {
                 const norm = this.normalizeRelationFilter(aliasRel, value);
                 if ('some' in norm || 'every' in norm || 'none' in norm || 'is' in norm || 'isNot' in norm) {
-                    // Same order as buildRelationFilter pushes params: some, none, every, is, isNot.
-                    if (norm.some != null)
-                        this.collectRelFilterParams(aliasRel.to, norm.some, params);
-                    if (norm.none != null)
-                        this.collectRelFilterParams(aliasRel.to, norm.none, params);
-                    if (norm.every != null)
-                        this.collectRelFilterParams(aliasRel.to, norm.every, params);
-                    if (norm.is != null)
-                        this.collectRelFilterParams(aliasRel.to, norm.is, params);
-                    if (norm.isNot != null)
-                        this.collectRelFilterParams(aliasRel.to, norm.isNot, params);
+                    // Mirrors buildRelationFilter (some→none→every→is→isNot, each: sub-where
+                    // params then target global-filter params).
+                    this.collectRelationFilterParams(aliasRel, norm, params);
                     continue;
                 }
             }
@@ -3402,10 +3728,37 @@ export class QueryInterface {
      * findMany path). When `params` is omitted (groupBy / relation path) a vector
      * ordering throws — KNN ordering is only supported at the top level.
      */
+    /**
+     * Value-shape fingerprint for a single orderBy entry, so two queries whose
+     * ORDER BY differs only in nulls placement, vector metric, or relation-count
+     * vs relation-column never collide on one cached SQL string. Captures the
+     * SQL-shaping bits (direction, nulls, metric, relation keys) — never values.
+     */
+    orderByEntryFingerprint(d) {
+        // Vector KNN ordering changes the emitted operator by metric and adds a
+        // `::vector` param, so metric + direction must be part of the cache key.
+        if (isVectorOrderBy(d)) {
+            return `vec(${d.distance.metric},${d.distance.direction ?? 'asc'})`;
+        }
+        if (isOrderBySpec(d))
+            return `spec(${d.sort},${d.nulls ?? ''})`;
+        if (d && typeof d === 'object') {
+            // Relation ordering (`{ _count: 'desc' }` or `{ name: 'asc' }`).
+            return `rel(${Object.entries(d)
+                .map(([k, v]) => `${k}=${this.orderByEntryFingerprint(v)}`)
+                .sort()
+                .join(',')})`;
+        }
+        return String(d);
+    }
     buildOrderBy(orderBy, params) {
-        // Dev-only: validate that orderBy fields exist in the table schema
+        // Dev-only: validate that orderBy fields exist in the table schema. Relation
+        // orderBy keys (object values that are neither a vector nor an OrderBySpec)
+        // are validated in the relation branch below, so skip them here.
         if (process.env.NODE_ENV !== 'production') {
-            for (const key of Object.keys(orderBy)) {
+            for (const [key, value] of Object.entries(orderBy)) {
+                if (this.isRelationOrderByValue(value) && this.tableMeta.relations[key])
+                    continue;
                 const snakeKey = camelToSnake(key);
                 if (!this.tableMeta.columns.some((c) => c.name === snakeKey) && !(key in this.tableMeta.columnMap)) {
                     console.warn(`[turbine] Unknown orderBy field "${key}" for table "${this.tableMeta.name}". ` +
@@ -3414,28 +3767,217 @@ export class QueryInterface {
             }
         }
         const meta = this.schema.tables[this.table];
+        let relOrdCounter = 0;
         return Object.entries(orderBy)
-            .map(([key, dir]) => {
-            if (meta && !(key in meta.columnMap)) {
-                throw new ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${this.table}". ` +
-                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
-            }
+            .map(([key, value]) => {
             // Vector KNN ordering: { distance: { to, metric, direction? } }
-            if (isVectorOrderBy(dir)) {
+            if (isVectorOrderBy(value)) {
+                if (meta && !(key in meta.columnMap)) {
+                    throw new ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${this.table}". ` +
+                        `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
+                }
                 if (!params) {
                     throw new ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
                 }
                 const rawColumn = this.toColumn(key);
-                const operator = this.vectorOperator(key, rawColumn, dir.distance.metric);
-                const placeholder = this.pushVectorParam(key, rawColumn, dir.distance.to, params);
-                const safeDir = dir.distance.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+                const operator = this.vectorOperator(key, rawColumn, value.distance.metric);
+                const placeholder = this.pushVectorParam(key, rawColumn, value.distance.to, params);
+                const safeDir = value.distance.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${this.q(rawColumn)} ${operator} ${placeholder} ${safeDir}`;
             }
-            const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-            return `${this.toSqlColumn(key)} ${safeDir}`;
+            // Relation ordering: an object value that is not a vector or OrderBySpec,
+            // keyed by a relation name (`{ posts: { _count: 'desc' } }` / `{ author:
+            // { name: 'asc' } }`).
+            if (this.isRelationOrderByValue(value)) {
+                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params);
+            }
+            // Scalar column ordering — a plain direction or an OrderBySpec (nulls).
+            if (meta && !(key in meta.columnMap)) {
+                throw new ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${this.table}". ` +
+                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
+            }
+            const { dir, nulls } = normalizeOrderBy(value);
+            return `${this.toSqlColumn(key)} ${dir}${this.nullsSuffix(nulls)}`;
         })
             .join(', ');
     }
+    /**
+     * True when an orderBy value is a relation-ordering object: a plain object
+     * that is neither a vector KNN ordering nor an {@link OrderBySpec}. Its key
+     * in the orderBy clause is a relation name.
+     */
+    isRelationOrderByValue(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            !isVectorOrderBy(value) &&
+            !isOrderBySpec(value));
+    }
+    /**
+     * Render the ` NULLS FIRST` / ` NULLS LAST` suffix for a column ordering.
+     * Only PostgreSQL and SQLite support the `NULLS FIRST/LAST` grammar — on any
+     * other engine a caller asking for explicit nulls placement gets a clear
+     * {@link UnsupportedFeatureError} (E017) instead of broken SQL.
+     */
+    nullsSuffix(nulls) {
+        if (!nulls)
+            return '';
+        if (this.dialect.name !== 'postgresql' && this.dialect.name !== 'sqlite') {
+            throw new UnsupportedFeatureError('NULLS FIRST/LAST ordering', this.dialect.name, 'Explicit nulls placement in orderBy is only available on PostgreSQL and SQLite.');
+        }
+        return nulls === 'first' ? ' NULLS FIRST' : ' NULLS LAST';
+    }
+    /**
+     * Compile a relation ordering term. For a to-many relation the only allowed
+     * key is `_count`, which becomes a correlated `COUNT(*)` subquery. For a
+     * to-one relation each entry names a target column and becomes a correlated
+     * scalar subquery (supporting {@link OrderBySpec} nulls placement).
+     *
+     * Validation: relation must exist (E005); to-many only allows `_count`, and
+     * to-one only allows real target columns (E003).
+     */
+    buildRelationOrderBy(relName, value, alias, params) {
+        const relDef = this.tableMeta.relations[relName];
+        if (!relDef) {
+            throw new RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${this.table}". ` +
+                `Available: ${Object.keys(this.tableMeta.relations).join(', ')}`);
+        }
+        // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
+        if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
+            const keys = Object.keys(value);
+            if (keys.length !== 1 || keys[0] !== '_count') {
+                throw new ValidationError(`[turbine] orderBy on to-many relation "${relName}" only supports "_count" ` +
+                    `(got: ${keys.join(', ') || '(empty)'}).`);
+            }
+            const { dir } = normalizeOrderBy(value._count);
+            return `${this.buildRelationCountExpr(relDef, this.table, alias, params)} ${dir}`;
+        }
+        // To-one: each entry orders by a correlated scalar subquery on a target column.
+        const targetMeta = this.schema.tables[relDef.to];
+        if (!targetMeta)
+            throw new RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        const qTarget = this.q(relDef.to);
+        const qParent = this.q(this.table);
+        // belongsTo: alias.referenceKey = parent.foreignKey; hasOne: reversed.
+        const correlation = relDef.type === 'belongsTo'
+            ? this.dialect.buildCorrelation(alias, relDef.referenceKey, qParent, relDef.foreignKey)
+            : this.dialect.buildCorrelation(alias, relDef.foreignKey, qParent, relDef.referenceKey);
+        const entries = Object.entries(value);
+        if (entries.length === 0) {
+            throw new ValidationError(`[turbine] orderBy on to-one relation "${relName}" needs at least one target column.`);
+        }
+        return entries
+            .map(([col, dirValue]) => {
+            const snakeCol = camelToSnake(col);
+            if (!targetMeta.allColumns.includes(snakeCol)) {
+                throw new ValidationError(`[turbine] Unknown column "${col}" in orderBy on relation "${relName}" (table "${relDef.to}").`);
+            }
+            const { dir, nulls } = normalizeOrderBy(dirValue);
+            // Target's global filter applies here too — otherwise ordering keys off
+            // a soft-deleted / other-tenant related row's value (matches the with
+            // subquery semantics for belongsTo/hasOne).
+            let where = correlation;
+            if (params) {
+                const gf = this.targetGlobalFilterAlias(relDef.to, alias, params);
+                if (gf)
+                    where += ` AND ${gf}`;
+            }
+            return `(SELECT ${alias}.${this.q(snakeCol)} FROM ${qTarget} ${alias} WHERE ${where}${this.limitOneClause()}) ${dir}${this.nullsSuffix(nulls)}`;
+        })
+            .join(', ');
+    }
+    /**
+     * Build a correlated `(SELECT COUNT(*) …)` scalar subquery for a to-many
+     * relation, correlated to `parentRef`. hasMany counts child rows via the FK;
+     * manyToMany counts junction rows via the source key. Shared by the `_count`
+     * `with` key and to-many relation orderBy.
+     *
+     * When `params` is supplied and the target has a global filter, it is
+     * AND-merged so the count only sees surviving rows (a soft-deleted child is
+     * not counted): hasMany filters the counted rows directly; manyToMany adds an
+     * `EXISTS` on the target through the junction (the junction rows themselves
+     * carry no filter). Params are mirrored by {@link collectRelationCountParams}.
+     */
+    buildRelationCountExpr(relDef, parentRef, alias, params) {
+        const qParent = this.q(parentRef);
+        const count = this.castAgg('COUNT(*)', 'int');
+        if (relDef.type === 'manyToMany') {
+            if (!relDef.through) {
+                throw new ValidationError(`[turbine] manyToMany relation "${relDef.name}" is missing its \`through\` junction.`);
+            }
+            const qJ = this.q(relDef.through.table);
+            const jalias = `${alias}j`;
+            const sourceKeys = normalizeKeyColumns(relDef.through.sourceKey);
+            const refKeys = normalizeKeyColumns(relDef.referenceKey);
+            let where = sourceKeys
+                .map((jc, i) => `${jalias}.${this.q(jc)} = ${qParent}.${this.q(refKeys[i])}`)
+                .join(' AND ');
+            if (params) {
+                const targetExists = this.manyToManyTargetGlobalFilterExists(relDef, alias, jalias, params);
+                if (targetExists)
+                    where += ` AND ${targetExists}`;
+            }
+            return `(SELECT ${count} FROM ${qJ} ${jalias} WHERE ${where})`;
+        }
+        // hasMany: child FK correlates to the parent reference key.
+        const qTarget = this.q(relDef.to);
+        let where = this.dialect.buildCorrelation(alias, relDef.foreignKey, qParent, relDef.referenceKey);
+        if (params) {
+            const gf = this.targetGlobalFilterAlias(relDef.to, alias, params);
+            if (gf)
+                where += ` AND ${gf}`;
+        }
+        return `(SELECT ${count} FROM ${qTarget} ${alias} WHERE ${where})`;
+    }
+    /**
+     * `EXISTS (SELECT 1 FROM <target> <talias> WHERE <join> AND <gf>)` restricting
+     * a manyToMany `_count` to targets that survive their global filter. `''` when
+     * the target has no filter. Pushes gf params; mirror:
+     * {@link collectManyToManyTargetGlobalFilter}.
+     */
+    manyToManyTargetGlobalFilterExists(relDef, alias, jalias, params) {
+        const gf = this.resolveGlobalFilter(relDef.to);
+        if (!gf || !relDef.through)
+            return '';
+        const tMeta = this.schema.tables[relDef.to];
+        if (!tMeta || tMeta.primaryKey.length === 0)
+            return '';
+        const talias = `${alias}t`;
+        const targetKeys = normalizeKeyColumns(relDef.through.targetKey);
+        const pk = tMeta.primaryKey;
+        if (targetKeys.length !== pk.length)
+            return '';
+        const join = targetKeys.map((jc, i) => `${talias}.${this.q(pk[i])} = ${jalias}.${this.q(jc)}`).join(' AND ');
+        const gfClause = this.buildAliasWhere(relDef.to, tMeta, talias, gf, params);
+        const gfAnd = gfClause ? ` AND ${gfClause}` : '';
+        return `EXISTS (SELECT 1 FROM ${this.q(relDef.to)} ${talias} WHERE ${join}${gfAnd})`;
+    }
+    /** Param-collect mirror of {@link manyToManyTargetGlobalFilterExists}. */
+    collectManyToManyTargetGlobalFilter(relDef, params) {
+        const gf = this.resolveGlobalFilter(relDef.to);
+        if (!gf || !relDef.through)
+            return;
+        const tMeta = this.schema.tables[relDef.to];
+        if (!tMeta || tMeta.primaryKey.length === 0)
+            return;
+        const targetKeys = normalizeKeyColumns(relDef.through.targetKey);
+        if (targetKeys.length !== tMeta.primaryKey.length)
+            return;
+        this.collectAliasWhereParams(relDef.to, tMeta, gf, params);
+    }
+    /**
+     * Param-collect mirror of {@link buildRelationCountExpr}'s global-filter
+     * params (hasMany direct filter, or manyToMany EXISTS-on-target). Only pushes
+     * when a filter applies — no-op otherwise.
+     */
+    collectRelationCountParams(relDef, params) {
+        if (relDef.type === 'manyToMany') {
+            this.collectManyToManyTargetGlobalFilter(relDef, params);
+        }
+        else {
+            this.collectTargetGlobalFilterAlias(relDef.to, params);
+        }
+    }
     // -------------------------------------------------------------------------
     // pgvector helpers (similarity search)
     // -------------------------------------------------------------------------
@@ -3564,6 +4106,19 @@ export class QueryInterface {
         const meta = this.schema.tables[table];
         if (!meta)
             return parsed;
+        // Assemble reserved `_count__<rel>` scalar columns into a `_count` object.
+        // parseRow copies these unknown columns through under their raw key.
+        let countObj;
+        for (const key of Object.keys(parsed)) {
+            if (key.startsWith('_count__')) {
+                if (countObj === undefined)
+                    countObj = {};
+                countObj[key.slice('_count__'.length)] = Number(parsed[key]);
+                delete parsed[key];
+            }
+        }
+        if (countObj)
+            parsed._count = countObj;
         for (const [relName, relDef] of Object.entries(meta.relations)) {
             const rawValue = row[relName];
             if (rawValue === undefined)
@@ -3830,6 +4385,9 @@ export class QueryInterface {
         const relationSelects = [];
         const aliasCounter = { n: 0 };
         for (const [relName, relSpec] of sortedEntries(withClause)) {
+            // `_count` is a reserved key handled after the relation subqueries.
+            if (relName === '_count')
+                continue;
             const relDef = meta.relations[relName];
             if (!relDef) {
                 throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${table}". ` +
@@ -3839,6 +4397,18 @@ export class QueryInterface {
             const subquery = this.buildRelationSubquery(relDef, relSpec, params, table, aliasCounter, depth, path);
             relationSelects.push(`(${subquery}) AS ${this.q(relName)}`);
         }
+        // Reserved `_count` key → one correlated COUNT(*) scalar subquery per
+        // selected to-many relation, aliased `_count__<rel>`. Appended after the
+        // relation subqueries; the only params they can push come from a global
+        // filter on the counted target (mirrored at the tail of collectWithParams).
+        // Read via a cast so WithClause keeps its narrow `true | WithOptions` type.
+        const countSpec = withClause._count;
+        if (countSpec !== undefined) {
+            for (const rel of resolveCountRelations(meta, countSpec)) {
+                const expr = this.buildRelationCountExpr(rel, table, `t${aliasCounter.n++}`, params);
+                relationSelects.push(`${expr} AS ${this.q(`_count__${rel.name}`)}`);
+            }
+        }
         return [baseCols, ...relationSelects].join(', ');
     }
     /**
@@ -4039,13 +4609,13 @@ export class QueryInterface {
         let orderClause = '';
         if (relOrderEntries.length > 0) {
             const orders = relOrderEntries
-                .map(([k, dir]) => {
+                .map(([k, dirValue]) => {
                 const col = camelToSnake(k);
                 if (!targetMeta.allColumns.includes(col)) {
                     throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
                 }
-                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-                return `${alias}.${this.q(col)} ${safeDir}`;
+                const { dir, nulls } = normalizeOrderBy(dirValue);
+                return `${alias}.${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`;
             })
                 .join(', ');
             orderClause = ` ORDER BY ${orders}`;
@@ -4071,6 +4641,12 @@ export class QueryInterface {
             if (extra)
                 whereClause += ` AND ${extra}`;
         }
+        // Global filter on the target table (soft-delete / tenancy) — AND-merged so
+        // a `with` never surfaces filtered-out child rows. Pushed AFTER spec.where,
+        // mirrored by collectRelationSubqueryParams.
+        const gfExtra = this.targetGlobalFilterAlias(targetTable, alias, params);
+        if (gfExtra)
+            whereClause += ` AND ${gfExtra}`;
         // LIMIT — only meaningful for hasMany. A belongsTo / hasOne subquery returns
         // a single row (literal `LIMIT 1` below), so a `spec.limit` here must NOT push
         // a parameter: doing so orphans an untyped `$N` that the SQL never references,
@@ -4181,13 +4757,13 @@ export class QueryInterface {
         let orderClause = '';
         if (relOrderEntries.length > 0) {
             const orders = relOrderEntries
-                .map(([k, dir]) => {
+                .map(([k, dirValue]) => {
                 const col = camelToSnake(k);
                 if (!targetMeta.allColumns.includes(col)) {
                     throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
                 }
-                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-                return `${talias}.${this.q(col)} ${safeDir}`;
+                const { dir, nulls } = normalizeOrderBy(dirValue);
+                return `${talias}.${this.q(col)} ${dir}${this.nullsSuffix(nulls)}`;
             })
                 .join(', ');
             orderClause = ` ORDER BY ${orders}`;
@@ -4199,6 +4775,11 @@ export class QueryInterface {
             if (extra)
                 whereClause += ` AND ${extra}`;
         }
+        // Global filter on the target table (mirrors collectRelationSubqueryParams'
+        // m2m branch: after spec.where, before limit).
+        const gfExtra = this.targetGlobalFilterAlias(targetTable, talias, params);
+        if (gfExtra)
+            whereClause += ` AND ${gfExtra}`;
         // LIMIT — `limit: 0` is honored (LIMIT 0 → empty array)
         let limitClause = '';
         if (spec !== true && spec.limit !== undefined) {