turbine-orm 0.35.0 → 0.36.0

package/dist/generate.js

@@ -161,8 +161,13 @@ export function generateTypes(schema, options) {
         for (const col of table.columns) {
             const pkNote = table.primaryKey.includes(col.name) ? ' (primary key)' : '';
             const nullNote = col.nullable ? ' (nullable)' : '';
-            lines.push(`  /** Column: ${col.name} — ${col.pgType}${pkNote}${nullNote} */`);
-            lines.push(`  ${col.field}: ${columnTsType(col, schema.enums)};`);
+            // PII columns are excluded from default projections, so the field is
+            // absent unless the query names it in `select` or passes `includePii`.
+            // The emitted type marks it optional so it tells the truth about absence.
+            const piiNote = col.pii ? ' (PII: absent unless selected or includePii)' : '';
+            const optional = col.pii ? '?' : '';
+            lines.push(`  /** Column: ${col.name}, ${col.pgType}${pkNote}${nullNote}${piiNote} */`);
+            lines.push(`  ${col.field}${optional}: ${columnTsType(col, schema.enums)};`);
         }
         lines.push('}');
         lines.push('');
@@ -524,6 +529,17 @@ export function generateMetadata(schema, options) {
             lines.push(`        { name: '${escSQ(idx.name)}', columns: [${idx.columns.map((c) => `'${escSQ(c)}'`).join(', ')}], unique: ${idx.unique}, definition: ${JSON.stringify(idx.definition)} },`);
         }
         lines.push('      ],');
+        // checks: introspected named CHECK constraints. Emitted only when present
+        // (byte-stable for check-less tables) and sorted by name so `--no-timestamp`
+        // output is deterministic regardless of catalog row order.
+        if (table.checks && table.checks.length > 0) {
+            const sortedChecks = [...table.checks].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+            lines.push('      checks: [');
+            for (const chk of sortedChecks) {
+                lines.push(`        { name: '${escSQ(chk.name)}', expression: ${JSON.stringify(chk.expression)} },`);
+            }
+            lines.push('      ],');
+        }
         // isView — read-only marker; the runtime write guard reads it.
         if (table.isView)
             lines.push('      isView: true,');
@@ -727,6 +743,11 @@ function serializeColumn(col) {
     if (col.generationExpression !== undefined) {
         parts.push(`generationExpression: '${escSQ(col.generationExpression)}'`);
     }
+    // PII marker: emitted only when set, so untagged schemas stay byte-identical.
+    // Introspection never sets this (code-first declaration), but a metadata
+    // object built from `defineSchema` (pii: true) carries it through codegen.
+    if (col.pii)
+        parts.push(`pii: true`);
     if (col.maxLength !== undefined)
         parts.push(`maxLength: ${col.maxLength}`);
     return `{ ${parts.join(', ')} }`;

package/dist/index.d.ts

@@ -49,7 +49,7 @@ export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, R
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnIndexDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, type DocFieldIndexDef, defineSchema, isDocFieldIndexDef, type ManyToManyDef, type ReferenceDef, type SchemaDef, type SchemaIndexDef, type TableDef, table, } from './schema-builder.js';
 export { schemaDefToMetadata } from './schema-metadata.js';
-export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
+export { type AlterColumnDef, type AlterDef, DestructivePushRefusal, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';
 export { type TurbineHttpOptions, turbineHttp } from './serverless.js';
 export { buildTypedSql, TypedSqlQuery } from './typed-sql.js';

package/dist/index.js

@@ -59,7 +59,7 @@ table, } from './schema-builder.js';
 // Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB
 export { schemaDefToMetadata } from './schema-metadata.js';
 // Schema SQL — generate DDL, diff, and push
-export { schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
+export { DestructivePushRefusal, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 // Seed helper
 export { defineSeed } from './seed.js';
 // Serverless / edge factory

package/dist/mssql.js

@@ -448,6 +448,23 @@ function mssqlColumnType(type, maxLength) {
 // ---------------------------------------------------------------------------
 // mssqlDialect — the full Dialect contract for SQL Server 2016+
 // ---------------------------------------------------------------------------
+/**
+ * Render the SQL Server `OUTPUT` clause for a write's returning selection.
+ * `'*'` → ` OUTPUT INSERTED.*` (byte-identical to the historical default); a
+ * quoted column list → ` OUTPUT INSERTED.[c1], INSERTED.[c2]`; each column
+ * carries its own `INSERTED.`/`DELETED.` prefix (a bare comma list is invalid
+ * T-SQL). Used to exclude PII columns from a write's returned row. Empty
+ * selection → no clause.
+ */
+function mssqlOutput(returning, alias) {
+    if (!returning)
+        return '';
+    if (returning === '*')
+        return ` OUTPUT ${alias}.*`;
+    if (returning.length === 0)
+        return '';
+    return ` OUTPUT ${returning.map((col) => `${alias}.${col}`).join(', ')}`;
+}
 /**
  * SQL Server 2016+ implementation of the {@link Dialect} contract. Bracket
  * identifier quoting (`[…]`), named `@pN` placeholders, the `FOR JSON PATH`
@@ -511,7 +528,7 @@ export const mssqlDialect = {
         return '';
     },
     buildInsertStatement(input) {
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES (${input.valuePlaceholders.join(', ')})`;
     },
     buildBulkInsertStatement(input) {
@@ -531,7 +548,7 @@ export const mssqlDialect = {
         const placeholders = input.rowValues
             .map((row) => `(${row.map(() => this.paramPlaceholder(++n)).join(', ')})`)
             .join(', ');
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         // skipDuplicates has no single-statement equivalent here; ignored (documented).
         return {
             sql: `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES ${placeholders}`,
@@ -546,7 +563,7 @@ export const mssqlDialect = {
         const on = input.conflictColumns.map((c) => `T.${c} = S.${c}`).join(' AND ');
         const insertCols = input.insertColumns.join(', ');
         const sourceVals = input.insertColumns.map((c) => `S.${c}`).join(', ');
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return (`MERGE INTO ${input.table} AS T ` +
             `USING (VALUES (${input.valuePlaceholders.join(', ')})) AS S (${insertCols}) ` +
             `ON (${on}) ` +
@@ -557,11 +574,11 @@ export const mssqlDialect = {
     // UPDATE/DELETE inject OUTPUT mid-statement (between SET and WHERE / FROM and
     // WHERE) — a trailing clause would be invalid T-SQL.
     buildUpdateStatement(input) {
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return `UPDATE ${input.table} SET ${input.setClauses.join(', ')}${out}${input.whereSql}`;
     },
     buildDeleteStatement(input) {
-        const out = input.returning ? ` OUTPUT DELETED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'DELETED');
         return `DELETE FROM ${input.table}${out}${input.whereSql}`;
     },
     // SQL Server has no LIMIT — emit OFFSET/FETCH, injecting a stable ORDER BY when

package/dist/powdb.d.ts

@@ -580,6 +580,26 @@ interface EmbeddedModule {
  * as data and cannot break out of the literal or inject a second statement.
  */
 export declare function encodePowqlLiteral(value: unknown): string;
+/**
+ * The newest PowDB engine LINE (major.minor) whose lexer escape handling
+ * {@link encodePowqlString} is VERIFIED against by reading
+ * `crates/query/src/lexer.rs`. The legacy materialize path
+ * ({@link materializePowql}) inlines encoded string literals directly into query
+ * text, so it is only injection-safe while the lexer recognizes exactly the
+ * escape set the escaper emits (`\"`, `\\`, `\n`, `\t`, everything else raw). If
+ * a future engine line teaches the lexer new escapes (e.g. `\u`, `\x`), a string
+ * that the escaper leaves raw could be re-interpreted by the lexer and break out
+ * of the literal, turning the fallback into an injection primitive.
+ *
+ * CONTRACT: bump this ceiling ONLY after re-verifying the escape handling in
+ * `crates/query/src/lexer.rs` for the newer line AND confirming
+ * {@link encodePowqlString} still escapes every breakout vector the lexer
+ * recognizes. The legacy path guards on this value (see
+ * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
+ * the ceiling yet still routes through the string wire is refused rather than
+ * materialized.
+ */
+export declare const POWQL_LEXER_TESTED_CEILING = "0.15";
 /**
  * Substitute every `$N` placeholder in a generator-produced PowQL template with
  * the encoded literal of `params[N-1]`. Safe because the template is produced by

package/dist/powdb.js

@@ -1372,6 +1372,26 @@ export function encodePowqlLiteral(value) {
         return encodePowqlString(value);
     throw new ValidationError(`[turbine] Value of type ${typeof value} cannot be encoded as a PowDB literal.`);
 }
+/**
+ * The newest PowDB engine LINE (major.minor) whose lexer escape handling
+ * {@link encodePowqlString} is VERIFIED against by reading
+ * `crates/query/src/lexer.rs`. The legacy materialize path
+ * ({@link materializePowql}) inlines encoded string literals directly into query
+ * text, so it is only injection-safe while the lexer recognizes exactly the
+ * escape set the escaper emits (`\"`, `\\`, `\n`, `\t`, everything else raw). If
+ * a future engine line teaches the lexer new escapes (e.g. `\u`, `\x`), a string
+ * that the escaper leaves raw could be re-interpreted by the lexer and break out
+ * of the literal, turning the fallback into an injection primitive.
+ *
+ * CONTRACT: bump this ceiling ONLY after re-verifying the escape handling in
+ * `crates/query/src/lexer.rs` for the newer line AND confirming
+ * {@link encodePowqlString} still escapes every breakout vector the lexer
+ * recognizes. The legacy path guards on this value (see
+ * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
+ * the ceiling yet still routes through the string wire is refused rather than
+ * materialized.
+ */
+export const POWQL_LEXER_TESTED_CEILING = '0.15';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
 function encodePowqlString(s) {
     let out = '"';
@@ -1474,6 +1494,26 @@ export class PowdbEmbeddedPool {
         // Legacy string wire (addon < 0.14): the engine takes no params array, so
         // materialize each `$N` into a PowQL literal. Byte-for-byte unchanged, kept
         // live and tested as the pre-0.14 fallback.
+        //
+        // Safety assertion (see {@link POWQL_LEXER_TESTED_CEILING}): an addon whose
+        // engine line EXCEEDS the escaper's verified lexer ceiling must never be
+        // materialized: a newer lexer may recognize escapes the escaper leaves raw,
+        // making the inline path an injection primitive. Reachability: addons >= 0.14
+        // expose `queryWithParams` and take the native path above, so the ONLY way to
+        // reach this branch with a newer-than-ceiling engine is the anomalous
+        // newer-addon-without-native case (feature-detect failed). Refuse it rather
+        // than inline-encode against an unverified lexer.
+        const engineSem = parsePowdbSemver(this.capabilities.engineVersion);
+        const ceiling = parsePowdbSemver(POWQL_LEXER_TESTED_CEILING);
+        if (engineSem &&
+            ceiling &&
+            (engineSem.major > ceiling.major || (engineSem.major === ceiling.major && engineSem.minor > ceiling.minor))) {
+            throw new ValidationError(`[turbine] Refusing the PowDB legacy string wire: this embedded addon reports engine ` +
+                `${this.capabilities.engineVersion}, which is newer than the escaper's verified lexer range ` +
+                `(<= ${POWQL_LEXER_TESTED_CEILING}) AND such an addon exposes the parameterized native API, so ` +
+                `reaching the legacy materialize path means the queryWithParams feature-detect failed. Upgrade ` +
+                `turbine-orm so its PowQL escaper is verified against this engine line before running on it.`);
+        }
         const materialized = materializePowql(powql, params);
         return adaptResult(normalizeEmbeddedResult(this.db.query(materialized)));
     }

package/dist/powql.d.ts

@@ -175,8 +175,40 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private resolveRelationCondition;
     /** Resolve a manyToMany filter through the junction to `{ sourceRefField: { in|notIn: [...] } }`. */
     private resolveManyToManyCondition;
-    /** Resolve the set of columns to project, honouring `select` / `omit`. */
+    /**
+     * Resolve the set of columns to project, honouring `select` / `omit` and the
+     * query-level `includePii` opt-in. PII-tagged (`defineSchema` `pii: true`)
+     * columns are EXCLUDED from a default (or omit-only) projection unless
+     * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
+     * and returns it regardless. Untagged tables project exactly as before.
+     */
     private projectedColumns;
+    /**
+     * The snake_case names of this table's PII-tagged columns. Empty for a table
+     * with no `pii: true` column, so untagged tables keep their prior projection.
+     */
+    private piiColumnNames;
+    /**
+     * The camelCase field names of this table's PII-tagged columns: the read
+     * policy applied to a write's returned row (create/update/upsert/delete accept
+     * no `includePii`/`select`, so their result always drops PII; you may still
+     * write PII fields freely).
+     *
+     * SPEC LIMITATION (PowQL): the driver contract
+     * (`docs/integrations/powql-for-drivers.md`) exposes `returning` only as a
+     * bare keyword that hands back every column; it accepts NO column list, so
+     * (unlike the SQL engines, which emit an explicit non-PII `RETURNING`/`OUTPUT`
+     * projection) the create/update/delete `returning` paths cannot exclude PII at
+     * the query-language level and must strip it here after the fact. This is the
+     * client-side strip of last resort, not defense-in-depth, for those paths; we
+     * do NOT reverse-engineer an undocumented projection form. The upsert path is
+     * different: it has no `returning` and reselects by PK through the read
+     * projection ({@link projectedColumns}), which already omits PII, so PII never
+     * crosses the wire there. If a future spec revision lets `returning` take a
+     * projection, switch the write paths to emit the non-PII list and this strip
+     * becomes a no-op like {@link parseWriteRow} on the SQL engines.
+     */
+    private stripWritePii;
     /** `{ .c1, .c2, … }` projection clause. */
     private projection;
     /**

package/dist/powql.js

@@ -617,10 +617,17 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     // Projection / order
     // -------------------------------------------------------------------------
-    /** Resolve the set of columns to project, honouring `select` / `omit`. */
-    projectedColumns(select, omit) {
+    /**
+     * Resolve the set of columns to project, honouring `select` / `omit` and the
+     * query-level `includePii` opt-in. PII-tagged (`defineSchema` `pii: true`)
+     * columns are EXCLUDED from a default (or omit-only) projection unless
+     * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
+     * and returns it regardless. Untagged tables project exactly as before.
+     */
+    projectedColumns(select, omit, includePii) {
         let cols = this.meta.columns.map((c) => c.name);
-        if (select && Object.keys(select).length) {
+        const hasSelect = select && Object.keys(select).length;
+        if (hasSelect) {
             const picked = new Set(Object.entries(select)
                 .filter(([, v]) => v)
                 .map(([k]) => this.column(k).name));
@@ -629,6 +636,14 @@ export class PowqlInterface {
                 picked.add(pk);
             cols = cols.filter((c) => picked.has(c));
         }
+        else if (!includePii) {
+            // Default / omit-only projection: drop PII columns (kept above only when a
+            // caller names them in `select`). PK is never PII in practice; if one is
+            // tagged it is still dropped here, so tag sensitive data, not keys.
+            const pii = this.piiColumnNames();
+            if (pii.size)
+                cols = cols.filter((c) => !pii.has(c));
+        }
         if (omit && Object.keys(omit).length) {
             const dropped = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
@@ -637,6 +652,47 @@ export class PowqlInterface {
         }
         return cols;
     }
+    /**
+     * The snake_case names of this table's PII-tagged columns. Empty for a table
+     * with no `pii: true` column, so untagged tables keep their prior projection.
+     */
+    piiColumnNames() {
+        const out = new Set();
+        for (const col of this.meta.columns) {
+            if (col.pii)
+                out.add(col.name);
+        }
+        return out;
+    }
+    /**
+     * The camelCase field names of this table's PII-tagged columns: the read
+     * policy applied to a write's returned row (create/update/upsert/delete accept
+     * no `includePii`/`select`, so their result always drops PII; you may still
+     * write PII fields freely).
+     *
+     * SPEC LIMITATION (PowQL): the driver contract
+     * (`docs/integrations/powql-for-drivers.md`) exposes `returning` only as a
+     * bare keyword that hands back every column; it accepts NO column list, so
+     * (unlike the SQL engines, which emit an explicit non-PII `RETURNING`/`OUTPUT`
+     * projection) the create/update/delete `returning` paths cannot exclude PII at
+     * the query-language level and must strip it here after the fact. This is the
+     * client-side strip of last resort, not defense-in-depth, for those paths; we
+     * do NOT reverse-engineer an undocumented projection form. The upsert path is
+     * different: it has no `returning` and reselects by PK through the read
+     * projection ({@link projectedColumns}), which already omits PII, so PII never
+     * crosses the wire there. If a future spec revision lets `returning` take a
+     * projection, switch the write paths to emit the non-PII list and this strip
+     * becomes a no-op like {@link parseWriteRow} on the SQL engines.
+     */
+    stripWritePii(entity) {
+        if (!entity)
+            return entity;
+        for (const col of this.meta.columns) {
+            if (col.pii)
+                delete entity[col.field];
+        }
+        return entity;
+    }
     /** `{ .c1, .c2, … }` projection clause. */
     projection(cols) {
         return `{ ${cols.map((c) => `.${c}`).join(', ')} }`;
@@ -841,10 +897,7 @@ export class PowqlInterface {
             const { rows, native, resolvedWhere } = await this.runFind(args, 'findMany');
             const entities = this.shape(rows, native);
             if (args.with) {
-                await this.loadRelations(entities, args.with, args.timeout, 0, {
-                    args,
-                    resolvedWhere,
-                });
+                await this.loadRelations(entities, args.with, args.timeout, 0, { args, resolvedWhere }, args.includePii === true);
             }
             return entities;
         });
@@ -861,7 +914,7 @@ export class PowqlInterface {
         }
         const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
         const where = this.buildWhere(resolvedWhere, params);
-        const cols = this.projectedColumns(args.select, args.omit);
+        const cols = this.projectedColumns(args.select, args.omit, args.includePii === true);
         const distinct = args.distinct?.length ? ' distinct' : '';
         const filter = where ? ` filter ${where}` : '';
         const order = this.buildOrder(args.orderBy, params);
@@ -913,7 +966,7 @@ export class PowqlInterface {
                 return null;
             const entities = this.shape(rows, native);
             if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout);
+                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
@@ -924,7 +977,7 @@ export class PowqlInterface {
                 return null;
             const entities = this.shape(rows, native);
             if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout);
+                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
@@ -954,7 +1007,7 @@ export class PowqlInterface {
      * the default `'batched'` strategy) keeps the loaders. Output is byte-equal
      * either way (the join reuses the same stitch / shape helpers).
      */
-    async loadRelations(parents, withClause, timeout, depth = 0, parent) {
+    async loadRelations(parents, withClause, timeout, depth = 0, parent, includePii = false) {
         if (depth >= 10) {
             throw new ValidationError(`[turbine] Nested 'with' on PowDB exceeded depth 10 (relation cycle?).`);
         }
@@ -974,7 +1027,7 @@ export class PowqlInterface {
                 throw new ValidationError(`[turbine] Unknown relation "${relName}" on "${this.table}".`);
             if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args, parents.length)) {
                 if (this.capabilities.serverJoins) {
-                    await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout);
+                    await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
                     continue;
                 }
                 // An otherwise-eligible relation the engine cannot join: a PER-QUERY
@@ -986,7 +1039,7 @@ export class PowqlInterface {
                 }
             }
             if (rel.type === 'manyToMany') {
-                await this.loadManyToMany(parents, rel, relName, opt, timeout);
+                await this.loadManyToMany(parents, rel, relName, opt, timeout, includePii);
                 continue;
             }
             const fk = normalizeKeyColumns(rel.foreignKey);
@@ -1043,6 +1096,7 @@ export class PowqlInterface {
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
+                    includePii,
                 }));
                 for (const child of children) {
                     const k = this.joinKey(child[childKeyField]);
@@ -1079,7 +1133,7 @@ export class PowqlInterface {
      * single-key N+1 loaders; the junction's source/target columns must be single
      * (composite junction keys would need PowQL tuple-`in`, which it lacks).
      */
-    async loadManyToMany(parents, rel, relName, opt, timeout) {
+    async loadManyToMany(parents, rel, relName, opt, timeout, includePii = false) {
         const through = rel.through;
         if (!through)
             throw new ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
@@ -1143,6 +1197,7 @@ export class PowqlInterface {
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
+                includePii,
             }));
             for (const t of targets)
                 targetByPk.set(String(t[targetPkField]), t);
@@ -1260,9 +1315,9 @@ export class PowqlInterface {
         return tableMeta.indexes.some((idx) => idx.unique && !idx.docPath && idx.columns.length === 1 && idx.columns[0] === col);
     }
     /** Dispatch one eligible relation to the correct native-join loader. */
-    async loadRelationViaJoin(parents, rel, relName, opt, parent, timeout) {
+    async loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii = false) {
         if (rel.type === 'manyToMany') {
-            await this.loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout);
+            await this.loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
             return;
         }
         const options = (opt === true ? {} : opt);
@@ -1280,7 +1335,7 @@ export class PowqlInterface {
         const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
         const parentKeyField = this.meta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
         const params = [];
-        const childCols = this.joinChildCols(targetQi, options);
+        const childCols = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 'c', params, options.timeout ?? timeout);
         const order = targetQi.buildOrder(options.orderBy, params, 'c');
         const limitClause = options.limit !== undefined ? ` limit ${this.param(options.limit, params)}` : '';
@@ -1304,7 +1359,7 @@ export class PowqlInterface {
      * → the already-fetched side (alias `p`), correlating `__tpk` from the
      * junction's source key. Always a list, stitched exactly like the loader.
      */
-    async loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout) {
+    async loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout, includePii = false) {
         const through = rel.through;
         if (!through)
             throw new ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
@@ -1319,7 +1374,7 @@ export class PowqlInterface {
         const targetPkCol = targetMeta.primaryKey[0];
         const parentRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
         const params = [];
-        const childCols = this.joinChildCols(targetQi, options);
+        const childCols = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 't', params, options.timeout ?? timeout);
         const proj = this.joinProjection(childCols, `j.${quotePowqlIdent(sourceJCol)}`, 't');
         const powql = `${targetQi.qt} as t ` +
@@ -1338,8 +1393,8 @@ export class PowqlInterface {
      * with a loud guard: a real column named `__tpk` would collide with the
      * reserved correlation alias, so refuse rather than silently mis-stitch.
      */
-    joinChildCols(targetQi, options) {
-        const cols = targetQi.projectedColumns(options.select, options.omit);
+    joinChildCols(targetQi, options, includePii = false) {
+        const cols = targetQi.projectedColumns(options.select, options.omit, includePii);
         if (cols.includes('__tpk')) {
             throw new ValidationError(`[turbine] relation target "${targetQi.table}" has a column named "__tpk", which collides with the reserved ` +
                 `join correlation alias. Rename the column or load this relation with relationLoadStrategy: 'batched'.`);
@@ -1468,7 +1523,7 @@ export class PowqlInterface {
                 .join(', ');
             // `returning` surfaces the inserted row (all columns, schema order) in one round-trip.
             const { rows, native } = await this.exec(`insert ${this.qt} { ${body} } returning`, params, args.timeout, 'create');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: data });
             return row;
@@ -1486,7 +1541,7 @@ export class PowqlInterface {
             });
             // Multi-row insert with `returning` hands back every inserted row in one round-trip.
             const { rows, native } = await this.exec(`insert ${this.qt} ${tuples.join(', ')} returning`, params, args.timeout, 'createMany');
-            return this.shape(rows, native);
+            return this.shape(rows, native).map((r) => this.stripWritePii(r));
         });
     }
     async update(args) {
@@ -1501,7 +1556,7 @@ export class PowqlInterface {
             const setClause = this.buildUpdateAssignments(args.data, params);
             // `returning` hands back the post-update row(s); take the first (single-row contract).
             const { rows, native } = await this.exec(`${this.qt} filter ${where} update { ${setClause} } returning`, params, args.timeout, 'update');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
             return row;
@@ -1647,7 +1702,7 @@ export class PowqlInterface {
             this.assertCompiledWhere(where, false, 'delete');
             // `returning` hands back the deleted row(s) — no separate pre-image reselect needed.
             const { rows, native } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout, 'delete');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
             return row;

package/dist/query/aggregates.d.ts

@@ -0,0 +1,74 @@
+/**
+ * turbine-orm: aggregate / groupBy compilation (extracted from builder.ts)
+ *
+ * buildAggregate + buildGroupBy and their helpers (HAVING clauses, groupBy
+ * ordering, DISTINCT-ON sources, JSON-path aggregate targets). All functions
+ * take a {@link BuilderCtx} first argument; WHERE compilation is reused from
+ * where.ts (via `whereMod`), and the shared orderBy / row-parse primitives
+ * stay class-resident, reached through the ctx. See builder.ts for the thin
+ * delegating methods (buildGroupBy / buildAggregate).
+ */
+import type { DeferredQuery } from './deferred.js';
+import type { AggregateArgs, AggregateResult, GroupByArgs, GroupByOrderBy, HavingClause, HavingFilter } from './types.js';
+import type { BuilderCtx } from './where.js';
+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
+ * ({@link buildOrderBy}, which validates keys against the table's physical
+ * columns), groupBy ordering targets the columns the RESULT actually
+ * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+ * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+ * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+ * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+ * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+ * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+ * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+ * by-key, throws {@link ValidationError} E003 listing the valid keys.
+ */
+export declare function buildGroupByOrderBy(qi: BuilderCtx, orderBy: GroupByOrderBy, byOrderExprs: Map<string, string>, aggOrderExprs: Map<string, string>): string;
+/**
+ * Validate a JSON-path target (group key or aggregate target) in groupBy:
+ * the field must resolve to a real json/jsonb column and the path must be a
+ * non-empty array of keys/indexes. Returns the resolved snake_case column.
+ */
+export declare function resolveJsonPathTarget(qi: BuilderCtx, context: string, field: string, path: (string | number)[]): string;
+/**
+ * Build the `distinctOn` row source for groupBy (PostgreSQL only: other
+ * engines throw {@link UnsupportedFeatureError} E017):
+ *
+ * ```sql
+ * (SELECT DISTINCT ON ("c1") * FROM "table"<WHERE> ORDER BY "c1", <orderBy>) AS "table"
+ * ```
+ *
+ * The wrapper is aliased as the table name so every outer expression (group
+ * keys, aggregates, HAVING, ORDER BY) is byte-identical to the plain path.
+ * `distinctOn.orderBy` is required (it decides which row survives) and
+ * supports plain columns, {@link OrderBySpec} nulls, and JSON-path specs;
+ * JSON paths push their text[] param here, after the WHERE params.
+ */
+export declare function buildDistinctOnSource<T extends object>(qi: BuilderCtx, distinctOn: NonNullable<GroupByArgs<T>['distinctOn']>, whereSql: string, params: unknown[]): string;
+/**
+ * Build the SQL fragments for a {@link HavingClause}.
+ *
+ * Each aggregate expression (`COUNT(*)`, `SUM("col")`, etc.) is constructed
+ * from a **schema-validated, quoted** column identifier: `qi.toColumn()`
+ * throws {@link ValidationError} for unknown fields and `qi.q()` quotes via
+ * the dialect, so no unvalidated identifier ever reaches the SQL string. Every
+ * comparison value is pushed onto the shared `params` array and referenced by
+ * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
+ * interpolation of user values.
+ *
+ * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the
+ * exact aggregate expression a JSON-path aggregate emitted in SELECT
+ * (including its already-bound path placeholder), so HAVING on a JSON-path
+ * aggregate alias reuses the same expression instead of resolving the alias
+ * as a column.
+ */
+export declare function buildHavingClauses<T extends object>(qi: BuilderCtx, having: HavingClause<T>, params: unknown[], jsonAggExprs?: Map<string, string>): string[];
+/**
+ * Convert a single having filter into one or more parameterized SQL
+ * comparisons against the given aggregate expression. A bare number is
+ * shorthand for equality. Unknown operator keys throw {@link ValidationError}.
+ */
+export declare function buildHavingNumericClauses(qi: BuilderCtx, expr: string, filter: HavingFilter, params: unknown[]): string[];
+export declare function buildAggregate<T extends object>(qi: BuilderCtx, args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;