turbine-orm 0.34.0 → 0.36.0

package/dist/powql.js

@@ -35,7 +35,7 @@
  * @module
  */
 import { randomUUID } from 'node:crypto';
-import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
+import { NotFoundError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb.js';
 import { isJsonFilter, isRelationPickOrderBy } from './query/filters.js';
@@ -62,6 +62,23 @@ const POWQL_READ_ACTIONS = new Set([
     'count',
     'aggregate',
     'groupBy',
+    'explain',
+]);
+/**
+ * Mutating actions the {@link PowqlInterface} readonly guard refuses locally
+ * (before the wire) on a read-only pool. A transaction-control `begin` is
+ * guarded separately in {@link PowqlInterface.runInImplicitTx}. Kept keyed on
+ * the per-call action string (never `this`-state) so a concurrent read can
+ * never be mistaken for one of these.
+ */
+const POWQL_WRITE_ACTIONS = new Set([
+    'create',
+    'createMany',
+    'update',
+    'updateMany',
+    'delete',
+    'deleteMany',
+    'upsert',
 ]);
 /** Operator keys recognised inside a `WhereOperator` object. */
 const OPERATOR_KEYS = new Set([
@@ -145,9 +162,19 @@ export class PowqlInterface {
         }
         return col;
     }
-    /** PowQL column reference (`.snake_name`) for a field. */
-    ref(field) {
-        return `.${this.column(field).name}`;
+    /**
+     * PowQL column reference for a field. Unqualified it is a dotted field
+     * reference (`.snake_name`), which bypasses keyword lookup. When an `alias`
+     * is supplied (the F2 join path) it is qualified (`alias.snake_name`) and the
+     * column name is backtick-quoted if it is a reserved word (a qualified
+     * `p.order` does NOT bypass keyword lookup, unlike the dotted `.order`).
+     */
+    ref(field, alias) {
+        return this.colRefName(this.column(field).name, alias);
+    }
+    /** Render a raw column name as a PowQL reference, qualified with `alias` when given. */
+    colRefName(name, alias) {
+        return alias ? `${alias}.${quotePowqlIdent(name)}` : `.${name}`;
     }
     /**
      * Push a value into the param array and return its `$N` placeholder. When the
@@ -216,8 +243,15 @@ export class PowqlInterface {
     /**
      * Compile a {@link WhereClause} into a PowQL filter expression, pushing every
      * value as a positional `$N` param. Returns `''` when there are no conditions.
+     *
+     * When `alias` is supplied (the F2 native-join path) every field reference is
+     * qualified with it (`.col` → `alias.col`, JSON path bases too); params bind
+     * exactly as in the unqualified path. The caller only ever passes an alias for
+     * an already-RESOLVED where (relation filters pre-resolved to literal in-lists
+     * by {@link resolveRelationFilters}): the relation-key branch below still
+     * throws, so an unresolved relation filter can never leak into a join.
      */
-    buildWhere(where, params) {
+    buildWhere(where, params, alias) {
         if (!where)
             return '';
         const parts = [];
@@ -225,17 +259,17 @@ export class PowqlInterface {
             if (value === undefined)
                 continue;
             if (key === 'AND') {
-                const sub = value.map((w) => this.buildWhere(w, params)).filter(Boolean);
+                const sub = value.map((w) => this.buildWhere(w, params, alias)).filter(Boolean);
                 if (sub.length)
                     parts.push(`(${sub.join(' and ')})`);
             }
             else if (key === 'OR') {
-                const sub = value.map((w) => this.buildWhere(w, params)).filter(Boolean);
+                const sub = value.map((w) => this.buildWhere(w, params, alias)).filter(Boolean);
                 if (sub.length)
                     parts.push(`(${sub.join(' or ')})`);
             }
             else if (key === 'NOT') {
-                const sub = this.buildWhere(value, params);
+                const sub = this.buildWhere(value, params, alias);
                 if (sub)
                     parts.push(`not (${sub})`);
             }
@@ -248,7 +282,7 @@ export class PowqlInterface {
             else {
                 // 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);
+                const cond = this.buildFieldCondition(key, value, params, alias);
                 if (cond)
                     parts.push(cond);
             }
@@ -256,9 +290,9 @@ export class PowqlInterface {
         return parts.join(' and ');
     }
     /** Build a single `field: value | operator` condition. */
-    buildFieldCondition(field, value, params) {
+    buildFieldCondition(field, value, params, alias) {
         const colMeta = this.column(field);
-        const ref = this.ref(field);
+        const ref = this.ref(field, alias);
         if (value === null)
             return `${ref} is null`;
         if (value instanceof Date || typeof value !== 'object') {
@@ -271,7 +305,7 @@ export class PowqlInterface {
         // 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);
+            return this.buildJsonPathCondition(colMeta, value, params, alias);
         }
         rejectUnsupportedFilter(op, field);
         if (!Object.keys(op).some((k) => OPERATOR_KEYS.has(k))) {
@@ -341,8 +375,8 @@ export class PowqlInterface {
      * (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}`;
+    jsonPathExpr(col, path, params, alias) {
+        let expr = this.colRefName(col.name, alias);
         for (const seg of path) {
             const bound = typeof seg === 'string' && /^\d+$/.test(seg) ? Number(seg) : seg;
             expr += `->${this.param(bound, params)}`;
@@ -368,13 +402,13 @@ export class PowqlInterface {
      * with SQL), so a mutation whose only `where` is a bare `{ path }` is refused
      * by the empty-where guard.
      */
-    buildJsonPathCondition(col, filter, params) {
+    buildJsonPathCondition(col, filter, params, alias) {
         const conds = [];
         // Bind the path segments at most once and reuse the expression string across
         // equals + range comparisons (they share the same `path`).
         let pathExpr = null;
         const pathP = () => {
-            pathExpr ??= this.jsonPathExpr(col, filter.path, params);
+            pathExpr ??= this.jsonPathExpr(col, filter.path, params, alias);
             return pathExpr;
         };
         if (filter.contains !== undefined) {
@@ -388,7 +422,7 @@ export class PowqlInterface {
         }
         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`);
+            conds.push(`json_type(${this.colRefName(col.name, alias)}->${this.param(filter.hasKey, params)}) is not null`);
         }
         // Range comparisons on the extracted path, in the fixed gt/gte/lt/lte order.
         // Same validation as SQL `jsonRangeEntries`: `path` required, value a finite
@@ -583,10 +617,17 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     // Projection / order
     // -------------------------------------------------------------------------
-    /** Resolve the set of columns to project, honouring `select` / `omit`. */
-    projectedColumns(select, omit) {
+    /**
+     * Resolve the set of columns to project, honouring `select` / `omit` and the
+     * query-level `includePii` opt-in. PII-tagged (`defineSchema` `pii: true`)
+     * columns are EXCLUDED from a default (or omit-only) projection unless
+     * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
+     * and returns it regardless. Untagged tables project exactly as before.
+     */
+    projectedColumns(select, omit, includePii) {
         let cols = this.meta.columns.map((c) => c.name);
-        if (select && Object.keys(select).length) {
+        const hasSelect = select && Object.keys(select).length;
+        if (hasSelect) {
             const picked = new Set(Object.entries(select)
                 .filter(([, v]) => v)
                 .map(([k]) => this.column(k).name));
@@ -595,6 +636,14 @@ export class PowqlInterface {
                 picked.add(pk);
             cols = cols.filter((c) => picked.has(c));
         }
+        else if (!includePii) {
+            // Default / omit-only projection: drop PII columns (kept above only when a
+            // caller names them in `select`). PK is never PII in practice; if one is
+            // tagged it is still dropped here, so tag sensitive data, not keys.
+            const pii = this.piiColumnNames();
+            if (pii.size)
+                cols = cols.filter((c) => !pii.has(c));
+        }
         if (omit && Object.keys(omit).length) {
             const dropped = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
@@ -603,6 +652,47 @@ export class PowqlInterface {
         }
         return cols;
     }
+    /**
+     * The snake_case names of this table's PII-tagged columns. Empty for a table
+     * with no `pii: true` column, so untagged tables keep their prior projection.
+     */
+    piiColumnNames() {
+        const out = new Set();
+        for (const col of this.meta.columns) {
+            if (col.pii)
+                out.add(col.name);
+        }
+        return out;
+    }
+    /**
+     * The camelCase field names of this table's PII-tagged columns: the read
+     * policy applied to a write's returned row (create/update/upsert/delete accept
+     * no `includePii`/`select`, so their result always drops PII; you may still
+     * write PII fields freely).
+     *
+     * SPEC LIMITATION (PowQL): the driver contract
+     * (`docs/integrations/powql-for-drivers.md`) exposes `returning` only as a
+     * bare keyword that hands back every column; it accepts NO column list, so
+     * (unlike the SQL engines, which emit an explicit non-PII `RETURNING`/`OUTPUT`
+     * projection) the create/update/delete `returning` paths cannot exclude PII at
+     * the query-language level and must strip it here after the fact. This is the
+     * client-side strip of last resort, not defense-in-depth, for those paths; we
+     * do NOT reverse-engineer an undocumented projection form. The upsert path is
+     * different: it has no `returning` and reselects by PK through the read
+     * projection ({@link projectedColumns}), which already omits PII, so PII never
+     * crosses the wire there. If a future spec revision lets `returning` take a
+     * projection, switch the write paths to emit the non-PII list and this strip
+     * becomes a no-op like {@link parseWriteRow} on the SQL engines.
+     */
+    stripWritePii(entity) {
+        if (!entity)
+            return entity;
+        for (const col of this.meta.columns) {
+            if (col.pii)
+                delete entity[col.field];
+        }
+        return entity;
+    }
     /** `{ .c1, .c2, … }` projection clause. */
     projection(cols) {
         return `{ ${cols.map((c) => `.${c}`).join(', ')} }`;
@@ -620,7 +710,7 @@ export class PowqlInterface {
      * contract): for identical cross-engine results pass `nulls: 'last'`
      * explicitly on Postgres, which defaults nulls-first for `desc`.
      */
-    buildOrder(orderBy, params) {
+    buildOrder(orderBy, params, alias) {
         if (!orderBy)
             return '';
         const keys = Object.entries(orderBy).filter(([, dir]) => dir !== undefined);
@@ -631,7 +721,7 @@ export class PowqlInterface {
                 const o = dir;
                 // JSON-path ordering on a json column.
                 if (Array.isArray(o.path)) {
-                    return this.buildJsonPathOrder(field, dir, params);
+                    return this.buildJsonPathOrder(field, dir, params, alias);
                 }
                 // OrderBySpec { sort, nulls }: accept nulls-last (PowDB default), refuse
                 // nulls-first (no placement grammar). Distinct from vector/pick/_count.
@@ -640,7 +730,7 @@ export class PowqlInterface {
                     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'}`;
+                    return `${this.ref(field, alias)} ${spec.sort === 'desc' ? 'desc' : 'asc'}`;
                 }
                 // Name the actual feature in the refusal — a pick-row ordering
                 // reported as "vector / distance ordering" sends users hunting for
@@ -656,12 +746,12 @@ export class PowqlInterface {
                                 : 'object-valued ordering';
                 throw new UnsupportedFeatureError(feature, 'PowDB', `field "${field}"`);
             }
-            return `${this.ref(field)} ${dir === 'desc' ? 'desc' : 'asc'}`;
+            return `${this.ref(field, alias)} ${dir === 'desc' ? 'desc' : 'asc'}`;
         });
         return ` order ${parts.join(', ')}`;
     }
     /** Compile one {@link JsonPathOrderBy} entry to `order .col->$n asc` (+ optional numeric cast). */
-    buildJsonPathOrder(field, spec, params) {
+    buildJsonPathOrder(field, spec, params, alias) {
         const col = this.column(field);
         if (!isJsonColumn(col)) {
             throw new UnsupportedFeatureError('JSON-path ordering', 'PowDB', `field "${field}" is not a json column`);
@@ -670,7 +760,7 @@ export class PowqlInterface {
         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);
+        const pathExpr = this.jsonPathExpr(col, spec.path, params, alias);
         // `type: 'numeric'` casts a JSON STRING number for numeric ordering; native
         // JSON numbers already order numerically without a cast.
         const expr = spec.type === 'numeric' ? `cast(${pathExpr}, "float")` : pathExpr;
@@ -690,6 +780,13 @@ export class PowqlInterface {
     async exec(powql, params, timeout, action = 'raw') {
         return this.execOnce(powql, params, timeout, action, false);
     }
+    /** Build the E018 refusal for a write / `begin` on a read-only pool. */
+    readOnlyError(operation) {
+        // Pass a clean detail: the ReadOnlyError constructor owns both the
+        // `[turbine] ` prefix and the "Route writes to a writable primary." hint,
+        // so adding either here would double them.
+        return new ReadOnlyError(`${operation} on "${this.table}" refused: this PowDB connection is read-only.`);
+    }
     /**
      * Execute one statement, with the opt-in single stale-frame READ replay. When
      * `retryStaleReads` is on and a first-statement READ fails with the stale-wire
@@ -704,6 +801,14 @@ export class PowqlInterface {
      * write into a retryable read.
      */
     async execOnce(powql, params, timeout, action, isRetry) {
+        // Read-only pool guard: refuse a write action locally, before the wire, so a
+        // read-only target never even attempts the mutation (the engine refusal, if
+        // any, is only the backstop for raw/injected paths). `action` is per-call,
+        // so a concurrent read is never mistaken for a write. Reads (incl. explain)
+        // and non-classified `raw` fall through unchanged.
+        if (this.pool.readonly === true && POWQL_WRITE_ACTIONS.has(action)) {
+            throw this.readOnlyError(action);
+        }
         const start = performance.now();
         const run = this.pool.query(powql, params);
         try {
@@ -789,22 +894,27 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
         return this.withMiddleware('findMany', args, async () => {
-            const { rows, native } = await this.runFind(args, 'findMany');
+            const { rows, native, resolvedWhere } = await this.runFind(args, 'findMany');
             const entities = this.shape(rows, native);
-            if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout);
+            if (args.with) {
+                await this.loadRelations(entities, args.with, args.timeout, 0, { args, resolvedWhere }, args.includePii === true);
+            }
             return entities;
         });
     }
-    /** Build + run the flat findMany select; returns raw rows + the serving wire. */
-    async runFind(args, action = 'findMany') {
+    /**
+     * Compile the flat findMany select into PowQL (no execution), pushing values
+     * into `params`. Returns the query plus the RESOLVED where (relation filters
+     * already collapsed to literal in-lists) so the F2 join path can re-emit the
+     * exact parent predicate alias-qualified, and so {@link explain} can wrap it.
+     */
+    async buildFind(args, params) {
         if (args.cursor) {
             throw new UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
         }
-        const params = [];
         const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
         const where = this.buildWhere(resolvedWhere, params);
-        const cols = this.projectedColumns(args.select, args.omit);
+        const cols = this.projectedColumns(args.select, args.omit, args.includePii === true);
         const distinct = args.distinct?.length ? ' distinct' : '';
         const filter = where ? ` filter ${where}` : '';
         const order = this.buildOrder(args.orderBy, params);
@@ -816,8 +926,38 @@ 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 };
+    }
+    /** Build + run the flat findMany select; returns raw rows, the serving wire, and the resolved where. */
+    async runFind(args, action = 'findMany') {
+        const params = [];
+        const { powql, resolvedWhere } = await this.buildFind(args, params);
         const { rows, native } = await this.exec(powql, params, args.timeout, action);
-        return { rows, native };
+        return { rows, native, resolvedWhere };
+    }
+    /**
+     * Diagnostic surface: compile the same PowQL {@link findMany} would run for
+     * `args` (no cache) and return the engine's plan as one string per line.
+     *
+     * Runs as a READ (`explain <query>`), so it is safe on a read-only pool and
+     * eligible for the stale-read replay. The line content is engine-owned and is
+     * NOT covered by semver (match plan node names / tree shape, never exact
+     * bytes; mirrors PowDB's own `explain` contract).
+     *
+     * Does NOT run through the middleware chain: plan text is a diagnostic, not
+     * entity rows, and `QueryInterface.explain` deliberately bypasses middleware
+     * too, so both engines agree.
+     */
+    async explain(args = {}) {
+        const params = [];
+        const { powql } = await this.buildFind(args, params);
+        const { rows } = await this.exec(`explain ${powql}`, params, args.timeout, 'explain');
+        return rows
+            .map((r) => {
+            const line = r.plan ?? Object.values(r)[0];
+            return line == null ? '' : String(line);
+        })
+            .filter((line) => line.length > 0);
     }
     async findUnique(args) {
         return this.withMiddleware('findUnique', args, async () => {
@@ -826,7 +966,7 @@ export class PowqlInterface {
                 return null;
             const entities = this.shape(rows, native);
             if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout);
+                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
@@ -837,7 +977,7 @@ export class PowqlInterface {
                 return null;
             const entities = this.shape(rows, native);
             if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout);
+                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
@@ -856,21 +996,50 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     // Nested relations — batched N+1 loaders (hasMany / hasOne / belongsTo)
     // -------------------------------------------------------------------------
-    /** Load each requested relation for `parents` and attach it onto each row. */
-    async loadRelations(parents, withClause, timeout, depth = 0) {
+    /**
+     * Load each requested relation for `parents` and attach it onto each row.
+     *
+     * `parent` is supplied ONLY by the top-level {@link findMany} (its args +
+     * resolved where). When the effective `relationLoadStrategy` resolves to an
+     * explicit `'join'` and the pool advertises `serverJoins`, an eligible
+     * top-level relation is loaded with a native PowQL join instead of the keyed
+     * loaders (F2); everything else (nested `with` levels, ineligible shapes, and
+     * the default `'batched'` strategy) keeps the loaders. Output is byte-equal
+     * either way (the join reuses the same stitch / shape helpers).
+     */
+    async loadRelations(parents, withClause, timeout, depth = 0, parent, includePii = false) {
         if (depth >= 10) {
             throw new ValidationError(`[turbine] Nested 'with' on PowDB exceeded depth 10 (relation cycle?).`);
         }
         if (!parents.length)
             return;
+        // The resolved strategy is 'join' only for an EXPLICIT 'join' (per-query arg
+        // or a client config the user set). The serverJoins capability is consulted
+        // PER RELATION below, AFTER joinEligible, so a relation that would have
+        // fallen back to the loaders anyway (paged parent, nested `with`, composite
+        // key, …) never triggers the capability's E017.
+        const strategyIsJoin = parent ? this.resolveStrategy(parent.args) === 'join' : false;
         for (const [relName, opt] of Object.entries(withClause)) {
             if (!opt)
                 continue;
             const rel = this.meta.relations[relName];
             if (!rel)
                 throw new ValidationError(`[turbine] Unknown relation "${relName}" on "${this.table}".`);
+            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args, parents.length)) {
+                if (this.capabilities.serverJoins) {
+                    await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
+                    continue;
+                }
+                // An otherwise-eligible relation the engine cannot join: a PER-QUERY
+                // `relationLoadStrategy: 'join'` is an explicit request, so throw a typed
+                // E017; a CLIENT-LEVEL default silently falls back to the keyed loaders
+                // (so pointing an existing app at an older engine keeps working).
+                if (parent.args.relationLoadStrategy === 'join') {
+                    requireCapability(this.capabilities, 'serverJoins', 'native PowQL relation joins');
+                }
+            }
             if (rel.type === 'manyToMany') {
-                await this.loadManyToMany(parents, rel, relName, opt, timeout);
+                await this.loadManyToMany(parents, rel, relName, opt, timeout, includePii);
                 continue;
             }
             const fk = normalizeKeyColumns(rel.foreignKey);
@@ -889,23 +1058,50 @@ export class PowqlInterface {
             const keys = [
                 ...new Set(parents.map((p) => p[parentKeyField]).filter((k) => k != null)),
             ];
-            const childByKey = new Map();
+            // The loader buckets children by their correlation column, so that column
+            // MUST be in the fetched projection even when the user's select/omit drops
+            // it. Force it into the fetch here and strip it back off the entities after
+            // stitching (the join path already gets this for free via `__tpk`).
+            const userSelect = options.select;
+            const userOmit = options.omit;
+            const fkProjected = userSelect ? Boolean(userSelect[childKeyField]) : userOmit ? !userOmit[childKeyField] : true;
+            let fetchOptions = options;
+            if (!fkProjected) {
+                if (userSelect) {
+                    fetchOptions = {
+                        ...options,
+                        select: { ...userSelect, [childKeyField]: true },
+                    };
+                }
+                else if (userOmit) {
+                    const omitWithoutFk = { ...userOmit };
+                    delete omitWithoutFk[childKeyField];
+                    fetchOptions = { ...options, omit: omitWithoutFk };
+                }
+            }
             // Chunk the key set so a single `in (…)` never exceeds PowDB's
-            // per-statement param / row limits; merge each chunk's children.
+            // per-statement param / row limits; merge each chunk's children. Keys are
+            // normalized through joinKey (a Date maps to micros, matching the child
+            // cell) so a datetime correlation column stitches instead of silently
+            // returning [].
+            const childByKey = new Map();
             for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS) {
                 const chunk = keys.slice(i, i + MAX_RELATION_KEYS);
                 const childWhere = {
-                    ...options.where,
+                    ...fetchOptions.where,
                     [childKeyField]: { in: chunk },
                 };
                 const children = (await targetQi.findMany({
-                    ...options,
+                    ...fetchOptions,
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
+                    includePii,
                 }));
                 for (const child of children) {
-                    const k = child[childKeyField];
+                    const k = this.joinKey(child[childKeyField]);
+                    if (k == null)
+                        continue;
                     const bucket = childByKey.get(k);
                     if (bucket)
                         bucket.push(child);
@@ -913,10 +1109,18 @@ export class PowqlInterface {
                         childByKey.set(k, [child]);
                 }
             }
+            // Strip the forced correlation column back off if the user excluded it,
+            // so the emitted entities match their select/omit exactly.
+            if (!fkProjected) {
+                for (const bucket of childByKey.values()) {
+                    for (const child of bucket)
+                        delete child[childKeyField];
+                }
+            }
             const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
             for (const parent of parents) {
-                const k = parent[parentKeyField];
-                const matches = childByKey.get(k) ?? [];
+                const k = this.joinKey(parent[parentKeyField]);
+                const matches = (k == null ? undefined : childByKey.get(k)) ?? [];
                 parent[relName] = single ? (matches[0] ?? null) : matches;
             }
         }
@@ -929,7 +1133,7 @@ export class PowqlInterface {
      * single-key N+1 loaders; the junction's source/target columns must be single
      * (composite junction keys would need PowQL tuple-`in`, which it lacks).
      */
-    async loadManyToMany(parents, rel, relName, opt, timeout) {
+    async loadManyToMany(parents, rel, relName, opt, timeout, includePii = false) {
         const through = rel.through;
         if (!through)
             throw new ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
@@ -993,6 +1197,7 @@ export class PowqlInterface {
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
+                includePii,
             }));
             for (const t of targets)
                 targetByPk.set(String(t[targetPkField]), t);
@@ -1011,6 +1216,257 @@ export class PowqlInterface {
         }
     }
     // -------------------------------------------------------------------------
+    // Nested relations: native PowQL joins (F2, opt-in via relationLoadStrategy)
+    // -------------------------------------------------------------------------
+    /**
+     * Resolve the effective relation-load strategy: the per-query arg wins, then
+     * the client config, then the PowDB default of `'batched'` (the keyed
+     * loaders). PowDB deliberately does NOT inherit the SQL-side implicit `'join'`
+     * default (that would silently flip every existing PowDB user onto brand-new
+     * join generation). Only a value the user actually set to `'join'` activates it.
+     */
+    resolveStrategy(args) {
+        const s = args.relationLoadStrategy ?? this.options.relationLoadStrategy ?? 'batched';
+        return s === 'join' ? 'join' : 'batched';
+    }
+    /**
+     * Per-relation eligibility for the join path (checked before the serverJoins
+     * capability). Any `false` here is a SILENT fallback to the keyed loaders (it
+     * is never an error), so an off-page or nested-`with` shape still returns
+     * correct rows:
+     *   - the parent query must not be paged (`limit`/`offset`/`take`, including the
+     *     configured `defaultLimit`): a parent-filter join under a page would scan
+     *     children of off-page parents, where the loaders are strictly better;
+     *   - the relation must not request a nested `with` (its subtree stays on the
+     *     loaders this round) or a `distinct`;
+     *   - single-column relation keys only (a composite key falls to the loader,
+     *     which throws the same E017 as today);
+     *   - the PARENT-SIDE correlation column must be a single-column PK or unique
+     *     column, or the INNER join would re-emit one child copy per matching
+     *     parent row (a non-unique correlation key produces duplicate children the
+     *     loader never would). For hasMany/hasOne/m2m that column is the relation's
+     *     `referenceKey` on THIS (fetched) table; for belongsTo it is the
+     *     `referenceKey` on the TARGET table (the join's non-fetched side);
+     *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
+     *     stitch can't be reproduced by the 3-table join deterministically);
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
+     *     does a to-many relation `limit`/`offset` when the parent set spills past
+     *     one loader chunk (the loader limits per chunk, the join once globally).
+     */
+    joinEligible(rel, opt, args, parentCount) {
+        const effLimit = args.limit ?? args.take ?? this.defaultLimit;
+        if (effLimit !== undefined || args.offset)
+            return false;
+        const options = (opt === true ? {} : opt);
+        if (options.with)
+            return false;
+        if (options.distinct?.length)
+            return false;
+        if (rel.type === 'manyToMany') {
+            const through = rel.through;
+            if (!through)
+                return false;
+            if (normalizeKeyColumns(through.sourceKey).length > 1 ||
+                normalizeKeyColumns(through.targetKey).length > 1 ||
+                normalizeKeyColumns(rel.referenceKey).length > 1 ||
+                (this.schema.tables[rel.to]?.primaryKey.length ?? 2) > 1) {
+                return false;
+            }
+            if (options.orderBy || options.limit !== undefined || options.offset)
+                return false;
+            // The parent joins on its referenceKey; a non-unique one duplicates.
+            if (!this.isSingleColumnUnique(this.meta, normalizeKeyColumns(rel.referenceKey)[0]))
+                return false;
+            return true;
+        }
+        if (normalizeKeyColumns(rel.foreignKey).length > 1 || normalizeKeyColumns(rel.referenceKey).length > 1) {
+            return false;
+        }
+        // Reject a non-unique correlation key: on belongsTo the fetched side joins on
+        // the target's referenceKey, otherwise the fetched side joins on its own.
+        if (rel.type === 'belongsTo') {
+            const targetMeta = this.schema.tables[rel.to];
+            if (!targetMeta || !this.isSingleColumnUnique(targetMeta, normalizeKeyColumns(rel.referenceKey)[0])) {
+                return false;
+            }
+        }
+        else if (!this.isSingleColumnUnique(this.meta, normalizeKeyColumns(rel.referenceKey)[0])) {
+            return false;
+        }
+        const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+        if ((options.limit !== undefined || options.offset) && (single || parentCount > MAX_RELATION_KEYS)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * True when `col` is a single-column unique key of `tableMeta`: the sole
+     * primary-key column, a single-column entry in `uniqueColumns` (where a
+     * per-column `unique: true` and an introspected single-column unique constraint
+     * both land), or a single-column unique index. Used by {@link joinEligible} to
+     * keep the INNER-join path off relations whose parent-side correlation column
+     * can repeat (which would duplicate children).
+     */
+    isSingleColumnUnique(tableMeta, col) {
+        if (tableMeta.primaryKey.length === 1 && tableMeta.primaryKey[0] === col)
+            return true;
+        if (tableMeta.uniqueColumns.some((cols) => cols.length === 1 && cols[0] === col))
+            return true;
+        return tableMeta.indexes.some((idx) => idx.unique && !idx.docPath && idx.columns.length === 1 && idx.columns[0] === col);
+    }
+    /** Dispatch one eligible relation to the correct native-join loader. */
+    async loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii = false) {
+        if (rel.type === 'manyToMany') {
+            await this.loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
+            return;
+        }
+        const options = (opt === true ? {} : opt);
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new ValidationError(`[turbine] Relation "${relName}" targets unknown table "${rel.to}".`);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const fk = normalizeKeyColumns(rel.foreignKey);
+        const rk = normalizeKeyColumns(rel.referenceKey);
+        // Correlation math is identical to the keyed loaders, only the transport
+        // (join vs in-list) changes. Always join the RELATION TARGET (alias `c`) to
+        // the already-fetched side (alias `p`), correlating on the fetched side's key
+        // and projecting `__tpk` from the fetched side's correlation column.
+        const parentKeyCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
+        const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
+        const parentKeyField = this.meta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
+        const params = [];
+        const childCols = this.joinChildCols(targetQi, options, includePii);
+        const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 'c', params, options.timeout ?? timeout);
+        const order = targetQi.buildOrder(options.orderBy, params, 'c');
+        const limitClause = options.limit !== undefined ? ` limit ${this.param(options.limit, params)}` : '';
+        const offsetClause = options.offset ? ` offset ${this.param(options.offset, params)}` : '';
+        const proj = this.joinProjection(childCols, `p.${quotePowqlIdent(parentKeyCol)}`, 'c');
+        const powql = `${targetQi.qt} as c join ${this.qt} as p ` +
+            `on c.${quotePowqlIdent(childKeyCol)} = p.${quotePowqlIdent(parentKeyCol)}` +
+            `${filter}${order}${limitClause}${offsetClause} ${proj}`;
+        // A READ: thread a read-shaped action through the exec seam.
+        const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
+        const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+        const byKey = this.bucketByTpk(targetQi, rows, native);
+        for (const p of parents) {
+            const key = this.joinKey(p[parentKeyField]);
+            const matches = (key == null ? undefined : byKey.get(key)) ?? [];
+            p[relName] = single ? (matches[0] ?? null) : matches;
+        }
+    }
+    /**
+     * manyToMany via chained joins: the target (alias `t`) → junction (alias `j`)
+     * → the already-fetched side (alias `p`), correlating `__tpk` from the
+     * junction's source key. Always a list, stitched exactly like the loader.
+     */
+    async loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout, includePii = false) {
+        const through = rel.through;
+        if (!through)
+            throw new ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
+        const options = (opt === true ? {} : opt);
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new ValidationError(`[turbine] Relation "${relName}" targets unknown table "${rel.to}".`);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const sourceJCol = normalizeKeyColumns(through.sourceKey)[0];
+        const targetJCol = normalizeKeyColumns(through.targetKey)[0];
+        const sourceRefCol = normalizeKeyColumns(rel.referenceKey)[0];
+        const targetPkCol = targetMeta.primaryKey[0];
+        const parentRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
+        const params = [];
+        const childCols = this.joinChildCols(targetQi, options, includePii);
+        const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 't', params, options.timeout ?? timeout);
+        const proj = this.joinProjection(childCols, `j.${quotePowqlIdent(sourceJCol)}`, 't');
+        const powql = `${targetQi.qt} as t ` +
+            `join ${quotePowqlIdent(through.table)} as j on t.${quotePowqlIdent(targetPkCol)} = j.${quotePowqlIdent(targetJCol)} ` +
+            `join ${this.qt} as p on j.${quotePowqlIdent(sourceJCol)} = p.${quotePowqlIdent(sourceRefCol)}` +
+            `${filter} ${proj}`;
+        const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
+        const byKey = this.bucketByTpk(targetQi, rows, native);
+        for (const p of parents) {
+            const key = this.joinKey(p[parentRefField]);
+            p[relName] = (key == null ? undefined : byKey.get(key)) ?? [];
+        }
+    }
+    /**
+     * The target column list to project through the join (honouring select/omit),
+     * with a loud guard: a real column named `__tpk` would collide with the
+     * reserved correlation alias, so refuse rather than silently mis-stitch.
+     */
+    joinChildCols(targetQi, options, includePii = false) {
+        const cols = targetQi.projectedColumns(options.select, options.omit, includePii);
+        if (cols.includes('__tpk')) {
+            throw new ValidationError(`[turbine] relation target "${targetQi.table}" has a column named "__tpk", which collides with the reserved ` +
+                `join correlation alias. Rename the column or load this relation with relationLoadStrategy: 'batched'.`);
+        }
+        return cols;
+    }
+    /**
+     * `{ __tpk: <tpkExpr>, <col>: <childAlias>.<col>, … }`. Each child column is
+     * ALIASED to its bare name (a bare qualified ref `c.col` would come back named
+     * `c.col`, not `col`) so the stitched rows shape identically to a flat select.
+     */
+    joinProjection(childCols, tpkExpr, childAlias) {
+        const parts = [
+            `__tpk: ${tpkExpr}`,
+            ...childCols.map((c) => `${quotePowqlIdent(c)}: ${childAlias}.${quotePowqlIdent(c)}`),
+        ];
+        return `{ ${parts.join(', ')} }`;
+    }
+    /**
+     * `filter <parentWhere qualified p> [and <relationWhere qualified childAlias>]`.
+     * The parent where is the ALREADY-RESOLVED predicate (relation filters collapsed
+     * to literal in-lists before the base query ran); the relation where is resolved
+     * on the target the same way before qualifying, so a nested relation filter in
+     * the relation `where` never reaches the join unresolved. Params bind in order.
+     */
+    async joinFilter(targetQi, parentResolvedWhere, relWhere, childAlias, params, timeout) {
+        const parts = [];
+        const pw = this.buildWhere(parentResolvedWhere, params, 'p');
+        if (pw)
+            parts.push(pw);
+        const relResolved = await targetQi.resolveRelationFilters(relWhere, timeout);
+        const rw = targetQi.buildWhere(relResolved, params, childAlias);
+        if (rw)
+            parts.push(rw);
+        return parts.length ? ` filter ${parts.join(' and ')}` : '';
+    }
+    /** Group join rows by their (normalized) `__tpk`, stripping it and shaping each child. */
+    bucketByTpk(targetQi, rows, native) {
+        const byKey = new Map();
+        for (const raw of rows) {
+            const tpk = this.joinKey(raw.__tpk);
+            delete raw.__tpk;
+            const child = targetQi.shape([raw], native)[0];
+            if (tpk == null)
+                continue;
+            const bucket = byKey.get(tpk);
+            if (bucket)
+                bucket.push(child);
+            else
+                byKey.set(tpk, [child]);
+        }
+        return byKey;
+    }
+    /**
+     * Normalize a correlation key to a stable string map key so a parent's key
+     * value (a shaped entity field) and a child row's `__tpk` cell match across
+     * wires and column types. A `Date` maps to microseconds
+     * (`getTime()` ms times 1000), because a datetime correlation cell arrives as
+     * raw micros (bigint on the native wire, a micros string on the legacy wire),
+     * never as ms. bigint / number / string all stringify to the same digits, so
+     * an int key matches whether it came back typed or as text.
+     */
+    joinKey(v) {
+        if (v == null)
+            return null;
+        if (v instanceof Date)
+            return (BigInt(v.getTime()) * 1000n).toString();
+        if (typeof v === 'bigint')
+            return v.toString();
+        return String(v);
+    }
+    // -------------------------------------------------------------------------
     // Writes (reselect — PowDB has no RETURNING)
     // -------------------------------------------------------------------------
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
@@ -1067,7 +1523,7 @@ export class PowqlInterface {
                 .join(', ');
             // `returning` surfaces the inserted row (all columns, schema order) in one round-trip.
             const { rows, native } = await this.exec(`insert ${this.qt} { ${body} } returning`, params, args.timeout, 'create');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: data });
             return row;
@@ -1085,7 +1541,7 @@ export class PowqlInterface {
             });
             // Multi-row insert with `returning` hands back every inserted row in one round-trip.
             const { rows, native } = await this.exec(`insert ${this.qt} ${tuples.join(', ')} returning`, params, args.timeout, 'createMany');
-            return this.shape(rows, native);
+            return this.shape(rows, native).map((r) => this.stripWritePii(r));
         });
     }
     async update(args) {
@@ -1100,7 +1556,7 @@ export class PowqlInterface {
             const setClause = this.buildUpdateAssignments(args.data, params);
             // `returning` hands back the post-update row(s); take the first (single-row contract).
             const { rows, native } = await this.exec(`${this.qt} filter ${where} update { ${setClause} } returning`, params, args.timeout, 'update');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
             return row;
@@ -1183,6 +1639,11 @@ export class PowqlInterface {
     }
     /** Open a flat PowDB transaction on a pinned connection and run `fn` inside it. */
     async runInImplicitTx(fn) {
+        // A transaction-control `begin` is a write on a read-only pool: refuse it
+        // locally before checking out a connection (zero wire / pool activity), the
+        // same guard the exec seam applies to plain writes.
+        if (this.pool.readonly === true)
+            throw this.readOnlyError('transaction (begin)');
         // Route tx keywords through the dialect (like the SQL path) so this never
         // drifts from `powdbDialect`; falls back to the literal lowercase keywords.
         const d = this.options.dialect;
@@ -1192,7 +1653,10 @@ export class PowqlInterface {
             await client.query(d?.beginStatement?.() ?? 'begin');
             began = true;
             const { TransactionClient } = await import('./client.js');
-            const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.options, 
+            // Pass the PowDB pool so its read-only guard + capabilities carry into
+            // the transaction-scoped proxy pool (see createTxPool).
+            this.pool);
             const ctx = { schema: this.schema, tx: tx };
             // Plant the single-writer re-entrancy marker for the implicit tx's
             // subtree (same seam TurbineClient.$transaction uses) — user code that
@@ -1238,7 +1702,7 @@ export class PowqlInterface {
             this.assertCompiledWhere(where, false, 'delete');
             // `returning` hands back the deleted row(s) — no separate pre-image reselect needed.
             const { rows, native } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout, 'delete');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
             return row;