turbine-orm 0.38.1 → 0.39.0

package/README.md

@@ -895,7 +895,7 @@ Everything is honest about what ports and what doesn't. Features marked **PG-onl
 
 **Engine notes:** SQLite uses `RETURNING` (≥ 3.35) just like Postgres. MySQL has no `RETURNING`, so writes re-`SELECT` the affected row and **`createMany` returns `[]`** (the rows ARE inserted — re-query if you need them). SQL Server returns rows via `OUTPUT`/`MERGE`; `DISTINCT ON` is Postgres-only. Only Postgres streams via a true cursor (constant memory); the other engines' `findManyStream` materializes the result then yields it in batches. Optimistic locking throws `OptimisticLockError` on all engines (on MySQL the conflict is detected from the version-checked UPDATE's affected-row count). The `turbine` CLI (`generate`, `migrate`) is currently PostgreSQL-only — point the engine factories at a hand-written or programmatically introspected `SCHEMA`.
 
-**PowDB** speaks its own non-SQL query language (PowQL), so it sits outside the SQL matrix above. Writes use a trailing **`returning`** keyword (upsert reselects by PK). PKs are server-assigned `auto` ints **or** client UUIDs. Nested relations load client-side (N+1, including many-to-many via the junction — no `json_agg`). Nested writes cover hasMany/hasOne/belongsTo; many-to-many nested writes are not supported. Transactions are single-writer: concurrent `$transaction` calls queue FIFO (bounded by `transactionQueueTimeoutMs`); nested/re-entrant transactions throw typed errors (no savepoints). Schema is code-first via `defineSchema` — `schemaDefToMetadata()` bridges it to any engine that needs runtime metadata, and a programmatic `describe`-based introspector exists since 0.34 (relations excluded). JSON documents are first-class on engine 0.12+: `JsonFilter` where-filters, JSON-path `orderBy`/`groupBy`, doc-field expression indexes, and a lossless native wire (0.13+) that keeps JSON `null`, missing fields, and the string `"null"` distinct. Embedded `syncMode: 'normal'` moves fsync off the commit path; the networked transport runs the same data over a socket. Cursor streaming and the Postgres-only trio (pgvector / LISTEN/NOTIFY / RLS session GUCs) throw `UnsupportedFeatureError`. Full details: **[turbineorm.dev/engines#powdb](https://turbineorm.dev/engines#powdb)**.
+**PowDB** speaks its own non-SQL query language (PowQL), so it sits outside the SQL matrix above. Writes use a trailing **`returning`** keyword (upsert reselects by PK). PKs are server-assigned `auto` ints **or** client UUIDs. Nested relations run as **one statement** on engine 0.18+ (PowQL nested projections — per-parent order/limit, childless parents kept, the same single-query shape as Postgres `json_agg`); older engines and ineligible shapes (many-to-many via the junction) load client-side with identical output. Nested writes cover hasMany/hasOne/belongsTo; many-to-many nested writes are not supported. Transactions are single-writer: concurrent `$transaction` calls queue FIFO (bounded by `transactionQueueTimeoutMs`); nested/re-entrant transactions throw typed errors (no savepoints). Schema is code-first via `defineSchema` — `schemaDefToMetadata()` bridges it to any engine that needs runtime metadata, and a programmatic `describe`-based introspector exists since 0.34 (relations excluded). JSON documents are first-class on engine 0.12+: `JsonFilter` where-filters, JSON-path `orderBy`/`groupBy`, doc-field expression indexes, and a lossless native wire (0.13+) that keeps JSON `null`, missing fields, and the string `"null"` distinct. Embedded `syncMode: 'normal'` moves fsync off the commit path; the networked transport runs the same data over a socket. Cursor streaming and the Postgres-only trio (pgvector / LISTEN/NOTIFY / RLS session GUCs) throw `UnsupportedFeatureError`. Full details: **[turbineorm.dev/engines#powdb](https://turbineorm.dev/engines#powdb)**.
 
 Full setup, signatures, and the complete support matrix: **[turbineorm.dev/engines](https://turbineorm.dev/engines)**.
 

package/dist/cjs/powdb.js

@@ -253,6 +253,7 @@ const POWDB_FEATURE_MIN_VERSION = {
     jsonDocs: '0.12',
     docFieldIndexes: '0.13',
     serverJoins: '0.13',
+    nestedProjections: '0.18',
 };
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
@@ -260,7 +261,9 @@ const POWDB_FEATURE_MIN_VERSION = {
  * did not go through {@link turbinePowDB}'s version probe (e.g. an injected
  * pool, or a unit-test pool). `nativeRaw` stays OFF here because it flips the
  * actual wire path and must only be enabled after a real server-version probe,
- * never inferred from a bare construction.
+ * never inferred from a bare construction. `nestedProjections` stays OFF for
+ * the same reason: it changes the generated PowQL for every `with` query, and
+ * an unprobed engine below 0.18 would reject the syntax outright.
  */
 exports.ALL_POWDB_CAPABILITIES = {
     engineVersion: null,
@@ -268,6 +271,7 @@ exports.ALL_POWDB_CAPABILITIES = {
     docFieldIndexes: true,
     introspection: true,
     serverJoins: true,
+    nestedProjections: false,
     nativeRaw: false,
 };
 /** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
@@ -296,6 +300,7 @@ function capabilitiesFromVersion(version, opts = {}) {
             docFieldIndexes: false,
             introspection: false,
             serverJoins: false,
+            nestedProjections: false,
             nativeRaw: false,
         };
     }
@@ -305,6 +310,7 @@ function capabilitiesFromVersion(version, opts = {}) {
         jsonDocs: atLeastVersion(sem, 0, 12),
         docFieldIndexes: atLeastVersion(sem, 0, 13),
         serverJoins: atLeastVersion(sem, 0, 13),
+        nestedProjections: atLeastVersion(sem, 0, 18),
         nativeRaw: Boolean(opts.hasNativeRaw) && atLeastVersion(sem, 0, 13),
     };
 }
@@ -731,7 +737,10 @@ function rowToEntity(raw, meta, native = false) {
  *     `Execution("type mismatch …")`, `Parse(…)`, `StorageError(…)`).
  *
  * So we always run the unique-constraint and message-shape checks first (they
- * fire for both transports), then fall through to the networked `.code` switch.
+ * fire for both transports and extract detail like constraint / column names),
+ * then classify by the typed wire error class (`.wireErrorClass`, networked
+ * server >= 0.17 — accurate even when the server sanitized the message text),
+ * then fall through to the networked `.code` switch.
  */
 function wrapPowdbError(err) {
     if (!err || typeof err !== 'object')
@@ -822,6 +831,46 @@ function wrapPowdbError(err) {
     if (/nested-loop join would evaluate|join result exceeds row limit/i.test(msg)) {
         return new errors_js_1.ValidationError(`[turbine] PowDB join rejected: ${msg}`);
     }
+    // Typed wire error class (networked, server >= 0.17): the client surfaces the
+    // stable one-byte class from the error frame as `.wireErrorClass`. Classify by
+    // it BEFORE the generic message regexes: the server sanitizes non-allowlisted
+    // messages to the generic "query execution error" text, but the class is
+    // derived from the typed error at response-build time, so it stays accurate
+    // when the message no longer is. The specific message families above still run
+    // first because they extract richer detail (constraint / column names) that
+    // the class byte cannot carry. Class values are append-only wire contract
+    // (docs/errors.md upstream); unknown / absent classes fall through to the
+    // pre-0.17 message + `.code` behavior.
+    const wireClass = err.wireErrorClass;
+    if (typeof wireClass === 'number') {
+        switch (wireClass) {
+            case 3: // timeout (per-query budget, gate wait, idle timeout) — retryable
+                return new errors_js_1.TimeoutError(0, 'PowDB query', { message: `[turbine] PowDB ${msg}`, cause: err });
+            case 4: // limit_exceeded (memory / size budget) — a query-shape defect
+                return new errors_js_1.ValidationError(`[turbine] PowDB resource limit exceeded: ${msg}`);
+            case 5: // readonly_refused — the snapshot-serving routing signal
+                return new errors_js_1.ReadOnlyError(`PowDB refused a write on a read-only database: ${msg}.`, {
+                    cause: err,
+                    reason: 'snapshot',
+                });
+            case 6: // auth_failed at CONNECT
+                return new errors_js_1.ConnectionError(`[turbine] PowDB authentication failed: ${msg} (check the user / password / dbName for this connection).`, { cause: err });
+            case 7: // rate_limited (repeated bad auth) — connection-establishment class
+                return new errors_js_1.ConnectionError(`[turbine] PowDB rate-limited this address after repeated failed authentication: ${msg}. Wait before retrying.`, { cause: err });
+            case 8: {
+                // constraint_violation — today that is always a unique index
+                const m = /on\s+\S+\.(\w+)/i.exec(msg);
+                return new errors_js_1.UniqueConstraintError({ constraint: m?.[1], cause: err });
+            }
+            case 9: // cancelled (issuing client disconnected) — final, never retry
+                return new errors_js_1.ConnectionError(`[turbine] PowDB query cancelled by client disconnect: ${msg}`, { cause: err });
+            case 1: // parse
+            case 2: // execution
+                return new errors_js_1.ValidationError(`[turbine] PowDB query rejected: ${msg}`);
+            default: // internal (0) or an unknown future class: fall through
+                break;
+        }
+    }
     // Type mismatch / parse / execution / storage / unexpected(token) / row too
     // large → validation (E003). On the embedded transport these are the only
     // signal we get (code is always 'GenericFailure'); on the networked path they
@@ -1449,7 +1498,7 @@ function encodePowqlLiteral(value) {
  * the ceiling yet still routes through the string wire is refused rather than
  * materialized.
  */
-exports.POWQL_LEXER_TESTED_CEILING = '0.16';
+exports.POWQL_LEXER_TESTED_CEILING = '0.18';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
 function encodePowqlString(s) {
     let out = '"';

package/dist/cjs/powql.js

@@ -930,30 +930,63 @@ class PowqlInterface {
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
         return this.withMiddleware('findMany', args, async () => {
-            const { rows, native, resolvedWhere } = await this.runFind(args, 'findMany');
+            const { rows, native, resolvedWhere, nestedPlans, residualWith } = 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 }, args.includePii === true);
+            if (nestedPlans.length)
+                this.attachNestedRows(entities, nestedPlans);
+            if (residualWith) {
+                await this.loadRelations(entities, residualWith, args.timeout, 0, { args, resolvedWhere }, args.includePii === true);
             }
             return entities;
         });
     }
     /**
-     * Compile the flat findMany select into PowQL (no execution), pushing values
-     * into `params`. Returns the query plus the RESOLVED where (relation filters
+     * Compile the 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.
+     *
+     * When the engine supports nested projections (>= 0.18) and the strategy
+     * does not opt out, eligible `with` relations compile INTO this statement as
+     * nested-projection blocks (`nestedPlans`) — one round-trip for the whole
+     * shape — and only the ineligible remainder (`residualWith`) goes to the
+     * post-execution loaders. Without nesting the emitted PowQL is byte-identical
+     * to the pre-0.18 output (no alias, `.col` refs).
      */
     async buildFind(args, params) {
         if (args.cursor) {
             throw new errors_js_1.UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
         }
         const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-        const where = this.buildWhere(resolvedWhere, params);
         const cols = this.projectedColumns(args.select, args.omit, args.includePii === true);
+        // Partition the `with` clause: nested-projection blocks vs loader residue.
+        // A parent `distinct` never nests (distinct over a row containing a JSON
+        // array is not a defined comparison), and a relation whose field name
+        // collides with a projected parent column stays on the loaders (its block
+        // key would duplicate the column's).
+        const withClause = args.with;
+        const nestedPlans = [];
+        let residualWith = withClause;
+        if (withClause && !args.distinct?.length && this.nestedProjectionsPreferred(args)) {
+            const residue = {};
+            for (const [relName, opt] of Object.entries(withClause)) {
+                if (!opt)
+                    continue;
+                const rel = this.meta.relations[relName];
+                const plan = rel && !cols.includes(relName) ? this.planNestedRelation(relName, rel, opt, args.includePii === true) : null;
+                if (plan)
+                    nestedPlans.push(plan);
+                else
+                    residue[relName] = opt; // unknown relation: the loader raises its E003
+            }
+            residualWith = Object.keys(residue).length ? residue : undefined;
+        }
+        const nest = nestedPlans.length > 0;
+        const alias = nest ? 't0' : undefined;
+        const where = this.buildWhere(resolvedWhere, params, alias);
         const distinct = args.distinct?.length ? ' distinct' : '';
         const filter = where ? ` filter ${where}` : '';
-        const order = this.buildOrder(args.orderBy, params);
+        const order = this.buildOrder(args.orderBy, params, alias);
         const limit = args.limit ?? args.take ?? this.defaultLimit;
         if (limit === undefined && this.warnOnUnlimited && !this.warnedUnlimited) {
             this.warnedUnlimited = true;
@@ -961,15 +994,29 @@ 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)}`;
-        return { powql, resolvedWhere };
+        let projection;
+        if (nest) {
+            // Aliased scan: every parent column keys itself (`col: t0.col`) so the
+            // result columns keep their bare snake names, then the nested blocks.
+            const aliasCtr = { n: 1 };
+            const parts = cols.map((c) => `${(0, powdb_js_1.quotePowqlIdent)(c)}: t0.${(0, powdb_js_1.quotePowqlIdent)(c)}`);
+            for (const plan of nestedPlans) {
+                parts.push(await this.buildNestedBlock(plan, 't0', aliasCtr, params, args.timeout));
+            }
+            projection = `{ ${parts.join(', ')} }`;
+        }
+        else {
+            projection = this.projection(cols);
+        }
+        const powql = `${this.qt}${nest ? ' as t0' : ''}${distinct}${filter}${order}${limitClause}${offsetClause} ${projection}`;
+        return { powql, resolvedWhere, nestedPlans, residualWith };
     }
-    /** Build + run the flat findMany select; returns raw rows, the serving wire, and the resolved where. */
+    /** Build + run the findMany select; returns raw rows, the serving wire, the resolved where, and the `with` partition. */
     async runFind(args, action = 'findMany') {
         const params = [];
-        const { powql, resolvedWhere } = await this.buildFind(args, params);
+        const { powql, resolvedWhere, nestedPlans, residualWith } = await this.buildFind(args, params);
         const { rows, native } = await this.exec(powql, params, args.timeout, action);
-        return { rows, native, resolvedWhere };
+        return { rows, native, resolvedWhere, nestedPlans, residualWith };
     }
     /**
      * Diagnostic surface: compile the same PowQL {@link findMany} would run for
@@ -997,23 +1044,27 @@ class PowqlInterface {
     }
     async findUnique(args) {
         return this.withMiddleware('findUnique', args, async () => {
-            const { rows, native } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
+            const { rows, native, nestedPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
             if (!rows.length)
                 return null;
             const entities = this.shape(rows, native);
-            if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
+            if (nestedPlans.length)
+                this.attachNestedRows(entities, nestedPlans);
+            if (residualWith)
+                await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
     async findFirst(args = {}) {
         return this.withMiddleware('findFirst', args, async () => {
-            const { rows, native } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
+            const { rows, native, nestedPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
             if (!rows.length)
                 return null;
             const entities = this.shape(rows, native);
-            if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
+            if (nestedPlans.length)
+                this.attachNestedRows(entities, nestedPlans);
+            if (residualWith)
+                await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
@@ -1503,6 +1554,160 @@ class PowqlInterface {
         return String(v);
     }
     // -------------------------------------------------------------------------
+    // Nested relations: nested projections / shaped results (PowDB >= 0.18)
+    // -------------------------------------------------------------------------
+    /**
+     * Should this query's `with` compile to nested-projection blocks? Requires
+     * the engine capability (>= 0.18), and an EXPLICIT `relationLoadStrategy:
+     * 'batched'` (per-query or client-level) opts back out to the keyed loaders.
+     * The default and `'join'` both prefer nesting: unlike the F2 INNER join it
+     * has no fan-out, keeps childless parents, works under parent paging, and
+     * applies per-parent `order`/`limit`/`offset` natively, so it is the
+     * strictly-better single-statement path wherever it is eligible. Ineligible
+     * relations fall through to the existing strategy resolution untouched.
+     */
+    nestedProjectionsPreferred(args) {
+        if (!this.capabilities.nestedProjections)
+            return false;
+        const explicit = args.relationLoadStrategy ?? this.options.relationLoadStrategy;
+        return explicit !== 'batched';
+    }
+    /**
+     * Plan one `with` relation as a nested-projection block, or return `null`
+     * when the shape must stay on the loaders (ALWAYS a silent fallback with
+     * identical output, never an error):
+     *   - m2m (the block takes exactly one child table; the junction-order
+     *     stitch has no nested equivalent), and composite relation keys;
+     *   - a to-one relation carrying `limit`/`offset` (the loaders' semantics);
+     *   - `distinct` inside the relation options (no nested grammar for it);
+     *   - a projected child column whose tsType is `bigint` or `Uint8Array`
+     *     (values ride a JSON array, which cannot carry them losslessly);
+     *   - a projection key collision (a child column named like a sub-relation);
+     *   - depth >= 10 (the loader path enforces the same cap by throwing, so the
+     *     fallback surfaces the identical E003 today's users get);
+     *   - any ineligible descendant (the WHOLE relation falls back, so one
+     *     statement never mixes nested and loader semantics mid-subtree).
+     */
+    planNestedRelation(relName, rel, opt, includePii, depth = 0) {
+        if (depth >= 10)
+            return null;
+        if (rel.type === 'manyToMany')
+            return null;
+        if ((0, schema_js_1.normalizeKeyColumns)(rel.foreignKey).length > 1 || (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey).length > 1) {
+            return null;
+        }
+        if (!this.schema.tables[rel.to])
+            return null; // the loader raises its own error
+        const options = (opt === true ? {} : opt);
+        if (options.distinct?.length)
+            return null;
+        const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+        if (single && (options.limit !== undefined || options.offset))
+            return null;
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const cols = targetQi.projectedColumns(options.select, options.omit, includePii);
+        const byName = new Map(targetQi.meta.columns.map((c) => [c.name, c]));
+        for (const c of cols) {
+            const ts = (byName.get(c)?.tsType ?? '').replace(/\s*\|\s*null$/i, '').trim();
+            if (ts === 'bigint' || ts === 'Uint8Array')
+                return null;
+        }
+        const children = [];
+        if (options.with) {
+            for (const [subName, subOpt] of Object.entries(options.with)) {
+                if (!subOpt)
+                    continue;
+                const subRel = targetQi.meta.relations[subName];
+                if (!subRel)
+                    return null; // let the loader raise its unknown-relation error
+                const child = targetQi.planNestedRelation(subName, subRel, subOpt, includePii, depth + 1);
+                if (!child)
+                    return null;
+                children.push(child);
+            }
+        }
+        // The block's object keys are the projected snake column names plus the
+        // sub-relation field names; a duplicate key would mis-shape the JSON.
+        const keys = new Set(cols);
+        for (const child of children) {
+            if (keys.has(child.relName))
+                return null;
+            keys.add(child.relName);
+        }
+        return { relName, rel, options, targetQi, single, cols, children };
+    }
+    /**
+     * Compile one {@link NestedRelationPlan} into its projection-field block:
+     * `name: Target as tN filter <correlation> [and (<child where>)] [order …]
+     * [limit …] [offset …] { col: tN.col, …, <sub-blocks> }`. Params bind in
+     * emission order (the projection is the statement's final clause, so nested
+     * params always follow the parent's filter/order/limit/offset params).
+     * Aliases share the parent statement's counter, so arbitrarily deep and
+     * self-referential trees stay collision-free (the same discipline as the SQL
+     * engine's json_agg subqueries).
+     */
+    async buildNestedBlock(plan, parentAlias, aliasCtr, params, timeout) {
+        const { rel, relName, targetQi, options, single } = plan;
+        const alias = `t${aliasCtr.n++}`;
+        const fk = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey)[0];
+        const rk = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey)[0];
+        const parentKeyCol = rel.type === 'belongsTo' ? fk : rk;
+        const childKeyCol = rel.type === 'belongsTo' ? rk : fk;
+        // Exactly one equi-correlation predicate (the 0.18 correlation rule); the
+        // child where chains behind it as a parenthesized `and` group, which the
+        // grammar accepts even when the group itself contains `or`.
+        const correlation = `${alias}.${(0, powdb_js_1.quotePowqlIdent)(childKeyCol)} = ${parentAlias}.${(0, powdb_js_1.quotePowqlIdent)(parentKeyCol)}`;
+        const resolved = await targetQi.resolveRelationFilters(options.where, timeout);
+        const childWhere = targetQi.buildWhere(resolved, params, alias);
+        const filter = childWhere ? `${correlation} and (${childWhere})` : correlation;
+        const order = targetQi.buildOrder(options.orderBy, params, alias);
+        const limitClause = single
+            ? ' limit 1'
+            : options.limit !== undefined
+                ? ` limit ${this.param(options.limit, params)}`
+                : '';
+        const offsetClause = !single && options.offset ? ` offset ${this.param(options.offset, params)}` : '';
+        const parts = plan.cols.map((c) => `${(0, powdb_js_1.quotePowqlIdent)(c)}: ${alias}.${(0, powdb_js_1.quotePowqlIdent)(c)}`);
+        for (const child of plan.children) {
+            parts.push(await targetQi.buildNestedBlock(child, alias, aliasCtr, params, timeout));
+        }
+        return (`${(0, powdb_js_1.quotePowqlIdent)(relName)}: ${targetQi.qt} as ${alias} ` +
+            `filter ${filter}${order}${limitClause}${offsetClause} { ${parts.join(', ')} }`);
+    }
+    /**
+     * Shape the nested JSON children back into typed entities on every parent
+     * row. The nested field arrives as a decoded JSON array on the native wire
+     * (or JSON text on the legacy wire — parsed here); its values are real JSON
+     * types, so each child object goes through the NATIVE coercion policy
+     * (`rowToEntity(…, true)`: a date column's micros number becomes a `Date`, a
+     * json column's document passes through, a str `"null"` stays a string).
+     * to-one relations unwrap to `[0] ?? null`, matching the loaders exactly.
+     */
+    attachNestedRows(entities, plans) {
+        for (const entity of entities) {
+            for (const plan of plans)
+                this.attachOneNested(entity, plan);
+        }
+    }
+    attachOneNested(row, plan) {
+        let value = row[plan.relName];
+        if (typeof value === 'string') {
+            try {
+                value = JSON.parse(value);
+            }
+            catch {
+                value = [];
+            }
+        }
+        const items = Array.isArray(value) ? value : [];
+        const shaped = items.map((o) => (0, powdb_js_1.rowToEntity)(o, plan.targetQi.meta, true));
+        for (const child of shaped) {
+            for (const sub of plan.children)
+                plan.targetQi.attachOneNested(child, sub);
+        }
+        row[plan.relName] = plan.single ? (shaped[0] ?? null) : shaped;
+    }
+    // -------------------------------------------------------------------------
     // Writes (reselect — PowDB has no RETURNING)
     // -------------------------------------------------------------------------
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */

package/dist/powdb.d.ts

@@ -254,18 +254,27 @@ export interface PowdbCapabilities {
     introspection: boolean;
     /** ≥ 0.13: server-side joins, hash-accelerated and bounded. */
     serverJoins: boolean;
+    /**
+     * ≥ 0.18: nested projections (shaped results) — a projection field may be a
+     * whole correlated child query returning a per-parent JSON array. When set,
+     * eligible `with` clauses compile into the parent statement instead of the
+     * batched loaders.
+     */
+    nestedProjections: boolean;
     /** Networked only: server ≥ 0.13 AND the client exposes `queryNativeRaw`. */
     nativeRaw: boolean;
 }
 /** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
-type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins';
+type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins' | 'nestedProjections';
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
  * for a directly-constructed {@link PowdbPool} / {@link PowdbEmbeddedPool} that
  * did not go through {@link turbinePowDB}'s version probe (e.g. an injected
  * pool, or a unit-test pool). `nativeRaw` stays OFF here because it flips the
  * actual wire path and must only be enabled after a real server-version probe,
- * never inferred from a bare construction.
+ * never inferred from a bare construction. `nestedProjections` stays OFF for
+ * the same reason: it changes the generated PowQL for every `with` query, and
+ * an unprobed engine below 0.18 would reject the syntax outright.
  */
 export declare const ALL_POWDB_CAPABILITIES: PowdbCapabilities;
 /**
@@ -388,7 +397,10 @@ export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMet
  *     `Execution("type mismatch …")`, `Parse(…)`, `StorageError(…)`).
  *
  * So we always run the unique-constraint and message-shape checks first (they
- * fire for both transports), then fall through to the networked `.code` switch.
+ * fire for both transports and extract detail like constraint / column names),
+ * then classify by the typed wire error class (`.wireErrorClass`, networked
+ * server >= 0.17 — accurate even when the server sanitized the message text),
+ * then fall through to the networked `.code` switch.
  */
 export declare function wrapPowdbError(err: unknown): Error;
 /**
@@ -599,7 +611,7 @@ export declare function encodePowqlLiteral(value: unknown): string;
  * the ceiling yet still routes through the string wire is refused rather than
  * materialized.
  */
-export declare const POWQL_LEXER_TESTED_CEILING = "0.16";
+export declare const POWQL_LEXER_TESTED_CEILING = "0.18";
 /**
  * Substitute every `$N` placeholder in a generator-produced PowQL template with
  * the encoded literal of `params[N-1]`. Safe because the template is produced by

package/dist/powdb.js

@@ -196,6 +196,7 @@ const POWDB_FEATURE_MIN_VERSION = {
     jsonDocs: '0.12',
     docFieldIndexes: '0.13',
     serverJoins: '0.13',
+    nestedProjections: '0.18',
 };
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
@@ -203,7 +204,9 @@ const POWDB_FEATURE_MIN_VERSION = {
  * did not go through {@link turbinePowDB}'s version probe (e.g. an injected
  * pool, or a unit-test pool). `nativeRaw` stays OFF here because it flips the
  * actual wire path and must only be enabled after a real server-version probe,
- * never inferred from a bare construction.
+ * never inferred from a bare construction. `nestedProjections` stays OFF for
+ * the same reason: it changes the generated PowQL for every `with` query, and
+ * an unprobed engine below 0.18 would reject the syntax outright.
  */
 export const ALL_POWDB_CAPABILITIES = {
     engineVersion: null,
@@ -211,6 +214,7 @@ export const ALL_POWDB_CAPABILITIES = {
     docFieldIndexes: true,
     introspection: true,
     serverJoins: true,
+    nestedProjections: false,
     nativeRaw: false,
 };
 /** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
@@ -239,6 +243,7 @@ export function capabilitiesFromVersion(version, opts = {}) {
             docFieldIndexes: false,
             introspection: false,
             serverJoins: false,
+            nestedProjections: false,
             nativeRaw: false,
         };
     }
@@ -248,6 +253,7 @@ export function capabilitiesFromVersion(version, opts = {}) {
         jsonDocs: atLeastVersion(sem, 0, 12),
         docFieldIndexes: atLeastVersion(sem, 0, 13),
         serverJoins: atLeastVersion(sem, 0, 13),
+        nestedProjections: atLeastVersion(sem, 0, 18),
         nativeRaw: Boolean(opts.hasNativeRaw) && atLeastVersion(sem, 0, 13),
     };
 }
@@ -674,7 +680,10 @@ export function rowToEntity(raw, meta, native = false) {
  *     `Execution("type mismatch …")`, `Parse(…)`, `StorageError(…)`).
  *
  * So we always run the unique-constraint and message-shape checks first (they
- * fire for both transports), then fall through to the networked `.code` switch.
+ * fire for both transports and extract detail like constraint / column names),
+ * then classify by the typed wire error class (`.wireErrorClass`, networked
+ * server >= 0.17 — accurate even when the server sanitized the message text),
+ * then fall through to the networked `.code` switch.
  */
 export function wrapPowdbError(err) {
     if (!err || typeof err !== 'object')
@@ -765,6 +774,46 @@ export function wrapPowdbError(err) {
     if (/nested-loop join would evaluate|join result exceeds row limit/i.test(msg)) {
         return new ValidationError(`[turbine] PowDB join rejected: ${msg}`);
     }
+    // Typed wire error class (networked, server >= 0.17): the client surfaces the
+    // stable one-byte class from the error frame as `.wireErrorClass`. Classify by
+    // it BEFORE the generic message regexes: the server sanitizes non-allowlisted
+    // messages to the generic "query execution error" text, but the class is
+    // derived from the typed error at response-build time, so it stays accurate
+    // when the message no longer is. The specific message families above still run
+    // first because they extract richer detail (constraint / column names) that
+    // the class byte cannot carry. Class values are append-only wire contract
+    // (docs/errors.md upstream); unknown / absent classes fall through to the
+    // pre-0.17 message + `.code` behavior.
+    const wireClass = err.wireErrorClass;
+    if (typeof wireClass === 'number') {
+        switch (wireClass) {
+            case 3: // timeout (per-query budget, gate wait, idle timeout) — retryable
+                return new TimeoutError(0, 'PowDB query', { message: `[turbine] PowDB ${msg}`, cause: err });
+            case 4: // limit_exceeded (memory / size budget) — a query-shape defect
+                return new ValidationError(`[turbine] PowDB resource limit exceeded: ${msg}`);
+            case 5: // readonly_refused — the snapshot-serving routing signal
+                return new ReadOnlyError(`PowDB refused a write on a read-only database: ${msg}.`, {
+                    cause: err,
+                    reason: 'snapshot',
+                });
+            case 6: // auth_failed at CONNECT
+                return new ConnectionError(`[turbine] PowDB authentication failed: ${msg} (check the user / password / dbName for this connection).`, { cause: err });
+            case 7: // rate_limited (repeated bad auth) — connection-establishment class
+                return new ConnectionError(`[turbine] PowDB rate-limited this address after repeated failed authentication: ${msg}. Wait before retrying.`, { cause: err });
+            case 8: {
+                // constraint_violation — today that is always a unique index
+                const m = /on\s+\S+\.(\w+)/i.exec(msg);
+                return new UniqueConstraintError({ constraint: m?.[1], cause: err });
+            }
+            case 9: // cancelled (issuing client disconnected) — final, never retry
+                return new ConnectionError(`[turbine] PowDB query cancelled by client disconnect: ${msg}`, { cause: err });
+            case 1: // parse
+            case 2: // execution
+                return new ValidationError(`[turbine] PowDB query rejected: ${msg}`);
+            default: // internal (0) or an unknown future class: fall through
+                break;
+        }
+    }
     // Type mismatch / parse / execution / storage / unexpected(token) / row too
     // large → validation (E003). On the embedded transport these are the only
     // signal we get (code is always 'GenericFailure'); on the networked path they
@@ -1391,7 +1440,7 @@ export function encodePowqlLiteral(value) {
  * the ceiling yet still routes through the string wire is refused rather than
  * materialized.
  */
-export const POWQL_LEXER_TESTED_CEILING = '0.16';
+export const POWQL_LEXER_TESTED_CEILING = '0.18';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
 function encodePowqlString(s) {
     let out = '"';

package/dist/powql.d.ts

@@ -267,13 +267,20 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private shape;
     findMany(args?: FindManyArgs<T>): Promise<T[]>;
     /**
-     * Compile the flat findMany select into PowQL (no execution), pushing values
-     * into `params`. Returns the query plus the RESOLVED where (relation filters
+     * Compile the 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.
+     *
+     * When the engine supports nested projections (>= 0.18) and the strategy
+     * does not opt out, eligible `with` relations compile INTO this statement as
+     * nested-projection blocks (`nestedPlans`) — one round-trip for the whole
+     * shape — and only the ineligible remainder (`residualWith`) goes to the
+     * post-execution loaders. Without nesting the emitted PowQL is byte-identical
+     * to the pre-0.18 output (no alias, `.col` refs).
      */
     private buildFind;
-    /** Build + run the flat findMany select; returns raw rows, the serving wire, and the resolved where. */
+    /** Build + run the findMany select; returns raw rows, the serving wire, the resolved where, and the `with` partition. */
     private runFind;
     /**
      * Diagnostic surface: compile the same PowQL {@link findMany} would run for
@@ -396,6 +403,56 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * an int key matches whether it came back typed or as text.
      */
     private joinKey;
+    /**
+     * Should this query's `with` compile to nested-projection blocks? Requires
+     * the engine capability (>= 0.18), and an EXPLICIT `relationLoadStrategy:
+     * 'batched'` (per-query or client-level) opts back out to the keyed loaders.
+     * The default and `'join'` both prefer nesting: unlike the F2 INNER join it
+     * has no fan-out, keeps childless parents, works under parent paging, and
+     * applies per-parent `order`/`limit`/`offset` natively, so it is the
+     * strictly-better single-statement path wherever it is eligible. Ineligible
+     * relations fall through to the existing strategy resolution untouched.
+     */
+    private nestedProjectionsPreferred;
+    /**
+     * Plan one `with` relation as a nested-projection block, or return `null`
+     * when the shape must stay on the loaders (ALWAYS a silent fallback with
+     * identical output, never an error):
+     *   - m2m (the block takes exactly one child table; the junction-order
+     *     stitch has no nested equivalent), and composite relation keys;
+     *   - a to-one relation carrying `limit`/`offset` (the loaders' semantics);
+     *   - `distinct` inside the relation options (no nested grammar for it);
+     *   - a projected child column whose tsType is `bigint` or `Uint8Array`
+     *     (values ride a JSON array, which cannot carry them losslessly);
+     *   - a projection key collision (a child column named like a sub-relation);
+     *   - depth >= 10 (the loader path enforces the same cap by throwing, so the
+     *     fallback surfaces the identical E003 today's users get);
+     *   - any ineligible descendant (the WHOLE relation falls back, so one
+     *     statement never mixes nested and loader semantics mid-subtree).
+     */
+    private planNestedRelation;
+    /**
+     * Compile one {@link NestedRelationPlan} into its projection-field block:
+     * `name: Target as tN filter <correlation> [and (<child where>)] [order …]
+     * [limit …] [offset …] { col: tN.col, …, <sub-blocks> }`. Params bind in
+     * emission order (the projection is the statement's final clause, so nested
+     * params always follow the parent's filter/order/limit/offset params).
+     * Aliases share the parent statement's counter, so arbitrarily deep and
+     * self-referential trees stay collision-free (the same discipline as the SQL
+     * engine's json_agg subqueries).
+     */
+    private buildNestedBlock;
+    /**
+     * Shape the nested JSON children back into typed entities on every parent
+     * row. The nested field arrives as a decoded JSON array on the native wire
+     * (or JSON text on the legacy wire — parsed here); its values are real JSON
+     * types, so each child object goes through the NATIVE coercion policy
+     * (`rowToEntity(…, true)`: a date column's micros number becomes a `Date`, a
+     * json column's document passes through, a str `"null"` stays a string).
+     * to-one relations unwrap to `[0] ?? null`, matching the loaders exactly.
+     */
+    private attachNestedRows;
+    private attachOneNested;
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
     private scalarData;
     /**

package/dist/powql.js

@@ -894,30 +894,63 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
         return this.withMiddleware('findMany', args, async () => {
-            const { rows, native, resolvedWhere } = await this.runFind(args, 'findMany');
+            const { rows, native, resolvedWhere, nestedPlans, residualWith } = 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 }, args.includePii === true);
+            if (nestedPlans.length)
+                this.attachNestedRows(entities, nestedPlans);
+            if (residualWith) {
+                await this.loadRelations(entities, residualWith, args.timeout, 0, { args, resolvedWhere }, args.includePii === true);
             }
             return entities;
         });
     }
     /**
-     * Compile the flat findMany select into PowQL (no execution), pushing values
-     * into `params`. Returns the query plus the RESOLVED where (relation filters
+     * Compile the 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.
+     *
+     * When the engine supports nested projections (>= 0.18) and the strategy
+     * does not opt out, eligible `with` relations compile INTO this statement as
+     * nested-projection blocks (`nestedPlans`) — one round-trip for the whole
+     * shape — and only the ineligible remainder (`residualWith`) goes to the
+     * post-execution loaders. Without nesting the emitted PowQL is byte-identical
+     * to the pre-0.18 output (no alias, `.col` refs).
      */
     async buildFind(args, params) {
         if (args.cursor) {
             throw new UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
         }
         const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-        const where = this.buildWhere(resolvedWhere, params);
         const cols = this.projectedColumns(args.select, args.omit, args.includePii === true);
+        // Partition the `with` clause: nested-projection blocks vs loader residue.
+        // A parent `distinct` never nests (distinct over a row containing a JSON
+        // array is not a defined comparison), and a relation whose field name
+        // collides with a projected parent column stays on the loaders (its block
+        // key would duplicate the column's).
+        const withClause = args.with;
+        const nestedPlans = [];
+        let residualWith = withClause;
+        if (withClause && !args.distinct?.length && this.nestedProjectionsPreferred(args)) {
+            const residue = {};
+            for (const [relName, opt] of Object.entries(withClause)) {
+                if (!opt)
+                    continue;
+                const rel = this.meta.relations[relName];
+                const plan = rel && !cols.includes(relName) ? this.planNestedRelation(relName, rel, opt, args.includePii === true) : null;
+                if (plan)
+                    nestedPlans.push(plan);
+                else
+                    residue[relName] = opt; // unknown relation: the loader raises its E003
+            }
+            residualWith = Object.keys(residue).length ? residue : undefined;
+        }
+        const nest = nestedPlans.length > 0;
+        const alias = nest ? 't0' : undefined;
+        const where = this.buildWhere(resolvedWhere, params, alias);
         const distinct = args.distinct?.length ? ' distinct' : '';
         const filter = where ? ` filter ${where}` : '';
-        const order = this.buildOrder(args.orderBy, params);
+        const order = this.buildOrder(args.orderBy, params, alias);
         const limit = args.limit ?? args.take ?? this.defaultLimit;
         if (limit === undefined && this.warnOnUnlimited && !this.warnedUnlimited) {
             this.warnedUnlimited = true;
@@ -925,15 +958,29 @@ 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)}`;
-        return { powql, resolvedWhere };
+        let projection;
+        if (nest) {
+            // Aliased scan: every parent column keys itself (`col: t0.col`) so the
+            // result columns keep their bare snake names, then the nested blocks.
+            const aliasCtr = { n: 1 };
+            const parts = cols.map((c) => `${quotePowqlIdent(c)}: t0.${quotePowqlIdent(c)}`);
+            for (const plan of nestedPlans) {
+                parts.push(await this.buildNestedBlock(plan, 't0', aliasCtr, params, args.timeout));
+            }
+            projection = `{ ${parts.join(', ')} }`;
+        }
+        else {
+            projection = this.projection(cols);
+        }
+        const powql = `${this.qt}${nest ? ' as t0' : ''}${distinct}${filter}${order}${limitClause}${offsetClause} ${projection}`;
+        return { powql, resolvedWhere, nestedPlans, residualWith };
     }
-    /** Build + run the flat findMany select; returns raw rows, the serving wire, and the resolved where. */
+    /** Build + run the findMany select; returns raw rows, the serving wire, the resolved where, and the `with` partition. */
     async runFind(args, action = 'findMany') {
         const params = [];
-        const { powql, resolvedWhere } = await this.buildFind(args, params);
+        const { powql, resolvedWhere, nestedPlans, residualWith } = await this.buildFind(args, params);
         const { rows, native } = await this.exec(powql, params, args.timeout, action);
-        return { rows, native, resolvedWhere };
+        return { rows, native, resolvedWhere, nestedPlans, residualWith };
     }
     /**
      * Diagnostic surface: compile the same PowQL {@link findMany} would run for
@@ -961,23 +1008,27 @@ export class PowqlInterface {
     }
     async findUnique(args) {
         return this.withMiddleware('findUnique', args, async () => {
-            const { rows, native } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
+            const { rows, native, nestedPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
             if (!rows.length)
                 return null;
             const entities = this.shape(rows, native);
-            if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
+            if (nestedPlans.length)
+                this.attachNestedRows(entities, nestedPlans);
+            if (residualWith)
+                await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
     async findFirst(args = {}) {
         return this.withMiddleware('findFirst', args, async () => {
-            const { rows, native } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
+            const { rows, native, nestedPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
             if (!rows.length)
                 return null;
             const entities = this.shape(rows, native);
-            if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
+            if (nestedPlans.length)
+                this.attachNestedRows(entities, nestedPlans);
+            if (residualWith)
+                await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
@@ -1467,6 +1518,160 @@ export class PowqlInterface {
         return String(v);
     }
     // -------------------------------------------------------------------------
+    // Nested relations: nested projections / shaped results (PowDB >= 0.18)
+    // -------------------------------------------------------------------------
+    /**
+     * Should this query's `with` compile to nested-projection blocks? Requires
+     * the engine capability (>= 0.18), and an EXPLICIT `relationLoadStrategy:
+     * 'batched'` (per-query or client-level) opts back out to the keyed loaders.
+     * The default and `'join'` both prefer nesting: unlike the F2 INNER join it
+     * has no fan-out, keeps childless parents, works under parent paging, and
+     * applies per-parent `order`/`limit`/`offset` natively, so it is the
+     * strictly-better single-statement path wherever it is eligible. Ineligible
+     * relations fall through to the existing strategy resolution untouched.
+     */
+    nestedProjectionsPreferred(args) {
+        if (!this.capabilities.nestedProjections)
+            return false;
+        const explicit = args.relationLoadStrategy ?? this.options.relationLoadStrategy;
+        return explicit !== 'batched';
+    }
+    /**
+     * Plan one `with` relation as a nested-projection block, or return `null`
+     * when the shape must stay on the loaders (ALWAYS a silent fallback with
+     * identical output, never an error):
+     *   - m2m (the block takes exactly one child table; the junction-order
+     *     stitch has no nested equivalent), and composite relation keys;
+     *   - a to-one relation carrying `limit`/`offset` (the loaders' semantics);
+     *   - `distinct` inside the relation options (no nested grammar for it);
+     *   - a projected child column whose tsType is `bigint` or `Uint8Array`
+     *     (values ride a JSON array, which cannot carry them losslessly);
+     *   - a projection key collision (a child column named like a sub-relation);
+     *   - depth >= 10 (the loader path enforces the same cap by throwing, so the
+     *     fallback surfaces the identical E003 today's users get);
+     *   - any ineligible descendant (the WHOLE relation falls back, so one
+     *     statement never mixes nested and loader semantics mid-subtree).
+     */
+    planNestedRelation(relName, rel, opt, includePii, depth = 0) {
+        if (depth >= 10)
+            return null;
+        if (rel.type === 'manyToMany')
+            return null;
+        if (normalizeKeyColumns(rel.foreignKey).length > 1 || normalizeKeyColumns(rel.referenceKey).length > 1) {
+            return null;
+        }
+        if (!this.schema.tables[rel.to])
+            return null; // the loader raises its own error
+        const options = (opt === true ? {} : opt);
+        if (options.distinct?.length)
+            return null;
+        const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+        if (single && (options.limit !== undefined || options.offset))
+            return null;
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const cols = targetQi.projectedColumns(options.select, options.omit, includePii);
+        const byName = new Map(targetQi.meta.columns.map((c) => [c.name, c]));
+        for (const c of cols) {
+            const ts = (byName.get(c)?.tsType ?? '').replace(/\s*\|\s*null$/i, '').trim();
+            if (ts === 'bigint' || ts === 'Uint8Array')
+                return null;
+        }
+        const children = [];
+        if (options.with) {
+            for (const [subName, subOpt] of Object.entries(options.with)) {
+                if (!subOpt)
+                    continue;
+                const subRel = targetQi.meta.relations[subName];
+                if (!subRel)
+                    return null; // let the loader raise its unknown-relation error
+                const child = targetQi.planNestedRelation(subName, subRel, subOpt, includePii, depth + 1);
+                if (!child)
+                    return null;
+                children.push(child);
+            }
+        }
+        // The block's object keys are the projected snake column names plus the
+        // sub-relation field names; a duplicate key would mis-shape the JSON.
+        const keys = new Set(cols);
+        for (const child of children) {
+            if (keys.has(child.relName))
+                return null;
+            keys.add(child.relName);
+        }
+        return { relName, rel, options, targetQi, single, cols, children };
+    }
+    /**
+     * Compile one {@link NestedRelationPlan} into its projection-field block:
+     * `name: Target as tN filter <correlation> [and (<child where>)] [order …]
+     * [limit …] [offset …] { col: tN.col, …, <sub-blocks> }`. Params bind in
+     * emission order (the projection is the statement's final clause, so nested
+     * params always follow the parent's filter/order/limit/offset params).
+     * Aliases share the parent statement's counter, so arbitrarily deep and
+     * self-referential trees stay collision-free (the same discipline as the SQL
+     * engine's json_agg subqueries).
+     */
+    async buildNestedBlock(plan, parentAlias, aliasCtr, params, timeout) {
+        const { rel, relName, targetQi, options, single } = plan;
+        const alias = `t${aliasCtr.n++}`;
+        const fk = normalizeKeyColumns(rel.foreignKey)[0];
+        const rk = normalizeKeyColumns(rel.referenceKey)[0];
+        const parentKeyCol = rel.type === 'belongsTo' ? fk : rk;
+        const childKeyCol = rel.type === 'belongsTo' ? rk : fk;
+        // Exactly one equi-correlation predicate (the 0.18 correlation rule); the
+        // child where chains behind it as a parenthesized `and` group, which the
+        // grammar accepts even when the group itself contains `or`.
+        const correlation = `${alias}.${quotePowqlIdent(childKeyCol)} = ${parentAlias}.${quotePowqlIdent(parentKeyCol)}`;
+        const resolved = await targetQi.resolveRelationFilters(options.where, timeout);
+        const childWhere = targetQi.buildWhere(resolved, params, alias);
+        const filter = childWhere ? `${correlation} and (${childWhere})` : correlation;
+        const order = targetQi.buildOrder(options.orderBy, params, alias);
+        const limitClause = single
+            ? ' limit 1'
+            : options.limit !== undefined
+                ? ` limit ${this.param(options.limit, params)}`
+                : '';
+        const offsetClause = !single && options.offset ? ` offset ${this.param(options.offset, params)}` : '';
+        const parts = plan.cols.map((c) => `${quotePowqlIdent(c)}: ${alias}.${quotePowqlIdent(c)}`);
+        for (const child of plan.children) {
+            parts.push(await targetQi.buildNestedBlock(child, alias, aliasCtr, params, timeout));
+        }
+        return (`${quotePowqlIdent(relName)}: ${targetQi.qt} as ${alias} ` +
+            `filter ${filter}${order}${limitClause}${offsetClause} { ${parts.join(', ')} }`);
+    }
+    /**
+     * Shape the nested JSON children back into typed entities on every parent
+     * row. The nested field arrives as a decoded JSON array on the native wire
+     * (or JSON text on the legacy wire — parsed here); its values are real JSON
+     * types, so each child object goes through the NATIVE coercion policy
+     * (`rowToEntity(…, true)`: a date column's micros number becomes a `Date`, a
+     * json column's document passes through, a str `"null"` stays a string).
+     * to-one relations unwrap to `[0] ?? null`, matching the loaders exactly.
+     */
+    attachNestedRows(entities, plans) {
+        for (const entity of entities) {
+            for (const plan of plans)
+                this.attachOneNested(entity, plan);
+        }
+    }
+    attachOneNested(row, plan) {
+        let value = row[plan.relName];
+        if (typeof value === 'string') {
+            try {
+                value = JSON.parse(value);
+            }
+            catch {
+                value = [];
+            }
+        }
+        const items = Array.isArray(value) ? value : [];
+        const shaped = items.map((o) => rowToEntity(o, plan.targetQi.meta, true));
+        for (const child of shaped) {
+            for (const sub of plan.children)
+                plan.targetQi.attachOneNested(child, sub);
+        }
+        row[plan.relName] = plan.single ? (shaped[0] ?? null) : shaped;
+    }
+    // -------------------------------------------------------------------------
     // Writes (reselect — PowDB has no RETURNING)
     // -------------------------------------------------------------------------
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.38.1",
+  "version": "0.39.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {
@@ -103,8 +103,8 @@
     "@size-limit/esbuild": "^12.1.0",
     "@size-limit/file": "^12.1.0",
     "@types/node": "^26.1.0",
-    "@zvndev/powdb-client": "^0.16.0",
-    "@zvndev/powdb-embedded": "^0.16.0",
+    "@zvndev/powdb-client": "^0.17.0",
+    "@zvndev/powdb-embedded": "^0.17.0",
     "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",