turbine-orm 0.47.0 → 0.48.0

package/dist/powdb.js

@@ -57,6 +57,8 @@ import { TurbineClient, } from './client.js';
 import { postgresDialect } from './dialect.js';
 import { ConnectionError, NotNullViolationError, ReadOnlyError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import importOptionalPeer from './optional-peer-import.cjs';
+import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
+import { normalizeKeyColumns } from './schema.js';
 /**
  * Capability descriptor for PowDB. PowQL generation is owned by
  * {@link PowqlInterface} (not the SQL `Dialect`), so this dialect exists only to
@@ -190,7 +192,14 @@ export function assertSupportedPowdbVersion(version) {
     throw new ConnectionError(`[turbine] turbine-orm/powdb requires PowDB >= ${MIN_POWDB_VERSION}; the server reports "${version}". ` +
         'Upgrade the PowDB server (0.7.0 added the `returning` keyword and the int->float coercion fix Turbine relies on).');
 }
-/** Minimum engine version each gated feature needs, for the E017 hint text. */
+/**
+ * Minimum engine version each gated feature needs, for the E017 hint text.
+ * Most gates carry a `major.minor` floor (patch-insensitive); the two link
+ * lanes carry a `major.minor.patch` floor (`0.19.1`) because the listing
+ * statement and the safe traversal semantics landed in the PATCH release, not
+ * in 0.19.0. {@link atLeastVersion} compares all three components, so a
+ * `major.minor` floor still matches every patch of that minor.
+ */
 const POWDB_FEATURE_MIN_VERSION = {
     introspection: '0.10',
     jsonDocs: '0.12',
@@ -198,6 +207,8 @@ const POWDB_FEATURE_MIN_VERSION = {
     serverJoins: '0.13',
     nestedProjections: '0.18',
     entityLinks: '0.19',
+    linkIntrospection: '0.19.1',
+    linkPaths: '0.19.1',
 };
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
@@ -211,6 +222,11 @@ const POWDB_FEATURE_MIN_VERSION = {
  * `entityLinks` stays OFF for a stronger reason still: declaring a link
  * one-way-upgrades the on-disk catalog to v7 and locks out pre-0.19 binaries,
  * so it must only ever light up behind a real version probe.
+ * `linkIntrospection` / `linkPaths` stay OFF for the same probe-only discipline:
+ * `linkPaths` flips real query generation (a to-one `with` compiling to link
+ * projections), and `linkIntrospection` is only meaningful once genuinely
+ * probed, so both must come from a real version resolution, never a bare
+ * construction.
  */
 export const ALL_POWDB_CAPABILITIES = {
     engineVersion: null,
@@ -220,6 +236,8 @@ export const ALL_POWDB_CAPABILITIES = {
     serverJoins: true,
     nestedProjections: false,
     entityLinks: false,
+    linkIntrospection: false,
+    linkPaths: false,
     nativeRaw: false,
 };
 /** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
@@ -229,9 +247,20 @@ function parsePowdbSemver(version) {
         return null;
     return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0) };
 }
-/** Is `sem` at least `major.minor`? */
-function atLeastVersion(sem, major, minor) {
-    return sem.major > major || (sem.major === major && sem.minor >= minor);
+/**
+ * Is `sem` at least `major.minor.patch`? PATCH-AWARE: `patch` defaults to `0`,
+ * so a two-component floor (`atLeastVersion(sem, 0, 19)`) behaves exactly as the
+ * old major/minor comparison did (matches every patch of 0.19), while a
+ * three-component floor (`atLeastVersion(sem, 0, 19, 1)`) additionally requires
+ * the patch, the distinction the link lanes need (0.19.1, never 0.19.0). Every
+ * existing two-argument call keeps its prior semantics unchanged.
+ */
+function atLeastVersion(sem, major, minor, patch = 0) {
+    if (sem.major !== major)
+        return sem.major > major;
+    if (sem.minor !== minor)
+        return sem.minor > minor;
+    return sem.patch >= patch;
 }
 /**
  * Derive {@link PowdbCapabilities} from an engine version string. A non-semver /
@@ -250,6 +279,8 @@ export function capabilitiesFromVersion(version, opts = {}) {
             serverJoins: false,
             nestedProjections: false,
             entityLinks: false,
+            linkIntrospection: false,
+            linkPaths: false,
             nativeRaw: false,
         };
     }
@@ -261,6 +292,11 @@ export function capabilitiesFromVersion(version, opts = {}) {
         serverJoins: atLeastVersion(sem, 0, 13),
         nestedProjections: atLeastVersion(sem, 0, 18),
         entityLinks: atLeastVersion(sem, 0, 19),
+        // PATCH-floored at 0.19.1: the `schema links` listing + `describe` link rows
+        // and the safe (hard-erroring) scalar-path traversal both landed in 0.19.1,
+        // never 0.19.0.
+        linkIntrospection: atLeastVersion(sem, 0, 19, 1),
+        linkPaths: atLeastVersion(sem, 0, 19, 1),
         nativeRaw: Boolean(opts.hasNativeRaw) && atLeastVersion(sem, 0, 13),
     };
 }
@@ -469,6 +505,48 @@ export function quotePowqlIdent(name) {
     }
     return POWQL_KEYWORDS.has(name) || !POWQL_BARE_IDENT.test(name) ? `\`${name}\`` : name;
 }
+/**
+ * Derive the entity links Turbine would declare from a schema's relations. One
+ * link per single-column hasMany / hasOne / belongsTo relation, owned by the
+ * relation's `from` table:
+ *   - belongsTo Order->User: `Order.user -> User on user_id = id`
+ *     (localKey = the FK on the owner, targetKey = the referenced key on target).
+ *   - hasMany  User->Order: `User.orders -> Order on id = user_id`
+ *     (localKey = the referenced key on the owner, targetKey = the FK on the child).
+ * Composite-key relations and m2m junctions are skipped (links are single-column;
+ * a junction cannot be inferred from links). A relation whose name collides with
+ * a column on the owner is skipped and reported through `onCollision` (the caller
+ * decides whether to warn). Pure: no capability gate, no side effects.
+ */
+export function deriveDesiredLinks(schema, onCollision) {
+    const links = [];
+    for (const meta of Object.values(schema.tables)) {
+        for (const rel of Object.values(meta.relations)) {
+            if (rel.type === 'manyToMany')
+                continue;
+            const fk = normalizeKeyColumns(rel.foreignKey);
+            const rk = normalizeKeyColumns(rel.referenceKey);
+            if (fk.length !== 1 || rk.length !== 1)
+                continue; // links are single-column
+            // A link name that collides with a column on the owner is a hard engine
+            // error at declare time, so skip it (and let the caller warn).
+            const collides = meta.columns.some((c) => c.name === rel.name || c.field === rel.name);
+            if (collides) {
+                onCollision?.(meta.name, rel.name);
+                continue;
+            }
+            const localKey = rel.type === 'belongsTo' ? fk[0] : rk[0];
+            const targetKey = rel.type === 'belongsTo' ? rk[0] : fk[0];
+            links.push({ owner: meta.name, name: rel.name, target: rel.to, localKey, targetKey });
+        }
+    }
+    return links;
+}
+/** Render one {@link PowdbDesiredLink} as its create-only `link ...` DDL statement. */
+export function powdbLinkStatement(link) {
+    return (`link ${quotePowqlIdent(link.owner)}.${quotePowqlIdent(link.name)} -> ` +
+        `${quotePowqlIdent(link.target)} on ${quotePowqlIdent(link.localKey)} = ${quotePowqlIdent(link.targetKey)}`);
+}
 export function powqlSchemaDDL(schema, opts = {}) {
     const caps = opts.capabilities;
     const stmts = [];
@@ -549,8 +627,94 @@ export function powqlSchemaDDL(schema, opts = {}) {
             }
         }
     }
+    // Entity-link DDL (opt-in). Appended after every type so the referenced types
+    // already exist when the links declare. Gated behind the entityLinks capability
+    // when a caller supplied one (an old engine has no `link` statement).
+    if (opts.emitLinks) {
+        if (caps)
+            requireCapability(caps, 'entityLinks', 'entity link DDL (`emitLinks`)');
+        const links = deriveDesiredLinks(schema, (owner, name) => {
+            if (shouldWarnOnce(WARN_NS.powdbLinks, `collide:${owner}.${name}`)) {
+                console.warn(`[turbine] powqlSchemaDDL(emitLinks): relation "${name}" on "${owner}" collides with a column of the ` +
+                    'same name; skipping its link declaration (PowDB hard-errors on a link that shadows a column).');
+            }
+        });
+        for (const link of links)
+            stmts.push(powdbLinkStatement(link));
+    }
     return stmts;
 }
+/**
+ * Existence-checked apply of entity-link DDL against a LIVE PowDB database.
+ * Because link DDL is create-only (no `if not exists`, redeclaring is an error,
+ * and there is no drop spelling), an apply layer must diff against the live
+ * catalog first: this reads the `schema links` listing, then executes only the
+ * links that are genuinely missing.
+ *
+ *   - a desired link already declared with the SAME endpoints  → skipped (idempotent);
+ *   - a link declared with the same owner + name but DIFFERENT endpoints → skipped
+ *     with a one-time warning (never dropped/replaced: there is no drop DDL, and a
+ *     silent replace would be a destructive schema change);
+ *   - a name/column collision on the owner → skipped (deriveDesiredLinks warns).
+ *
+ * Requires the `entityLinks` + `linkIntrospection` capabilities when `capabilities`
+ * is supplied (the listing statement is 0.19.1+). Returns the statements executed.
+ * `exec` runs one PowQL statement (embedded `db.raw` / a networked query shim); it
+ * must return rows keyed by column name for the `schema links` read.
+ */
+export async function applyPowdbLinks(exec, schema, options = {}) {
+    const caps = options.capabilities;
+    if (caps) {
+        requireCapability(caps, 'entityLinks', 'entity link DDL (`applyPowdbLinks`)');
+        requireCapability(caps, 'linkIntrospection', 'PowDB `schema links` introspection');
+    }
+    const existing = await listPowdbLinks(exec);
+    const byOwnerName = new Map(existing.map((l) => [`${l.owner}${l.name}`, l]));
+    const desired = deriveDesiredLinks(schema, (owner, name) => {
+        if (shouldWarnOnce(WARN_NS.powdbLinks, `collide:${owner}.${name}`)) {
+            console.warn(`[turbine] applyPowdbLinks: relation "${name}" on "${owner}" collides with a column of the same name; ` +
+                'skipping its link (PowDB hard-errors on a link that shadows a column).');
+        }
+    });
+    const executed = [];
+    for (const link of desired) {
+        const found = byOwnerName.get(`${link.owner}${link.name}`);
+        if (found) {
+            const same = found.target === link.target && found.localKey === link.localKey && found.targetKey === link.targetKey;
+            if (!same && shouldWarnOnce(WARN_NS.powdbLinks, `drift:${link.owner}.${link.name}`)) {
+                console.warn(`[turbine] applyPowdbLinks: link "${link.name}" on "${link.owner}" is already declared with different ` +
+                    `endpoints (have ${found.target} on ${found.localKey} = ${found.targetKey}, want ${link.target} on ` +
+                    `${link.localKey} = ${link.targetKey}); leaving it untouched (PowDB has no drop-link DDL).`);
+            }
+            continue; // identical → idempotent skip; drift → warned skip
+        }
+        const stmt = powdbLinkStatement(link);
+        await exec(stmt);
+        executed.push(stmt);
+    }
+    return executed;
+}
+/**
+ * Read the live `schema links` listing into {@link PowdbDesiredLink} rows (owner,
+ * name, target, localKey, targetKey; cardinality is dropped — it is derived, not
+ * a DDL input). An empty catalog returns `[]`, never an error. Naming edge: a
+ * table literally named `links` is described with `describe links`, but the
+ * link LISTING is the contextual keyword form `schema links`.
+ */
+async function listPowdbLinks(exec) {
+    const { rows } = await exec('schema links');
+    return rows.map((r) => ({
+        owner: powdbCell(r.owner),
+        name: powdbCell(r.name),
+        target: powdbCell(r.target),
+        localKey: powdbCell(r.local_key),
+        targetKey: powdbCell(r.target_key),
+    }));
+}
+/** Coerce a wire cell (string on the legacy wire, typed on the native wire) to string. */
+function powdbCell(v) {
+    return v === null || v === undefined ? '' : String(v);
+}
 /** Coerce a JS value into a PowDB positional param (the write side). */
 function toPowdbParam(value, col) {
     if (value instanceof PowdbFloatParam)
@@ -790,6 +954,18 @@ 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}`);
     }
+    // Entity-link misuse hard errors (0.19.1 turned the two silent-wrong-results
+    // 0.19.0 behaviors into hard errors) → ValidationError (E003), a query defect
+    // to fix. Matched explicitly on the pinned message text so both transports
+    // classify identically regardless of how the wire wraps them (embedded tags
+    // every error `GenericFailure`; networked carries a wire class): a bare dotted
+    // projection path that was not alias-qualified, and an aggregate over a nested
+    // or link projection. Turbine's own generator never emits either shape (it
+    // always aliases and never aggregates over a link), so these fire only for a
+    // raw user PowQL string; mapping them keeps that path typed.
+    if (/is ambiguous in a projection|aggregates over a nested or link projection/i.test(msg)) {
+        return new ValidationError(`[turbine] PowDB query 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
@@ -1460,7 +1636,11 @@ export function encodePowqlLiteral(value) {
  * between v0.18.0 and v0.19.0 (empty git diff), and `link` was already a lexer
  * keyword at 0.18.0. The 0.19 entity-links surface adds new STATEMENTS built from
  * pre-existing tokens, so the tokenization / escape surface this ceiling guards is
- * unmoved.
+ * unmoved. The 0.19.1 link-introspection / link-path round is likewise lexer-neutral:
+ * `git diff v0.19.0 v0.19.1 -- crates/query/src/lexer.rs` is empty (the bare-dotted-path
+ * hard error is parser-level, not tokenization), so this ceiling stays `'0.19'`. The
+ * guard in {@link PowdbEmbeddedPool.exec} compares major.minor only, so `'0.19'`
+ * already covers every 0.19.x patch — no bump is needed for 0.19.1.
  */
 export const POWQL_LEXER_TESTED_CEILING = '0.19';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */

package/dist/powql.d.ts

@@ -453,6 +453,57 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private attachNestedRows;
     private attachOneNested;
+    /**
+     * The `schema links` snapshot for this pool, fetched at most once and cached on
+     * the pool identity. A fetch failure resolves to `[]` (a missing listing is a
+     * silent fallback to loaders, never an error). Only called when the `linkPaths`
+     * capability is on, so the listing statement is guaranteed to exist.
+     */
+    private linksSnapshot;
+    private fetchLinksSnapshot;
+    /** True when `name` is a bare PowQL identifier (quoting leaves it unchanged). */
+    private isBareIdent;
+    /**
+     * Find the declared to-one link on THIS table that matches `rel` exactly: same
+     * target, same correlation columns (owner localKey = the FK on this table, target
+     * targetKey = the referenced key on target), cardinality `"to-one"`. Returns the
+     * declared link (whose NAME drives the path spelling, which may differ from the
+     * relation's own name) or `null` for no verifiable match (→ silent loader
+     * fallback, never an error).
+     */
+    private findMatchingLink;
+    /**
+     * Plan one belongsTo `with` as a scalar link-path relation, or `null` when it
+     * must stay on the loaders (ALWAYS a silent fallback with identical output).
+     *
+     * SCOPED TIGHT: this fires ONLY for a to-one relation whose child projection
+     * includes a bigint/bytes column — exactly the case a JSON nested block cannot
+     * carry, so nested projections have already fallen back to a per-relation loader
+     * (`planNestedRelation` returned `null` for the same shape). Cases nested
+     * projections DO serve keep nested projections: link-bearing statements are
+     * NEVER plan-cached upstream, so replacing a cacheable nested projection with a
+     * link path would regress a hot path for no gain. Requires: single-column
+     * belongsTo; no relation `with` / `where` / `distinct` / `orderBy` /
+     * `limit` / `offset` (a scalar path has no per-hop filter/order and cannot
+     * reproduce those — such inputs stay on the loader for exact parity); a link
+     * name and all projected columns that are bare identifiers (a quoted segment in
+     * a dotted link path is outside the verified spelling — fall back); and a
+     * DECLARED link that verifiably matches (`findMatchingLink`).
+     */
+    private planLinkPathRelation;
+    /** The flat `l<i>_<col>: t0.<linkName>.<col>` projection fields for one link plan. */
+    private linkPathFields;
+    /**
+     * Reconstruct each link-path relation's child entity from its flat hop fields
+     * and attach it under the relation name — output indistinguishable from the
+     * loader (same keys, same coercions). Presence: the target PK cell arriving
+     * Empty (a null/dangling FK at the hop) means no linked row → `null`, matching
+     * the loader's `matches[0] ?? null`. Otherwise the gathered snake cells go
+     * through the SAME `rowToEntity` policy the loader uses (native micros → Date,
+     * bigint per the int8 policy), and the PK is stripped back off if the user did
+     * not project it. `native` is the wire that actually served the parent row.
+     */
+    private attachLinkRows;
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
     private scalarData;
     /**

package/dist/powql.js

@@ -81,6 +81,16 @@ const POWQL_WRITE_ACTIONS = new Set([
     'deleteMany',
     'upsert',
 ]);
+/**
+ * Per-pool cache of the `schema links` snapshot (fetched at most once per pool):
+ * scalar link-path query generation verifies a declared link matches the
+ * relation before compiling to it. Keyed on the pool object identity so every
+ * table interface over the same connection shares one snapshot; a WeakMap lets a
+ * discarded pool's snapshot be collected. A fetch failure caches `[]` (a missing
+ * listing means "no verifiable links" — a silent fallback to loaders, never an
+ * error).
+ */
+const LINK_SNAPSHOT_CACHE = new WeakMap();
 /** Operator keys recognised inside a `WhereOperator` object. */
 const OPERATOR_KEYS = new Set([
     'equals',
@@ -905,10 +915,12 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
         return this.withMiddleware('findMany', args, async () => {
-            const { rows, native, resolvedWhere, nestedPlans, residualWith } = await this.runFind(args, 'findMany');
+            const { rows, native, resolvedWhere, nestedPlans, linkPlans, residualWith } = await this.runFind(args, 'findMany');
             const entities = this.shape(rows, native);
             if (nestedPlans.length)
                 this.attachNestedRows(entities, nestedPlans);
+            if (linkPlans.length)
+                this.attachLinkRows(entities, linkPlans, native);
             if (residualWith) {
                 await this.loadRelations(entities, residualWith, args.timeout, 0, { args, resolvedWhere }, args.includePii === true);
             }
@@ -941,6 +953,7 @@ export class PowqlInterface {
         // key would duplicate the column's).
         const withClause = args.with;
         const nestedPlans = [];
+        const linkPlans = [];
         let residualWith = withClause;
         if (withClause && !args.distinct?.length && this.nestedProjectionsPreferred(args)) {
             const residue = {};
@@ -949,14 +962,25 @@ export class PowqlInterface {
                     continue;
                 const rel = this.meta.relations[relName];
                 const plan = rel && !cols.includes(relName) ? this.planNestedRelation(relName, rel, opt, args.includePii === true) : null;
-                if (plan)
+                if (plan) {
                     nestedPlans.push(plan);
+                    continue;
+                }
+                // Nested projection could not serve it: try a scalar link path (the narrow
+                // to-one bigint/bytes case; the `schema links` snapshot is fetched lazily
+                // inside, only when a genuine candidate reaches it), else it stays on the
+                // loaders.
+                const linkPlan = rel && !cols.includes(relName)
+                    ? await this.planLinkPathRelation(relName, rel, opt, args.includePii === true, cols, linkPlans.length + 1)
+                    : null;
+                if (linkPlan)
+                    linkPlans.push(linkPlan);
                 else
                     residue[relName] = opt; // unknown relation: the loader raises its E003
             }
             residualWith = Object.keys(residue).length ? residue : undefined;
         }
-        const nest = nestedPlans.length > 0;
+        const nest = nestedPlans.length > 0 || linkPlans.length > 0;
         const alias = nest ? 't0' : undefined;
         const where = this.buildWhere(resolvedWhere, params, alias);
         const distinct = args.distinct?.length ? ' distinct' : '';
@@ -978,20 +1002,23 @@ export class PowqlInterface {
             for (const plan of nestedPlans) {
                 parts.push(await this.buildNestedBlock(plan, 't0', aliasCtr, params, args.timeout));
             }
+            // Scalar link-path hops (flat native-typed fields; never a JSON block).
+            for (const plan of linkPlans)
+                parts.push(...this.linkPathFields(plan, 't0'));
             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 };
+        return { powql, resolvedWhere, nestedPlans, linkPlans, residualWith };
     }
     /** 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, nestedPlans, residualWith } = await this.buildFind(args, params);
+        const { powql, resolvedWhere, nestedPlans, linkPlans, residualWith } = await this.buildFind(args, params);
         const { rows, native } = await this.exec(powql, params, args.timeout, action);
-        return { rows, native, resolvedWhere, nestedPlans, residualWith };
+        return { rows, native, resolvedWhere, nestedPlans, linkPlans, residualWith };
     }
     /**
      * Diagnostic surface: compile the same PowQL {@link findMany} would run for
@@ -1026,12 +1053,14 @@ export class PowqlInterface {
                 args = { ...args, where: expanded };
         }
         return this.withMiddleware('findUnique', args, async () => {
-            const { rows, native, nestedPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
+            const { rows, native, nestedPlans, linkPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
             if (!rows.length)
                 return null;
             const entities = this.shape(rows, native);
             if (nestedPlans.length)
                 this.attachNestedRows(entities, nestedPlans);
+            if (linkPlans.length)
+                this.attachLinkRows(entities, linkPlans, native);
             if (residualWith)
                 await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
@@ -1039,12 +1068,14 @@ export class PowqlInterface {
     }
     async findFirst(args = {}) {
         return this.withMiddleware('findFirst', args, async () => {
-            const { rows, native, nestedPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
+            const { rows, native, nestedPlans, linkPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
             if (!rows.length)
                 return null;
             const entities = this.shape(rows, native);
             if (nestedPlans.length)
                 this.attachNestedRows(entities, nestedPlans);
+            if (linkPlans.length)
+                this.attachLinkRows(entities, linkPlans, native);
             if (residualWith)
                 await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
@@ -1690,6 +1721,174 @@ export class PowqlInterface {
         row[plan.relName] = plan.single ? (shaped[0] ?? null) : shaped;
     }
     // -------------------------------------------------------------------------
+    // Scalar to-one link paths (PowDB >= 0.19.1, `linkPaths` capability)
+    // -------------------------------------------------------------------------
+    /**
+     * The `schema links` snapshot for this pool, fetched at most once and cached on
+     * the pool identity. A fetch failure resolves to `[]` (a missing listing is a
+     * silent fallback to loaders, never an error). Only called when the `linkPaths`
+     * capability is on, so the listing statement is guaranteed to exist.
+     */
+    linksSnapshot() {
+        const pool = this.pool;
+        let snap = LINK_SNAPSHOT_CACHE.get(pool);
+        if (!snap) {
+            snap = this.fetchLinksSnapshot();
+            LINK_SNAPSHOT_CACHE.set(pool, snap);
+        }
+        return snap;
+    }
+    async fetchLinksSnapshot() {
+        try {
+            const { rows } = await this.exec('schema links', [], undefined, 'introspect');
+            return rows.map((r) => ({
+                owner: String(r.owner ?? ''),
+                name: String(r.name ?? ''),
+                target: String(r.target ?? ''),
+                localKey: String(r.local_key ?? ''),
+                targetKey: String(r.target_key ?? ''),
+                cardinality: String(r.cardinality ?? ''),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** True when `name` is a bare PowQL identifier (quoting leaves it unchanged). */
+    isBareIdent(name) {
+        return quotePowqlIdent(name) === name;
+    }
+    /**
+     * Find the declared to-one link on THIS table that matches `rel` exactly: same
+     * target, same correlation columns (owner localKey = the FK on this table, target
+     * targetKey = the referenced key on target), cardinality `"to-one"`. Returns the
+     * declared link (whose NAME drives the path spelling, which may differ from the
+     * relation's own name) or `null` for no verifiable match (→ silent loader
+     * fallback, never an error).
+     */
+    findMatchingLink(snapshot, rel) {
+        const localKey = normalizeKeyColumns(rel.foreignKey)[0];
+        const targetKey = normalizeKeyColumns(rel.referenceKey)[0];
+        if (!localKey || !targetKey)
+            return null;
+        for (const l of snapshot) {
+            if (l.cardinality === 'to-one' &&
+                l.owner === this.table &&
+                l.target === rel.to &&
+                l.localKey === localKey &&
+                l.targetKey === targetKey) {
+                return l;
+            }
+        }
+        return null;
+    }
+    /**
+     * Plan one belongsTo `with` as a scalar link-path relation, or `null` when it
+     * must stay on the loaders (ALWAYS a silent fallback with identical output).
+     *
+     * SCOPED TIGHT: this fires ONLY for a to-one relation whose child projection
+     * includes a bigint/bytes column — exactly the case a JSON nested block cannot
+     * carry, so nested projections have already fallen back to a per-relation loader
+     * (`planNestedRelation` returned `null` for the same shape). Cases nested
+     * projections DO serve keep nested projections: link-bearing statements are
+     * NEVER plan-cached upstream, so replacing a cacheable nested projection with a
+     * link path would regress a hot path for no gain. Requires: single-column
+     * belongsTo; no relation `with` / `where` / `distinct` / `orderBy` /
+     * `limit` / `offset` (a scalar path has no per-hop filter/order and cannot
+     * reproduce those — such inputs stay on the loader for exact parity); a link
+     * name and all projected columns that are bare identifiers (a quoted segment in
+     * a dotted link path is outside the verified spelling — fall back); and a
+     * DECLARED link that verifiably matches (`findMatchingLink`).
+     */
+    async planLinkPathRelation(relName, rel, opt, includePii, parentCols, index) {
+        if (!this.capabilities.linkPaths)
+            return null;
+        if (rel.type !== 'belongsTo')
+            return null;
+        if (normalizeKeyColumns(rel.foreignKey).length !== 1 || normalizeKeyColumns(rel.referenceKey).length !== 1) {
+            return null;
+        }
+        const targetMeta = this.schema.tables[rel.to];
+        if (targetMeta?.primaryKey.length !== 1)
+            return null;
+        const options = (opt === true ? {} : opt);
+        if (options.with || options.where || options.distinct?.length)
+            return null;
+        if (options.orderBy || options.limit !== undefined || options.offset)
+            return null;
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const userCols = targetQi.projectedColumns(options.select, options.omit, includePii);
+        const byName = new Map(targetMeta.columns.map((c) => [c.name, c]));
+        // Only adopt link paths where a JSON block genuinely cannot serve the case:
+        // at least one projected child column is bigint/bytes. Otherwise nested
+        // projections already handle it (and cache), so leave it to them.
+        const hasCarrierBlockedCol = userCols.some((c) => {
+            const ts = (byName.get(c)?.tsType ?? '').replace(/\s*\|\s*null$/i, '').trim();
+            return ts === 'bigint' || ts === 'Uint8Array';
+        });
+        if (!hasCarrierBlockedCol)
+            return null;
+        // All cheap checks passed: NOW fetch (and cache) the link snapshot — never
+        // before, so a query with no link-path candidate issues no `schema links`.
+        const link = this.findMatchingLink(await this.linksSnapshot(), rel);
+        if (!link)
+            return null;
+        if (!this.isBareIdent(link.name))
+            return null;
+        if (!userCols.every((c) => this.isBareIdent(c)))
+            return null;
+        // Always project the target PK for presence detection (an absent to-one yields
+        // Empty at every hop; PK-Empty is the unambiguous "no linked row" signal). Add
+        // it if the user's projection dropped it, and remember to strip it back off.
+        const pkCol = targetMeta.primaryKey[0];
+        if (!this.isBareIdent(pkCol))
+            return null;
+        const pkProjected = userCols.includes(pkCol);
+        const cols = pkProjected ? userCols : [...userCols, pkCol];
+        // Synthetic flat result keys (`l<index>_<col>`) keep the hop fields from
+        // colliding with real parent columns or each other. Refuse the (astronomically
+        // unlikely) case where a real parent/child column already uses the prefix.
+        const keyPrefix = `l${index}_`;
+        if (parentCols.some((c) => c.startsWith(keyPrefix)) || cols.some((c) => c.startsWith(keyPrefix)))
+            return null;
+        return { relName, linkName: link.name, targetQi, cols, pkCol, pkProjected, keyPrefix };
+    }
+    /** The flat `l<i>_<col>: t0.<linkName>.<col>` projection fields for one link plan. */
+    linkPathFields(plan, parentAlias) {
+        return plan.cols.map((c) => `${plan.keyPrefix}${c}: ${parentAlias}.${plan.linkName}.${c}`);
+    }
+    /**
+     * Reconstruct each link-path relation's child entity from its flat hop fields
+     * and attach it under the relation name — output indistinguishable from the
+     * loader (same keys, same coercions). Presence: the target PK cell arriving
+     * Empty (a null/dangling FK at the hop) means no linked row → `null`, matching
+     * the loader's `matches[0] ?? null`. Otherwise the gathered snake cells go
+     * through the SAME `rowToEntity` policy the loader uses (native micros → Date,
+     * bigint per the int8 policy), and the PK is stripped back off if the user did
+     * not project it. `native` is the wire that actually served the parent row.
+     */
+    attachLinkRows(entities, plans, native) {
+        for (const plan of plans) {
+            const pkField = plan.targetQi.meta.reverseColumnMap[plan.pkCol] ?? plan.pkCol;
+            for (const entity of entities) {
+                const row = entity;
+                const raw = {};
+                for (const c of plan.cols) {
+                    raw[c] = row[`${plan.keyPrefix}${c}`];
+                    delete row[`${plan.keyPrefix}${c}`];
+                }
+                const child = rowToEntity(raw, plan.targetQi.meta, native);
+                if (child[pkField] == null) {
+                    row[plan.relName] = null;
+                    continue;
+                }
+                if (!plan.pkProjected)
+                    delete child[pkField];
+                row[plan.relName] = child;
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
     // Writes (reselect — PowDB has no RETURNING)
     // -------------------------------------------------------------------------
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */

package/dist/query/warn-registry.d.ts

@@ -54,4 +54,6 @@ export declare const WARN_NS: {
     readonly autoStrategy: "autoStrategy";
     /** Deep-`with` (depth > 5) advisory (builder.ts `findMany`). */
     readonly deepWith: "deepWith";
+    /** PowDB `emitLinks` DDL skips (name/column collision, endpoint drift). */
+    readonly powdbLinks: "powdbLinks";
 };

package/dist/query/warn-registry.js

@@ -89,4 +89,6 @@ export const WARN_NS = {
     autoStrategy: 'autoStrategy',
     /** Deep-`with` (depth > 5) advisory (builder.ts `findMany`). */
     deepWith: 'deepWith',
+    /** PowDB `emitLinks` DDL skips (name/column collision, endpoint drift). */
+    powdbLinks: 'powdbLinks',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.47.0",
+  "version": "0.48.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": {
@@ -108,8 +108,8 @@
     "@size-limit/esbuild": "^12.1.0",
     "@size-limit/file": "^12.1.0",
     "@types/node": "^26.1.0",
-    "@zvndev/powdb-client": "^0.19.0",
-    "@zvndev/powdb-embedded": "^0.19.0",
+    "@zvndev/powdb-client": "^0.19.1",
+    "@zvndev/powdb-embedded": "^0.19.1",
     "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",