turbine-orm 0.33.0 → 0.35.0

package/dist/powql.js

@@ -35,10 +35,10 @@
  * @module
  */
 import { randomUUID } from 'node:crypto';
-import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
+import { NotFoundError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
-import { PowdbFloatParam, powqlColumnType, quotePowqlIdent, rowToEntity } from './powdb.js';
-import { isRelationPickOrderBy } from './query/filters.js';
+import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb.js';
+import { isJsonFilter, isRelationPickOrderBy } from './query/filters.js';
 import { escapeLike } from './query/utils.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -48,6 +48,38 @@ import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
  * before grouping. Mirrors the chunking the parity matrix documents.
  */
 const MAX_RELATION_KEYS = 1000;
+/**
+ * Read-shaped actions whose statement may be transparently replayed once on a
+ * stale wire frame when `retryStaleReads` is enabled (see
+ * {@link PowqlInterface.execOnce}). Writes are deliberately absent: replaying a
+ * mutation after an ambiguous reply can double-execute, matching the client's
+ * own native-path policy.
+ */
+const POWQL_READ_ACTIONS = new Set([
+    'findMany',
+    'findUnique',
+    'findFirst',
+    'count',
+    'aggregate',
+    'groupBy',
+    'explain',
+]);
+/**
+ * Mutating actions the {@link PowqlInterface} readonly guard refuses locally
+ * (before the wire) on a read-only pool. A transaction-control `begin` is
+ * guarded separately in {@link PowqlInterface.runInImplicitTx}. Kept keyed on
+ * the per-call action string (never `this`-state) so a concurrent read can
+ * never be mistaken for one of these.
+ */
+const POWQL_WRITE_ACTIONS = new Set([
+    'create',
+    'createMany',
+    'update',
+    'updateMany',
+    'delete',
+    'deleteMany',
+    'upsert',
+]);
 /** Operator keys recognised inside a `WhereOperator` object. */
 const OPERATOR_KEYS = new Set([
     'equals',
@@ -93,7 +125,6 @@ export class PowqlInterface {
     defaultLimit;
     warnOnUnlimited;
     onQuery;
-    currentAction = 'raw';
     warnedUnlimited = false;
     constructor(pool, table, schema, middlewares = [], options = {}) {
         this.pool = pool;
@@ -131,9 +162,19 @@ export class PowqlInterface {
         }
         return col;
     }
-    /** PowQL column reference (`.snake_name`) for a field. */
-    ref(field) {
-        return `.${this.column(field).name}`;
+    /**
+     * PowQL column reference for a field. Unqualified it is a dotted field
+     * reference (`.snake_name`), which bypasses keyword lookup. When an `alias`
+     * is supplied (the F2 join path) it is qualified (`alias.snake_name`) and the
+     * column name is backtick-quoted if it is a reserved word (a qualified
+     * `p.order` does NOT bypass keyword lookup, unlike the dotted `.order`).
+     */
+    ref(field, alias) {
+        return this.colRefName(this.column(field).name, alias);
+    }
+    /** Render a raw column name as a PowQL reference, qualified with `alias` when given. */
+    colRefName(name, alias) {
+        return alias ? `${alias}.${quotePowqlIdent(name)}` : `.${name}`;
     }
     /**
      * Push a value into the param array and return its `$N` placeholder. When the
@@ -144,7 +185,17 @@ export class PowqlInterface {
      * {@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;
+        let tagged = value;
+        if (col && typeof value === 'number' && this.isFloatCol(col)) {
+            // Float column: force a float-form literal even for an integer value.
+            tagged = new PowdbFloatParam(value);
+        }
+        else if (col && value !== null && typeof value === 'object' && !(value instanceof Date) && isJsonColumn(col)) {
+            // json document column: a JS object/array is serialized to canonical JSON
+            // text and stored as a json document (a JS string passes through raw, same
+            // contract as pg jsonb; `null` stays `null`).
+            tagged = new PowdbJsonParam(value);
+        }
         params.push(tagged);
         return `$${params.length}`;
     }
@@ -172,6 +223,15 @@ export class PowqlInterface {
             return false;
         }
     }
+    /**
+     * The bound pool's {@link PowdbCapabilities}. Falls back to the trusted-caller
+     * default (all feature gates on, `nativeRaw` off) when a directly-constructed
+     * pool did not carry them, matching {@link PowdbPool}'s own constructor
+     * default so a hand-built test pool never crashes the version gates.
+     */
+    get capabilities() {
+        return this.pool.capabilities ?? ALL_POWDB_CAPABILITIES;
+    }
     /** A predicate that is always false — the empty-`in` / contradiction sentinel. */
     alwaysFalse() {
         const pk = this.meta.primaryKey[0] ?? this.meta.columns[0]?.name;
@@ -183,8 +243,15 @@ export class PowqlInterface {
     /**
      * Compile a {@link WhereClause} into a PowQL filter expression, pushing every
      * value as a positional `$N` param. Returns `''` when there are no conditions.
+     *
+     * When `alias` is supplied (the F2 native-join path) every field reference is
+     * qualified with it (`.col` → `alias.col`, JSON path bases too); params bind
+     * exactly as in the unqualified path. The caller only ever passes an alias for
+     * an already-RESOLVED where (relation filters pre-resolved to literal in-lists
+     * by {@link resolveRelationFilters}): the relation-key branch below still
+     * throws, so an unresolved relation filter can never leak into a join.
      */
-    buildWhere(where, params) {
+    buildWhere(where, params, alias) {
         if (!where)
             return '';
         const parts = [];
@@ -192,17 +259,17 @@ export class PowqlInterface {
             if (value === undefined)
                 continue;
             if (key === 'AND') {
-                const sub = value.map((w) => this.buildWhere(w, params)).filter(Boolean);
+                const sub = value.map((w) => this.buildWhere(w, params, alias)).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);
+                const sub = value.map((w) => this.buildWhere(w, params, alias)).filter(Boolean);
                 if (sub.length)
                     parts.push(`(${sub.join(' or ')})`);
             }
             else if (key === 'NOT') {
-                const sub = this.buildWhere(value, params);
+                const sub = this.buildWhere(value, params, alias);
                 if (sub)
                     parts.push(`not (${sub})`);
             }
@@ -213,20 +280,33 @@ export class PowqlInterface {
                 throw new ValidationError(`[turbine] internal: relation filter "${key}" reached buildWhere unresolved (missing resolveRelationFilters()).`);
             }
             else {
-                parts.push(this.buildFieldCondition(key, value, params));
+                // A JsonFilter (or a bare `{ path }`) can compile to zero clauses; skip
+                // empty results so buildWhere never emits a dangling ` and `.
+                const cond = this.buildFieldCondition(key, value, params, alias);
+                if (cond)
+                    parts.push(cond);
             }
         }
         return parts.join(' and ');
     }
     /** Build a single `field: value | operator` condition. */
-    buildFieldCondition(field, value, params) {
-        const ref = this.ref(field);
+    buildFieldCondition(field, value, params, alias) {
+        const colMeta = this.column(field);
+        const ref = this.ref(field, alias);
         if (value === null)
             return `${ref} is null`;
         if (value instanceof Date || typeof value !== 'object') {
-            return `${ref} = ${this.param(value, params)}`;
+            return `${ref} = ${this.param(value, params, colMeta)}`;
         }
         const op = value;
+        // JSON path / key filters on a json document column compile to PowQL `->`
+        // path filters (≥ 0.12). `isJsonFilter` matches `path`/`equals`/`contains`/
+        // `hasKey`; on a NON-json column those fall through to the scalar operator
+        // path below (e.g. `equals` stays a plain equality), exactly like SQL.
+        if (isJsonColumn(colMeta) && isJsonFilter(value)) {
+            requireCapability(this.capabilities, 'jsonDocs', 'JSON path filters');
+            return this.buildJsonPathCondition(colMeta, value, params, alias);
+        }
         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.
@@ -278,6 +358,100 @@ export class PowqlInterface {
         }
         return conds.length > 1 ? `(${conds.join(' and ')})` : (conds[0] ?? this.alwaysFalse());
     }
+    /**
+     * PowQL JSON path expression `.col->$a->$b…`, binding EVERY path segment as a
+     * positional param (a string segment as a `str` token, an integer index as an
+     * `int` token). `->` binds tighter than every operator, so no parens are
+     * needed around the path in a comparison. Segments are bound (never inlined)
+     * to keep {@link materializePowql}'s `$N`-scan invariant intact: a segment
+     * that literally contained `$1` would otherwise be rewritten. Shared by the
+     * F1 where-filter path and the F2 orderBy / groupBy path emitters.
+     *
+     * A digit-only STRING segment (`'0'`) binds as an `int` array index, matching
+     * the SQL engines: `JsonFilter.path` is typed `string[]`, so an array index
+     * can only be expressed as a digit string, and the SQL builder converts it the
+     * same way (`/^\d+$/ → [n]`, query/builder.ts). Without this, PowDB's typed
+     * `->` treats `'0'` as a string KEY and silently matches nothing on an array
+     * (a wrong result, not an error). Same object-key-`'0'` caveat SQL accepts: a
+     * json object whose key is literally `"0"` is addressed as an array index.
+     */
+    jsonPathExpr(col, path, params, alias) {
+        let expr = this.colRefName(col.name, alias);
+        for (const seg of path) {
+            const bound = typeof seg === 'string' && /^\d+$/.test(seg) ? Number(seg) : seg;
+            expr += `->${this.param(bound, params)}`;
+        }
+        return expr;
+    }
+    /**
+     * Compile a {@link JsonFilter} on a json document column into a PowQL filter
+     * (≥ 0.12). Operators PowQL cannot express EXACTLY throw a per-operator E017
+     * (never a wrong result): containment (`contains`, and `equals` without a
+     * `path`) has no PowQL operator. The mapped shapes:
+     *   - `{ path, equals: v }`  → `P = $n` (typed: string→str, bool→bool,
+     *      integral number→int, fractional→float; NOT stringified)
+     *   - `{ path, equals: null }` → `P is null` (matches JSON null AND a missing
+     *      key, a deliberate divergence from the PG driver, documented on
+     *      {@link JsonFilter})
+     *   - `{ path, gt|gte|lt|lte: v }` → `P > $n` … (range ops require `path`; the
+     *      engine coerces int/float numerically)
+     *   - `{ hasKey: k }` → `json_type(.col->$n) is not null` (top-level key test,
+     *      ignoring `path`, mirroring PG `col ? key`; includes keys holding JSON
+     *      null)
+     * A bare `{ path }` with no operators compiles to zero clauses (byte-parity
+     * with SQL), so a mutation whose only `where` is a bare `{ path }` is refused
+     * by the empty-where guard.
+     */
+    buildJsonPathCondition(col, filter, params, alias) {
+        const conds = [];
+        // Bind the path segments at most once and reuse the expression string across
+        // equals + range comparisons (they share the same `path`).
+        let pathExpr = null;
+        const pathP = () => {
+            pathExpr ??= this.jsonPathExpr(col, filter.path, params, alias);
+            return pathExpr;
+        };
+        if (filter.contains !== undefined) {
+            throw new UnsupportedFeatureError('JSON containment filters (contains)', 'PowDB', `column "${col.name}": PowQL has no JSON containment operator`);
+        }
+        if (filter.equals !== undefined) {
+            if (filter.path === undefined || filter.path.length === 0) {
+                throw new UnsupportedFeatureError('JSON containment (equals without path)', 'PowDB', `column "${col.name}": pass a \`path\` to compare a specific json value; PowQL has no whole-document containment`);
+            }
+            conds.push(filter.equals === null ? `${pathP()} is null` : `${pathP()} = ${this.param(filter.equals, params)}`);
+        }
+        if (filter.hasKey !== undefined) {
+            // Top-level key existence, independent of `path` (mirrors PG `col ? key`).
+            conds.push(`json_type(${this.colRefName(col.name, alias)}->${this.param(filter.hasKey, params)}) is not null`);
+        }
+        // Range comparisons on the extracted path, in the fixed gt/gte/lt/lte order.
+        // Same validation as SQL `jsonRangeEntries`: `path` required, value a finite
+        // number or a string.
+        for (const [op, powOp] of [
+            ['gt', '>'],
+            ['gte', '>='],
+            ['lt', '<'],
+            ['lte', '<='],
+        ]) {
+            const v = filter[op];
+            if (v === undefined)
+                continue;
+            if (filter.path === undefined) {
+                throw new ValidationError(`[turbine] JSON range operator '${op}' on ${col.name} requires a \`path\` ` +
+                    `(e.g. { path: ['meta', 'score'], ${op}: ${JSON.stringify(v)} }).`);
+            }
+            if (typeof v !== 'number' && typeof v !== 'string') {
+                throw new ValidationError(`[turbine] JSON range operator '${op}' on ${col.name} requires a number or string, got ${JSON.stringify(v)}.`);
+            }
+            if (typeof v === 'number' && !Number.isFinite(v)) {
+                throw new ValidationError(`[turbine] JSON range operator '${op}' on ${col.name} requires a finite number.`);
+            }
+            conds.push(`${pathP()} ${powOp} ${this.param(v, params)}`);
+        }
+        if (!conds.length)
+            return '';
+        return conds.length > 1 ? `(${conds.join(' and ')})` : conds[0];
+    }
     /** Bind a value, lowercasing for case-insensitive comparisons. */
     bind(value, params, insensitive) {
         const ph = this.param(value, params);
@@ -419,7 +593,7 @@ export class PowqlInterface {
                 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(`${quotePowqlIdent(through.table)} filter .${targetJCol} in (${ph}) { .${sourceJCol} }`, params, timeout);
+                const { rows } = await this.exec(`${quotePowqlIdent(through.table)} filter .${targetJCol} in (${ph}) { .${sourceJCol} }`, params, timeout, 'findMany');
                 for (const r of rows) {
                     const v = r[sourceJCol];
                     if (v != null)
@@ -467,8 +641,20 @@ export class PowqlInterface {
     projection(cols) {
         return `{ ${cols.map((c) => `.${c}`).join(', ')} }`;
     }
-    /** `order .c1 asc, .c2 desc` clause (empty string when no orderBy). */
-    buildOrder(orderBy) {
+    /**
+     * `order .c1 asc, .c2 desc` clause (empty string when no orderBy). Supports,
+     * besides a plain direction:
+     *   - {@link JsonPathOrderBy} on a json column (≥ 0.12): `{ data: { path: […],
+     *     type?, direction? } }` → `order .data->$n asc` (or
+     *     `cast(.data->$n, "float")` for `type: 'numeric'`);
+     *   - {@link OrderBySpec} `{ sort, nulls }`: `nulls: 'last'` is accepted as a
+     *     no-op (PowDB is always nulls-last), `nulls: 'first'` throws E017.
+     *
+     * PowDB orders missing / JSON-null keys LAST in BOTH directions (an engine
+     * contract): for identical cross-engine results pass `nulls: 'last'`
+     * explicitly on Postgres, which defaults nulls-first for `desc`.
+     */
+    buildOrder(orderBy, params, alias) {
         if (!orderBy)
             return '';
         const keys = Object.entries(orderBy).filter(([, dir]) => dir !== undefined);
@@ -476,32 +662,97 @@ export class PowqlInterface {
             return '';
         const parts = keys.map(([field, dir]) => {
             if (dir && typeof dir === 'object') {
+                const o = dir;
+                // JSON-path ordering on a json column.
+                if (Array.isArray(o.path)) {
+                    return this.buildJsonPathOrder(field, dir, params, alias);
+                }
+                // OrderBySpec { sort, nulls }: accept nulls-last (PowDB default), refuse
+                // nulls-first (no placement grammar). Distinct from vector/pick/_count.
+                if ('sort' in o && !('distance' in o) && !('_count' in o) && !isRelationPickOrderBy(dir)) {
+                    const spec = dir;
+                    if (spec.nulls === 'first') {
+                        throw new UnsupportedFeatureError('NULLS FIRST placement', 'PowDB', `field "${field}": PowDB orders NULLs / missing keys LAST in both directions`);
+                    }
+                    return `${this.ref(field, alias)} ${spec.sort === 'desc' ? 'desc' : 'asc'}`;
+                }
                 // Name the actual feature in the refusal — a pick-row ordering
                 // reported as "vector / distance ordering" sends users hunting for
-                // pgvector docs. All object-valued orderings stay E017 on PowDB.
-                const o = dir;
+                // pgvector docs. Everything else stays E017 on PowDB.
                 const feature = isRelationPickOrderBy(dir)
                     ? 'relation pick-row ordering'
                     : 'distance' in o
                         ? 'vector / distance ordering'
-                        : Array.isArray(o.path)
-                            ? 'JSON-path ordering'
-                            : '_count' in o
-                                ? 'relation _count ordering'
-                                : 'sort' in o || 'nulls' in o
-                                    ? 'NULLS placement / sort-spec ordering'
-                                    : 'object-valued ordering';
+                        : '_count' in o
+                            ? 'relation _count ordering'
+                            : 'nulls' in o
+                                ? 'NULLS placement / sort-spec ordering'
+                                : 'object-valued ordering';
                 throw new UnsupportedFeatureError(feature, 'PowDB', `field "${field}"`);
             }
-            return `${this.ref(field)} ${dir === 'desc' ? 'desc' : 'asc'}`;
+            return `${this.ref(field, alias)} ${dir === 'desc' ? 'desc' : 'asc'}`;
         });
         return ` order ${parts.join(', ')}`;
     }
+    /** Compile one {@link JsonPathOrderBy} entry to `order .col->$n asc` (+ optional numeric cast). */
+    buildJsonPathOrder(field, spec, params, alias) {
+        const col = this.column(field);
+        if (!isJsonColumn(col)) {
+            throw new UnsupportedFeatureError('JSON-path ordering', 'PowDB', `field "${field}" is not a json column`);
+        }
+        requireCapability(this.capabilities, 'jsonDocs', 'JSON path ordering');
+        if (spec.nulls === 'first') {
+            throw new UnsupportedFeatureError('NULLS FIRST placement', 'PowDB', `field "${field}": PowDB orders missing / JSON-null keys LAST in both directions`);
+        }
+        const pathExpr = this.jsonPathExpr(col, spec.path, params, alias);
+        // `type: 'numeric'` casts a JSON STRING number for numeric ordering; native
+        // JSON numbers already order numerically without a cast.
+        const expr = spec.type === 'numeric' ? `cast(${pathExpr}, "float")` : pathExpr;
+        return `${expr} ${spec.direction === 'desc' ? 'desc' : 'asc'}`;
+    }
     // -------------------------------------------------------------------------
     // Execution plumbing
     // -------------------------------------------------------------------------
-    /** Run PowQL with optional timeout, emitting a query event either way. */
-    async exec(powql, params, timeout) {
+    /**
+     * Run PowQL with optional timeout, emitting a query event either way. The
+     * `action` is passed PER CALL (never read from shared instance state) so the
+     * retry-eligibility and the emitted event action stay correct even when a
+     * concurrent operation runs on the same cached interface: a WRITE statement
+     * carries a write action and can therefore never be mistaken for a replayable
+     * read. Read statements pass a read-shaped action from {@link POWQL_READ_ACTIONS}.
+     */
+    async exec(powql, params, timeout, action = 'raw') {
+        return this.execOnce(powql, params, timeout, action, false);
+    }
+    /** Build the E018 refusal for a write / `begin` on a read-only pool. */
+    readOnlyError(operation) {
+        // Pass a clean detail: the ReadOnlyError constructor owns both the
+        // `[turbine] ` prefix and the "Route writes to a writable primary." hint,
+        // so adding either here would double them.
+        return new ReadOnlyError(`${operation} on "${this.table}" refused: this PowDB connection is read-only.`);
+    }
+    /**
+     * Execute one statement, with the opt-in single stale-frame READ replay. When
+     * `retryStaleReads` is on and a first-statement READ fails with the stale-wire
+     * {@link isStaleFramePowdbError} ConnectionError (a socket idle-gap "received
+     * unexpected frame" that the client cannot recover), the statement is retried
+     * exactly once on a fresh pooled connection (the broken one was destroyed).
+     * The replay is refused for writes (an ambiguous mutation reply is unsafe to
+     * replay) and inside a transaction (a mid-tx statement cannot move connection),
+     * so only the read-shaped actions in {@link POWQL_READ_ACTIONS}, outside a
+     * `_txScoped` interface, are eligible. `action` is a per-call argument (never
+     * `this`-state), so a concurrent op flipping instance fields cannot turn a
+     * write into a retryable read.
+     */
+    async execOnce(powql, params, timeout, action, isRetry) {
+        // Read-only pool guard: refuse a write action locally, before the wire, so a
+        // read-only target never even attempts the mutation (the engine refusal, if
+        // any, is only the backstop for raw/injected paths). `action` is per-call,
+        // so a concurrent read is never mistaken for a write. Reads (incl. explain)
+        // and non-classified `raw` fall through unchanged.
+        if (this.pool.readonly === true && POWQL_WRITE_ACTIONS.has(action)) {
+            throw this.readOnlyError(action);
+        }
         const start = performance.now();
         const run = this.pool.query(powql, params);
         try {
@@ -511,15 +762,37 @@ export class PowqlInterface {
                     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;
+            this.emit(action, powql, params, performance.now() - start, result.rowCount ?? result.rows.length);
+            // The pool tags each result with the wire that actually served it
+            // (adaptResult → false, adaptNativeResult → true). A heterogeneous
+            // injected pool can fall back to the legacy wire per call, so read the
+            // per-result flag and only fall back to the pool-level capability when a
+            // hand-built pool (tests) omits the tag; never coerce legacy rows with
+            // the native policy just because the pool reports nativeRaw.
+            const native = result.native ?? Boolean(this.capabilities.nativeRaw);
+            return { rows: result.rows, rowCount: result.rowCount ?? result.rows.length, native };
         }
         catch (err) {
-            this.emit(powql, params, performance.now() - start, 0, err);
+            if (!isRetry && this.shouldRetryStaleRead(err, action)) {
+                // Transparent single replay on a fresh connection; the first (swallowed)
+                // failure is not emitted, only the retried outcome is observed.
+                return this.execOnce(powql, params, timeout, action, true);
+            }
+            this.emit(action, powql, params, performance.now() - start, 0, err);
             throw err;
         }
     }
-    emit(sql, params, duration, rows, error) {
+    /** Is `err` a replayable stale-frame failure for THIS (per-call) read-shaped, non-tx action? */
+    shouldRetryStaleRead(err, action) {
+        if (!this.pool.retryStaleReads)
+            return false;
+        if (this.isTxScoped())
+            return false;
+        if (!POWQL_READ_ACTIONS.has(action))
+            return false;
+        return isStaleFramePowdbError(err);
+    }
+    emit(action, sql, params, duration, rows, error) {
         if (!this.onQuery)
             return;
         try {
@@ -528,7 +801,7 @@ export class PowqlInterface {
                 params,
                 duration,
                 model: this.table,
-                action: this.currentAction,
+                action,
                 rows,
                 timestamp: new Date(),
                 error,
@@ -540,7 +813,6 @@ export class PowqlInterface {
     }
     /** 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;
@@ -551,34 +823,48 @@ export class PowqlInterface {
         };
         return next({ model: this.table, action, args: { ...args } });
     }
-    /** Map raw rows to typed entities. */
-    shape(rows) {
-        return rows.map((r) => rowToEntity(r, this.meta));
+    /** Map raw rows to typed entities. `native` is the wire that ACTUALLY served
+     * this result (threaded from {@link execOnce}, not the pool-level capability),
+     * so cells that arrived pre-typed over `queryNativeRaw` (F3) skip the legacy
+     * string coercion (a genuine str `"null"` stays `"null"` instead of collapsing
+     * to null) while a per-call legacy fallback on a native-capable pool still
+     * coerces its string cells correctly. Defaults to the pool capability for the
+     * rare caller with no per-result flag (hand-built test pools). */
+    shape(rows, native = Boolean(this.capabilities.nativeRaw)) {
+        return rows.map((r) => rowToEntity(r, this.meta, native));
     }
     // -------------------------------------------------------------------------
     // 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);
+            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,
+                });
+            }
             return entities;
         });
     }
-    /** Build + run the flat findMany select; returns raw rows. */
-    async runFind(args) {
+    /**
+     * Compile the flat findMany select into PowQL (no execution), pushing values
+     * into `params`. Returns the query plus the RESOLVED where (relation filters
+     * already collapsed to literal in-lists) so the F2 join path can re-emit the
+     * exact parent predicate alias-qualified, and so {@link explain} can wrap it.
+     */
+    async buildFind(args, params) {
         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 order = this.buildOrder(args.orderBy, params);
         const limit = args.limit ?? args.take ?? this.defaultLimit;
         if (limit === undefined && this.warnOnUnlimited && !this.warnedUnlimited) {
             this.warnedUnlimited = true;
@@ -587,15 +873,45 @@ export class PowqlInterface {
         const limitClause = limit !== undefined ? ` limit ${this.param(limit, params)}` : '';
         const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';
         const powql = `${this.qt}${distinct}${filter}${order}${limitClause}${offsetClause} ${this.projection(cols)}`;
-        const { rows } = await this.exec(powql, params, args.timeout);
-        return rows;
+        return { powql, resolvedWhere };
+    }
+    /** Build + run the flat findMany select; returns raw rows, the serving wire, and the resolved where. */
+    async runFind(args, action = 'findMany') {
+        const params = [];
+        const { powql, resolvedWhere } = await this.buildFind(args, params);
+        const { rows, native } = await this.exec(powql, params, args.timeout, action);
+        return { rows, native, resolvedWhere };
+    }
+    /**
+     * Diagnostic surface: compile the same PowQL {@link findMany} would run for
+     * `args` (no cache) and return the engine's plan as one string per line.
+     *
+     * Runs as a READ (`explain <query>`), so it is safe on a read-only pool and
+     * eligible for the stale-read replay. The line content is engine-owned and is
+     * NOT covered by semver (match plan node names / tree shape, never exact
+     * bytes; mirrors PowDB's own `explain` contract).
+     *
+     * Does NOT run through the middleware chain: plan text is a diagnostic, not
+     * entity rows, and `QueryInterface.explain` deliberately bypasses middleware
+     * too, so both engines agree.
+     */
+    async explain(args = {}) {
+        const params = [];
+        const { powql } = await this.buildFind(args, params);
+        const { rows } = await this.exec(`explain ${powql}`, params, args.timeout, 'explain');
+        return rows
+            .map((r) => {
+            const line = r.plan ?? Object.values(r)[0];
+            return line == null ? '' : String(line);
+        })
+            .filter((line) => line.length > 0);
     }
     async findUnique(args) {
         return this.withMiddleware('findUnique', args, async () => {
-            const rows = await this.runFind({ ...args, limit: 1 });
+            const { rows, native } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
             if (!rows.length)
                 return null;
-            const entities = this.shape(rows);
+            const entities = this.shape(rows, native);
             if (args.with)
                 await this.loadRelations(entities, args.with, args.timeout);
             return entities[0];
@@ -603,10 +919,10 @@ export class PowqlInterface {
     }
     async findFirst(args = {}) {
         return this.withMiddleware('findFirst', args, async () => {
-            const rows = await this.runFind({ ...args, limit: 1 });
+            const { rows, native } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
             if (!rows.length)
                 return null;
-            const entities = this.shape(rows);
+            const entities = this.shape(rows, native);
             if (args.with)
                 await this.loadRelations(entities, args.with, args.timeout);
             return entities[0];
@@ -627,19 +943,48 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     // 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) {
+    /**
+     * Load each requested relation for `parents` and attach it onto each row.
+     *
+     * `parent` is supplied ONLY by the top-level {@link findMany} (its args +
+     * resolved where). When the effective `relationLoadStrategy` resolves to an
+     * explicit `'join'` and the pool advertises `serverJoins`, an eligible
+     * top-level relation is loaded with a native PowQL join instead of the keyed
+     * loaders (F2); everything else (nested `with` levels, ineligible shapes, and
+     * 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) {
         if (depth >= 10) {
             throw new ValidationError(`[turbine] Nested 'with' on PowDB exceeded depth 10 (relation cycle?).`);
         }
         if (!parents.length)
             return;
+        // The resolved strategy is 'join' only for an EXPLICIT 'join' (per-query arg
+        // or a client config the user set). The serverJoins capability is consulted
+        // PER RELATION below, AFTER joinEligible, so a relation that would have
+        // fallen back to the loaders anyway (paged parent, nested `with`, composite
+        // key, …) never triggers the capability's E017.
+        const strategyIsJoin = parent ? this.resolveStrategy(parent.args) === 'join' : false;
         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 (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args, parents.length)) {
+                if (this.capabilities.serverJoins) {
+                    await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout);
+                    continue;
+                }
+                // An otherwise-eligible relation the engine cannot join: a PER-QUERY
+                // `relationLoadStrategy: 'join'` is an explicit request, so throw a typed
+                // E017; a CLIENT-LEVEL default silently falls back to the keyed loaders
+                // (so pointing an existing app at an older engine keeps working).
+                if (parent.args.relationLoadStrategy === 'join') {
+                    requireCapability(this.capabilities, 'serverJoins', 'native PowQL relation joins');
+                }
+            }
             if (rel.type === 'manyToMany') {
                 await this.loadManyToMany(parents, rel, relName, opt, timeout);
                 continue;
@@ -660,23 +1005,49 @@ export class PowqlInterface {
             const keys = [
                 ...new Set(parents.map((p) => p[parentKeyField]).filter((k) => k != null)),
             ];
-            const childByKey = new Map();
+            // The loader buckets children by their correlation column, so that column
+            // MUST be in the fetched projection even when the user's select/omit drops
+            // it. Force it into the fetch here and strip it back off the entities after
+            // stitching (the join path already gets this for free via `__tpk`).
+            const userSelect = options.select;
+            const userOmit = options.omit;
+            const fkProjected = userSelect ? Boolean(userSelect[childKeyField]) : userOmit ? !userOmit[childKeyField] : true;
+            let fetchOptions = options;
+            if (!fkProjected) {
+                if (userSelect) {
+                    fetchOptions = {
+                        ...options,
+                        select: { ...userSelect, [childKeyField]: true },
+                    };
+                }
+                else if (userOmit) {
+                    const omitWithoutFk = { ...userOmit };
+                    delete omitWithoutFk[childKeyField];
+                    fetchOptions = { ...options, omit: omitWithoutFk };
+                }
+            }
             // Chunk the key set so a single `in (…)` never exceeds PowDB's
-            // per-statement param / row limits; merge each chunk's children.
+            // per-statement param / row limits; merge each chunk's children. Keys are
+            // normalized through joinKey (a Date maps to micros, matching the child
+            // cell) so a datetime correlation column stitches instead of silently
+            // returning [].
+            const childByKey = new Map();
             for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS) {
                 const chunk = keys.slice(i, i + MAX_RELATION_KEYS);
                 const childWhere = {
-                    ...options.where,
+                    ...fetchOptions.where,
                     [childKeyField]: { in: chunk },
                 };
                 const children = (await targetQi.findMany({
-                    ...options,
+                    ...fetchOptions,
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
                 }));
                 for (const child of children) {
-                    const k = child[childKeyField];
+                    const k = this.joinKey(child[childKeyField]);
+                    if (k == null)
+                        continue;
                     const bucket = childByKey.get(k);
                     if (bucket)
                         bucket.push(child);
@@ -684,10 +1055,18 @@ export class PowqlInterface {
                         childByKey.set(k, [child]);
                 }
             }
+            // Strip the forced correlation column back off if the user excluded it,
+            // so the emitted entities match their select/omit exactly.
+            if (!fkProjected) {
+                for (const bucket of childByKey.values()) {
+                    for (const child of bucket)
+                        delete child[childKeyField];
+                }
+            }
             const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
             for (const parent of parents) {
-                const k = parent[parentKeyField];
-                const matches = childByKey.get(k) ?? [];
+                const k = this.joinKey(parent[parentKeyField]);
+                const matches = (k == null ? undefined : childByKey.get(k)) ?? [];
                 parent[relName] = single ? (matches[0] ?? null) : matches;
             }
         }
@@ -736,7 +1115,7 @@ export class PowqlInterface {
             const params = [];
             const placeholders = chunk.map((v) => this.param(v, params)).join(', ');
             const powql = `${quotePowqlIdent(through.table)} filter .${sourceJCol} in (${placeholders}) { .${sourceJCol}, .${targetJCol} }`;
-            const { rows } = await this.exec(powql, params, timeout);
+            const { rows } = await this.exec(powql, params, timeout, 'findMany');
             for (const row of rows) {
                 const sv = String(row[sourceJCol]);
                 const tv = String(row[targetJCol]);
@@ -782,6 +1161,257 @@ export class PowqlInterface {
         }
     }
     // -------------------------------------------------------------------------
+    // Nested relations: native PowQL joins (F2, opt-in via relationLoadStrategy)
+    // -------------------------------------------------------------------------
+    /**
+     * Resolve the effective relation-load strategy: the per-query arg wins, then
+     * the client config, then the PowDB default of `'batched'` (the keyed
+     * loaders). PowDB deliberately does NOT inherit the SQL-side implicit `'join'`
+     * default (that would silently flip every existing PowDB user onto brand-new
+     * join generation). Only a value the user actually set to `'join'` activates it.
+     */
+    resolveStrategy(args) {
+        const s = args.relationLoadStrategy ?? this.options.relationLoadStrategy ?? 'batched';
+        return s === 'join' ? 'join' : 'batched';
+    }
+    /**
+     * Per-relation eligibility for the join path (checked before the serverJoins
+     * capability). Any `false` here is a SILENT fallback to the keyed loaders (it
+     * is never an error), so an off-page or nested-`with` shape still returns
+     * correct rows:
+     *   - the parent query must not be paged (`limit`/`offset`/`take`, including the
+     *     configured `defaultLimit`): a parent-filter join under a page would scan
+     *     children of off-page parents, where the loaders are strictly better;
+     *   - the relation must not request a nested `with` (its subtree stays on the
+     *     loaders this round) or a `distinct`;
+     *   - single-column relation keys only (a composite key falls to the loader,
+     *     which throws the same E017 as today);
+     *   - the PARENT-SIDE correlation column must be a single-column PK or unique
+     *     column, or the INNER join would re-emit one child copy per matching
+     *     parent row (a non-unique correlation key produces duplicate children the
+     *     loader never would). For hasMany/hasOne/m2m that column is the relation's
+     *     `referenceKey` on THIS (fetched) table; for belongsTo it is the
+     *     `referenceKey` on the TARGET table (the join's non-fetched side);
+     *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
+     *     stitch can't be reproduced by the 3-table join deterministically);
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
+     *     does a to-many relation `limit`/`offset` when the parent set spills past
+     *     one loader chunk (the loader limits per chunk, the join once globally).
+     */
+    joinEligible(rel, opt, args, parentCount) {
+        const effLimit = args.limit ?? args.take ?? this.defaultLimit;
+        if (effLimit !== undefined || args.offset)
+            return false;
+        const options = (opt === true ? {} : opt);
+        if (options.with)
+            return false;
+        if (options.distinct?.length)
+            return false;
+        if (rel.type === 'manyToMany') {
+            const through = rel.through;
+            if (!through)
+                return false;
+            if (normalizeKeyColumns(through.sourceKey).length > 1 ||
+                normalizeKeyColumns(through.targetKey).length > 1 ||
+                normalizeKeyColumns(rel.referenceKey).length > 1 ||
+                (this.schema.tables[rel.to]?.primaryKey.length ?? 2) > 1) {
+                return false;
+            }
+            if (options.orderBy || options.limit !== undefined || options.offset)
+                return false;
+            // The parent joins on its referenceKey; a non-unique one duplicates.
+            if (!this.isSingleColumnUnique(this.meta, normalizeKeyColumns(rel.referenceKey)[0]))
+                return false;
+            return true;
+        }
+        if (normalizeKeyColumns(rel.foreignKey).length > 1 || normalizeKeyColumns(rel.referenceKey).length > 1) {
+            return false;
+        }
+        // Reject a non-unique correlation key: on belongsTo the fetched side joins on
+        // the target's referenceKey, otherwise the fetched side joins on its own.
+        if (rel.type === 'belongsTo') {
+            const targetMeta = this.schema.tables[rel.to];
+            if (!targetMeta || !this.isSingleColumnUnique(targetMeta, normalizeKeyColumns(rel.referenceKey)[0])) {
+                return false;
+            }
+        }
+        else if (!this.isSingleColumnUnique(this.meta, normalizeKeyColumns(rel.referenceKey)[0])) {
+            return false;
+        }
+        const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+        if ((options.limit !== undefined || options.offset) && (single || parentCount > MAX_RELATION_KEYS)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * True when `col` is a single-column unique key of `tableMeta`: the sole
+     * primary-key column, a single-column entry in `uniqueColumns` (where a
+     * per-column `unique: true` and an introspected single-column unique constraint
+     * both land), or a single-column unique index. Used by {@link joinEligible} to
+     * keep the INNER-join path off relations whose parent-side correlation column
+     * can repeat (which would duplicate children).
+     */
+    isSingleColumnUnique(tableMeta, col) {
+        if (tableMeta.primaryKey.length === 1 && tableMeta.primaryKey[0] === col)
+            return true;
+        if (tableMeta.uniqueColumns.some((cols) => cols.length === 1 && cols[0] === col))
+            return true;
+        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) {
+        if (rel.type === 'manyToMany') {
+            await this.loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout);
+            return;
+        }
+        const options = (opt === true ? {} : opt);
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new ValidationError(`[turbine] Relation "${relName}" targets unknown table "${rel.to}".`);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const fk = normalizeKeyColumns(rel.foreignKey);
+        const rk = normalizeKeyColumns(rel.referenceKey);
+        // Correlation math is identical to the keyed loaders, only the transport
+        // (join vs in-list) changes. Always join the RELATION TARGET (alias `c`) to
+        // the already-fetched side (alias `p`), correlating on the fetched side's key
+        // and projecting `__tpk` from the fetched side's correlation column.
+        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 params = [];
+        const childCols = this.joinChildCols(targetQi, options);
+        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)}` : '';
+        const offsetClause = options.offset ? ` offset ${this.param(options.offset, params)}` : '';
+        const proj = this.joinProjection(childCols, `p.${quotePowqlIdent(parentKeyCol)}`, 'c');
+        const powql = `${targetQi.qt} as c join ${this.qt} as p ` +
+            `on c.${quotePowqlIdent(childKeyCol)} = p.${quotePowqlIdent(parentKeyCol)}` +
+            `${filter}${order}${limitClause}${offsetClause} ${proj}`;
+        // A READ: thread a read-shaped action through the exec seam.
+        const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
+        const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+        const byKey = this.bucketByTpk(targetQi, rows, native);
+        for (const p of parents) {
+            const key = this.joinKey(p[parentKeyField]);
+            const matches = (key == null ? undefined : byKey.get(key)) ?? [];
+            p[relName] = single ? (matches[0] ?? null) : matches;
+        }
+    }
+    /**
+     * manyToMany via chained joins: the target (alias `t`) → junction (alias `j`)
+     * → 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) {
+        const through = rel.through;
+        if (!through)
+            throw new ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
+        const options = (opt === true ? {} : opt);
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new ValidationError(`[turbine] Relation "${relName}" targets unknown table "${rel.to}".`);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const sourceJCol = normalizeKeyColumns(through.sourceKey)[0];
+        const targetJCol = normalizeKeyColumns(through.targetKey)[0];
+        const sourceRefCol = normalizeKeyColumns(rel.referenceKey)[0];
+        const targetPkCol = targetMeta.primaryKey[0];
+        const parentRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
+        const params = [];
+        const childCols = this.joinChildCols(targetQi, options);
+        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 ` +
+            `join ${quotePowqlIdent(through.table)} as j on t.${quotePowqlIdent(targetPkCol)} = j.${quotePowqlIdent(targetJCol)} ` +
+            `join ${this.qt} as p on j.${quotePowqlIdent(sourceJCol)} = p.${quotePowqlIdent(sourceRefCol)}` +
+            `${filter} ${proj}`;
+        const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
+        const byKey = this.bucketByTpk(targetQi, rows, native);
+        for (const p of parents) {
+            const key = this.joinKey(p[parentRefField]);
+            p[relName] = (key == null ? undefined : byKey.get(key)) ?? [];
+        }
+    }
+    /**
+     * The target column list to project through the join (honouring select/omit),
+     * 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);
+        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'.`);
+        }
+        return cols;
+    }
+    /**
+     * `{ __tpk: <tpkExpr>, <col>: <childAlias>.<col>, … }`. Each child column is
+     * ALIASED to its bare name (a bare qualified ref `c.col` would come back named
+     * `c.col`, not `col`) so the stitched rows shape identically to a flat select.
+     */
+    joinProjection(childCols, tpkExpr, childAlias) {
+        const parts = [
+            `__tpk: ${tpkExpr}`,
+            ...childCols.map((c) => `${quotePowqlIdent(c)}: ${childAlias}.${quotePowqlIdent(c)}`),
+        ];
+        return `{ ${parts.join(', ')} }`;
+    }
+    /**
+     * `filter <parentWhere qualified p> [and <relationWhere qualified childAlias>]`.
+     * The parent where is the ALREADY-RESOLVED predicate (relation filters collapsed
+     * to literal in-lists before the base query ran); the relation where is resolved
+     * on the target the same way before qualifying, so a nested relation filter in
+     * the relation `where` never reaches the join unresolved. Params bind in order.
+     */
+    async joinFilter(targetQi, parentResolvedWhere, relWhere, childAlias, params, timeout) {
+        const parts = [];
+        const pw = this.buildWhere(parentResolvedWhere, params, 'p');
+        if (pw)
+            parts.push(pw);
+        const relResolved = await targetQi.resolveRelationFilters(relWhere, timeout);
+        const rw = targetQi.buildWhere(relResolved, params, childAlias);
+        if (rw)
+            parts.push(rw);
+        return parts.length ? ` filter ${parts.join(' and ')}` : '';
+    }
+    /** Group join rows by their (normalized) `__tpk`, stripping it and shaping each child. */
+    bucketByTpk(targetQi, rows, native) {
+        const byKey = new Map();
+        for (const raw of rows) {
+            const tpk = this.joinKey(raw.__tpk);
+            delete raw.__tpk;
+            const child = targetQi.shape([raw], native)[0];
+            if (tpk == null)
+                continue;
+            const bucket = byKey.get(tpk);
+            if (bucket)
+                bucket.push(child);
+            else
+                byKey.set(tpk, [child]);
+        }
+        return byKey;
+    }
+    /**
+     * Normalize a correlation key to a stable string map key so a parent's key
+     * value (a shaped entity field) and a child row's `__tpk` cell match across
+     * wires and column types. A `Date` maps to microseconds
+     * (`getTime()` ms times 1000), because a datetime correlation cell arrives as
+     * raw micros (bigint on the native wire, a micros string on the legacy wire),
+     * never as ms. bigint / number / string all stringify to the same digits, so
+     * an int key matches whether it came back typed or as text.
+     */
+    joinKey(v) {
+        if (v == null)
+            return null;
+        if (v instanceof Date)
+            return (BigInt(v.getTime()) * 1000n).toString();
+        if (typeof v === 'bigint')
+            return v.toString();
+        return String(v);
+    }
+    // -------------------------------------------------------------------------
     // Writes (reselect — PowDB has no RETURNING)
     // -------------------------------------------------------------------------
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
@@ -837,8 +1467,8 @@ export class PowqlInterface {
                 .map((a) => `${quotePowqlIdent(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.qt} { ${body} } returning`, params, args.timeout);
-            const row = rows.length ? this.shape(rows)[0] : null;
+            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;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: data });
             return row;
@@ -855,8 +1485,8 @@ export class PowqlInterface {
                 return `{ ${assigns.map((a) => `${quotePowqlIdent(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.qt} ${tuples.join(', ')} returning`, params, args.timeout);
-            return this.shape(rows);
+            const { rows, native } = await this.exec(`insert ${this.qt} ${tuples.join(', ')} returning`, params, args.timeout, 'createMany');
+            return this.shape(rows, native);
         });
     }
     async update(args) {
@@ -870,8 +1500,8 @@ export class PowqlInterface {
             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.qt} filter ${where} update { ${setClause} } returning`, params, args.timeout);
-            const row = rows.length ? this.shape(rows)[0] : null;
+            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;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
             return row;
@@ -885,7 +1515,7 @@ export class PowqlInterface {
             this.assertCompiledWhere(where, args.allowFullTableScan, 'updateMany');
             const setClause = this.buildUpdateAssignments(args.data, params);
             const filter = where ? ` filter ${where}` : '';
-            const { rowCount } = await this.exec(`${this.qt}${filter} update { ${setClause} }`, params, args.timeout);
+            const { rowCount } = await this.exec(`${this.qt}${filter} update { ${setClause} }`, params, args.timeout, 'updateMany');
             return { count: rowCount };
         });
     }
@@ -954,6 +1584,11 @@ export class PowqlInterface {
     }
     /** Open a flat PowDB transaction on a pinned connection and run `fn` inside it. */
     async runInImplicitTx(fn) {
+        // A transaction-control `begin` is a write on a read-only pool: refuse it
+        // locally before checking out a connection (zero wire / pool activity), the
+        // same guard the exec seam applies to plain writes.
+        if (this.pool.readonly === true)
+            throw this.readOnlyError('transaction (begin)');
         // 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;
@@ -963,7 +1598,10 @@ export class PowqlInterface {
             await client.query(d?.beginStatement?.() ?? 'begin');
             began = true;
             const { TransactionClient } = await import('./client.js');
-            const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.options, 
+            // Pass the PowDB pool so its read-only guard + capabilities carry into
+            // the transaction-scoped proxy pool (see createTxPool).
+            this.pool);
             const ctx = { schema: this.schema, tx: tx };
             // Plant the single-writer re-entrancy marker for the implicit tx's
             // subtree (same seam TurbineClient.$transaction uses) — user code that
@@ -1008,8 +1646,8 @@ export class PowqlInterface {
             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.qt} filter ${where} delete returning`, params, args.timeout);
-            const row = rows.length ? this.shape(rows)[0] : null;
+            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;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
             return row;
@@ -1022,7 +1660,7 @@ export class PowqlInterface {
             const where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, args.allowFullTableScan, 'deleteMany');
             const filter = where ? ` filter ${where}` : '';
-            const { rowCount } = await this.exec(`${this.qt}${filter} delete`, params, args.timeout);
+            const { rowCount } = await this.exec(`${this.qt}${filter} delete`, params, args.timeout, 'deleteMany');
             return { count: rowCount };
         });
     }
@@ -1044,7 +1682,7 @@ export class PowqlInterface {
             // (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.qt} on .${pkCol} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout);
+            await this.exec(`upsert ${this.qt} on .${pkCol} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout, 'upsert');
             const pkField = this.meta.reverseColumnMap[pkCol] ?? pkCol;
             const row = await this.reselectByPk(createData[pkField], args.timeout);
             if (!row)
@@ -1089,7 +1727,7 @@ export class PowqlInterface {
             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.qt}${filter})`, params, args.timeout);
+            const { rows } = await this.exec(`count(${this.qt}${filter})`, params, args.timeout, 'count');
             return Number((rows[0]?.value ?? rows[0]?.count ?? 0));
         });
     }
@@ -1103,7 +1741,7 @@ export class PowqlInterface {
             const filter = where ? ` filter ${where}` : '';
             const scalar = async (expr) => {
                 const params = [...filterParams];
-                const { rows } = await this.exec(expr, params, args.timeout);
+                const { rows } = await this.exec(expr, params, args.timeout, 'aggregate');
                 const v = rows[0]?.value;
                 return v == null || v === 'null' ? null : Number(v);
             };
@@ -1135,90 +1773,196 @@ export class PowqlInterface {
     }
     async groupBy(args) {
         return this.withMiddleware('groupBy', args, async () => {
-            // The SQL-only groupBy extensions (DISTINCT ON row source, JSON-path
-            // group keys / aggregate targets) have no PowQL equivalent: refuse
-            // clearly instead of emitting broken PowQL.
+            // DISTINCT ON has no PowQL equivalent (no DISTINCT ON row source).
             if (args.distinctOn) {
                 throw new UnsupportedFeatureError('groupBy distinctOn row source', 'PowDB');
             }
-            for (const entry of args.by) {
-                if (typeof entry !== 'string') {
-                    throw new UnsupportedFeatureError('JSON-path groupBy keys', 'PowDB');
-                }
-            }
-            for (const fn of ['_sum', '_avg', '_min', '_max']) {
-                const spec = args[fn];
-                if (!spec)
-                    continue;
-                for (const value of Object.values(spec)) {
-                    if (value !== undefined && typeof value !== 'boolean') {
-                        throw new UnsupportedFeatureError(`JSON-path ${fn} aggregate targets`, 'PowDB');
-                    }
-                }
+            // JSON-path group keys / aggregate targets (≥ 0.12) are gated once here.
+            const usesJson = args.by.some((e) => typeof e !== 'string') ||
+                ['_sum', '_avg', '_min', '_max'].some((fn) => {
+                    const spec = args[fn];
+                    return spec !== undefined && Object.values(spec).some((v) => v != null && typeof v === 'object');
+                });
+            if (usesJson) {
+                requireCapability(this.capabilities, 'jsonDocs', 'JSON-path groupBy keys / aggregate targets');
             }
+            // `emitNative` decides whether the query GENERATION needs the legacy-wire
+            // `json_type` discriminator (pool-level capability). The DECODE side reads
+            // the wire that ACTUALLY served the result (`resultNative`, from exec), so
+            // a per-call legacy fallback on a native-capable pool still decodes right.
+            const emitNative = Boolean(this.capabilities.nativeRaw);
             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' });
+            // Result-key namespace, mirroring the SQL builder's `claimResultKey`
+            // (query/builder.ts): a group-key / aggregate output-name collision (with
+            // `_count`, another key, or an aggregate output) throws E003.
+            const usedKeys = new Set();
+            const claim = (key, what) => {
+                if (key === '_count' || usedKeys.has(key)) {
+                    throw new ValidationError(`[turbine] groupBy output name "${key}" (${what}) collides with another output column on table ` +
+                        `"${this.table}": set an explicit \`alias\` (or rename the aggregate key) to disambiguate.`);
+                }
+                usedKeys.add(key);
+            };
+            const groupExprs = [];
+            const proj = [];
+            const byOrderExprs = new Map();
+            const byReaders = [];
+            let gkN = 0;
+            let gtN = 0;
+            for (const entry of args.by) {
+                if (typeof entry === 'string') {
+                    const col = this.column(entry);
+                    claim(entry, `column "${col.name}"`);
+                    if (col.name !== entry)
+                        claim(col.name, `column "${col.name}"`);
+                    groupExprs.push(`.${col.name}`);
+                    proj.push(`.${col.name}`);
+                    byOrderExprs.set(entry, `.${col.name}`);
+                    byReaders.push({ kind: 'plain', resultKey: entry, rowKey: col.name, col });
+                }
+                else {
+                    const col = this.column(entry.field);
+                    if (!isJsonColumn(col)) {
+                        throw new ValidationError(`[turbine] groupBy JSON group key on "${entry.field}" (table "${this.table}") requires a json column.`);
+                    }
+                    this.assertJsonPath('group key', entry.field, entry.path);
+                    const pathExpr = this.jsonPathExpr(col, entry.path, params);
+                    const alias = entry.alias ?? String(entry.path[entry.path.length - 1]);
+                    claim(alias, `JSON path on "${entry.field}"`);
+                    const gkAlias = `gk_${gkN++}`;
+                    groupExprs.push(pathExpr);
+                    proj.push(`${gkAlias}: ${pathExpr}`);
+                    byOrderExprs.set(alias, `.${gkAlias}`);
+                    let discrim;
+                    if (!emitNative) {
+                        // Legacy wire renders a missing value, JSON null, AND the string
+                        // "null" all as the cell "null". `min(json_type(path))` over the
+                        // group is "string" ONLY for the string-"null" group and "null"
+                        // otherwise (a bare `json_type` projection is not group-correlated).
+                        discrim = `gt_${gtN++}`;
+                        proj.push(`${discrim}: min(json_type(${pathExpr}))`);
+                    }
+                    byReaders.push({ kind: 'json', resultKey: alias, rowKey: gkAlias, discrim });
+                }
+            }
+            // Aggregates: `agg_N` internal aliases (PowQL rejects reserved-word
+            // aliases like `count:`). `aggInner` lets HAVING re-emit the exact inner
+            // expression by user key; `aggOrderExprs` lets orderBy reference the alias.
+            const aggReaders = [];
+            const aggOrderExprs = new Map();
+            const aggInner = new Map();
+            let aggN = 0;
+            // Parity with the SQL builder (query/builder.ts): `_count` is selected by
+            // DEFAULT unless the caller explicitly opts out with `_count: false`, so
+            // every groupBy row carries `_count` and `orderBy: { _count }` works
+            // without requesting it (the alias is seeded into `aggOrderExprs`).
+            const countSelected = args._count === true || args._count === undefined;
+            if (countSelected) {
+                const alias = `agg_${aggN++}`;
+                proj.push(`${alias}: count(*)`);
+                aggReaders.push({ alias, outKey: '_count', numeric: true });
+                aggOrderExprs.set('_count', `.${alias}`);
             }
             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);
-            // groupBy aggregate ordering (`_count` / `_sum` / … keys) has no PowQL
-            // equivalent here: `buildOrder` treats an `orderBy` key as a field ref, so
-            // a bare `_count: 'desc'` would silently emit an invalid `._count` sort.
-            // Refuse those keys explicitly; plain by-field ordering still flows through.
-            if (args.orderBy) {
-                for (const key of Object.keys(args.orderBy)) {
-                    if (key === '_count' || key === '_sum' || key === '_avg' || key === '_min' || key === '_max') {
-                        throw new UnsupportedFeatureError('groupBy ordering by an aggregate', 'PowDB', `orderBy key "${key}"`);
+                const powfn = fn.slice(1); // sum/avg/min/max
+                for (const [key, target] of Object.entries(spec)) {
+                    if (!target)
+                        continue;
+                    const alias = `agg_${aggN++}`;
+                    if (target === true) {
+                        const col = this.column(key);
+                        claim(`${fn}_${col.name}`, `${fn} of column "${col.name}"`);
+                        const inner = `.${col.name}`;
+                        proj.push(`${alias}: ${powfn}(${inner})`);
+                        aggReaders.push({ alias, outKey: `${fn}:${key}`, numeric: true });
+                        aggOrderExprs.set(`${fn}:${key}`, `.${alias}`);
+                        aggInner.set(key, inner);
+                    }
+                    else {
+                        const col = this.column(target.field);
+                        if (!isJsonColumn(col)) {
+                            throw new ValidationError(`[turbine] groupBy ${fn} target "${key}" on "${target.field}" (table "${this.table}") requires a json column.`);
+                        }
+                        this.assertJsonPath(`${fn} target "${key}"`, target.field, target.path);
+                        const alwaysNumeric = fn === '_sum' || fn === '_avg';
+                        if (alwaysNumeric && target.type === 'text') {
+                            throw new ValidationError(`[turbine] groupBy ${fn} target "${key}" on table "${this.table}": ` +
+                                `${fn} over a JSON path is always numeric: remove \`type: 'text'\`.`);
+                        }
+                        const numeric = alwaysNumeric || target.type === 'numeric';
+                        claim(`${fn}_${key}`, `${fn} JSON target "${key}"`);
+                        const pathExpr = this.jsonPathExpr(col, target.path, params);
+                        const inner = numeric ? `cast(${pathExpr}, "float")` : pathExpr;
+                        proj.push(`${alias}: ${powfn}(${inner})`);
+                        aggReaders.push({ alias, outKey: `${fn}:${key}`, numeric });
+                        aggOrderExprs.set(`${fn}:${key}`, `.${alias}`);
+                        aggInner.set(key, inner);
                     }
                 }
             }
-            const order = this.buildOrder(args.orderBy);
-            const powql = `${this.qt}${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}}.
+            const having = this.buildHaving(args.having, params, aggInner);
+            const order = this.buildGroupOrder(args.orderBy, byOrderExprs, aggOrderExprs);
+            const powql = `${this.qt}${filter} group ${groupExprs.join(', ')}${having}${order} { ${proj.join(', ')} }`;
+            const { rows, native: resultNative } = await this.exec(powql, params, args.timeout, 'groupBy');
+            // Reshape: group keys → user fields (coerced / null-disambiguated),
+            // aggregates → nested `{ _sum: { field } }`; discriminators are stripped.
+            // Group-key cells go through the SAME coercion policy `rowToEntity` uses,
+            // by the wire that actually served this result, so a native-wire int cell
+            // (bigint) or datetime cell (micros) never leaks into the result: it
+            // becomes the same number / Date / PG-text-parity string an embedded /
+            // legacy / SQL groupBy returns for the identical query.
             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 r of byReaders) {
+                    if (r.kind === 'plain') {
+                        const cell = raw[r.rowKey];
+                        out[r.resultKey] = resultNative
+                            ? coerceNativeValue(cell, r.col)
+                            : typeof cell === 'string'
+                                ? coerceScalar(cell, r.col.tsType)
+                                : cell;
+                    }
+                    else {
+                        out[r.resultKey] = decodeGroupKeyCell(raw[r.rowKey], r.discrim ? raw[r.discrim] : undefined, resultNative);
+                    }
                 }
-                for (const a of aliasMap) {
-                    const val = raw[a.alias];
-                    const num = val == null || val === 'null' ? null : Number(val);
+                for (const a of aggReaders) {
+                    const cell = raw[a.alias];
+                    const v = cell == null || cell === 'null' ? null : a.numeric ? Number(cell) : cell;
                     if (a.outKey === '_count')
-                        out._count = num ?? 0;
+                        out._count = v ?? 0;
                     else {
                         const [bucket, field] = a.outKey.split(':');
                         out[bucket] ??= {};
-                        out[bucket][field] = num;
+                        out[bucket][field] = v;
                     }
                 }
                 return out;
             });
         });
     }
-    /** `having <expr>` over group aggregates (count/sum/avg/min/max). */
-    buildHaving(having, params) {
+    /** Validate a JSON-path target (group key / aggregate target): non-empty array of keys/indexes. */
+    assertJsonPath(context, field, path) {
+        if (!Array.isArray(path) ||
+            path.length === 0 ||
+            path.some((el) => typeof el !== 'string' && !(typeof el === 'number' && Number.isFinite(el)))) {
+            throw new ValidationError(`[turbine] groupBy ${context} on "${field}" (table "${this.table}") requires a non-empty \`path\` ` +
+                `array of keys/indexes (e.g. { field: '${field}', path: ['category'] }).`);
+        }
+    }
+    /**
+     * `having <expr>` over group aggregates. `_count` compares `count(*)` (parity
+     * with the projection); a per-field aggregate re-emits its inner expression
+     * (from `aggInner` when the field is a requested aggregate, so a JSON-path
+     * aggregate reuses its bound placeholders, else `.field` for a plain column).
+     */
+    buildHaving(having, params, aggInner) {
         if (!having)
             return '';
         const conds = [];
@@ -1236,18 +1980,88 @@ export class PowqlInterface {
             if (spec == null)
                 continue;
             if (key === '_count') {
-                conds.push(cmp(`count(.${this.meta.primaryKey[0]})`, spec));
+                conds.push(cmp('count(*)', spec));
             }
             else {
                 for (const [fn, filter] of Object.entries(spec)) {
                     if (filter == null)
                         continue;
-                    conds.push(cmp(`${fn.slice(1)}(${this.ref(key)})`, filter));
+                    const inner = aggInner.get(key) ?? this.ref(key);
+                    conds.push(cmp(`${fn.slice(1)}(${inner})`, filter));
                 }
             }
         }
         return conds.length ? ` having ${conds.join(' and ')}` : '';
     }
+    /**
+     * Compile a groupBy `orderBy` into a PowQL `order` body over the group RESULT
+     * columns (by-fields, JSON group-key aliases, and requested aggregates). PowQL
+     * cannot re-emit an aggregate EXPRESSION in `order` (engine error), but CAN
+     * order by a projection alias on a grouped query (probed), so each key maps to
+     * its projected alias (`.agg_N` / `.gk_N` / `.col`). Semantics and error
+     * surface mirror the SQL `buildGroupByOrderBy` (0.32.2 R3-1): an aggregate not
+     * requested in this call, or an unknown by-key, throws E003 listing the valid
+     * keys. `nulls: 'first'` stays E017 (PowDB has no NULLS placement grammar).
+     */
+    buildGroupOrder(orderBy, byOrderExprs, aggOrderExprs) {
+        if (!orderBy)
+            return '';
+        const aggBlocks = new Set(['_count', '_sum', '_avg', '_min', '_max']);
+        const validKeys = () => {
+            const keys = [...byOrderExprs.keys()];
+            for (const k of aggOrderExprs.keys())
+                keys.push(k.includes(':') ? k.replace(':', '.') : k);
+            return keys.join(', ') || '(none)';
+        };
+        const parts = [];
+        for (const [key, value] of Object.entries(orderBy)) {
+            if (value === undefined)
+                continue;
+            if (aggBlocks.has(key)) {
+                if (key === '_count') {
+                    const expr = aggOrderExprs.get('_count');
+                    if (!expr) {
+                        throw new ValidationError(`[turbine] Cannot order groupBy by "_count" on table "${this.table}": _count is not selected. ` +
+                            `Orderable keys: ${validKeys()}.`);
+                    }
+                    parts.push(`${expr} ${this.groupOrderDir(value, '_count')}`);
+                    continue;
+                }
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    throw new ValidationError(`[turbine] Invalid groupBy orderBy for "${key}" on table "${this.table}": ` +
+                        `expected a field map like { ${key}: { amount: 'desc' } }.`);
+                }
+                for (const [field, dirSpec] of Object.entries(value)) {
+                    if (dirSpec === undefined)
+                        continue;
+                    const expr = aggOrderExprs.get(`${key}:${field}`);
+                    if (!expr) {
+                        throw new ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${this.table}": ` +
+                            `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
+                    }
+                    parts.push(`${expr} ${this.groupOrderDir(dirSpec, `${key}.${field}`)}`);
+                }
+                continue;
+            }
+            const expr = byOrderExprs.get(key);
+            if (!expr) {
+                throw new ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${this.table}". Orderable keys: ${validKeys()}.`);
+            }
+            parts.push(`${expr} ${this.groupOrderDir(value, key)}`);
+        }
+        return parts.length ? ` order ${parts.join(', ')}` : '';
+    }
+    /** Resolve a groupBy order direction, refusing `nulls: 'first'` (E017); `nulls: 'last'` is a no-op. */
+    groupOrderDir(value, keyForMsg) {
+        if (value !== null && typeof value === 'object') {
+            const spec = value;
+            if (spec.nulls === 'first') {
+                throw new UnsupportedFeatureError('NULLS FIRST placement', 'PowDB', `groupBy orderBy "${keyForMsg}": PowDB orders NULLs / missing keys LAST in both directions`);
+            }
+            return spec.sort === 'desc' ? 'desc' : 'asc';
+        }
+        return value === 'desc' ? 'desc' : 'asc';
+    }
     // -------------------------------------------------------------------------
     // Streaming / unsupported
     // -------------------------------------------------------------------------
@@ -1261,12 +2075,12 @@ export class PowqlInterface {
     /** 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({
+        const { rows, native } = await this.runFind({
             where: { [pkField]: pkValue },
             limit: 1,
             timeout,
         });
-        return rows.length ? this.shape(rows)[0] : null;
+        return rows.length ? this.shape(rows, native)[0] : null;
     }
     /**
      * Empty-where guard — blocks accidental whole-table writes. Mirrors the SQL
@@ -1301,3 +2115,53 @@ function coerceScalar(raw, tsType) {
         return new Date(Number(raw) / 1000);
     return raw;
 }
+/**
+ * Decode a JSON group-key cell, resolving the legacy-wire `null` ambiguity AND
+ * normalizing the native typed wire to the SAME PG-`#>>`-text-parity shape.
+ *
+ * On the native typed wire (`native`) a cell arrives pre-typed (a JSON int as a
+ * `bigint`, a bool as `boolean`, an unset value as `null`). Returned as-is that
+ * would diverge from every other transport: the embedded / legacy / SQL wire
+ * all yield the extracted TEXT (`'7'`, `'true'`), and a raw `bigint` even throws
+ * on `JSON.stringify`. So a native scalar cell is rendered to its text form
+ * ({@link nativeJsonKeyText}); `null`/`empty` stays `null`, and a genuine string
+ * `"null"` stays the string (the wart the native wire was adopted to fix).
+ *
+ * On the legacy string wire a missing value, JSON null, AND the string `"null"`
+ * all render the cell `"null"`; the group's `min(json_type(…))` discriminator is
+ * `"string"` ONLY for the string-`"null"` group, so the cell is the string
+ * `"null"` iff the discriminator is `"string"`, else `null`. Other cell values
+ * pass through as the extracted string.
+ */
+function decodeGroupKeyCell(cell, discrim, native) {
+    if (native)
+        return nativeJsonKeyText(cell);
+    if (cell == null)
+        return null;
+    if (cell === 'null')
+        return discrim === 'string' ? 'null' : null;
+    return cell;
+}
+/**
+ * Render a native-wire JSON group-key cell to the extracted-text shape the other
+ * transports return (PG `#>>` / embedded legacy / SQL all give text keys). Keeps
+ * `null` as `null`; a scalar (`bigint`/`number`/`boolean`/`string`) becomes its
+ * string form; an object/array json sub-document is stringified (best-effort
+ * parity: canonical byte-for-byte matching is not guaranteed for nested docs).
+ */
+function nativeJsonKeyText(cell) {
+    if (cell === null || cell === undefined)
+        return null;
+    if (typeof cell === 'bigint')
+        return cell.toString();
+    if (typeof cell === 'number' || typeof cell === 'boolean')
+        return String(cell);
+    if (typeof cell === 'string')
+        return cell;
+    try {
+        return JSON.stringify(cell);
+    }
+    catch {
+        return String(cell);
+    }
+}