turbine-orm 0.21.0 → 0.23.0

package/dist/powql.js

@@ -0,0 +1,1226 @@
+/**
+ * PowqlInterface — Turbine's PowQL query generator (the PowDB analogue of
+ * {@link QueryInterface}). It exposes the same public method surface as the SQL
+ * `QueryInterface` (`findMany`, `create`, `update`, …) but emits **PowQL** — a
+ * pipeline language, not SQL — executed through {@link PowdbPool}.
+ *
+ * It is a *parallel* implementation rather than a `Dialect` of the SQL builder:
+ * PowQL's grammar (`T filter <e> order <k> { .col }`) shares no surface with
+ * `SELECT … FROM … WHERE`, so the SQL `Dialect` seam cannot express it. Keeping
+ * it separate also means the four SQL engines are untouched.
+ *
+ * Behavioural deltas from the SQL path, all driven by PowDB's wire reality (see
+ * `docs/strategy/powdb-parity-matrix.md`, every row verified against a live
+ * server):
+ *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
+ *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows
+ *     in one round-trip. `upsert` is the lone exception — its statement does not
+ *     accept `returning`, so it reselects the row by PK (a composite-PK upsert
+ *     reselects-or-writes inside one flat transaction).
+ *   - The PK is server-assigned when the column is `isGenerated` (PowDB's `auto`
+ *     int — read back via `returning`); otherwise a defaulted **string** PK is
+ *     generated client-side (UUID).
+ *   - `with` (nested relations) uses **batched N+1 loaders** — D round-trips for
+ *     depth D, not one query — including manyToMany (junction → targets).
+ *   - **Relation filters** (`some`/`none`/`every`, all cardinalities incl. m2m)
+ *     are resolved client-side to a literal `in (…)` list, never an IN-subquery:
+ *     PowDB's executor caches a subquery's result by plan shape and would return
+ *     a stale prior result for a later subquery of the same shape.
+ *   - **Nested writes** (relation ops in `create`/`update` data) run through the
+ *     shared nested-write engine as one flat top-level transaction (PowDB is
+ *     single-writer, no savepoints).
+ *   - pgvector / JSON / array filters and cursor streaming throw
+ *     {@link UnsupportedFeatureError} (E017) — they have no PowDB equivalent.
+ *
+ * @module
+ */
+import { randomUUID } from 'node:crypto';
+import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
+import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
+import { PowdbFloatParam, powqlColumnType, rowToEntity } from './powdb.js';
+import { escapeLike } from './query/utils.js';
+import { normalizeKeyColumns, } from './schema.js';
+/**
+ * Max parent keys per relation-loader `in (…)` query. A `with` over a large
+ * parent set is split into batches of this size so a single query never exceeds
+ * PowDB's per-statement param / row limits; the batches' children are merged
+ * before grouping. Mirrors the chunking the parity matrix documents.
+ */
+const MAX_RELATION_KEYS = 1000;
+/** Operator keys recognised inside a `WhereOperator` object. */
+const OPERATOR_KEYS = new Set([
+    'equals',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'not',
+    'in',
+    'notIn',
+    'contains',
+    'startsWith',
+    'endsWith',
+    'mode',
+]);
+/** Filters that have no PowDB representation and must throw E017. */
+function rejectUnsupportedFilter(value, field) {
+    if ('distance' in value || 'metric' in value) {
+        throw new UnsupportedFeatureError('pgvector distance filters', 'PowDB', `field "${field}"`);
+    }
+    if ('path' in value || 'hasKey' in value) {
+        throw new UnsupportedFeatureError('JSON path/key filters', 'PowDB', `field "${field}"`);
+    }
+    if ('hasEvery' in value || 'hasSome' in value || 'isEmpty' in value) {
+        throw new UnsupportedFeatureError('array filters', 'PowDB', `field "${field}"`);
+    }
+    if ('search' in value) {
+        throw new UnsupportedFeatureError('full-text search filters', 'PowDB', `field "${field}"`);
+    }
+}
+/**
+ * The PowQL query interface. Constructed by `turbinePowDB` via the
+ * `queryInterfaceFactory` seam and cast to `QueryInterface<object>` so
+ * `TurbineClient.table()` can return it transparently.
+ */
+export class PowqlInterface {
+    pool;
+    table;
+    schema;
+    middlewares;
+    options;
+    meta;
+    defaultLimit;
+    warnOnUnlimited;
+    onQuery;
+    currentAction = 'raw';
+    warnedUnlimited = false;
+    constructor(pool, table, schema, middlewares = [], options = {}) {
+        this.pool = pool;
+        this.table = table;
+        this.schema = schema;
+        this.middlewares = middlewares;
+        this.options = options;
+        const meta = schema.tables[table];
+        if (!meta) {
+            throw new ValidationError(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
+        }
+        this.meta = meta;
+        this.defaultLimit = options.defaultLimit;
+        this.warnOnUnlimited = options.warnOnUnlimited !== false;
+        this.onQuery = options._onQuery;
+    }
+    // -------------------------------------------------------------------------
+    // Column / value helpers
+    // -------------------------------------------------------------------------
+    /** Resolve a camelCase field name (or raw snake) to its column metadata. */
+    column(field) {
+        const snake = this.meta.columnMap[field] ?? field;
+        const col = this.meta.columns.find((c) => c.name === snake || c.field === field);
+        if (!col) {
+            throw new ValidationError(`[turbine] Unknown column "${field}" on table "${this.table}". Known: ${this.meta.columns
+                .map((c) => c.field)
+                .join(', ')}`);
+        }
+        return col;
+    }
+    /** PowQL column reference (`.snake_name`) for a field. */
+    ref(field) {
+        return `.${this.column(field).name}`;
+    }
+    /**
+     * Push a value into the param array and return its `$N` placeholder. When the
+     * value targets a `float` column it is wrapped in {@link PowdbFloatParam} so
+     * the *embedded* literal encoder emits a float-form literal even for an
+     * integer value (PowQL's `42` is an int literal, `42.0` a float). The
+     * networked driver unwraps the marker back to the plain number in
+     * {@link toPowdbParam}, so the wire param is unchanged.
+     */
+    param(value, params, col) {
+        const tagged = col && typeof value === 'number' && this.isFloatCol(col) ? new PowdbFloatParam(value) : value;
+        params.push(tagged);
+        return `$${params.length}`;
+    }
+    /**
+     * Render a value for a write *assignment* (`col := …`). Every value — float
+     * columns included — is sent as a positional `$N` param. PowDB ≥ 0.7.0 fixed
+     * the int→float UPDATE coercion bug (`score := $n` with an integer param now
+     * reads back the integer value, not the raw i64 bits), so the float-literal
+     * inlining workaround Turbine carried for ≤ 0.6.2 is gone. Marks the column as
+     * float-typed for the *embedded* literal encoder (which materializes params
+     * into PowQL text) so an integer-valued float still encodes as a float literal
+     * and coercion stays unambiguous. Non-finite floats are still rejected.
+     */
+    writeRef(value, col, params) {
+        if (typeof value === 'number' && !Number.isFinite(value) && this.isFloatCol(col)) {
+            throw new ValidationError(`[turbine] Non-finite value for float column "${col.name}" on "${this.table}".`);
+        }
+        return this.param(value, params, col);
+    }
+    isFloatCol(col) {
+        try {
+            return powqlColumnType(col) === 'float';
+        }
+        catch {
+            return false;
+        }
+    }
+    /** A predicate that is always false — the empty-`in` / contradiction sentinel. */
+    alwaysFalse() {
+        const pk = this.meta.primaryKey[0] ?? this.meta.columns[0]?.name;
+        return `(.${pk} is null and .${pk} is not null)`;
+    }
+    // -------------------------------------------------------------------------
+    // WHERE builder
+    // -------------------------------------------------------------------------
+    /**
+     * Compile a {@link WhereClause} into a PowQL filter expression, pushing every
+     * value as a positional `$N` param. Returns `''` when there are no conditions.
+     */
+    buildWhere(where, params) {
+        if (!where)
+            return '';
+        const parts = [];
+        for (const [key, value] of Object.entries(where)) {
+            if (value === undefined)
+                continue;
+            if (key === 'AND') {
+                const sub = value.map((w) => this.buildWhere(w, params)).filter(Boolean);
+                if (sub.length)
+                    parts.push(`(${sub.join(' and ')})`);
+            }
+            else if (key === 'OR') {
+                const sub = value.map((w) => this.buildWhere(w, params)).filter(Boolean);
+                if (sub.length)
+                    parts.push(`(${sub.join(' or ')})`);
+            }
+            else if (key === 'NOT') {
+                const sub = this.buildWhere(value, params);
+                if (sub)
+                    parts.push(`not (${sub})`);
+            }
+            else if (this.meta.relations[key]) {
+                // Relation filters are pre-resolved to scalar in/notIn by
+                // resolveRelationFilters() before buildWhere runs — reaching here means
+                // a caller skipped that step (an internal bug, not user error).
+                throw new ValidationError(`[turbine] internal: relation filter "${key}" reached buildWhere unresolved (missing resolveRelationFilters()).`);
+            }
+            else {
+                parts.push(this.buildFieldCondition(key, value, params));
+            }
+        }
+        return parts.join(' and ');
+    }
+    /** Build a single `field: value | operator` condition. */
+    buildFieldCondition(field, value, params) {
+        const ref = this.ref(field);
+        if (value === null)
+            return `${ref} is null`;
+        if (value instanceof Date || typeof value !== 'object') {
+            return `${ref} = ${this.param(value, params)}`;
+        }
+        const op = value;
+        rejectUnsupportedFilter(op, field);
+        if (!Object.keys(op).some((k) => OPERATOR_KEYS.has(k))) {
+            // A bare object that is not an operator set — equality by value.
+            return `${ref} = ${this.param(value, params)}`;
+        }
+        const insensitive = op.mode === 'insensitive';
+        const lhs = insensitive ? `lower(${ref})` : ref;
+        const conds = [];
+        for (const [opName, opVal] of Object.entries(op)) {
+            if (opVal === undefined || opName === 'mode')
+                continue;
+            switch (opName) {
+                case 'equals':
+                    conds.push(opVal === null ? `${ref} is null` : `${lhs} = ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'not':
+                    conds.push(opVal === null ? `${ref} is not null` : `not (${lhs} = ${this.bind(opVal, params, insensitive)})`);
+                    break;
+                case 'gt':
+                    conds.push(`${lhs} > ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'gte':
+                    conds.push(`${lhs} >= ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'lt':
+                    conds.push(`${lhs} < ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'lte':
+                    conds.push(`${lhs} <= ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'in':
+                    conds.push(this.buildInList(lhs, opVal, params, insensitive, false));
+                    break;
+                case 'notIn':
+                    conds.push(this.buildInList(lhs, opVal, params, insensitive, true));
+                    break;
+                case 'contains':
+                    conds.push(`${lhs} like ${this.bindLike(`%${escapeLike(String(opVal))}%`, params, insensitive)}`);
+                    break;
+                case 'startsWith':
+                    conds.push(`${lhs} like ${this.bindLike(`${escapeLike(String(opVal))}%`, params, insensitive)}`);
+                    break;
+                case 'endsWith':
+                    conds.push(`${lhs} like ${this.bindLike(`%${escapeLike(String(opVal))}`, params, insensitive)}`);
+                    break;
+                default:
+                    throw new ValidationError(`[turbine] Unsupported operator "${opName}" on PowDB.`);
+            }
+        }
+        return conds.length > 1 ? `(${conds.join(' and ')})` : (conds[0] ?? this.alwaysFalse());
+    }
+    /** Bind a value, lowercasing for case-insensitive comparisons. */
+    bind(value, params, insensitive) {
+        const ph = this.param(value, params);
+        return insensitive ? `lower(${ph})` : ph;
+    }
+    /** Bind a LIKE pattern (already escaped), lowercasing for insensitive mode. */
+    bindLike(pattern, params, insensitive) {
+        const ph = this.param(pattern, params);
+        return insensitive ? `lower(${ph})` : ph;
+    }
+    /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
+    buildInList(lhs, values, params, insensitive, negate) {
+        if (!Array.isArray(values) || values.length === 0) {
+            // `in []` matches nothing; `not in []` matches everything.
+            return negate ? '(1 = 1)' : this.alwaysFalse();
+        }
+        const items = values.map((v) => this.bind(v, params, insensitive)).join(', ');
+        return `${lhs} ${negate ? 'not in' : 'in'} (${items})`;
+    }
+    /**
+     * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause
+     * into a plain scalar `in`/`notIn` condition on the **local key**, by running
+     * the inner predicate as its own query and materializing the matching keys as
+     * a literal list. The compiled where is then relation-free and `buildWhere`
+     * emits only `in (<literal list>)`.
+     *
+     * Why not an IN-subquery (`.k in (Target filter <e> { .fk })`)? PowDB's
+     * executor caches a subquery's result by **plan shape, ignoring the literal**,
+     * so a second subquery of the same shape with a different value returns the
+     * first one's stale rows (reproduced live on the embedded engine; the
+     * single-statement literal `in (list)` form is always correct). Resolving
+     * client-side trades extra round-trips for correctness, and recurses — nested
+     * relation filters in the inner predicate resolve when the target query runs.
+     */
+    async resolveRelationFilters(where, timeout) {
+        if (!where)
+            return where;
+        const scalar = {};
+        const relConds = [];
+        for (const [key, value] of Object.entries(where)) {
+            if (value === undefined)
+                continue;
+            if (key === 'AND' || key === 'OR') {
+                scalar[key] = await Promise.all(value.map((w) => this.resolveRelationFilters(w, timeout)));
+            }
+            else if (key === 'NOT') {
+                scalar[key] = await this.resolveRelationFilters(value, timeout);
+            }
+            else if (this.meta.relations[key]) {
+                relConds.push(await this.resolveRelationCondition(this.meta.relations[key], value, timeout));
+            }
+            else {
+                scalar[key] = value;
+            }
+        }
+        if (!relConds.length)
+            return scalar;
+        const hasScalar = Object.keys(scalar).length > 0;
+        return { AND: [...(hasScalar ? [scalar] : []), ...relConds] };
+    }
+    /** Resolve one hasMany/hasOne/belongsTo filter to `{ localField: { in|notIn: [...] } }`. */
+    async resolveRelationCondition(rel, filter, timeout) {
+        const mode = filter.some ? 'some' : filter.none ? 'none' : filter.every ? 'every' : null;
+        if (!mode)
+            return {};
+        const innerWhere = filter[mode];
+        const innerEmpty = !innerWhere || Object.keys(innerWhere).length === 0;
+        if (rel.type === 'manyToMany') {
+            return this.resolveManyToManyCondition(rel, mode, innerWhere, innerEmpty, timeout);
+        }
+        const fk = normalizeKeyColumns(rel.foreignKey);
+        const rk = normalizeKeyColumns(rel.referenceKey);
+        if (fk.length > 1 || rk.length > 1) {
+            throw new UnsupportedFeatureError('composite-key relation filters', 'PowDB', `relation "${rel.name}" uses a composite key — PowQL has no tuple-\`in\` to express it`);
+        }
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new ValidationError(`[turbine] Relation "${rel.name}" targets unknown table "${rel.to}".`);
+        // hasMany/hasOne: localKey = our referenceKey, collect the child's foreignKey.
+        // belongsTo:      localKey = our foreignKey,   collect the target's referenceKey.
+        const localCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
+        const childCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
+        const localField = this.meta.reverseColumnMap[localCol] ?? localCol;
+        const childField = targetMeta.reverseColumnMap[childCol] ?? childCol;
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const collect = async (w) => {
+            const rows = await targetQi.findMany({
+                where: w,
+                select: { [childField]: true },
+                timeout,
+            });
+            return [...new Set(rows.map((r) => r[childField]).filter((v) => v != null))];
+        };
+        if (mode === 'some')
+            return { [localField]: { in: await collect(innerWhere) } };
+        if (mode === 'none')
+            return { [localField]: { notIn: await collect(innerWhere) } };
+        // every: a parent qualifies unless it has a child FAILING the predicate.
+        if (innerEmpty)
+            return {}; // every:{} ⇒ trivially true for all parents
+        return { [localField]: { notIn: await collect({ NOT: innerWhere }) } };
+    }
+    /** Resolve a manyToMany filter through the junction to `{ sourceRefField: { in|notIn: [...] } }`. */
+    async resolveManyToManyCondition(rel, mode, innerWhere, innerEmpty, timeout) {
+        const through = rel.through;
+        if (!through)
+            throw new ValidationError(`[turbine] manyToMany relation "${rel.name}" is missing its junction (\`through\`).`);
+        const sourceJ = normalizeKeyColumns(through.sourceKey);
+        const targetJ = normalizeKeyColumns(through.targetKey);
+        const sourceRef = normalizeKeyColumns(rel.referenceKey);
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new ValidationError(`[turbine] Relation "${rel.name}" targets unknown table "${rel.to}".`);
+        if (sourceJ.length > 1 || targetJ.length > 1 || sourceRef.length > 1 || targetMeta.primaryKey.length > 1) {
+            throw new UnsupportedFeatureError('composite-key manyToMany filters', 'PowDB', `relation "${rel.name}" — PowQL has no tuple-\`in\` for composite junction/target keys`);
+        }
+        const sourceJCol = sourceJ[0];
+        const targetJCol = targetJ[0];
+        const sourceRefCol = sourceRef[0];
+        const targetPkCol = targetMeta.primaryKey[0];
+        const sourceRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
+        const sourceRefColMeta = this.meta.columns.find((c) => c.name === sourceRefCol);
+        const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const collectTargetPks = async (w) => {
+            const rows = await targetQi.findMany({
+                where: w,
+                select: { [targetPkField]: true },
+                timeout,
+            });
+            return [...new Set(rows.map((r) => r[targetPkField]).filter((v) => v != null))];
+        };
+        // Junction source keys linking any of `targetPks` (literal IN-list — never a subquery).
+        const sourcesForTargets = async (targetPks) => {
+            if (!targetPks.length)
+                return [];
+            const out = new Set();
+            for (let i = 0; i < targetPks.length; i += MAX_RELATION_KEYS) {
+                const chunk = targetPks.slice(i, i + MAX_RELATION_KEYS);
+                const params = [];
+                const ph = chunk.map((v) => this.param(v, params)).join(', ');
+                const { rows } = await this.exec(`${through.table} filter .${targetJCol} in (${ph}) { .${sourceJCol} }`, params, timeout);
+                for (const r of rows) {
+                    const v = r[sourceJCol];
+                    if (v != null)
+                        out.add(sourceRefColMeta ? coerceScalar(String(v), sourceRefColMeta.tsType) : v);
+                }
+            }
+            return [...out];
+        };
+        if (mode === 'some') {
+            return { [sourceRefField]: { in: await sourcesForTargets(await collectTargetPks(innerWhere)) } };
+        }
+        if (mode === 'none') {
+            return { [sourceRefField]: { notIn: await sourcesForTargets(await collectTargetPks(innerWhere)) } };
+        }
+        // every: exclude parents that link a target FAILING the predicate.
+        if (innerEmpty)
+            return {}; // every:{} ⇒ trivially true
+        const failing = await sourcesForTargets(await collectTargetPks({ NOT: innerWhere }));
+        return { [sourceRefField]: { notIn: failing } };
+    }
+    // -------------------------------------------------------------------------
+    // Projection / order
+    // -------------------------------------------------------------------------
+    /** Resolve the set of columns to project, honouring `select` / `omit`. */
+    projectedColumns(select, omit) {
+        let cols = this.meta.columns.map((c) => c.name);
+        if (select && Object.keys(select).length) {
+            const picked = new Set(Object.entries(select)
+                .filter(([, v]) => v)
+                .map(([k]) => this.column(k).name));
+            // Always keep the PK so reselect / relation stitching has a key to work with.
+            for (const pk of this.meta.primaryKey)
+                picked.add(pk);
+            cols = cols.filter((c) => picked.has(c));
+        }
+        if (omit && Object.keys(omit).length) {
+            const dropped = new Set(Object.entries(omit)
+                .filter(([, v]) => v)
+                .map(([k]) => this.column(k).name));
+            cols = cols.filter((c) => !dropped.has(c));
+        }
+        return cols;
+    }
+    /** `{ .c1, .c2, … }` projection clause. */
+    projection(cols) {
+        return `{ ${cols.map((c) => `.${c}`).join(', ')} }`;
+    }
+    /** `order .c1 asc, .c2 desc` clause (empty string when no orderBy). */
+    buildOrder(orderBy) {
+        if (!orderBy)
+            return '';
+        const keys = Object.entries(orderBy).filter(([, dir]) => dir !== undefined);
+        if (!keys.length)
+            return '';
+        const parts = keys.map(([field, dir]) => {
+            if (dir && typeof dir === 'object') {
+                throw new UnsupportedFeatureError('vector / distance ordering', 'PowDB', `field "${field}"`);
+            }
+            return `${this.ref(field)} ${dir === 'desc' ? 'desc' : 'asc'}`;
+        });
+        return ` order ${parts.join(', ')}`;
+    }
+    // -------------------------------------------------------------------------
+    // Execution plumbing
+    // -------------------------------------------------------------------------
+    /** Run PowQL with optional timeout, emitting a query event either way. */
+    async exec(powql, params, timeout) {
+        const start = performance.now();
+        const run = this.pool.query(powql, params);
+        try {
+            const result = timeout
+                ? await Promise.race([
+                    run,
+                    new Promise((_, reject) => setTimeout(() => reject(new TimeoutError(timeout)), timeout)),
+                ])
+                : await run;
+            this.emit(powql, params, performance.now() - start, result.rowCount ?? result.rows.length);
+            return result;
+        }
+        catch (err) {
+            this.emit(powql, params, performance.now() - start, 0, err);
+            throw err;
+        }
+    }
+    emit(sql, params, duration, rows, error) {
+        if (!this.onQuery)
+            return;
+        try {
+            this.onQuery({
+                sql,
+                params,
+                duration,
+                model: this.table,
+                action: this.currentAction,
+                rows,
+                timestamp: new Date(),
+                error,
+            });
+        }
+        catch {
+            /* listener errors never crash a query */
+        }
+    }
+    /** Run a method body through the middleware chain (mirrors QueryInterface). */
+    async withMiddleware(action, args, executor) {
+        this.currentAction = action;
+        if (this.middlewares.length === 0)
+            return executor();
+        let index = 0;
+        const next = async (p) => {
+            if (index < this.middlewares.length)
+                return this.middlewares[index++](p, next);
+            return executor();
+        };
+        return next({ model: this.table, action, args: { ...args } });
+    }
+    /** Map raw rows to typed entities. */
+    shape(rows) {
+        return rows.map((r) => rowToEntity(r, this.meta));
+    }
+    // -------------------------------------------------------------------------
+    // Reads
+    // -------------------------------------------------------------------------
+    async findMany(args = {}) {
+        return this.withMiddleware('findMany', args, async () => {
+            const rows = await this.runFind(args);
+            const entities = this.shape(rows);
+            if (args.with)
+                await this.loadRelations(entities, args.with, args.timeout);
+            return entities;
+        });
+    }
+    /** Build + run the flat findMany select; returns raw rows. */
+    async runFind(args) {
+        if (args.cursor) {
+            throw new UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
+        }
+        const params = [];
+        const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+        const where = this.buildWhere(resolvedWhere, params);
+        const cols = this.projectedColumns(args.select, args.omit);
+        const distinct = args.distinct?.length ? ' distinct' : '';
+        const filter = where ? ` filter ${where}` : '';
+        const order = this.buildOrder(args.orderBy);
+        const limit = args.limit ?? args.take ?? this.defaultLimit;
+        if (limit === undefined && this.warnOnUnlimited && !this.warnedUnlimited) {
+            this.warnedUnlimited = true;
+            console.warn(`[turbine] findMany on "${this.table}" has no limit — this scans the whole table.`);
+        }
+        const limitClause = limit !== undefined ? ` limit ${this.param(limit, params)}` : '';
+        const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';
+        const powql = `${this.table}${distinct}${filter}${order}${limitClause}${offsetClause} ${this.projection(cols)}`;
+        const { rows } = await this.exec(powql, params, args.timeout);
+        return rows;
+    }
+    async findUnique(args) {
+        return this.withMiddleware('findUnique', args, async () => {
+            const rows = await this.runFind({ ...args, limit: 1 });
+            if (!rows.length)
+                return null;
+            const entities = this.shape(rows);
+            if (args.with)
+                await this.loadRelations(entities, args.with, args.timeout);
+            return entities[0];
+        });
+    }
+    async findFirst(args = {}) {
+        return this.withMiddleware('findFirst', args, async () => {
+            const rows = await this.runFind({ ...args, limit: 1 });
+            if (!rows.length)
+                return null;
+            const entities = this.shape(rows);
+            if (args.with)
+                await this.loadRelations(entities, args.with, args.timeout);
+            return entities[0];
+        });
+    }
+    async findUniqueOrThrow(args) {
+        const row = await this.findUnique(args);
+        if (!row)
+            throw new NotFoundError({ table: this.table, where: args.where });
+        return row;
+    }
+    async findFirstOrThrow(args = {}) {
+        const row = await this.findFirst(args);
+        if (!row)
+            throw new NotFoundError({ table: this.table, where: (args.where ?? {}) });
+        return row;
+    }
+    // -------------------------------------------------------------------------
+    // Nested relations — batched N+1 loaders (hasMany / hasOne / belongsTo)
+    // -------------------------------------------------------------------------
+    /** Load each requested relation for `parents` and attach it onto each row. */
+    async loadRelations(parents, withClause, timeout, depth = 0) {
+        if (depth >= 10) {
+            throw new ValidationError(`[turbine] Nested 'with' on PowDB exceeded depth 10 (relation cycle?).`);
+        }
+        if (!parents.length)
+            return;
+        for (const [relName, opt] of Object.entries(withClause)) {
+            if (!opt)
+                continue;
+            const rel = this.meta.relations[relName];
+            if (!rel)
+                throw new ValidationError(`[turbine] Unknown relation "${relName}" on "${this.table}".`);
+            if (rel.type === 'manyToMany') {
+                await this.loadManyToMany(parents, rel, relName, opt, timeout);
+                continue;
+            }
+            const fk = normalizeKeyColumns(rel.foreignKey);
+            const rk = normalizeKeyColumns(rel.referenceKey);
+            if (fk.length > 1 || rk.length > 1) {
+                throw new UnsupportedFeatureError('composite-key nested reads', 'PowDB', `relation "${relName}"`);
+            }
+            const options = (opt === true ? {} : opt);
+            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+            const targetMeta = this.schema.tables[rel.to];
+            // Local key on the parent, remote key on the target child.
+            const parentKeyCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
+            const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
+            const parentKeyField = this.meta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
+            const childKeyField = targetMeta.reverseColumnMap[childKeyCol] ?? childKeyCol;
+            const keys = [
+                ...new Set(parents.map((p) => p[parentKeyField]).filter((k) => k != null)),
+            ];
+            const childByKey = new Map();
+            // Chunk the key set so a single `in (…)` never exceeds PowDB's
+            // per-statement param / row limits; merge each chunk's children.
+            for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS) {
+                const chunk = keys.slice(i, i + MAX_RELATION_KEYS);
+                const childWhere = {
+                    ...options.where,
+                    [childKeyField]: { in: chunk },
+                };
+                const children = (await targetQi.findMany({
+                    ...options,
+                    where: childWhere,
+                    with: options.with,
+                    timeout: options.timeout ?? timeout,
+                }));
+                for (const child of children) {
+                    const k = child[childKeyField];
+                    const bucket = childByKey.get(k);
+                    if (bucket)
+                        bucket.push(child);
+                    else
+                        childByKey.set(k, [child]);
+                }
+            }
+            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+            for (const parent of parents) {
+                const k = parent[parentKeyField];
+                const matches = childByKey.get(k) ?? [];
+                parent[relName] = single ? (matches[0] ?? null) : matches;
+            }
+        }
+    }
+    /**
+     * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
+     * pushdown): (1) read the junction rows for all parents in `sourceKey in (…)`
+     * chunks, (2) read the target rows for the collected `targetKey`s, (3) stitch
+     * each parent → its junction rows → its targets in memory. Mirrors the
+     * 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) {
+        const through = rel.through;
+        if (!through)
+            throw new ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
+        const sourceJ = normalizeKeyColumns(through.sourceKey);
+        const targetJ = normalizeKeyColumns(through.targetKey);
+        const sourceRef = normalizeKeyColumns(rel.referenceKey);
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new ValidationError(`[turbine] Relation "${relName}" targets unknown table "${rel.to}".`);
+        if (sourceJ.length > 1 || targetJ.length > 1 || sourceRef.length > 1 || targetMeta.primaryKey.length > 1) {
+            throw new UnsupportedFeatureError('composite-key manyToMany', 'PowDB', `relation "${relName}" — PowQL has no tuple-\`in\`, so composite junction/target keys can't be loaded`);
+        }
+        const sourceJCol = sourceJ[0];
+        const targetJCol = targetJ[0];
+        const sourceRefCol = sourceRef[0];
+        const targetPkCol = targetMeta.primaryKey[0];
+        const parentRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
+        const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
+        const targetPkColMeta = targetMeta.columns.find((c) => c.name === targetPkCol);
+        const parentKeys = [
+            ...new Set(parents.map((p) => p[parentRefField]).filter((k) => k != null)),
+        ];
+        if (!parentKeys.length) {
+            for (const parent of parents)
+                parent[relName] = [];
+            return;
+        }
+        // (1) Junction rows: sourceKeyVal(String) → [targetKeyVal(String)].
+        const targetsBySource = new Map();
+        const allTargetVals = new Set();
+        for (let i = 0; i < parentKeys.length; i += MAX_RELATION_KEYS) {
+            const chunk = parentKeys.slice(i, i + MAX_RELATION_KEYS);
+            const params = [];
+            const placeholders = chunk.map((v) => this.param(v, params)).join(', ');
+            const powql = `${through.table} filter .${sourceJCol} in (${placeholders}) { .${sourceJCol}, .${targetJCol} }`;
+            const { rows } = await this.exec(powql, params, timeout);
+            for (const row of rows) {
+                const sv = String(row[sourceJCol]);
+                const tv = String(row[targetJCol]);
+                const bucket = targetsBySource.get(sv);
+                if (bucket)
+                    bucket.push(tv);
+                else
+                    targetsBySource.set(sv, [tv]);
+                allTargetVals.add(tv);
+            }
+        }
+        // (2) Target rows by PK, honouring the relation's own where/with/select/…
+        const options = (opt === true ? {} : opt);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetByPk = new Map();
+        const targetValList = [...allTargetVals].map((v) => targetPkColMeta ? coerceScalar(v, targetPkColMeta.tsType) : v);
+        for (let i = 0; i < targetValList.length; i += MAX_RELATION_KEYS) {
+            const chunk = targetValList.slice(i, i + MAX_RELATION_KEYS);
+            const where = {
+                ...options.where,
+                [targetPkField]: { in: chunk },
+            };
+            const targets = (await targetQi.findMany({
+                ...options,
+                where,
+                with: options.with,
+                timeout: options.timeout ?? timeout,
+            }));
+            for (const t of targets)
+                targetByPk.set(String(t[targetPkField]), t);
+        }
+        // (3) Stitch: each parent → its junction targets (m2m is always a list).
+        for (const parent of parents) {
+            const sv = String(parent[parentRefField]);
+            const tvs = targetsBySource.get(sv) ?? [];
+            const children = [];
+            for (const tv of tvs) {
+                const child = targetByPk.get(tv);
+                if (child)
+                    children.push(child);
+            }
+            parent[relName] = children;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Writes (reselect — PowDB has no RETURNING)
+    // -------------------------------------------------------------------------
+    /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
+    scalarData(data) {
+        const out = [];
+        for (const [field, value] of Object.entries(data)) {
+            if (value === undefined)
+                continue;
+            if (this.meta.relations[field]) {
+                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" — nested writes need create()/update(), not createMany()/upsert()`);
+            }
+            out.push({ col: this.column(field), value });
+        }
+        return out;
+    }
+    /**
+     * Fill in a client-generated UUID for a defaulted **string** PK that wasn't
+     * supplied. A server-generated PK ({@link ColumnMetadata.isGenerated}, e.g. an
+     * `int` column with PowDB's `auto` modifier) is left untouched — PowDB assigns
+     * it and the trailing `returning` reads it back — as is any non-string PK.
+     */
+    applyPkDefault(data) {
+        const out = { ...data };
+        for (const pk of this.meta.primaryKey) {
+            const field = this.meta.reverseColumnMap[pk] ?? pk;
+            const col = this.meta.columns.find((c) => c.name === pk);
+            if (out[field] == null &&
+                col?.hasDefault &&
+                !col.isGenerated &&
+                col.tsType.replace(/\s*\|\s*null$/, '').trim() === 'string') {
+                out[field] = randomUUID();
+            }
+        }
+        return out;
+    }
+    async create(args) {
+        return this.withMiddleware('create', args, async () => {
+            if (hasRelationFields(args.data, this.meta)) {
+                return this.nestedCreate(args);
+            }
+            const data = this.applyPkDefault(args.data);
+            const assigns = this.scalarData(data);
+            const params = [];
+            const body = assigns.map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`).join(', ');
+            // `returning` surfaces the inserted row (all columns, schema order) in one round-trip.
+            const { rows } = await this.exec(`insert ${this.table} { ${body} } returning`, params, args.timeout);
+            const row = rows.length ? this.shape(rows)[0] : null;
+            if (!row)
+                throw new NotFoundError({ table: this.table, where: data });
+            return row;
+        });
+    }
+    async createMany(args) {
+        return this.withMiddleware('createMany', args, async () => {
+            const inputs = args.data.map((d) => this.applyPkDefault(d));
+            if (!inputs.length)
+                return [];
+            const params = [];
+            const tuples = inputs.map((d) => {
+                const assigns = this.scalarData(d);
+                return `{ ${assigns.map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`).join(', ')} }`;
+            });
+            // Multi-row insert with `returning` hands back every inserted row in one round-trip.
+            const { rows } = await this.exec(`insert ${this.table} ${tuples.join(', ')} returning`, params, args.timeout);
+            return this.shape(rows);
+        });
+    }
+    async update(args) {
+        return this.withMiddleware('update', args, async () => {
+            if (hasRelationFields(args.data, this.meta)) {
+                return this.nestedUpdate(args);
+            }
+            const params = [];
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
+            this.assertCompiledWhere(where, false, 'update');
+            const setClause = this.buildUpdateAssignments(args.data, params);
+            // `returning` hands back the post-update row(s); take the first (single-row contract).
+            const { rows } = await this.exec(`${this.table} filter ${where} update { ${setClause} } returning`, params, args.timeout);
+            const row = rows.length ? this.shape(rows)[0] : null;
+            if (!row)
+                throw new NotFoundError({ table: this.table, where: args.where });
+            return row;
+        });
+    }
+    async updateMany(args) {
+        return this.withMiddleware('updateMany', args, async () => {
+            const params = [];
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
+            this.assertCompiledWhere(where, args.allowFullTableScan, 'updateMany');
+            const setClause = this.buildUpdateAssignments(args.data, params);
+            const filter = where ? ` filter ${where}` : '';
+            const { rowCount } = await this.exec(`${this.table}${filter} update { ${setClause} }`, params, args.timeout);
+            return { count: rowCount };
+        });
+    }
+    /** Compile `data` into PowQL update assignments, including atomic operators. */
+    buildUpdateAssignments(data, params) {
+        const parts = [];
+        for (const [field, value] of Object.entries(data)) {
+            if (value === undefined)
+                continue;
+            if (this.meta.relations[field]) {
+                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" — nested writes need create()/update(), not updateMany()/upsert()`);
+            }
+            const colMeta = this.column(field);
+            const ref = this.ref(field);
+            const col = colMeta.name;
+            if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
+                const opObj = value;
+                if ('set' in opObj)
+                    parts.push(`${col} := ${this.writeRef(opObj.set, colMeta, params)}`);
+                else if ('increment' in opObj)
+                    parts.push(`${col} := ${ref} + ${this.writeRef(opObj.increment, colMeta, params)}`);
+                else if ('decrement' in opObj)
+                    parts.push(`${col} := ${ref} - ${this.writeRef(opObj.decrement, colMeta, params)}`);
+                else if ('multiply' in opObj)
+                    parts.push(`${col} := ${ref} * ${this.writeRef(opObj.multiply, colMeta, params)}`);
+                else if ('divide' in opObj)
+                    parts.push(`${col} := ${ref} / ${this.writeRef(opObj.divide, colMeta, params)}`);
+                else
+                    throw new ValidationError(`[turbine] Unsupported update operator on "${field}".`);
+            }
+            else {
+                parts.push(`${col} := ${this.writeRef(value, colMeta, params)}`);
+            }
+        }
+        if (!parts.length)
+            throw new ValidationError(`[turbine] update on "${this.table}" has no fields to set.`);
+        return parts.join(', ');
+    }
+    // -------------------------------------------------------------------------
+    // Nested writes — create/update whose `data` carries relation ops (create,
+    // connect, connectOrCreate, disconnect, set, delete, update, upsert). Reuses
+    // the engine-agnostic nested-write engine (it only needs ctx.schema + the
+    // table accessors PowqlInterface already provides). Runs as ONE flat top-level
+    // PowDB transaction — single global write lock, no savepoints, so the whole
+    // tree commits or rolls back together (mirrors the SQL path's coverage:
+    // hasMany / hasOne / belongsTo; manyToMany nested writes are not handled by
+    // the shared engine on any backend).
+    // -------------------------------------------------------------------------
+    isTxScoped() {
+        return this.options._txScoped === true;
+    }
+    async nestedCreate(args) {
+        const data = args.data;
+        if (this.isTxScoped()) {
+            return executeNestedCreate(this.buildNestedCtx(), this.table, data);
+        }
+        return this.runInImplicitTx((ctx) => executeNestedCreate(ctx, this.table, data));
+    }
+    async nestedUpdate(args) {
+        const data = args.data;
+        const where = args.where;
+        if (this.isTxScoped()) {
+            return executeNestedUpdate(this.buildNestedCtx(), this.table, where, data);
+        }
+        return this.runInImplicitTx((ctx) => executeNestedUpdate(ctx, this.table, where, data));
+    }
+    /** Open a flat PowDB transaction on a pinned connection and run `fn` inside it. */
+    async runInImplicitTx(fn) {
+        // Route tx keywords through the dialect (like the SQL path) so this never
+        // drifts from `powdbDialect`; falls back to the literal lowercase keywords.
+        const d = this.options.dialect;
+        const client = await this.pool.connect();
+        try {
+            await client.query(d?.beginStatement?.() ?? 'begin');
+            const { TransactionClient } = await import('./client.js');
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
+            const ctx = { schema: this.schema, tx: tx };
+            const result = await fn(ctx);
+            await client.query(d?.commitStatement?.() ?? 'commit');
+            return result;
+        }
+        catch (err) {
+            try {
+                await client.query(d?.rollbackStatement?.() ?? 'rollback');
+            }
+            catch {
+                /* best-effort — the connection may be gone */
+            }
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /** Already inside a transaction: build a context whose table accessors reuse the pinned pool. */
+    buildNestedCtx() {
+        const opts = { ...this.options, _txScoped: true };
+        const tx = {
+            table: (name) => new PowqlInterface(this.pool, name, this.schema, this.middlewares, opts),
+        };
+        return { schema: this.schema, tx: tx };
+    }
+    async delete(args) {
+        return this.withMiddleware('delete', args, async () => {
+            const params = [];
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
+            this.assertCompiledWhere(where, false, 'delete');
+            // `returning` hands back the deleted row(s) — no separate pre-image reselect needed.
+            const { rows } = await this.exec(`${this.table} filter ${where} delete returning`, params, args.timeout);
+            const row = rows.length ? this.shape(rows)[0] : null;
+            if (!row)
+                throw new NotFoundError({ table: this.table, where: args.where });
+            return row;
+        });
+    }
+    async deleteMany(args) {
+        return this.withMiddleware('deleteMany', args, async () => {
+            const params = [];
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
+            this.assertCompiledWhere(where, args.allowFullTableScan, 'deleteMany');
+            const filter = where ? ` filter ${where}` : '';
+            const { rowCount } = await this.exec(`${this.table}${filter} delete`, params, args.timeout);
+            return { count: rowCount };
+        });
+    }
+    async upsert(args) {
+        return this.withMiddleware('upsert', args, async () => {
+            const createData = this.applyPkDefault(args.create);
+            const pkCol = this.meta.primaryKey[0];
+            if (this.meta.primaryKey.length !== 1 || !pkCol) {
+                // PowQL's native `upsert … on .col` takes a single conflict column, so a
+                // composite PK falls back to an atomic reselect-or-write transaction.
+                return this.upsertComposite(createData, args.update);
+            }
+            const params = [];
+            const createBody = this.scalarData(createData)
+                .map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`)
+                .join(', ');
+            const updateBody = this.buildUpdateAssignments(args.update, params);
+            // PowDB 0.7.0's `upsert` statement does NOT accept a trailing `returning`
+            // (verified: "unexpected trailing token … 'returning'"), because it is one
+            // atomic insert-or-update, not two branches. So upsert alone keeps the
+            // reselect-by-PK fetch; create/update/delete all use `returning`.
+            await this.exec(`upsert ${this.table} on .${pkCol} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout);
+            const pkField = this.meta.reverseColumnMap[pkCol] ?? pkCol;
+            const row = await this.reselectByPk(createData[pkField], args.timeout);
+            if (!row)
+                throw new NotFoundError({ table: this.table, where: createData });
+            return row;
+        });
+    }
+    /**
+     * Composite-key upsert: PowQL's `upsert … on .col` only takes one conflict
+     * column, so reselect by the full composite PK and update-or-create inside one
+     * flat transaction (PowDB single-writer makes the read-then-write safe from
+     * concurrent writers; the transaction makes it atomic with the write).
+     */
+    async upsertComposite(createData, updateData) {
+        // Accept either the camelCase field or the snake_case column in `create`
+        // (create() resolves both), and key the where by field name.
+        const pkPairs = this.meta.primaryKey.map((pk) => {
+            const field = this.meta.reverseColumnMap[pk] ?? pk;
+            return { field, value: createData[field] ?? createData[pk] };
+        });
+        if (pkPairs.some((p) => p.value == null)) {
+            throw new ValidationError(`[turbine] upsert on "${this.table}" needs every composite-PK field in \`create\` (${pkPairs
+                .map((p) => p.field)
+                .join(', ')}).`);
+        }
+        const pkWhere = Object.fromEntries(pkPairs.map((p) => [p.field, p.value]));
+        const run = async (ctx) => {
+            const tbl = ctx.tx.table(this.table);
+            const existing = await tbl.findUnique({ where: pkWhere });
+            return existing
+                ? (await tbl.update({ where: pkWhere, data: updateData }))
+                : (await tbl.create({ data: createData }));
+        };
+        return this.isTxScoped() ? run(this.buildNestedCtx()) : this.runInImplicitTx(run);
+    }
+    // -------------------------------------------------------------------------
+    // Aggregates
+    // -------------------------------------------------------------------------
+    async count(args = {}) {
+        return this.withMiddleware('count', (args ?? {}), async () => {
+            const params = [];
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
+            const filter = where ? ` filter ${where}` : '';
+            const { rows } = await this.exec(`count(${this.table}${filter})`, params, args.timeout);
+            return Number((rows[0]?.value ?? rows[0]?.count ?? 0));
+        });
+    }
+    async aggregate(args) {
+        return this.withMiddleware('aggregate', args, async () => {
+            // One scalar query per aggregate — PowDB's bare-projection aggregate is broken.
+            const result = {};
+            const filterParams = [];
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, filterParams);
+            const filter = where ? ` filter ${where}` : '';
+            const scalar = async (expr) => {
+                const params = [...filterParams];
+                const { rows } = await this.exec(expr, params, args.timeout);
+                const v = rows[0]?.value;
+                return v == null || v === 'null' ? null : Number(v);
+            };
+            if (args._count) {
+                if (args._count === true) {
+                    result._count = (await scalar(`count(${this.table}${filter})`)) ?? 0;
+                }
+                else {
+                    const counts = {};
+                    for (const field of Object.keys(args._count).filter((f) => args._count[f])) {
+                        counts[field] = (await scalar(`count(${this.table}${filter} { ${this.ref(field)} })`)) ?? 0;
+                    }
+                    result._count = counts;
+                }
+            }
+            for (const fn of ['_sum', '_avg', '_min', '_max']) {
+                const spec = args[fn];
+                if (!spec)
+                    continue;
+                const acc = {};
+                for (const field of Object.keys(spec).filter((f) => spec[f])) {
+                    const powfn = fn.slice(1); // sum/avg/min/max
+                    acc[field] = await scalar(`${powfn}(${this.table}${filter} { ${this.ref(field)} })`);
+                }
+                result[fn] = acc;
+            }
+            return result;
+        });
+    }
+    async groupBy(args) {
+        return this.withMiddleware('groupBy', args, async () => {
+            const params = [];
+            const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
+            const where = this.buildWhere(resolvedWhere, params);
+            const filter = where ? ` filter ${where}` : '';
+            const groupKeys = args.by.map((f) => this.ref(f));
+            // Safe aliases — PowQL rejects reserved-word aliases (e.g. `count:`).
+            const aliasMap = [];
+            let n = 0;
+            const proj = args.by.map((f) => this.ref(f));
+            if (args._count) {
+                aliasMap.push({ alias: `agg_${n++}`, fn: 'count', field: null, outKey: '_count' });
+            }
+            for (const fn of ['_sum', '_avg', '_min', '_max']) {
+                const spec = args[fn];
+                if (!spec)
+                    continue;
+                for (const field of Object.keys(spec).filter((f) => spec[f])) {
+                    aliasMap.push({ alias: `agg_${n++}`, fn: fn.slice(1), field, outKey: `${fn}:${field}` });
+                }
+            }
+            for (const a of aliasMap) {
+                proj.push(`${a.alias}: ${a.fn}(${a.field ? this.ref(a.field) : `.${this.meta.primaryKey[0]}`})`);
+            }
+            const having = this.buildHaving(args.having, params);
+            const order = this.buildOrder(args.orderBy);
+            const powql = `${this.table}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
+            const { rows } = await this.exec(powql, params, args.timeout);
+            // Reshape: group keys → camel fields + coerced; aggregates → nested {_sum:{field}}.
+            return rows.map((raw) => {
+                const out = {};
+                for (const f of args.by) {
+                    const col = this.column(f);
+                    out[f] =
+                        typeof raw[col.name] === 'string' ? coerceScalar(raw[col.name], col.tsType) : raw[col.name];
+                }
+                for (const a of aliasMap) {
+                    const val = raw[a.alias];
+                    const num = val == null || val === 'null' ? null : Number(val);
+                    if (a.outKey === '_count')
+                        out._count = num ?? 0;
+                    else {
+                        const [bucket, field] = a.outKey.split(':');
+                        out[bucket] ??= {};
+                        out[bucket][field] = num;
+                    }
+                }
+                return out;
+            });
+        });
+    }
+    /** `having <expr>` over group aggregates (count/sum/avg/min/max). */
+    buildHaving(having, params) {
+        if (!having)
+            return '';
+        const conds = [];
+        const cmp = (expr, filter) => {
+            if (typeof filter === 'number')
+                return `${expr} = ${this.param(filter, params)}`;
+            const f = filter;
+            const ops = { equals: '=', gt: '>', gte: '>=', lt: '<', lte: '<=', not: '!=' };
+            return Object.entries(f)
+                .filter(([k]) => ops[k])
+                .map(([k, v]) => `${expr} ${ops[k]} ${this.param(v, params)}`)
+                .join(' and ');
+        };
+        for (const [key, spec] of Object.entries(having)) {
+            if (spec == null)
+                continue;
+            if (key === '_count') {
+                conds.push(cmp(`count(.${this.meta.primaryKey[0]})`, spec));
+            }
+            else {
+                for (const [fn, filter] of Object.entries(spec)) {
+                    if (filter == null)
+                        continue;
+                    conds.push(cmp(`${fn.slice(1)}(${this.ref(key)})`, filter));
+                }
+            }
+        }
+        return conds.length ? ` having ${conds.join(' and ')}` : '';
+    }
+    // -------------------------------------------------------------------------
+    // Streaming / unsupported
+    // -------------------------------------------------------------------------
+    // biome-ignore lint/correctness/useYield: intentionally throws before yielding — PowDB has no server cursor.
+    async *findManyStream() {
+        throw new UnsupportedFeatureError('cursor streaming (findManyStream)', 'PowDB', 'PowDB has no server-side cursor; page with findMany({ limit, offset }) instead');
+    }
+    // -------------------------------------------------------------------------
+    // Reselect helper (upsert only — PowDB's upsert has no `returning`)
+    // -------------------------------------------------------------------------
+    /** Reselect a single row by its single-column primary key value. */
+    async reselectByPk(pkValue, timeout) {
+        const pkField = this.meta.reverseColumnMap[this.meta.primaryKey[0]] ?? this.meta.primaryKey[0];
+        const rows = await this.runFind({
+            where: { [pkField]: pkValue },
+            limit: 1,
+            timeout,
+        });
+        return rows.length ? this.shape(rows)[0] : null;
+    }
+    /**
+     * Empty-where guard — blocks accidental whole-table writes. Mirrors the SQL
+     * path's `assertMutationHasPredicate` (query/builder.ts): it gates on the
+     * *compiled* PowQL filter fragment, NOT the shape of the `where` object. A
+     * `where` whose conditions all evaporate during compilation — `{}`,
+     * `{ id: undefined }`, `{ OR: [] }`, `{ AND: [] }`, `{ NOT: {} }`,
+     * `{ OR: [{ f: undefined }] }` — compiles to the empty string and is refused,
+     * because emitting a filter-less write would hit every row.
+     */
+    assertCompiledWhere(compiledWhere, allow, action) {
+        if (allow === true)
+            return;
+        if (compiledWhere.length > 0)
+            return;
+        throw new ValidationError(`[turbine] ${action} on "${this.table}" refused: the \`where\` clause is empty. ` +
+            `Pass \`allowFullTableScan: true\` to opt in, or check that your filter values are defined.`);
+    }
+}
+/** Coerce a group-key scalar string by the column's TS type (numbers/bools). */
+function coerceScalar(raw, tsType) {
+    const ts = tsType.replace(/\s*\|\s*null$/i, '').trim();
+    if (raw === 'null')
+        return null;
+    if (ts === 'number' || ts === 'bigint') {
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : raw;
+    }
+    if (ts === 'boolean')
+        return raw === 'true';
+    if (ts === 'Date')
+        return new Date(Number(raw) / 1000);
+    return raw;
+}
+//# sourceMappingURL=powql.js.map