turbine-orm 0.48.0 → 0.49.0

package/dist/observe.js

@@ -13,6 +13,15 @@
  * carries SQL text or bound parameter values.
  */
 import pg from 'pg';
+import { ValidationError } from './errors.js';
+/**
+ * Buffer key: minute bucket + model + action. Joined on a NUL, which cannot
+ * appear in a table name or an action, so `model: 'a:b'` and `action: 'c'`
+ * can never collapse into the same series as `model: 'a'` / `action: 'b:c'`.
+ */
+function bufferKey(bucket, model, action) {
+    return `${bucket.getTime()}\u0000${model}\u0000${action}`;
+}
 function floorToMinute(date) {
     const d = new Date(date);
     d.setSeconds(0, 0);
@@ -139,31 +148,28 @@ export class HttpJsonSink {
 export class ObserveEngine {
     sink;
     buffer = new Map();
-    currentBucket;
     flushIntervalMs;
     timer;
     listener;
     stopped = false;
     constructor(config) {
         if (!config.sink && !config.connectionString) {
-            throw new Error('ObserveEngine requires either a connectionString or a sink');
+            throw new ValidationError('ObserveEngine requires either a connectionString or a sink');
         }
         this.sink =
             config.sink ??
                 new PgMetricsSink({ connectionString: config.connectionString, retentionDays: config.retentionDays ?? 30 });
         this.flushIntervalMs = config.flushIntervalMs ?? 60_000;
-        this.currentBucket = floorToMinute(new Date());
         this.listener = (event) => {
             if (this.stopped)
                 return;
-            const nowBucket = floorToMinute(new Date());
-            if (nowBucket.getTime() !== this.currentBucket.getTime()) {
-                this.currentBucket = nowBucket;
-            }
-            const key = `${event.model}:${event.action}`;
+            // Bucket by the event's own timestamp so a late-arriving event is
+            // attributed to the minute it happened in, not the minute it was seen.
+            const bucket = floorToMinute(event.timestamp);
+            const key = bufferKey(bucket, event.model, event.action);
             let entry = this.buffer.get(key);
             if (!entry) {
-                entry = { durations: [], errors: 0 };
+                entry = { bucket, model: event.model, action: event.action, durations: [], errors: 0 };
                 this.buffer.set(key, entry);
             }
             entry.durations.push(event.duration);
@@ -187,19 +193,19 @@ export class ObserveEngine {
     async flush() {
         if (this.buffer.size === 0)
             return;
-        const bucket = this.currentBucket;
         const entries = new Map(this.buffer);
         this.buffer.clear();
         const rows = [];
-        for (const [key, entry] of entries) {
-            const [model, action] = key.split(':');
+        for (const entry of entries.values()) {
             const sorted = entry.durations.slice().sort((a, b) => a - b);
             const count = sorted.length;
             const avg = sorted.reduce((s, v) => s + v, 0) / count;
             rows.push({
-                bucket,
-                model: model ?? '',
-                action: action ?? '',
+                // Each entry carries the minute it accumulated in, so a flush that
+                // spans a rollover emits one correctly stamped row per minute.
+                bucket: entry.bucket,
+                model: entry.model,
+                action: entry.action,
                 count,
                 avg,
                 p50: percentile(sorted, 0.5),

package/dist/powdb.js

@@ -90,6 +90,9 @@ export const powdbDialect = {
     resultStrategy: 'returning',
     supportsReturning: true,
     supportsVector: false,
+    // PowQL has no tsvector/tsquery surface and no array column type.
+    supportsFullTextSearch: false,
+    supportsArrayColumns: false,
     supportsListenNotify: false,
     supportsRLS: false,
     supportsAdvisoryLock: false,

package/dist/powql.js

@@ -38,6 +38,7 @@ import { randomUUID } from 'node:crypto';
 import { NotFoundError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb.js';
+import { assertAggregatePiiOptIn } from './query/aggregates.js';
 import { expandCompoundUniqueWhere } from './query/compound-unique.js';
 import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
 import { escapeLike } from './query/utils.js';
@@ -2246,6 +2247,10 @@ export class PowqlInterface {
                 const acc = {};
                 for (const field of Object.keys(spec).filter((f) => spec[f])) {
                     const powfn = fn.slice(1); // sum/avg/min/max
+                    // Same PII contract as the SQL engines: _min/_max return a stored cell.
+                    if (fn === '_min' || fn === '_max') {
+                        assertAggregatePiiOptIn(this.table, this.meta, field, this.column(field).name, `aggregate ${fn}`, args.includePii);
+                    }
                     acc[field] = await scalar(`${powfn}(${this.qt}${filter} { ${this.ref(field)} })`);
                 }
                 result[fn] = acc;
@@ -2297,6 +2302,7 @@ export class PowqlInterface {
             for (const entry of args.by) {
                 if (typeof entry === 'string') {
                     const col = this.column(entry);
+                    assertAggregatePiiOptIn(this.table, this.meta, entry, col.name, 'groupBy `by` key', args.includePii);
                     claim(entry, `column "${col.name}"`);
                     if (col.name !== entry)
                         claim(col.name, `column "${col.name}"`);
@@ -2310,6 +2316,7 @@ export class PowqlInterface {
                     if (!isJsonColumn(col)) {
                         throw new ValidationError(`[turbine] groupBy JSON group key on "${entry.field}" (table "${this.table}") requires a json column.`);
                     }
+                    assertAggregatePiiOptIn(this.table, this.meta, entry.field, col.name, 'groupBy JSON `by` key', args.includePii);
                     this.assertJsonPath('group key', entry.field, entry.path);
                     const pathExpr = this.jsonPathExpr(col, entry.path, params);
                     const alias = entry.alias ?? String(entry.path[entry.path.length - 1]);
@@ -2359,6 +2366,9 @@ export class PowqlInterface {
                     const alias = `agg_${aggN++}`;
                     if (target === true) {
                         const col = this.column(key);
+                        if (fn === '_min' || fn === '_max') {
+                            assertAggregatePiiOptIn(this.table, this.meta, key, col.name, `groupBy ${fn}`, args.includePii);
+                        }
                         claim(`${fn}_${col.name}`, `${fn} of column "${col.name}"`);
                         const inner = `.${col.name}`;
                         proj.push(`${alias}: ${powfn}(${inner})`);
@@ -2371,6 +2381,9 @@ export class PowqlInterface {
                         if (!isJsonColumn(col)) {
                             throw new ValidationError(`[turbine] groupBy ${fn} target "${key}" on "${target.field}" (table "${this.table}") requires a json column.`);
                         }
+                        if (fn === '_min' || fn === '_max') {
+                            assertAggregatePiiOptIn(this.table, this.meta, target.field, col.name, `groupBy ${fn} JSON target`, args.includePii);
+                        }
                         this.assertJsonPath(`${fn} target "${key}"`, target.field, target.path);
                         const alwaysNumeric = fn === '_sum' || fn === '_avg';
                         if (alwaysNumeric && target.type === 'text') {

package/dist/prisma-compat.js

@@ -417,6 +417,11 @@ function translateReadArgs(ctx, mm, prismaArgs) {
         t.relationLoadStrategy = prismaArgs.relationLoadStrategy;
     if (typeof prismaArgs.timeout === 'number')
         t.timeout = prismaArgs.timeout;
+    // Turbine-only passthrough. Prisma has no PII concept, so a compat caller
+    // whose schema tags columns needs SOME way to opt in; without this the
+    // adapter is a one-way door into redacted reads and refused aggregates.
+    if (prismaArgs.includePii !== undefined)
+        t.includePii = prismaArgs.includePii;
     if (ctx.options.stablePkOrder)
         t.stableRelationOrder = true;
     translateCursor(ctx, mm, prismaArgs, t);
@@ -651,6 +656,10 @@ function translateAggregateArgs(ctx, mm, args, isGroupBy) {
     }
     if (typeof args.timeout === 'number')
         t.timeout = args.timeout;
+    // Turbine-only passthrough: the PII gate on groupBy keys and _min/_max needs
+    // an opt-in that Prisma's arg shape has no equivalent for.
+    if (args.includePii !== undefined)
+        t.includePii = args.includePii;
     if (isGroupBy) {
         if (Array.isArray(args.by))
             t.by = args.by.map((f) => renameField(mm, f));

package/dist/query/aggregates.d.ts

@@ -8,9 +8,27 @@
  * stay class-resident, reached through the ctx. See builder.ts for the thin
  * delegating methods (buildGroupBy / buildAggregate).
  */
+import type { TableMetadata } from '../schema.js';
 import type { DeferredQuery } from './deferred.js';
 import type { AggregateArgs, AggregateResult, GroupByArgs, GroupByOrderBy, HavingClause, HavingFilter } from './types.js';
 import type { BuilderCtx } from './where.js';
+/**
+ * Enforce the PII contract on the aggregate surface. A PII-tagged
+ * (`defineSchema` `pii: true`) column is excluded from every default
+ * projection, and a value-returning aggregate is a projection by another name:
+ * `groupBy({ by: ['email'] })` emits one row per distinct plaintext email, and
+ * `_min`/`_max` return a stored cell verbatim. Both therefore REQUIRE the same
+ * `includePii: true` opt-in reads use.
+ *
+ * Deliberately NOT gated: `_count` (a count, never a value), `_sum` / `_avg`
+ * (a computed total across many rows, not a stored cell), and `where` /
+ * `orderBy` / `having` on PII columns (they return no values at all). Untagged
+ * schemas short-circuit on the `pii` lookup, so their SQL is byte-identical.
+ *
+ * Shared with the PowQL aggregate paths (src/powql.ts) so every engine applies
+ * one policy.
+ */
+export declare function assertAggregatePiiOptIn(table: string, meta: TableMetadata | undefined, field: string, column: string, usage: string, includePii: boolean | undefined): void;
 export declare function buildGroupBy<T extends object>(qi: BuilderCtx, args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
 /**
  * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY

package/dist/query/aggregates.js

@@ -12,6 +12,34 @@ import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
 import { isJsonPathOrderBy, isVectorOrderBy, normalizeOrderBy, orderByEntries } from './filters.js';
 import * as whereMod from './where.js';
+/**
+ * Enforce the PII contract on the aggregate surface. A PII-tagged
+ * (`defineSchema` `pii: true`) column is excluded from every default
+ * projection, and a value-returning aggregate is a projection by another name:
+ * `groupBy({ by: ['email'] })` emits one row per distinct plaintext email, and
+ * `_min`/`_max` return a stored cell verbatim. Both therefore REQUIRE the same
+ * `includePii: true` opt-in reads use.
+ *
+ * Deliberately NOT gated: `_count` (a count, never a value), `_sum` / `_avg`
+ * (a computed total across many rows, not a stored cell), and `where` /
+ * `orderBy` / `having` on PII columns (they return no values at all). Untagged
+ * schemas short-circuit on the `pii` lookup, so their SQL is byte-identical.
+ *
+ * Shared with the PowQL aggregate paths (src/powql.ts) so every engine applies
+ * one policy.
+ */
+export function assertAggregatePiiOptIn(table, meta, field, column, usage, includePii) {
+    if (includePii === true || !meta)
+        return;
+    const colMeta = meta.columns.find((c) => c.name === column);
+    if (!colMeta?.pii)
+        return;
+    throw new ValidationError(`[turbine] ${usage} on column "${field}" of table "${table}" is refused: that column is ` +
+        'PII-tagged (`pii: true`), and this aggregate returns its stored values, which are excluded ' +
+        'from every default projection. Pass `includePii: true` on this call to opt in. ' +
+        '`_count` over a PII column (a count, not a value) and `where` / `orderBy` / `having` on PII ' +
+        'columns need no opt-in.');
+}
 export function buildGroupBy(qi, args) {
     const meta = qi.schema.tables[qi.table];
     if (meta) {
@@ -65,6 +93,7 @@ export function buildGroupBy(qi, args) {
     for (const entry of args.by) {
         if (typeof entry === 'string') {
             const col = qi.toColumn(entry);
+            assertAggregatePiiOptIn(qi.table, meta, entry, col, 'groupBy `by` key', args.includePii);
             claimResultKey(entry, `column "${col}"`);
             // The emitted output column is the snake_case name; claim it too (when
             // it differs from the result key) so a JSON alias like 'created_at'
@@ -78,6 +107,7 @@ export function buildGroupBy(qi, args) {
         }
         else {
             const col = resolveJsonPathTarget(qi, 'group key', entry.field, entry.path);
+            assertAggregatePiiOptIn(qi.table, meta, entry.field, col, 'groupBy JSON `by` key', args.includePii);
             params.push(whereMod.jsonPathParam(qi, entry.path));
             const extract = qi.dialect.buildJsonPathExtract(qi.q(col), qi.p(params.length));
             const alias = entry.alias ?? String(entry.path[entry.path.length - 1]);
@@ -141,6 +171,9 @@ export function buildGroupBy(qi, args) {
                 continue;
             if (target === true) {
                 const col = qi.toColumn(key);
+                if (aggKey === '_min' || aggKey === '_max') {
+                    assertAggregatePiiOptIn(qi.table, meta, key, col, `groupBy ${aggKey}`, args.includePii);
+                }
                 // Aggregate output aliases share the same output-name namespace as
                 // the group keys: `_sum: { totalPrice: true, total_price: {json} }`
                 // would emit two "_sum_total_price" columns and silently drop one.
@@ -152,6 +185,9 @@ export function buildGroupBy(qi, args) {
                 continue;
             }
             const col = resolveJsonPathTarget(qi, `${aggKey} target "${key}"`, target.field, target.path);
+            if (aggKey === '_min' || aggKey === '_max') {
+                assertAggregatePiiOptIn(qi.table, meta, target.field, col, `groupBy ${aggKey} JSON target`, args.includePii);
+            }
             const alwaysNumeric = aggKey === '_sum' || aggKey === '_avg';
             if (alwaysNumeric && target.type === 'text') {
                 throw new ValidationError(`[turbine] groupBy ${aggKey} target "${key}" on table "${qi.table}": ` +
@@ -611,11 +647,13 @@ export function buildAggregate(qi, args) {
             }
         }
     }
-    // _min
+    // _min / _max return a stored cell verbatim, so a PII-tagged column needs the
+    // same `includePii` opt-in a row projection needs. _count / _sum / _avg do not.
     if (args._min) {
         for (const [field, enabled] of Object.entries(args._min)) {
             if (enabled) {
                 const col = qi.toColumn(field);
+                assertAggregatePiiOptIn(qi.table, meta, field, col, 'aggregate _min', args.includePii);
                 selectExprs.push(`MIN(${qi.q(col)}) AS ${qi.q(`_min_${col}`)}`);
             }
         }
@@ -625,6 +663,7 @@ export function buildAggregate(qi, args) {
         for (const [field, enabled] of Object.entries(args._max)) {
             if (enabled) {
                 const col = qi.toColumn(field);
+                assertAggregatePiiOptIn(qi.table, meta, field, col, 'aggregate _max', args.includePii);
                 selectExprs.push(`MAX(${qi.q(col)}) AS ${qi.q(`_max_${col}`)}`);
             }
         }

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

@@ -112,6 +112,19 @@ export interface RelationLoadContext {
         params: unknown[];
     } | null;
 }
+/**
+ * The default projection of `meta` expressed in FIELD names: which fields the
+ * default (no `select`/`omit`) projection hides, and which it returns. Today the
+ * only hidden class is PII-tagged columns, and only when `includePii` is off.
+ *
+ * Returns `undefined` for the overwhelmingly common untagged case, so callers
+ * keep the `select: undefined, omit: undefined` fast path and the emitted SQL
+ * stays byte-identical.
+ */
+export declare function defaultProjectionFields(meta: TableMetadata, includePii: boolean | undefined): {
+    hidden: ReadonlySet<string>;
+    visible: string[];
+} | undefined;
 /**
  * Adjust a `select`/`omit` pair so that `fields` are guaranteed present in the
  * query result, returning the adjusted projection plus the list of fields that
@@ -121,7 +134,22 @@ export interface RelationLoadContext {
  * keys) so a caller's `select: { title: true }` on a relation still stitches even
  * though the FK was not requested — and the FK never appears in the output.
  */
-export declare function includeKeysForBatching(select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined, fields: string[]): {
+export declare function includeKeysForBatching(select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined, fields: string[], 
+/**
+ * The default projection for this table when it is NOT `select`/`omit`-driven:
+ * `hidden` are fields the default projection leaves out (today: PII-tagged
+ * columns without `includePii`), `visible` is everything it does return.
+ *
+ * Without this, a correlation key that is itself PII-tagged is absent from
+ * every row, the loader sees no keys, and it silently hands back empty
+ * relation arrays. Passing it turns that case into an explicit select that
+ * re-adds only the key, which is then stripped like any other stitch-only
+ * field, so no PII value ever reaches the caller.
+ */
+defaultProjection?: {
+    hidden: ReadonlySet<string>;
+    visible: string[];
+}): {
     select?: Record<string, boolean>;
     omit?: Record<string, boolean>;
     strip: string[];

package/dist/query/batched-loader.js

@@ -61,6 +61,29 @@ import { ownLookup } from './utils.js';
 const MAX_RELATION_KEYS = 32_000;
 /** Nesting cap — parity with the join strategy's depth-10 guard. */
 const MAX_DEPTH = 10;
+/**
+ * The default projection of `meta` expressed in FIELD names: which fields the
+ * default (no `select`/`omit`) projection hides, and which it returns. Today the
+ * only hidden class is PII-tagged columns, and only when `includePii` is off.
+ *
+ * Returns `undefined` for the overwhelmingly common untagged case, so callers
+ * keep the `select: undefined, omit: undefined` fast path and the emitted SQL
+ * stays byte-identical.
+ */
+export function defaultProjectionFields(meta, includePii) {
+    if (includePii)
+        return undefined;
+    const hidden = new Set();
+    const visible = [];
+    for (const col of meta.columns) {
+        const field = meta.reverseColumnMap[col.name] ?? col.name;
+        if (col.pii)
+            hidden.add(field);
+        else
+            visible.push(field);
+    }
+    return hidden.size === 0 ? undefined : { hidden, visible };
+}
 /**
  * Adjust a `select`/`omit` pair so that `fields` are guaranteed present in the
  * query result, returning the adjusted projection plus the list of fields that
@@ -70,7 +93,19 @@ const MAX_DEPTH = 10;
  * keys) so a caller's `select: { title: true }` on a relation still stitches even
  * though the FK was not requested — and the FK never appears in the output.
  */
-export function includeKeysForBatching(select, omit, fields) {
+export function includeKeysForBatching(select, omit, fields, 
+/**
+ * The default projection for this table when it is NOT `select`/`omit`-driven:
+ * `hidden` are fields the default projection leaves out (today: PII-tagged
+ * columns without `includePii`), `visible` is everything it does return.
+ *
+ * Without this, a correlation key that is itself PII-tagged is absent from
+ * every row, the loader sees no keys, and it silently hands back empty
+ * relation arrays. Passing it turns that case into an explicit select that
+ * re-adds only the key, which is then stripped like any other stitch-only
+ * field, so no PII value ever reaches the caller.
+ */
+defaultProjection) {
     const unique = [...new Set(fields)];
     if (select) {
         const next = { ...select };
@@ -94,7 +129,19 @@ export function includeKeysForBatching(select, omit, fields) {
         }
         return { select, omit: next, strip };
     }
-    // Neither select nor omit — every column is already present; nothing to strip.
+    // Neither select nor omit. Every column the DEFAULT projection returns is
+    // already present, so normally there is nothing to strip; the exception is a
+    // key the default projection hides (a PII-tagged correlation column), which
+    // has to be asked for explicitly.
+    const hiddenKeys = defaultProjection ? unique.filter((f) => defaultProjection.hidden.has(f)) : [];
+    if (hiddenKeys.length > 0 && defaultProjection) {
+        const explicit = {};
+        for (const f of defaultProjection.visible)
+            explicit[f] = true;
+        for (const f of hiddenKeys)
+            explicit[f] = true;
+        return { select: explicit, omit: undefined, strip: hiddenKeys };
+    }
     return { select, omit, strip: [] };
 }
 /** Delete stitch-only key fields from each row (no-op when `fields` is empty). */
@@ -272,7 +319,7 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     }
     // The follow-up must project the child correlation key even if the caller's
     // select/omit excluded it; strip it back off afterwards so the shape matches join.
-    const proj = includeKeysForBatching(options.select, options.omit, [childKeyField]);
+    const proj = includeKeysForBatching(options.select, options.omit, [childKeyField], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
     const chunks = [];
     for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS)
@@ -374,7 +421,7 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
         }
     }
     // (2) Target rows by PK, honouring the relation's own where/select/omit/orderBy.
-    const proj = includeKeysForBatching(options.select, options.omit, [targetPkField]);
+    const proj = includeKeysForBatching(options.select, options.omit, [targetPkField], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
     const targetVals = [...targetValSet];
     const tChunks = [];
@@ -527,9 +574,25 @@ async function loadOneCount(ctx, parents, rel) {
 // ---------------------------------------------------------------------------
 // Small helpers
 // ---------------------------------------------------------------------------
-/** Merge the batched correlation predicate (`key IN chunk`) into the relation's own where. */
+/**
+ * AND the batched correlation predicate (`key IN chunk`) onto the relation's own
+ * `where`, matching the join strategy, which appends the correlation with
+ * ` AND <extra>` and so never lets one predicate replace the other.
+ *
+ * A flat spread is kept for the overwhelmingly common case where the caller's
+ * `where` does not name the correlation field, so the emitted SQL is unchanged
+ * there. When it DOES name it (e.g. `with: { posts: { where: { userId: 1 } } }`,
+ * or a belongsTo `where` on the child's PK), a bare spread would let the chunk
+ * predicate silently overwrite the caller's filter and return rows the join
+ * strategy excludes; the two are combined with `AND` instead so both apply.
+ */
 function mergeChildWhere(where, keyField, chunk) {
-    return { ...(where ?? {}), [keyField]: { in: chunk } };
+    const correlation = { [keyField]: { in: chunk } };
+    if (!where)
+        return correlation;
+    if (Object.hasOwn(where, keyField))
+        return { AND: [where, correlation] };
+    return { ...where, ...correlation };
 }
 /** Distinct, non-null values of `field` across `rows`. */
 function uniqueKeys(rows, field) {

package/dist/query/builder.js

@@ -16,7 +16,7 @@ import { missingIndexForRelation, schemaHasIndexInfo } from '../index-advisor.js
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
-import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
+import { defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import * as relationsMod from './relations.js';
@@ -745,7 +745,7 @@ export class QueryInterface {
         rejectNestedPickOrder(batchedWith);
         const skip = args.skipGlobalFilters;
         const needed = neededParentKeyFields(this.tableMeta, batchedWith);
-        const proj = includeKeysForBatching(args.select, args.omit, needed);
+        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, args.includePii));
         const hasJoin = Object.keys(joinWith).length > 0;
         // Force the residual `with` onto the join plan so the base query never
         // re-enters this auto planning.
@@ -858,7 +858,7 @@ export class QueryInterface {
      */
     prepareBatchedBase(args, withClause) {
         const needed = neededParentKeyFields(this.tableMeta, withClause);
-        const proj = includeKeysForBatching(args.select, args.omit, needed);
+        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, args.includePii));
         const baseArgs = {
             ...args,
             with: undefined,
@@ -1164,7 +1164,7 @@ export class QueryInterface {
         // Same scope-rule parity as runFindManyBatched: reject before querying.
         rejectNestedPickOrder(withClause);
         const needed = neededParentKeyFields(this.tableMeta, withClause);
-        const proj = includeKeysForBatching(args.select, args.omit, needed);
+        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, args.includePii));
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
         const deferred = this.buildFindUnique(baseArgs);
         const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);

package/dist/query/relations.js

@@ -480,8 +480,18 @@ export function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lat
     const parentRef = ctx?.parentRef ?? qi.table;
     const relDef = ownerMeta.relations[relName];
     if (!relDef) {
-        throw new RelationError(`[turbine] Unknown relation "${relName}" in orderBy on table "${ownerTable}". ` +
-            `Available: ${Object.keys(ownerMeta.relations).join(', ')}`);
+        // A table with no relations at all would otherwise render a dangling
+        // "Available: " and read as a broken message; and the most likely cause of
+        // landing here on such a table is an orderBy VALUE of the wrong shape on a
+        // scalar column, which deserves to be named rather than reported as a
+        // missing relation.
+        const known = Object.keys(ownerMeta.relations);
+        const isColumn = Object.hasOwn(ownerMeta.columnMap, relName) || ownerMeta.allColumns.includes(relName);
+        throw new RelationError(isColumn
+            ? `[turbine] orderBy on "${ownerTable}.${relName}" got a relation-shaped value, but "${relName}" is a ` +
+                `column. Order a column with 'asc' / 'desc' (or { sort, nulls }); the object form is for relations.`
+            : `[turbine] Unknown relation "${relName}" in orderBy on table "${ownerTable}". ` +
+                (known.length > 0 ? `Available: ${known.join(', ')}` : `"${ownerTable}" has no relations.`));
     }
     // Pick-row ordering (`{ pick, by }`): order by a value from ONE related
     // row: a correlated scalar subquery with its own ORDER BY … LIMIT 1.

package/dist/query/types.d.ts

@@ -802,6 +802,14 @@ export interface GroupByArgs<T> {
      * grouped results; combine with `limit` and a deterministic `orderBy`.
      */
     offset?: number;
+    /**
+     * Opt in to grouping on / aggregating PII-tagged (`defineSchema` `pii: true`)
+     * columns. A PII column in `by`, and `_min` / `_max` over a PII column, return
+     * 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.
+     */
+    includePii?: boolean;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
@@ -894,6 +902,14 @@ export interface AggregateArgs<T> {
     _min?: Partial<Record<keyof T & string, boolean>>;
     /** Maximum value of fields */
     _max?: Partial<Record<keyof T & string, boolean>>;
+    /**
+     * Opt in to aggregating PII-tagged (`defineSchema` `pii: true`) columns.
+     * `_min` / `_max` return a STORED VALUE, so without this they throw
+     * `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.
+     */
+    includePii?: boolean;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */

package/dist/query/where.d.ts

@@ -170,7 +170,7 @@ export declare function collectOperatorParams(qi: BuilderCtx, column: string, op
  */
 export declare function collectJsonFilterParams(qi: BuilderCtx, filter: JsonFilter, params: unknown[], column: string): void;
 /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
-export declare function collectArrayFilterParams(_qi: BuilderCtx, filter: ArrayFilter, params: unknown[]): void;
+export declare function collectArrayFilterParams(qi: BuilderCtx, filter: ArrayFilter, params: unknown[]): void;
 /**
  * Collect params for a vector distance WHERE filter. Mirrors
  * {@link buildVectorFilterClauses}: the `$n::vector` query vector first, then
@@ -386,6 +386,23 @@ export declare function columnRefSql(qi: BuilderCtx, ref: ColumnRef, ctx: Column
  * pushing nothing and the referenced name lives in the fingerprint.
  */
 export declare function buildOperatorClauses(qi: BuilderCtx, column: string, op: WhereOperator, params: unknown[], refCtx?: ColumnRefContext): string[];
+/**
+ * Gate the full-text `search` filter on {@link Dialect.supportsFullTextSearch}.
+ * The clause it guards is `to_tsvector(...) @@ to_tsquery(...)`, which only
+ * PostgreSQL parses, so every other engine gets a typed
+ * {@link UnsupportedFeatureError} (E017) instead of a raw driver syntax error.
+ * Called from BOTH the build and the param-collect side (mirroring the vector
+ * gate) so the two paths can never diverge.
+ */
+export declare function requireFullTextSearch(qi: BuilderCtx): void;
+/**
+ * Gate the array filter operators (`has` / `hasEvery` / `hasSome` / `isEmpty`)
+ * on {@link Dialect.supportsArrayColumns}. They compile to PostgreSQL array
+ * operators (`= ANY(col)`, `@>`, `&&`, `cardinality(col)`) over a native array
+ * column, which no other supported engine has. Called from BOTH the build and
+ * the param-collect side.
+ */
+export declare function requireArrayColumns(qi: BuilderCtx): void;
 /**
  * Resolve a {@link VectorMetric} to its pgvector distance operator from a
  * fixed allow-list, validating the target column is actually a `vector`

package/dist/query/where.js

@@ -148,6 +148,9 @@ export function collectScalarParams(qi, key, value, params) {
             collectArrayFilterParams(qi, value, params);
             return;
         case 'textsearch':
+            // Same gate the build path applies, so the collect path never diverges
+            // (it throws before any param is pushed).
+            requireFullTextSearch(qi);
             params.push(value.search);
             return;
         case 'operator':
@@ -284,7 +287,8 @@ export function collectJsonFilterParams(qi, filter, params, column) {
     }
 }
 /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
-export function collectArrayFilterParams(_qi, filter, params) {
+export function collectArrayFilterParams(qi, filter, params) {
+    requireArrayColumns(qi);
     if (filter.has !== undefined)
         params.push(filter.has);
     if (filter.hasEvery !== undefined)
@@ -1161,6 +1165,33 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
     }
     return clauses;
 }
+/**
+ * Gate the full-text `search` filter on {@link Dialect.supportsFullTextSearch}.
+ * The clause it guards is `to_tsvector(...) @@ to_tsquery(...)`, which only
+ * PostgreSQL parses, so every other engine gets a typed
+ * {@link UnsupportedFeatureError} (E017) instead of a raw driver syntax error.
+ * Called from BOTH the build and the param-collect side (mirroring the vector
+ * gate) so the two paths can never diverge.
+ */
+export function requireFullTextSearch(qi) {
+    if (qi.dialect.supportsFullTextSearch)
+        return;
+    throw new UnsupportedFeatureError('the full-text search filter (`search`)', qi.dialect.name, 'Full-text `search` compiles to PostgreSQL to_tsvector/to_tsquery. ' +
+        'Use `contains` (LIKE) on this engine, or run the query on PostgreSQL.');
+}
+/**
+ * Gate the array filter operators (`has` / `hasEvery` / `hasSome` / `isEmpty`)
+ * on {@link Dialect.supportsArrayColumns}. They compile to PostgreSQL array
+ * operators (`= ANY(col)`, `@>`, `&&`, `cardinality(col)`) over a native array
+ * column, which no other supported engine has. Called from BOTH the build and
+ * the param-collect side.
+ */
+export function requireArrayColumns(qi) {
+    if (qi.dialect.supportsArrayColumns)
+        return;
+    throw new UnsupportedFeatureError('the array column filter set (`has` / `hasEvery` / `hasSome` / `isEmpty`)', qi.dialect.name, 'Array filters compile to PostgreSQL array operators over a native array ' +
+        'column; this engine has no array column type.');
+}
 /**
  * Resolve a {@link VectorMetric} to its pgvector distance operator from a
  * fixed allow-list, validating the target column is actually a `vector`
@@ -1378,6 +1409,7 @@ export function castJsonNumeric(qi, extract) {
  * Supports: has, hasEvery, hasSome, isEmpty.
  */
 export function buildArrayFilterClauses(qi, column, filter, params, pgType) {
+    requireArrayColumns(qi);
     const clauses = [];
     const elementType = getArrayElementType(qi, pgType);
     if (filter.has !== undefined) {
@@ -1443,6 +1475,7 @@ export function buildVectorFilterClauses(qi, field, rawColumn, filter, params) {
  * The config name is validated to prevent injection (only alphanumeric + underscore).
  */
 export function buildTextSearchClause(qi, column, filter, params) {
+    requireFullTextSearch(qi);
     const config = filter.config ?? 'english';
     if (!validateTextSearchConfig(config)) {
         throw new ValidationError(`[turbine] Invalid text search config "${config}": only alphanumeric characters and underscores are allowed.`);