turbine-orm 0.32.2 → 0.34.0

package/dist/powql.js

@@ -37,8 +37,8 @@
 import { randomUUID } from 'node:crypto';
 import { NotFoundError, 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,21 @@ 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',
+]);
 /** Operator keys recognised inside a `WhereOperator` object. */
 const OPERATOR_KEYS = new Set([
     'equals',
@@ -93,7 +108,6 @@ export class PowqlInterface {
     defaultLimit;
     warnOnUnlimited;
     onQuery;
-    currentAction = 'raw';
     warnedUnlimited = false;
     constructor(pool, table, schema, middlewares = [], options = {}) {
         this.pool = pool;
@@ -144,7 +158,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 +196,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;
@@ -213,20 +246,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);
+                if (cond)
+                    parts.push(cond);
             }
         }
         return parts.join(' and ');
     }
     /** Build a single `field: value | operator` condition. */
     buildFieldCondition(field, value, params) {
+        const colMeta = this.column(field);
         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)}`;
+            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);
+        }
         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 +324,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) {
+        let expr = `.${col.name}`;
+        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) {
+        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);
+            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(.${col.name}->${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 +559,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 +607,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) {
         if (!orderBy)
             return '';
         const keys = Object.entries(orderBy).filter(([, dir]) => dir !== undefined);
@@ -476,32 +628,82 @@ 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);
+                }
+                // 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)} ${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 ` order ${parts.join(', ')}`;
     }
+    /** Compile one {@link JsonPathOrderBy} entry to `order .col->$n asc` (+ optional numeric cast). */
+    buildJsonPathOrder(field, spec, params) {
+        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);
+        // `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);
+    }
+    /**
+     * 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) {
         const start = performance.now();
         const run = this.pool.query(powql, params);
         try {
@@ -511,15 +713,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 +752,7 @@ export class PowqlInterface {
                 params,
                 duration,
                 model: this.table,
-                action: this.currentAction,
+                action,
                 rows,
                 timestamp: new Date(),
                 error,
@@ -540,7 +764,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,24 +774,30 @@ 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);
+            const { rows, native } = await this.runFind(args, 'findMany');
+            const entities = this.shape(rows, native);
             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) {
+    /** Build + run the flat findMany select; returns raw rows + the serving wire. */
+    async runFind(args, action = 'findMany') {
         if (args.cursor) {
             throw new UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
         }
@@ -578,7 +807,7 @@ export class PowqlInterface {
         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 +816,15 @@ 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;
+        const { rows, native } = await this.exec(powql, params, args.timeout, action);
+        return { rows, native };
     }
     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 +832,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];
@@ -736,7 +965,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]);
@@ -837,8 +1066,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 +1084,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 +1099,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 +1114,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 };
         });
     }
@@ -1008,8 +1237,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 +1251,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 +1273,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 +1318,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 +1332,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 +1364,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 +1571,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 +1666,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 +1706,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);
+    }
+}