turbine-orm 0.34.0 → 0.35.0

package/dist/powdb.js

@@ -55,7 +55,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { TurbineClient, } from './client.js';
 import { postgresDialect } from './dialect.js';
-import { ConnectionError, NotNullViolationError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
+import { ConnectionError, NotNullViolationError, ReadOnlyError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 /**
  * Capability descriptor for PowDB. PowQL generation is owned by
@@ -195,6 +195,7 @@ const POWDB_FEATURE_MIN_VERSION = {
     introspection: '0.10',
     jsonDocs: '0.12',
     docFieldIndexes: '0.13',
+    serverJoins: '0.13',
 };
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
@@ -209,6 +210,7 @@ export const ALL_POWDB_CAPABILITIES = {
     jsonDocs: true,
     docFieldIndexes: true,
     introspection: true,
+    serverJoins: true,
     nativeRaw: false,
 };
 /** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
@@ -236,6 +238,7 @@ export function capabilitiesFromVersion(version, opts = {}) {
             jsonDocs: false,
             docFieldIndexes: false,
             introspection: false,
+            serverJoins: false,
             nativeRaw: false,
         };
     }
@@ -244,6 +247,7 @@ export function capabilitiesFromVersion(version, opts = {}) {
         introspection: atLeastVersion(sem, 0, 10),
         jsonDocs: atLeastVersion(sem, 0, 12),
         docFieldIndexes: atLeastVersion(sem, 0, 13),
+        serverJoins: atLeastVersion(sem, 0, 13),
         nativeRaw: Boolean(opts.hasNativeRaw) && atLeastVersion(sem, 0, 13),
     };
 }
@@ -688,9 +692,10 @@ export function wrapPowdbError(err) {
         const m = /column ['"]?(\w+)['"]?/i.exec(msg);
         return new NotNullViolationError({ column: m?.[1], cause: err });
     }
-    // Driver pool lifecycle errors (acquire after close, acquire timeout) carry
-    // no .code — classify by message so both transports surface E004.
-    if (/pool closed|pool acquire timeout/i.test(msg)) {
+    // Driver pool lifecycle errors (acquire after close, acquire timeout, or a
+    // statement reaching an already-closed embedded handle) carry no .code:
+    // classify by message so both transports surface E004.
+    if (/pool closed|pool acquire timeout|database is closed/i.test(msg)) {
         return new ConnectionError(`[turbine] PowDB connection unavailable: ${msg}`, { cause: err });
     }
     // Server-side transaction-gate wait bound (PowDB ≥ 0.10, default 5s): another
@@ -712,6 +717,54 @@ export function wrapPowdbError(err) {
         /received unexpected frame|unknown message type|truncated payload|bad framing/i.test(msg)) {
         return new ConnectionError(`[turbine] PowDB connection is in an invalid state: ${msg}`, { cause: err });
     }
+    // Read-only refusal → ReadOnlyError (E018). Two engine shapes, both mapped by
+    // substring (the networked transport prefixes the message with `query failed:
+    // `, so never anchor on the start): an embedded database opened read-only for
+    // snapshot serving (`readonly mode: statement requires a writer …`), and a
+    // networked read-only role (`permission denied: role '<role>' cannot execute
+    // write statements`). These run BEFORE the generic validation regex below so a
+    // read-only write is surfaced as the routing signal E018, not a query defect.
+    // The driver spec (0.15) distinguishes them via `reason`: snapshot mode
+    // means "nothing can write here; route writes to the primary", RBAC means
+    // "this connection's role may not write here".
+    if (/readonly mode: statement requires a writer/i.test(msg)) {
+        return new ReadOnlyError(`PowDB refused a write on a read-only database: ${msg}.`, {
+            cause: err,
+            reason: 'snapshot',
+        });
+    }
+    if (/permission denied: role/i.test(msg)) {
+        return new ReadOnlyError(`PowDB refused a write for a read-only role: ${msg}.`, { cause: err, reason: 'rbac' });
+    }
+    // Open-time read-only failure: a read-only handle over a directory whose WAL
+    // still has uncommitted frames is refused (`cannot open read-only: the WAL is
+    // not empty …`). It is a connection failure (E004), not a query defect, the
+    // fix is to recover the directory with a writable open first.
+    if (/cannot open read-only: the WAL is not empty/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB could not open the directory read-only: ${msg}. Open it once with a writable handle to ` +
+            'flush the WAL (recover the directory), then reopen it read-only for snapshot serving.', { cause: err });
+    }
+    // Per-query deadline → TimeoutError (E002). Message-path so it fires on the
+    // embedded transport too (code is always 'GenericFailure' there); retryable.
+    // Pass the engine prose through the message override (same pattern as the
+    // transaction-gate timeout below) so the real "query timeout after <n>ms"
+    // survives instead of rendering the placeholder "timed out after 0ms".
+    if (/query timeout after/i.test(msg)) {
+        return new TimeoutError(0, 'PowDB query', { message: `[turbine] PowDB ${msg}`, cause: err });
+    }
+    // Client-initiated cancellation → ConnectionError (E004). This is FINAL: the
+    // issuing client disconnected, so the query was a clean early return, never
+    // auto-retry it (the opt-in stale-read retry only replays stale-FRAME reads).
+    if (/query cancelled by client disconnect/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB query cancelled by client disconnect: ${msg}`, { cause: err });
+    }
+    // Bounded join rejection → ValidationError (E003). The engine rejects a pure
+    // nested-loop join whose candidate-pair count (or result row count) exceeds
+    // the safety bound BEFORE executing, and names the fix in the message, keep
+    // that fix-hint intact so the caller knows how to make the join eligible.
+    if (/nested-loop join would evaluate|join result exceeds row limit/i.test(msg)) {
+        return new ValidationError(`[turbine] PowDB join rejected: ${msg}`);
+    }
     // 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
@@ -1052,12 +1105,20 @@ export class PowdbPool {
     capabilities;
     /** Opt-in first-statement-read replay on a stale wire frame (read by {@link PowqlInterface}). */
     retryStaleReads;
+    /**
+     * True when the caller marked this pool read-only (`readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own read-only-role refusal (mapped by
+     * {@link wrapPowdbError}) is the backstop for raw / injected paths.
+     */
+    readonly;
     constructor(pool, toParam = (v) => toPowdbParam(v), options = {}) {
         this.pool = pool;
         this.toParam = toParam;
         this.txGate = new PowdbTxGate(options.transactionQueueTimeoutMs ?? DEFAULT_TX_QUEUE_TIMEOUT_MS);
         this.capabilities = options.capabilities ?? ALL_POWDB_CAPABILITIES;
         this.retryStaleReads = options.retryStaleReads ?? false;
+        this.readonly = options.readonly ?? false;
     }
     /**
      * Run one statement on `c`, choosing the lossless native typed wire when the
@@ -1347,10 +1408,14 @@ export function materializePowql(powql, params) {
 }
 /**
  * A {@link PgCompatPool} backed by an in-process `@zvndev/powdb-embedded`
- * `Database`. The embedded addon takes **no params array** — its `query(powql)`
- * accepts only a string — so this pool materializes each positional `$N` into a
- * PowQL literal via {@link materializePowql} before handing the text to the
- * engine. One handle, single connection: transaction keywords (`begin`/`commit`/
+ * `Database`. On the addon's typed native wire (≥ 0.14, when
+ * `capabilities.nativeRaw` is set) this pool binds positional `$N` params via
+ * `queryWithParams` and decodes the typed cells, exactly like the networked
+ * transport. On an older addon (no `queryWithParams`) it falls back to the
+ * legacy string wire, which takes **no params array** (its `query(powql)`
+ * accepts only a string), so each positional `$N` is materialized into a PowQL
+ * literal via {@link materializePowql} before the text is handed to the engine.
+ * One handle, single connection: transaction keywords (`begin`/`commit`/
  * `rollback`) are issued serially as ordinary queries.
  */
 export class PowdbEmbeddedPool {
@@ -1371,20 +1436,44 @@ export class PowdbEmbeddedPool {
     poolHoldRef = { hold: null };
     /**
      * Feature capabilities of the embedded engine (resolved from the addon
-     * package version). `nativeRaw` is always false: the embedded addon exposes
-     * no native typed-wire surface (its rows are `string[][]`, the legacy wire).
+     * package version). `nativeRaw` is true when the addon is ≥ 0.14 and the
+     * opened handle exposes `queryWithParams` (the typed native wire); an older
+     * addon has no such method, so it stays false and the legacy string wire is
+     * used.
      */
     capabilities;
     /** Carried for surface uniformity with {@link PowdbPool}; inert on embedded (no protocol_error frames). */
     retryStaleReads;
+    /**
+     * True when this pool was opened read-only (an `{ embedded, readonly: true }`
+     * target, or a directly-constructed pool passed `readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own refusal (mapped by {@link wrapPowdbError}) is the
+     * backstop for raw / injected paths.
+     */
+    readonly;
     constructor(db, options = {}) {
         this.db = db;
         this.txGate = new PowdbTxGate(options.transactionQueueTimeoutMs ?? DEFAULT_TX_QUEUE_TIMEOUT_MS);
         this.capabilities = options.capabilities ?? ALL_POWDB_CAPABILITIES;
         this.retryStaleReads = options.retryStaleReads ?? false;
+        this.readonly = options.readonly ?? false;
     }
-    /** Materialize `$N` params and hand the PowQL to the in-process engine. */
+    /** Run the PowQL on the in-process engine, choosing the native or legacy wire. */
     exec(powql, params) {
+        // Native typed wire (addon ≥ 0.14): bind positional params with the SAME
+        // binder the networked transport uses ({@link toPowdbParam} yields exactly
+        // the NativeParam union null|bigint|number|boolean|string) and decode the
+        // typed cells: a genuine str "null" survives, a json-null document stays
+        // distinct from an absent value. Gated on the resolved capability AND a
+        // per-call feature-detect so a heterogeneous injected handle cannot crash.
+        if (this.capabilities.nativeRaw && typeof this.db.queryWithParams === 'function') {
+            const bound = params.map((v) => toPowdbParam(v));
+            return adaptNativeResult(this.db.queryWithParams(powql, bound));
+        }
+        // Legacy string wire (addon < 0.14): the engine takes no params array, so
+        // materialize each `$N` into a PowQL literal. Byte-for-byte unchanged, kept
+        // live and tested as the pre-0.14 fallback.
         const materialized = materializePowql(powql, params);
         return adaptResult(normalizeEmbeddedResult(this.db.query(materialized)));
     }
@@ -1404,6 +1493,15 @@ export class PowdbEmbeddedPool {
             // transaction callback throws re-entrant E017 fast; independent
             // concurrent ones wait their FIFO turn.
             holdRef.hold = await this.txGate.acquire();
+            // The gate may have handed us the slot AFTER disconnect() closed the
+            // handle (a transaction queued behind an in-flight one, released as the
+            // pool shut down). Re-check before touching the now-closed engine, and
+            // release the slot we just took so the queue keeps draining.
+            if (this.closed) {
+                holdRef.hold.finish();
+                holdRef.hold = null;
+                throw new ConnectionError('[turbine] The PowDB embedded pool is closed: disconnect() was already called on this client.');
+            }
         }
         if ((ctl === 'commit' || ctl === 'rollback') && holdRef.hold === null) {
             // This context never acquired the gate — its `begin` never ran (the
@@ -1479,13 +1577,15 @@ export class PowdbEmbeddedPool {
     async end() {
         if (this.closed)
             return;
-        // The addon exposes no explicit close — drop the reference and let GC /
-        // the engine's checkpoint flush. Marking the pool closed makes later
-        // queries fail with a typed ConnectionError instead of silently running
-        // against a handle the caller believes is gone. Caveat: durability is
-        // checkpoint-bound, so hold the process open long enough for the final
-        // WAL flush in short scripts.
         this.closed = true;
+        // Addon ≥ 0.14 exposes an explicit checkpoint-flushing close(): call it so
+        // the final WAL flush completes deterministically before the handle is
+        // dropped. An older addon has no close, dropping the reference and letting
+        // GC / the engine's checkpoint flush is the fallback (durability is then
+        // checkpoint-bound, so a short script must hold the process open long enough
+        // for the final flush). Marking the pool closed makes later queries fail
+        // with a typed ConnectionError instead of running against a gone handle.
+        this.db.close?.();
     }
 }
 // ---------------------------------------------------------------------------
@@ -1552,12 +1652,34 @@ function resolveEmbeddedVersion() {
     return importOptionalPeer.peerPackageVersion('@zvndev/powdb-embedded');
 }
 /** Open an embedded database handle, wrapping engine open failures (corrupt dir, etc.). */
-async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion) {
-    const mod = await loadPowdbEmbedded();
-    const { embedded: dir, syncMode, memoryLimit } = target;
+async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion, injectedModule) {
+    const mod = injectedModule ?? (await loadPowdbEmbedded());
+    const { embedded: dir, syncMode, memoryLimit, readonly } = target;
+    // A read-only engine never writes, so a durability selector is meaningless
+    // there, reject the combination loudly rather than silently ignoring one.
+    if (readonly && syncMode !== undefined) {
+        throw new ValidationError('[turbine] embedded `syncMode` is meaningless with `readonly: true` (a read-only database never writes). Remove one.');
+    }
     let db;
     try {
-        if (memoryLimit !== undefined) {
+        if (readonly) {
+            // Read-only snapshot serving (addon ≥ 0.14): route to the openReadOnly*
+            // constructors; feature-detect and fail with a clear version hint if the
+            // installed addon predates them.
+            if (memoryLimit !== undefined) {
+                if (typeof mod.Database.openReadOnlyWithMemoryLimit !== 'function') {
+                    throw new ConnectionError('[turbine] embedded `readonly` + `memoryLimit` requires @zvndev/powdb-embedded >= 0.14 (openReadOnlyWithMemoryLimit).');
+                }
+                db = mod.Database.openReadOnlyWithMemoryLimit(dir, memoryLimit);
+            }
+            else {
+                if (typeof mod.Database.openReadOnly !== 'function') {
+                    throw new ConnectionError('[turbine] embedded `readonly: true` requires @zvndev/powdb-embedded >= 0.14 (the installed addon has no openReadOnly).');
+                }
+                db = mod.Database.openReadOnly(dir);
+            }
+        }
+        else if (memoryLimit !== undefined) {
             if (typeof mod.Database.openWithMemoryLimit !== 'function') {
                 throw new ConnectionError('[turbine] embedded `memoryLimit` requires @zvndev/powdb-embedded ≥ 0.7.1.');
             }
@@ -1578,11 +1700,19 @@ async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion) {
         }
         db.setSyncMode(syncMode);
     }
-    // Embedded exposes no native typed-wire surface, so nativeRaw is always false.
+    // Native typed wire is feature-detected on the OPENED handle: an addon ≥ 0.14
+    // exposes `queryWithParams`, so nativeRaw turns on (server-gate ≥ 0.13 still
+    // applies via the version); an older addon has no such method → false.
     const capabilities = capabilitiesFromVersion(assumeEngineVersion ?? resolveEmbeddedVersion(), {
-        hasNativeRaw: false,
+        hasNativeRaw: typeof db.queryWithParams === 'function',
+    });
+    // A read-only target forces the pool's readonly flag; otherwise honor whatever
+    // `poolOptions` (threaded from `options.readonly`) carried.
+    return new PowdbEmbeddedPool(db, {
+        ...poolOptions,
+        capabilities,
+        readonly: Boolean(readonly) || Boolean(poolOptions.readonly),
     });
-    return new PowdbEmbeddedPool(db, { ...poolOptions, capabilities });
 }
 /**
  * Bind Turbine to PowDB. `target` is one of:
@@ -1608,6 +1738,7 @@ export async function turbinePowDB(target, schema, options = {}) {
     const poolOptions = {
         transactionQueueTimeoutMs: options.transactionQueueTimeoutMs,
         retryStaleReads: options.retryStaleReads,
+        readonly: options.readonly,
     };
     const max = options.connectionLimit ?? 10;
     if (typeof target === 'string') {
@@ -1622,7 +1753,7 @@ export async function turbinePowDB(target, schema, options = {}) {
         pool = target;
     }
     else if (isEmbeddedTarget(target)) {
-        pool = await openEmbeddedPool(target, poolOptions, options.assumeEngineVersion);
+        pool = await openEmbeddedPool(target, poolOptions, options.assumeEngineVersion, options.powdbEmbeddedModule);
         owns = true;
     }
     else if (isPowdbClientPool(target)) {
@@ -1649,6 +1780,7 @@ export async function turbinePowDB(target, schema, options = {}) {
         logging: options.logging,
         defaultLimit: options.defaultLimit,
         warnOnUnlimited: options.warnOnUnlimited,
+        relationLoadStrategy: options.relationLoadStrategy,
         queryInterfaceFactory,
     }, schema);
     if (owns) {

package/dist/powql.d.ts

@@ -57,8 +57,16 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     constructor(pool: PowdbPool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /** Resolve a camelCase field name (or raw snake) to its column metadata. */
     private column;
-    /** PowQL column reference (`.snake_name`) for a field. */
+    /**
+     * 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`).
+     */
     private ref;
+    /** Render a raw column name as a PowQL reference, qualified with `alias` when given. */
+    private colRefName;
     /**
      * Push a value into the param array and return its `$N` placeholder. When the
      * value targets a `float` column it is wrapped in {@link PowdbFloatParam} so
@@ -92,6 +100,13 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     /**
      * 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.
      */
     private buildWhere;
     /** Build a single `field: value | operator` condition. */
@@ -189,6 +204,8 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * read. Read statements pass a read-shaped action from {@link POWQL_READ_ACTIONS}.
      */
     private exec;
+    /** Build the E018 refusal for a write / `begin` on a read-only pool. */
+    private readOnlyError;
     /**
      * 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
@@ -217,13 +234,44 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * rare caller with no per-result flag (hand-built test pools). */
     private shape;
     findMany(args?: FindManyArgs<T>): Promise<T[]>;
-    /** Build + run the flat findMany select; returns raw rows + the serving wire. */
+    /**
+     * 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.
+     */
+    private buildFind;
+    /** Build + run the flat findMany select; returns raw rows, the serving wire, and the resolved where. */
     private runFind;
+    /**
+     * 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.
+     */
+    explain(args?: FindManyArgs<T>): Promise<string[]>;
     findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
     findFirst(args?: FindManyArgs<T>): Promise<T | null>;
     findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
     findFirstOrThrow(args?: FindManyArgs<T>): Promise<T>;
-    /** Load each requested relation for `parents` and attach it onto each row. */
+    /**
+     * 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).
+     */
     private loadRelations;
     /**
      * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
@@ -234,6 +282,88 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * (composite junction keys would need PowQL tuple-`in`, which it lacks).
      */
     private loadManyToMany;
+    /**
+     * 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.
+     */
+    private resolveStrategy;
+    /**
+     * 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).
+     */
+    private joinEligible;
+    /**
+     * 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).
+     */
+    private isSingleColumnUnique;
+    /** Dispatch one eligible relation to the correct native-join loader. */
+    private loadRelationViaJoin;
+    /**
+     * 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.
+     */
+    private loadManyToManyViaJoin;
+    /**
+     * 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.
+     */
+    private joinChildCols;
+    /**
+     * `{ __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.
+     */
+    private joinProjection;
+    /**
+     * `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.
+     */
+    private joinFilter;
+    /** Group join rows by their (normalized) `__tpk`, stripping it and shaping each child. */
+    private bucketByTpk;
+    /**
+     * 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.
+     */
+    private joinKey;
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
     private scalarData;
     /**