turbine-orm 0.47.0 → 0.48.0

package/dist/cjs/powql.js

@@ -117,6 +117,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',
@@ -941,10 +951,12 @@ 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);
             }
@@ -977,6 +989,7 @@ 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 = {};
@@ -985,14 +998,25 @@ 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' : '';
@@ -1014,20 +1038,23 @@ 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
@@ -1062,12 +1089,14 @@ 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];
@@ -1075,12 +1104,14 @@ 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];
@@ -1726,6 +1757,174 @@ 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 (0, powdb_js_1.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 = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey)[0];
+        const targetKey = (0, schema_js_1.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 ((0, schema_js_1.normalizeKeyColumns)(rel.foreignKey).length !== 1 || (0, schema_js_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 = (0, powdb_js_1.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/cjs/query/warn-registry.js

@@ -95,4 +95,6 @@ exports.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/dist/powdb-introspect.js

@@ -56,7 +56,7 @@
 import { ValidationError } from './errors.js';
 import { applyTableFilters } from './introspect.js';
 import { quotePowqlIdent, requireCapability } from './powdb.js';
-import { snakeToCamel } from './schema.js';
+import { singularize, snakeToCamel } from './schema.js';
 /** Coerce a wire cell to string (legacy wire cells are strings; native cells may be typed). */
 function asString(v) {
     return v === null || v === undefined ? '' : String(v);
@@ -125,7 +125,16 @@ export async function introspectPowdbDatabase(exec, options = {}) {
         // `describe` needs the table name in bare-identifier position → quote it so
         // a reserved-word / non-bare table name (`order`) does not become a parse
         // error.
-        const describeRows = (await exec(`describe ${quotePowqlIdent(tableName)}`)).rows.map((r) => ({
+        const describeRows = (await exec(`describe ${quotePowqlIdent(tableName)}`)).rows
+            // PowDB >= 0.19.1 appends entity-LINK rows after the 4 column rows in
+            // `describe <T>` (a `type` cell of literally `"link"`, an Empty nullable
+            // slot, and an arrow description in the index slot). They are NOT columns,
+            // so drop them before column parsing, unconditionally (no capability check):
+            // the rows simply never appear on a pre-0.19.1 engine, and a linked database
+            // introspected without this filter would produce garbage `link`-typed
+            // columns. Declared links are read separately via `schema links` below.
+            .filter((r) => asString(r.type) !== 'link')
+            .map((r) => ({
             column: asString(r.column),
             type: asString(r.type),
             nullable: asBool(r.nullable),
@@ -205,10 +214,120 @@ export async function introspectPowdbDatabase(exec, options = {}) {
             allColumns,
             primaryKey,
             uniqueColumns,
-            // PowDB has no declared foreign keys → no relations from introspection.
+            // Populated below from `schema links` when the engine supports link
+            // introspection (>= 0.19.1); stays `{}` otherwise (PowDB has no declared
+            // foreign keys, so pre-link introspection reports no relations).
             relations: {},
             indexes,
         };
     }
+    // Link introspection (>= 0.19.1): populate relations from declared entity links.
+    // Behaves exactly as before (relations stay `{}`) when the capability is absent
+    // or not supplied.
+    if (options.capabilities?.linkIntrospection) {
+        await introspectPowdbLinks(exec, tables);
+    }
     return { tables, enums: {} };
 }
+/**
+ * Read `schema links` and populate {@link TableMetadata.relations}: the first
+ * time PowDB introspection can report relations. Each declared link becomes a
+ * relation on its OWNER, and its natural REVERSE is synthesized on the target
+ * (mirroring the SQL introspector, which always emits both sides of a FK):
+ *
+ *   - `"to-one"`  link `Order.user -> User`: owner gets a `belongsTo` (localKey =
+ *     the FK on the owner, targetKey = the referenced key on target); the target
+ *     gets a reverse `hasMany` named for the pluralized owner table.
+ *   - `"to-many"` link `User.orders -> Order`: owner gets a `hasMany` (localKey =
+ *     the referenced key on the owner, targetKey = the FK on the child); the
+ *     target gets a reverse `belongsTo` named for the singularized owner table.
+ *
+ * Reverse synthesis is best-effort and collision-guarded: a synthesized name that
+ * would shadow a column field or an already-present relation on the target is
+ * skipped (never a hard error), so introspection can only ADD relations, never
+ * clobber. m2m junctions cannot be inferred from links and stay undetected;
+ * `defineSchema` remains the relation-complete path. Column names arrive as
+ * PowDB's emitted (snake) names and stay snake in `foreignKey`/`referenceKey`
+ * (the SQL introspector's convention); the relation NAME is camelCased to match
+ * the query field surface. Naming edge: `schema links` is the contextual listing
+ * keyword: a table literally named `links` is still read via `describe links`.
+ */
+async function introspectPowdbLinks(exec, tables) {
+    const linkRows = (await exec('schema links')).rows.map((r) => ({
+        owner: asString(r.owner),
+        name: asString(r.name),
+        target: asString(r.target),
+        localKey: asString(r.local_key),
+        targetKey: asString(r.target_key),
+        cardinality: asString(r.cardinality),
+    }));
+    for (const link of linkRows) {
+        const owner = tables[link.owner];
+        const target = tables[link.target];
+        // A link referencing a filtered-out (include/exclude) table is skipped: we
+        // cannot describe the target, so the relation would be unusable.
+        if (!owner || !target)
+            continue;
+        const toOne = link.cardinality === 'to-one';
+        const relName = snakeToCamel(link.name);
+        // Forward relation on the owner (the declared direction).
+        if (toOne) {
+            addRelation(owner, {
+                type: 'belongsTo',
+                name: relName,
+                from: link.owner,
+                to: link.target,
+                foreignKey: link.localKey,
+                referenceKey: link.targetKey,
+            });
+        }
+        else {
+            addRelation(owner, {
+                type: 'hasMany',
+                name: relName,
+                from: link.owner,
+                to: link.target,
+                foreignKey: link.targetKey, // FK on the child (target) side
+                referenceKey: link.localKey, // referenced key on the owner (parent) side
+            });
+        }
+        // Reverse relation on the target (synthesized, collision-guarded).
+        const reverseName = toOne ? pluralize(snakeToCamel(link.owner)) : singularize(snakeToCamel(link.owner));
+        if (!relationNameTaken(target, reverseName)) {
+            addRelation(target, {
+                type: toOne ? 'hasMany' : 'belongsTo',
+                name: reverseName,
+                from: link.target,
+                to: link.owner,
+                // Same two columns, roles swapped for the opposite direction.
+                foreignKey: toOne ? link.localKey : link.targetKey,
+                referenceKey: toOne ? link.targetKey : link.localKey,
+            });
+        }
+    }
+}
+/** True when `name` already names a relation OR a column field/name on `meta`. */
+function relationNameTaken(meta, name) {
+    if (meta.relations[name])
+        return true;
+    return meta.columns.some((c) => c.field === name || c.name === name);
+}
+/** Add a relation to a table's relations map (keyed by its camelCase name). */
+function addRelation(meta, rel) {
+    if (meta.relations[rel.name])
+        return; // never clobber an existing relation
+    meta.relations[rel.name] = rel;
+}
+/**
+ * Minimal English pluralizer for reverse-relation names (`user` → `users`,
+ * `company` → `companies`, `box` → `boxes`). Only ever produces a candidate name
+ * that {@link relationNameTaken} then vets, so an imperfect plural can at worst be
+ * skipped, never break a query.
+ */
+function pluralize(word) {
+    if (/[^aeiou]y$/i.test(word))
+        return `${word.slice(0, -1)}ies`;
+    if (/(s|x|z|ch|sh)$/i.test(word))
+        return `${word}es`;
+    return `${word}s`;
+}

package/dist/powdb.d.ts

@@ -54,7 +54,8 @@
  */
 import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
 import { type Dialect } from './dialect.js';
-import type { ColumnMetadata, SchemaMetadata, TableMetadata } from './schema.js';
+import type { PowdbExec } from './powdb-introspect.js';
+import { type ColumnMetadata, type SchemaMetadata, type TableMetadata } from './schema.js';
 /**
  * Capability descriptor for PowDB. PowQL generation is owned by
  * {@link PowqlInterface} (not the SQL `Dialect`), so this dialect exists only to
@@ -269,11 +270,29 @@ export interface PowdbCapabilities {
      * the on-disk catalog to v7, so this stays FALSE in ALL_POWDB_CAPABILITIES.
      */
     entityLinks: boolean;
+    /**
+     * ≥ 0.19.1: link INTROSPECTION, the `schema links` listing statement and the
+     * appended link rows in `describe <T>`. Only meaningful when probed (there is
+     * no query-generation flip behind it), so it stays FALSE in
+     * ALL_POWDB_CAPABILITIES like the other probe-only gates. Floored at the PATCH
+     * 0.19.1: the listing statement shipped there, not in 0.19.0.
+     */
+    linkIntrospection: boolean;
+    /**
+     * ≥ 0.19.1: scalar to-one link PATHS in query generation. Floored at the PATCH
+     * 0.19.1 (never 0.19.0) because 0.19.0 had silent-wrong-results link bugs
+     * (bare-dotted-path split, wrong aggregates over links) that make traversal
+     * unsafe; 0.19.1 turned those into hard errors. This flag flips real query
+     * generation (a to-one `with` whose child carries bigint/bytes compiles to
+     * link-path projections instead of a loader), so it stays FALSE in
+     * ALL_POWDB_CAPABILITIES: it must only light up behind a real version probe.
+     */
+    linkPaths: boolean;
     /** Networked only: server ≥ 0.13 AND the client exposes `queryNativeRaw`. */
     nativeRaw: boolean;
 }
 /** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
-type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins' | 'nestedProjections' | 'entityLinks';
+type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins' | 'nestedProjections' | 'entityLinks' | 'linkIntrospection' | 'linkPaths';
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
  * for a directly-constructed {@link PowdbPool} / {@link PowdbEmbeddedPool} that
@@ -286,6 +305,11 @@ type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serve
  * `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 declare const ALL_POWDB_CAPABILITIES: PowdbCapabilities;
 /**
@@ -368,8 +392,77 @@ export declare function quotePowqlIdent(name: string): string;
  */
 export interface PowqlSchemaDDLOptions {
     capabilities?: PowdbCapabilities;
+    /**
+     * Emit `link Owner.name -> Target on local = target` declarations (PowDB entity
+     * links, >= 0.19) for every single-column hasMany / hasOne / belongsTo relation
+     * in the metadata, appended after the `type` / index statements. Default
+     * `false`: links are opt-in. Composite-key relations and m2m junctions are
+     * skipped (a link is single-column only); a relation whose name collides with a
+     * column on the owner is skipped with a one-time warning (the engine hard-errors
+     * on such a collision). When `capabilities` is also supplied it must pass the
+     * `entityLinks` gate, else this throws a typed E017.
+     *
+     * ONE-WAY DOOR: the FIRST `link` a database ever executes permanently upgrades
+     * its on-disk catalog to format v7; pre-0.19 PowDB binaries / addons can then no
+     * longer open that data directory. A database that never declares a link stays
+     * on its current catalog format. The DDL is create-only (no `if not exists`, no
+     * drop spelling), so an apply layer must existence-check first (see
+     * {@link applyPowdbLinks}).
+     */
+    emitLinks?: boolean;
 }
+/**
+ * One entity link Turbine wants declared for a relation: `link owner.name ->
+ * target on localKey = targetKey`. Cardinality is NOT part of the DDL (PowDB
+ * derives to-one vs to-many from whether `targetKey` is unique on `target` at
+ * declare time), so a belongsTo and its reverse hasMany both round-trip to the
+ * same shape from opposite owners.
+ */
+export interface PowdbDesiredLink {
+    owner: string;
+    name: string;
+    target: string;
+    localKey: string;
+    targetKey: string;
+}
+/**
+ * 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 declare function deriveDesiredLinks(schema: SchemaMetadata, onCollision?: (owner: string, name: string) => void): PowdbDesiredLink[];
+/** Render one {@link PowdbDesiredLink} as its create-only `link ...` DDL statement. */
+export declare function powdbLinkStatement(link: PowdbDesiredLink): string;
 export declare function powqlSchemaDDL(schema: SchemaMetadata, opts?: PowqlSchemaDDLOptions): string[];
+/**
+ * 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 declare function applyPowdbLinks(exec: PowdbExec, schema: SchemaMetadata, options?: {
+    capabilities?: PowdbCapabilities;
+}): Promise<string[]>;
 /**
  * Coerce a single PowDB wire string into the JS value its column type implies.
  * Every PowDB value arrives as a string; NULL arrives as the bareword `"null"`.
@@ -626,7 +719,11 @@ export declare function encodePowqlLiteral(value: unknown): string;
  * 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 declare const POWQL_LEXER_TESTED_CEILING = "0.19";
 /**