turbine-orm 0.48.0 → 0.49.0

package/dist/cjs/nested-write.js

@@ -118,6 +118,152 @@ function pkWhere(tableMeta, row) {
     }
     return where;
 }
+/**
+ * The child-side predicate that ties a hasMany/hasOne relation's rows to THIS
+ * parent: `child.foreignKey = parent.referenceKey`. This is the exact
+ * correlation the connect/connectOrCreate/set paths already write when they
+ * point a child AT the parent, read back here as a filter.
+ *
+ * Returns `null` when the parent's reference key is null/undefined: SQL
+ * equality never matches NULL, so no child can be related and every scoped
+ * operation must report not-found rather than run unscoped.
+ */
+function parentCorrelationWhere(ctx, rel, parentRow) {
+    const fks = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+    const refs = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+    const childTable = ctx.schema.tables[rel.to];
+    const parentTable = ctx.schema.tables[rel.from];
+    const where = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = childTable?.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = parentTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        const value = parentRow[refField];
+        if (value === null || value === undefined)
+            return null;
+        where[fkField] = value;
+    }
+    return where;
+}
+/**
+ * The related-side predicate for a belongsTo relation: the parent holds the
+ * foreign key, so the related row this parent points at satisfies
+ * `related.referenceKey = parent.foreignKey`. The mirror image of
+ * {@link parentCorrelationWhere}, which reads the hasMany/hasOne direction.
+ *
+ * Returns `null` when the parent's foreign key is null/undefined: the parent
+ * points at nothing, so no related row is in scope.
+ */
+function belongsToCorrelationWhere(ctx, rel, parentRow, parentTable) {
+    const fks = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+    const refs = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    const where = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = parentMeta?.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        const value = parentRow[fkField];
+        if (value === null || value === undefined)
+            return null;
+        where[refField] = value;
+    }
+    return where;
+}
+/**
+ * AND the caller-supplied child `where` with the parent correlation so a nested
+ * delete/update/disconnect can only ever touch rows that actually belong to the
+ * parent being written.
+ *
+ * The flat merge is used whenever the two predicates name disjoint fields (the
+ * overwhelmingly common case: the caller addresses the child by its primary
+ * key). It keeps every caller key at the top level, so compound-unique selector
+ * expansion still sees them. When the caller's `where` names a correlation
+ * field itself, the two are combined with `AND` instead, so neither predicate
+ * can silently overwrite the other.
+ */
+function scopeWhereToParent(target, correlation) {
+    for (const key of Object.keys(correlation)) {
+        if (Object.hasOwn(target, key))
+            return { AND: [target, correlation] };
+    }
+    return { ...target, ...correlation };
+}
+/**
+ * The caller's own selector must name at least one bound value.
+ *
+ * The parent correlation is ANDed onto every nested delete/update/disconnect
+ * target, which makes the merged predicate non-empty by construction. That
+ * defeats the empty-where guard downstream: `delete: {}` or
+ * `delete: { id: req.body.postId }` with an undefined body field would compile
+ * to `WHERE user_id = $1` and remove EVERY child of this parent instead of
+ * throwing. So the caller's half is checked here, before the merge.
+ *
+ * `true` is accepted only on a to-one relation, where it means "the single
+ * related row" and the correlation alone identifies it. On a to-many it would
+ * mean "all of them", which is never what a caller spelled `delete: true` for.
+ */
+function assertTargetSelectsSomething(target, op, relName, rel) {
+    const toOne = rel.type === 'hasOne' || rel.type === 'belongsTo';
+    if (target === true) {
+        if (toOne)
+            return;
+        throw new errors_js_1.ValidationError(`[turbine] Nested ${op} on to-many relation "${relName}" needs a "where" selector: ` +
+            `"${op}: true" would ${op} every related "${rel.to}" row.`);
+    }
+    if (target && typeof target === 'object' && !Array.isArray(target)) {
+        const bound = Object.values(target).some((v) => v !== undefined);
+        if (bound)
+            return;
+    }
+    throw new errors_js_1.ValidationError(`[turbine] Nested ${op} on relation "${relName}" requires a selector with at least one defined value. ` +
+        `An empty or all-undefined "where" would ${op} every related "${rel.to}" row of this parent.`);
+}
+/**
+ * many-to-many relations have no nested-write branch on any engine: the junction
+ * row would have to be written too, and there is no safe default for what to put
+ * in its extra columns. Refusing loudly is the only honest option, because the
+ * alternative (falling off the end of the dispatch) drops the write silently and
+ * reports success.
+ */
+function manyToManyUnsupported(relName, rel) {
+    return new errors_js_1.ValidationError(`[turbine] Nested writes are not supported on the many-to-many relation "${relName}" ` +
+        `(via the "${rel.through?.table ?? 'junction'}" junction table). Write the junction rows directly ` +
+        `(db.${rel.through?.table ?? 'junction'}.create / createMany) inside the same $transaction.`);
+}
+/**
+ * The E001 raised when a nested delete/update/disconnect target is not a child
+ * of this parent (it belongs to another parent, or does not exist at all).
+ * Matches Prisma's behavior: the nested where is scoped to the relation, so a
+ * row outside the relation is simply "not found".
+ */
+function notRelatedToParent(op, relName, rel, target) {
+    // Object form, not the legacy string one: `err.table` / `err.where` /
+    // `err.operation` are a documented part of the NotFoundError contract, and a
+    // string-constructed error silently drops all three.
+    return new errors_js_1.NotFoundError({
+        table: rel.to,
+        where: target,
+        operation: `nested ${op}`,
+        message: `[turbine] Nested ${op} on relation "${relName}": no "${rel.to}" record matching ` +
+            `${(0, errors_js_1.describeTargetForMessage)(target)} is related to this parent. Either it does not exist, ` +
+            `or it belongs to a different parent (a nested ${op} can only touch this parent's rows).`,
+    });
+}
+/** Re-tag a NotFoundError from a scoped child write as a relation-scoped miss. */
+function rethrowAsNotRelated(err, op, relName, rel, target) {
+    if (err instanceof errors_js_1.NotFoundError) {
+        // Only re-tag a miss on THIS relation's own write. A NotFoundError raised
+        // deeper in the tree already names its own relation, and re-tagging it here
+        // would rename someone else's failure; keep it, and preserve the original
+        // as `cause` in either direction.
+        if (err.operation?.startsWith('nested '))
+            throw err;
+        const tagged = notRelatedToParent(op, relName, rel, target);
+        tagged.cause ??= err;
+        throw tagged;
+    }
+    throw err;
+}
 // ---------------------------------------------------------------------------
 // executeNestedCreate
 // ---------------------------------------------------------------------------
@@ -155,6 +301,9 @@ async function executeNestedCreate(ctx, tableName, data, depth = 0, path = []) {
         if (rel.type === 'belongsTo') {
             Object.assign(belongsToFks, await resolveBelongsToForCreate(ctx, rel, ops, tableName, depth, path, relName));
         }
+        else if (rel.type === 'manyToMany') {
+            throw manyToManyUnsupported(relName, rel);
+        }
     }
     // Insert the parent row (scalars + resolved belongsTo foreign keys)
     const parentRow = (await ctx.tx.table(tableName).create({
@@ -225,7 +374,7 @@ async function executeNestedUpdate(ctx, tableName, where, data, depth = 0, path
             await processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName);
             // disconnect
             if (ops.disconnect !== undefined) {
-                await processDisconnect(ctx, rel, ops.disconnect, relName);
+                await processDisconnect(ctx, rel, ops.disconnect, relName, parentRow);
             }
             // set
             if (ops.set !== undefined) {
@@ -233,15 +382,15 @@ async function executeNestedUpdate(ctx, tableName, where, data, depth = 0, path
             }
             // delete
             if (ops.delete !== undefined) {
-                await processDelete(ctx, rel, ops.delete);
+                await processDelete(ctx, rel, ops.delete, relName, parentRow);
             }
             // update
             if (ops.update !== undefined) {
-                await processNestedUpdate(ctx, rel, ops.update);
+                await processNestedUpdate(ctx, rel, ops.update, relName, parentRow);
             }
             // upsert
             if (ops.upsert !== undefined) {
-                await processNestedUpsert(ctx, rel, ops.upsert, parentRow);
+                await processNestedUpsert(ctx, rel, ops.upsert, parentRow, relName);
             }
         }
         else if (rel.type === 'belongsTo') {
@@ -275,6 +424,9 @@ async function executeNestedUpdate(ctx, tableName, where, data, depth = 0, path
                 });
             }
         }
+        else {
+            throw manyToManyUnsupported(relName, rel);
+        }
     }
     // Final read with all touched relations
     const withClause = {};
@@ -481,7 +633,7 @@ async function connectOrCreate(ctx, rel, op, parentRow) {
         await ctx.tx.table(rel.to).update({ where: op.where, data: updateData });
     }
 }
-async function processDisconnect(ctx, rel, disconnectArg, relName) {
+async function processDisconnect(ctx, rel, disconnectArg, relName, parentRow) {
     const fks = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
     const childTable = ctx.schema.tables[rel.to];
     if (!childTable)
@@ -495,13 +647,26 @@ async function processDisconnect(ctx, rel, disconnectArg, relName) {
         throw new errors_js_1.ValidationError(`[turbine] Cannot disconnect "${relName}": foreign key column(s) ${fks.join(', ')} on "${rel.to}" are NOT NULL. Use delete instead.`);
     }
     const items = toArray(disconnectArg);
+    if (items.length === 0)
+        return;
     const nullData = {};
     for (const fk of fks) {
         const field = childTable.reverseColumnMap[fk] ?? fk;
         nullData[field] = null;
     }
+    // Disconnect nulls the child's FK, so an unscoped target would strip ANOTHER
+    // parent's child off that parent. Scope every target to this parent's rows.
+    const correlation = parentCorrelationWhere(ctx, rel, parentRow);
     for (const target of items) {
-        await ctx.tx.table(rel.to).update({ where: target, data: nullData });
+        assertTargetSelectsSomething(target, 'disconnect', relName, rel);
+        if (!correlation)
+            throw notRelatedToParent('disconnect', relName, rel, target);
+        try {
+            await ctx.tx.table(rel.to).update({ where: scopeWhereToParent(target, correlation), data: nullData });
+        }
+        catch (err) {
+            rethrowAsNotRelated(err, 'disconnect', relName, rel, target);
+        }
     }
 }
 async function processSet(ctx, rel, setItems, parentRow) {
@@ -510,12 +675,23 @@ async function processSet(ctx, rel, setItems, parentRow) {
     const childTable = ctx.schema.tables[rel.to];
     if (!childTable)
         return;
-    // Build parent FK match for finding current children
+    // Build parent FK match for finding current children. `set` clears the
+    // current children with `allowFullTableScan: true`, which is exactly what
+    // disables the empty-where guard downstream, so a null/undefined reference
+    // key here would null the FK of EVERY row in the child table. Same guard as
+    // parentCorrelationWhere, spelled inline because `set` also needs the
+    // (identical) forward direction for the reconnect below.
     const parentWhere = {};
     for (let i = 0; i < fks.length; i++) {
         const fkField = childTable.reverseColumnMap[fks[i]] ?? fks[i];
         const refField = ctx.schema.tables[rel.from]?.reverseColumnMap[refs[i]] ?? refs[i];
-        parentWhere[fkField] = parentRow[refField];
+        const value = parentRow[refField];
+        if (value === null || value === undefined) {
+            throw new errors_js_1.ValidationError(`[turbine] Nested set on relation "${rel.name}" cannot run: the parent's reference key ` +
+                `"${refField}" is ${value === null ? 'null' : 'missing from the loaded row'}, so no child rows ` +
+                `can be correlated to this parent.`);
+        }
+        parentWhere[fkField] = value;
     }
     // Disconnect all current children
     const nullData = {};
@@ -542,24 +718,49 @@ async function processSet(ctx, rel, setItems, parentRow) {
 // ---------------------------------------------------------------------------
 // update / upsert operations (update-context only)
 // ---------------------------------------------------------------------------
-async function processNestedUpdate(ctx, rel, updateArg) {
+async function processNestedUpdate(ctx, rel, updateArg, relName, parentRow) {
     const items = toArray(updateArg);
+    if (items.length === 0)
+        return;
+    const correlation = parentCorrelationWhere(ctx, rel, parentRow);
     for (const item of items) {
         if (!item.where || !item.data) {
             throw new errors_js_1.ValidationError(`[turbine] Nested update on "${rel.name}" requires both "where" and "data" fields.`);
         }
-        await ctx.tx.table(rel.to).update({ where: item.where, data: item.data });
+        assertTargetSelectsSomething(item.where, 'update', relName, rel);
+        if (!correlation)
+            throw notRelatedToParent('update', relName, rel, item.where);
+        try {
+            await ctx.tx.table(rel.to).update({ where: scopeWhereToParent(item.where, correlation), data: item.data });
+        }
+        catch (err) {
+            rethrowAsNotRelated(err, 'update', relName, rel, item.where);
+        }
     }
 }
-async function processNestedUpsert(ctx, rel, upsertArg, parentRow) {
+async function processNestedUpsert(ctx, rel, upsertArg, parentRow, relName) {
     const items = toArray(upsertArg);
+    if (items.length === 0)
+        return;
+    // The upsert's `where` is scoped to the relation, so a row that matches it but
+    // belongs to ANOTHER parent is not "existing" here: it is never updated, and
+    // the create branch runs instead (any resulting unique-constraint violation is
+    // surfaced to the caller rather than silently rewriting a stranger's row).
+    const correlation = parentCorrelationWhere(ctx, rel, parentRow);
     for (const item of items) {
         if (!item.where || !item.create || !item.update) {
             throw new errors_js_1.ValidationError(`[turbine] Nested upsert on "${rel.name}" requires "where", "create", and "update" fields.`);
         }
-        const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
-        if (existing) {
-            await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+        assertTargetSelectsSomething(item.where, 'upsert', relName, rel);
+        const scoped = correlation ? scopeWhereToParent(item.where, correlation) : null;
+        const existing = scoped ? await ctx.tx.table(rel.to).findUnique({ where: scoped }) : null;
+        if (existing && scoped) {
+            try {
+                await ctx.tx.table(rel.to).update({ where: scoped, data: item.update });
+            }
+            catch (err) {
+                rethrowAsNotRelated(err, 'upsert', relName, rel, item.where);
+            }
         }
         else {
             const injected = injectForeignKey(item.create, rel, parentRow, ctx.schema);
@@ -590,9 +791,25 @@ async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTabl
     if (!item.where || !item.create || !item.update) {
         throw new errors_js_1.ValidationError(`[turbine] Nested upsert on belongsTo "${rel.name}" requires "where", "create", and "update" fields.`);
     }
-    const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
+    // Scope the lookup to the row this parent actually points at. Without the
+    // correlation, a `where` naming any other row would update a record with no
+    // relationship to the parent being written. A miss falls through to the
+    // create branch (and re-points the parent's FK), which is the same choice the
+    // hasMany/hasOne nested upsert makes: an upsert whose target is out of the
+    // relation creates a row owned by this parent rather than rewriting a
+    // stranger's.
+    const correlation = belongsToCorrelationWhere(ctx, rel, parentRow, parentTable);
+    // findMany, not findUnique: the scoped where ANDs a non-unique-looking
+    // correlation onto the caller's selector. The correlation targets the
+    // relation's reference key (unique or the PK by construction), so at most one
+    // row can come back.
+    const existing = correlation
+        ? ((await ctx.tx.table(rel.to).findMany({ where: scopeWhereToParent(item.where, correlation) }))[0] ??
+            null)
+        : null;
     if (existing) {
-        await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+        const relatedMeta = ctx.schema.tables[rel.to];
+        await ctx.tx.table(rel.to).update({ where: pkWhere(relatedMeta, existing), data: item.update });
     }
     else {
         // Create the related row, then update parent's FK to point at it
@@ -613,9 +830,22 @@ async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTabl
         });
     }
 }
-async function processDelete(ctx, rel, deleteArg) {
+async function processDelete(ctx, rel, deleteArg, relName, parentRow) {
     const items = toArray(deleteArg);
+    if (items.length === 0)
+        return;
+    // Without the correlation this deletes ANY row the caller can name: a
+    // cross-tenant delete primitive for any endpoint that forwards a client id.
+    const correlation = parentCorrelationWhere(ctx, rel, parentRow);
     for (const target of items) {
-        await ctx.tx.table(rel.to).delete({ where: target });
+        assertTargetSelectsSomething(target, 'delete', relName, rel);
+        if (!correlation)
+            throw notRelatedToParent('delete', relName, rel, target);
+        try {
+            await ctx.tx.table(rel.to).delete({ where: scopeWhereToParent(target, correlation) });
+        }
+        catch (err) {
+            rethrowAsNotRelated(err, 'delete', relName, rel, target);
+        }
     }
 }

package/dist/cjs/observe.js

@@ -21,6 +21,15 @@ exports.ObserveEngine = exports.HttpJsonSink = exports.PgMetricsSink = void 0;
 exports.floorToMinute = floorToMinute;
 exports.percentile = percentile;
 const pg_1 = __importDefault(require("pg"));
+const errors_js_1 = require("./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);
@@ -149,31 +158,28 @@ exports.HttpJsonSink = HttpJsonSink;
 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 errors_js_1.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);
@@ -197,19 +203,19 @@ 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/cjs/powdb.js

@@ -148,6 +148,9 @@ exports.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/cjs/powql.js

@@ -74,6 +74,7 @@ const node_crypto_1 = require("node:crypto");
 const errors_js_1 = require("./errors.js");
 const nested_write_js_1 = require("./nested-write.js");
 const powdb_js_1 = require("./powdb.js");
+const aggregates_js_1 = require("./query/aggregates.js");
 const compound_unique_js_1 = require("./query/compound-unique.js");
 const filters_js_1 = require("./query/filters.js");
 const utils_js_1 = require("./query/utils.js");
@@ -2282,6 +2283,10 @@ 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') {
+                        (0, aggregates_js_1.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;
@@ -2333,6 +2338,7 @@ class PowqlInterface {
             for (const entry of args.by) {
                 if (typeof entry === 'string') {
                     const col = this.column(entry);
+                    (0, aggregates_js_1.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}"`);
@@ -2346,6 +2352,7 @@ class PowqlInterface {
                     if (!(0, powdb_js_1.isJsonColumn)(col)) {
                         throw new errors_js_1.ValidationError(`[turbine] groupBy JSON group key on "${entry.field}" (table "${this.table}") requires a json column.`);
                     }
+                    (0, aggregates_js_1.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]);
@@ -2395,6 +2402,9 @@ class PowqlInterface {
                     const alias = `agg_${aggN++}`;
                     if (target === true) {
                         const col = this.column(key);
+                        if (fn === '_min' || fn === '_max') {
+                            (0, aggregates_js_1.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})`);
@@ -2407,6 +2417,9 @@ class PowqlInterface {
                         if (!(0, powdb_js_1.isJsonColumn)(col)) {
                             throw new errors_js_1.ValidationError(`[turbine] groupBy ${fn} target "${key}" on "${target.field}" (table "${this.table}") requires a json column.`);
                         }
+                        if (fn === '_min' || fn === '_max') {
+                            (0, aggregates_js_1.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/cjs/prisma-compat.js

@@ -421,6 +421,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);
@@ -655,6 +660,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/cjs/query/aggregates.js

@@ -43,6 +43,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertAggregatePiiOptIn = assertAggregatePiiOptIn;
 exports.buildGroupBy = buildGroupBy;
 exports.buildGroupByOrderBy = buildGroupByOrderBy;
 exports.resolveJsonPathTarget = resolveJsonPathTarget;
@@ -54,6 +55,34 @@ const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
 const filters_js_1 = require("./filters.js");
 const whereMod = __importStar(require("./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.
+ */
+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 errors_js_1.ValidationError(`[turbine] ${usage} on column "${field}" of table "${table}" is refused: that column is ` +
+        'PII-tagged (`pii: true`), and this aggregate returns its stored values, which are excluded ' +
+        'from every default projection. Pass `includePii: true` on this call to opt in. ' +
+        '`_count` over a PII column (a count, not a value) and `where` / `orderBy` / `having` on PII ' +
+        'columns need no opt-in.');
+}
 function buildGroupBy(qi, args) {
     const meta = qi.schema.tables[qi.table];
     if (meta) {
@@ -107,6 +136,7 @@ function buildGroupBy(qi, args) {
     for (const entry of args.by) {
         if (typeof entry === 'string') {
             const col = qi.toColumn(entry);
+            assertAggregatePiiOptIn(qi.table, meta, entry, col, 'groupBy `by` key', args.includePii);
             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'
@@ -120,6 +150,7 @@ function buildGroupBy(qi, args) {
         }
         else {
             const col = resolveJsonPathTarget(qi, 'group key', entry.field, entry.path);
+            assertAggregatePiiOptIn(qi.table, meta, entry.field, col, 'groupBy JSON `by` key', args.includePii);
             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]);
@@ -183,6 +214,9 @@ 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.
@@ -194,6 +228,9 @@ 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 errors_js_1.ValidationError(`[turbine] groupBy ${aggKey} target "${key}" on table "${qi.table}": ` +
@@ -653,11 +690,13 @@ 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}`)}`);
             }
         }
@@ -667,6 +706,7 @@ function buildAggregate(qi, args) {
         for (const [field, enabled] of Object.entries(args._max)) {
             if (enabled) {
                 const col = qi.toColumn(field);
+                assertAggregatePiiOptIn(qi.table, meta, field, col, 'aggregate _max', args.includePii);
                 selectExprs.push(`MAX(${qi.q(col)}) AS ${qi.q(`_max_${col}`)}`);
             }
         }