@rebasepro/server-postgres 0.10.1-canary.262a5be → 0.10.1-canary.3d09338

package/src/services/RelationService.ts

@@ -15,6 +15,7 @@ import {
 import { parseDataFromServer } from "../data-transformer";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { logger } from "@rebasepro/server";
+import type { NestedPathHop } from "./nested-path";
 
 /**
  * Typed wrapper for Drizzle dynamic query innerJoin.
@@ -333,6 +334,24 @@ export class RelationService {
             throw new Error(`Relation '${relationKey}' not found in collection '${parentCollectionPath}'. Available relations: [${available}]`);
         }
 
+        return this.countRelatedRows(parentCollection, parentId, relation, []);
+    }
+
+    /**
+     * Count the target rows a parent reaches through `relation`, narrowed by
+     * `additionalFilters` (conditions on the target table).
+     *
+     * Shared by the public count and by {@link isRelated}, so "how many children
+     * does this parent have" and "is this row one of them" are answered by the
+     * same join — a membership test that reconstructed the join separately would
+     * be free to disagree with the listing it is supposed to gate.
+     */
+    private async countRelatedRows(
+        parentCollection: CollectionConfig,
+        parentId: string | number,
+        relation: Relation,
+        additionalFilters: SQL[]
+    ): Promise<number> {
         const targetCollection = relation.target();
         const targetTable = getTableForCollection(targetCollection, this.registry);
         const targetPks = requirePrimaryKeys(targetCollection, this.registry);
@@ -350,9 +369,6 @@ export class RelationService {
         // Start count with distinct to avoid duplicates from junction tables
         let query = this.db.select({ count: sql<number>`count(distinct ${targetIdField})` }).from(targetTable).$dynamic();
 
-        // Build additional filter conditions
-        const additionalFilters: SQL[] = [];
-
         // Use unified count query builder from DrizzleConditionBuilder
         query = DrizzleConditionBuilder.buildRelationCountQuery(
             query,
@@ -370,6 +386,75 @@ export class RelationService {
         return Number(result[0]?.count || 0);
     }
 
+    /**
+     * Whether `targetId` is actually reachable from the parent named in `hop`.
+     *
+     * A nested address like `authors/1/posts/43` used to resolve to the target
+     * collection and then match on the primary key alone, so the parent segment
+     * decided nothing: the row came back, and was updated or deleted, whoever it
+     * belonged to. Reads, updates and deletes now all gate on this.
+     */
+    async isRelated(hop: NestedPathHop, targetId: string | number): Promise<boolean> {
+        const targetTable = getTableForCollection(hop.targetCollection, this.registry);
+        const targetPks = requirePrimaryKeys(hop.targetCollection, this.registry);
+        const parsedTargetId = parseIdValues(targetId, targetPks);
+
+        const identity: SQL[] = targetPks.map(pk => {
+            const column = targetTable[pk.fieldName as keyof typeof targetTable] as AnyPgColumn;
+            if (!column) {
+                throw new Error(`ID field '${pk.fieldName}' not found in table for collection '${hop.targetCollection.slug}'`);
+            }
+            return eq(column, parsedTargetId[pk.fieldName]);
+        });
+
+        return (await this.countRelatedRows(hop.parentCollection, hop.parentId, hop.relation, identity)) > 0;
+    }
+
+    /**
+     * Remove the junction row linking a parent to `targetId`, leaving the target
+     * row itself alone.
+     *
+     * This is what `DELETE authors/1/tags/5` has to mean for a many-to-many: the
+     * target is shared, so deleting the row would remove the tag from every other
+     * post that uses it. It used to do exactly that — resolve the path to the
+     * `tags` table and delete by primary key.
+     */
+    async unlinkRelatedEntity(
+        tx: DrizzleClient,
+        hop: NestedPathHop,
+        targetId: string | number
+    ): Promise<void> {
+        const through = hop.relation.through;
+        if (!through) {
+            throw new Error(`Relation '${hop.relationKey}' has no junction table to unlink through`);
+        }
+
+        const junctionTable = this.registry.getTable(through.table);
+        if (!junctionTable) {
+            throw new Error(`Junction table not found: ${through.table}`);
+        }
+
+        const sourceJunctionColumn = junctionTable[through.sourceColumn as keyof typeof junctionTable] as AnyPgColumn;
+        const targetJunctionColumn = junctionTable[through.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
+
+        if (!sourceJunctionColumn || !targetJunctionColumn) {
+            throw new Error(`Junction columns not found for relation '${hop.relationKey}' on table '${through.table}'`);
+        }
+
+        const parentPks = requirePrimaryKeys(hop.parentCollection, this.registry);
+        const parsedParentId = parseIdValues(hop.parentId, parentPks)[parentPks[0].fieldName];
+
+        const targetPks = requirePrimaryKeys(hop.targetCollection, this.registry);
+        const parsedTargetId = parseIdValues(targetId, targetPks)[targetPks[0].fieldName];
+
+        await tx.delete(junctionTable).where(and(
+            eq(sourceJunctionColumn, parsedParentId),
+            eq(targetJunctionColumn, parsedTargetId)
+        ));
+
+        logger.info(`Unlinked '${hop.relationKey}' ${parsedTargetId} from ${hop.parentCollection.slug} ${parsedParentId}`);
+    }
+
     /**
      * Batch fetch related rows for multiple parent rows to avoid N+1 queries
      */
@@ -1348,15 +1433,19 @@ parentSourceColName };
             const parsedNewEntityIdObj = parseIdValues(newEntityId, targetPks);
             const parsedNewEntityId = parsedNewEntityIdObj[targetIdInfo.fieldName];
 
-            // Create the junction table entry linking parent to the new row
+            // Create the junction table entry linking parent to the target row.
             const junctionData = {
                 [sourceJunctionColumn.name]: parentId,
                 [targetJunctionColumn.name]: parsedNewEntityId
             };
 
-            await tx.insert(junctionTable).values(junctionData);
+            // Idempotent: a link either exists or it does not, so asking for one
+            // twice is not an error. This is what lets `PUT parent/id/child/childId`
+            // mean "this row belongs to this parent's set" — the only way to
+            // attach an *existing* row, which previously had none.
+            await tx.insert(junctionTable).values(junctionData).onConflictDoNothing();
 
-            logger.info(`Created junction table entry for many-to-many relation '${relationKey}': ${JSON.stringify(junctionData)}`);
+            logger.info(`Linked '${relationKey}' ${parsedNewEntityId} to ${parentId}`);
         } catch (error) {
             logger.error(`Failed to create junction table entry for relation '${relationKey}'`, { error: error });
             throw error;

package/src/services/cdc/junction-tables.ts

@@ -0,0 +1,91 @@
+import { CollectionConfig } from "@rebasepro/types";
+import { resolveCollectionRelations } from "@rebasepro/common";
+
+import { PostgresCollectionRegistry } from "../../collections/PostgresCollectionRegistry";
+
+/**
+ * One end of a many-to-many, as seen from the junction table.
+ *
+ * A junction table is not a collection, so nothing in the registry maps it to
+ * one — which is why a change to it was invisible to change capture. But its
+ * rows are exactly the contents of a parent's child list, so a write to it is a
+ * change to `<parentSlug>/<sourceId>/<relationKey>` and to nothing else.
+ */
+export interface JunctionLink {
+    schema: string;
+    /** The junction table itself, e.g. `posts_tags`. */
+    table: string;
+    /** The collection whose relation this is, e.g. `posts`. */
+    parentCollection: CollectionConfig;
+    /** The relation's key — the path segment a child list is addressed by. */
+    relationKey: string;
+    /** Junction column holding the parent's id. */
+    sourceColumn: string;
+    /** Junction column holding the target's id. */
+    targetColumn: string;
+}
+
+/**
+ * Every junction table reachable from a registered collection, once per
+ * relation that uses it.
+ *
+ * A junction is listed once per *direction* when both sides declare it, because
+ * each direction addresses a different child list: `posts/1/tags` and
+ * `tags/t/posts` both change when one link is written.
+ */
+export function collectJunctionLinks(registry: PostgresCollectionRegistry): JunctionLink[] {
+    const links: JunctionLink[] = [];
+    const seen = new Set<string>();
+
+    for (const collection of registry.getCollections()) {
+        let relations: Record<string, { through?: { table: string; sourceColumn: string; targetColumn: string } }>;
+        try {
+            relations = resolveCollectionRelations(collection);
+        } catch {
+            // A collection whose relations cannot be resolved (an unresolvable
+            // target, typically mid-migration) simply contributes none.
+            continue;
+        }
+
+        for (const [relationKey, relation] of Object.entries(relations)) {
+            const through = relation?.through;
+            if (!through?.table) continue;
+
+            // Same relation registered under both its canonical name and the
+            // declaring property key would otherwise notify the same path twice.
+            const key = `${collection.slug}::${relationKey}::${through.table}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+
+            links.push({
+                schema: (collection as { schema?: string }).schema ?? "public",
+                table: through.table,
+                parentCollection: collection,
+                relationKey,
+                sourceColumn: through.sourceColumn,
+                targetColumn: through.targetColumn
+            });
+        }
+    }
+
+    return links;
+}
+
+/**
+ * Index {@link collectJunctionLinks} by table, under both the qualified and the
+ * bare name — a change event carries whatever the trigger reports, and a
+ * collection need not declare a schema.
+ */
+export function buildJunctionLinkMap(registry: PostgresCollectionRegistry): Map<string, JunctionLink[]> {
+    const map = new Map<string, JunctionLink[]>();
+
+    for (const link of collectJunctionLinks(registry)) {
+        for (const key of [`${link.schema}.${link.table}`, link.table]) {
+            const existing = map.get(key);
+            if (existing) existing.push(link);
+            else map.set(key, [link]);
+        }
+    }
+
+    return map;
+}

package/src/services/nested-path.ts

@@ -0,0 +1,130 @@
+import { CollectionConfig, Relation } from "@rebasepro/types";
+import { findRelation, resolveCollectionRelations } from "@rebasepro/common";
+import { ApiError } from "@rebasepro/server";
+
+import { getCollectionByPath } from "./collection-helpers";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+
+/**
+ * The last hop of a nested collection path, e.g. `authors/1/posts`.
+ *
+ * The walk that produces this was written out four separate times — in
+ * `FetchService.fetchCollectionFromPath`, `FetchService.countEntitiesFromPath`,
+ * `PersistService.save` and `CollectionRegistry.getCollectionByPath` — and had
+ * drifted, so the read path and the write path did not agree on which relation
+ * a path named. It lives here once now.
+ */
+export interface NestedPathHop {
+    /** The collection the final relation is declared on (e.g. `authors`). */
+    parentCollection: CollectionConfig;
+    /** The parent's id as it appeared in the path, unparsed. */
+    parentId: string;
+    /** The path segment that named the relation (e.g. `posts`). */
+    relationKey: string;
+    relation: Relation;
+    /** `relation.target()`, resolved once. */
+    targetCollection: CollectionConfig;
+}
+
+/**
+ * True when `path` addresses rows through a relation rather than a root
+ * collection.
+ *
+ * Any separator at all counts — a root collection slug never contains one — so
+ * a malformed path like `collection/id` is a *broken* nested path and gets
+ * reported as one by {@link resolveNestedPath}, rather than being looked up as
+ * a root collection whose slug happens to contain a slash.
+ */
+export function isNestedPath(path: string): boolean {
+    return path.includes("/");
+}
+
+export function splitPathSegments(path: string): string[] {
+    return path.split("/").filter(s => s && s !== "undefined");
+}
+
+/**
+ * Walk a nested collection path down to the relation it ends in.
+ *
+ * Returns `undefined` for a plain root-collection path so callers can keep the
+ * root case on its existing code path. Throws when the path is malformed, or
+ * when a segment names a relation that does not exist — the same errors the
+ * individual walks used to raise, with the available names attached.
+ */
+export function resolveNestedPath(
+    path: string,
+    registry: PostgresCollectionRegistry
+): NestedPathHop | undefined {
+    if (!isNestedPath(path)) return undefined;
+
+    const segments = splitPathSegments(path);
+    if (segments.length < 3 || segments.length % 2 === 0) {
+        throw new Error(`Invalid relation path: ${path}. Expected format: collection/id/relation`);
+    }
+
+    let parentCollection = getCollectionByPath(segments[0], registry);
+    let parentId = segments[1];
+
+    for (let i = 2; i < segments.length; i += 2) {
+        const relationKey = segments[i];
+        const resolvedRelations = resolveCollectionRelations(parentCollection);
+        const relation = findRelation(resolvedRelations, relationKey);
+
+        if (!relation) {
+            const available = Object.keys(resolvedRelations).join(", ") || "(none)";
+            throw new Error(
+                `Relation '${relationKey}' not found in collection '${parentCollection.slug}'. Available relations: [${available}]`
+            );
+        }
+
+        const targetCollection = relation.target();
+
+        if (i === segments.length - 1) {
+            return {
+                parentCollection,
+                parentId,
+                relationKey,
+                relation,
+                targetCollection
+            };
+        }
+
+        parentCollection = targetCollection;
+        parentId = segments[i + 1];
+    }
+
+    // Unreachable: the loop returns on the final segment, and the odd-length
+    // check above guarantees there is one.
+    throw new Error(`Unable to resolve path: ${path}`);
+}
+
+/**
+ * A relation reached through a junction table — many-to-many, or a multi-hop
+ * `joinPath`. The target row is shared with other parents, so writing "through"
+ * such a path addresses the *link*, not the row.
+ */
+export function isJunctionBackedRelation(relation: Relation): boolean {
+    return Boolean(relation.through) || Boolean(relation.joinPath && relation.joinPath.length > 1);
+}
+
+/**
+ * Reject a nested write whose final segment is a to-one relation.
+ *
+ * There is no column on the target row that records a to-one parent — the
+ * foreign key lives on the *parent* table. The write path used to fall through
+ * to `relation.localKey` here and stamp the parent's own FK column onto the
+ * target row, which either raised an opaque "column does not exist" or, when a
+ * column of that name happened to exist on the target, silently wrote the wrong
+ * one.
+ */
+export function assertWritableThrough(hop: NestedPathHop, path: string): void {
+    if (hop.relation.cardinality !== "many") {
+        throw ApiError.badRequest(
+            `"${path}" ends in the to-one relation '${hop.relationKey}', which cannot be written through: ` +
+            `the foreign key for a to-one relation lives on '${hop.parentCollection.slug}', not on ` +
+            `'${hop.targetCollection.slug}'. Write the target row at "${hop.targetCollection.slug}" and set ` +
+            `'${hop.relationKey}' on the parent instead.`,
+            "RELATION_NOT_WRITABLE"
+        );
+    }
+}

package/src/services/realtimeService.ts

@@ -11,6 +11,7 @@ import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfi
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { buildPropertyCallbacks, getTableName } from "@rebasepro/common";
 import { applyAuthContext } from "../security/rls-enforcement";
+import { buildJunctionLinkMap, type JunctionLink } from "./cdc/junction-tables";
 import { logger } from "@rebasepro/server";
 import { sanitizeErrorForClient } from "../utils/pg-error-utils";
 import { CdcListener, type CdcChangeEvent } from "./cdc/CdcListener";
@@ -159,6 +160,9 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
     private cdcListener?: CdcListener;
     /** Whether database-level CDC is the active cross-instance change source. */
     private cdcActive = false;
+    /** Junction table → the child lists its rows belong to, built when CDC starts. */
+    private junctionLinkMap?: Map<string, JunctionLink[]>;
+
     /** Reverse lookup: `schema.table` (and bare `table`) → collection, built when CDC starts. */
     private cdcTableMap?: Map<string, CollectionConfig>;
     /**
@@ -1795,6 +1799,7 @@ lastSeen: Date.now() });
             return;
         }
         this.cdcTableMap = this.buildCdcTableMap();
+        this.junctionLinkMap = buildJunctionLinkMap(this.registry);
         this.cdcListener = new CdcListener(connectionString, (event) => this.handleCdcEvent(event));
         try {
             // start() validates the initial connection; if it can't be established
@@ -1805,6 +1810,7 @@ lastSeen: Date.now() });
             await this.cdcListener.stop().catch(() => { /* best effort */ });
             this.cdcListener = undefined;
             this.cdcTableMap = undefined;
+            this.junctionLinkMap = undefined;
             throw err;
         }
         this.cdcActive = true;
@@ -1822,6 +1828,7 @@ lastSeen: Date.now() });
             this.cdcListener = undefined;
         }
         this.cdcTableMap = undefined;
+        this.junctionLinkMap = undefined;
         this.recentAppEmits.clear();
     }
 
@@ -1862,6 +1869,10 @@ lastSeen: Date.now() });
     private async handleCdcEvent(event: CdcChangeEvent): Promise<void> {
         const collection = this.resolveCollectionForTable(event.schema, event.table);
         if (!collection) {
+            // A junction table backs no collection, but its rows *are* a child
+            // list. Route the change to the lists it changes before giving up.
+            if (await this.handleJunctionCdcEvent(event)) return;
+
             // Unmapped table (not backed by a collection) — nothing to deliver.
             this.debugLog(`📡 [CDC] Ignoring change on unmapped table ${event.schema}.${event.table}`);
             return;
@@ -1878,6 +1889,55 @@ lastSeen: Date.now() });
         await this.notifyUpdate(path, id, row, databaseId, /* broadcast */ false, /* origin */ "cdc");
     }
 
+    /**
+     * Deliver a change on a many-to-many junction table as a change to the child
+     * lists it belongs to.
+     *
+     * Linking a tag to a post writes only `posts_tags`. That table backs no
+     * collection, so change capture dropped the event as unmapped and the
+     * subscribers of `posts/1/tags` never heard about it — every other write in
+     * the system was realtime, and this one silently was not. The junction row
+     * carries both ids, so it names its own paths exactly.
+     *
+     * Notifies the nested path rather than either endpoint collection, because
+     * invalidation walks *parent* paths and never child ones: telling `tags` it
+     * changed would not reach a subscription on `posts/1/tags`.
+     *
+     * Returns whether the table was recognised as a junction.
+     */
+    private async handleJunctionCdcEvent(event: CdcChangeEvent): Promise<boolean> {
+        const links = this.junctionLinkMap?.get(`${event.schema}.${event.table}`)
+            ?? this.junctionLinkMap?.get(event.table);
+        if (!links?.length) return false;
+
+        for (const link of links) {
+            const sourceId = event.row?.[link.sourceColumn];
+            const targetId = event.row?.[link.targetColumn];
+            if (sourceId === undefined || sourceId === null || targetId === undefined || targetId === null) {
+                this.debugLog(
+                    `📡 [CDC] Junction row on ${event.table} is missing '${link.sourceColumn}'/'${link.targetColumn}' — skipping.`
+                );
+                continue;
+            }
+
+            const path = `${link.parentCollection.slug}/${String(sourceId)}/${link.relationKey}`;
+            // An unlink removes the target from this list; a link invalidates it
+            // so each subscriber refetches under its own RLS context.
+            const row = event.op === "DELETE" ? null : { _rebase_invalidated: true };
+
+            await this.notifyUpdate(
+                path,
+                String(targetId),
+                row,
+                (link.parentCollection as { databaseId?: string }).databaseId,
+                /* broadcast */ false,
+                /* origin */ "cdc"
+            );
+        }
+
+        return true;
+    }
+
     /** Compute the canonical (possibly composite) id string from a captured row. */
     private extractIdFromCdcRow(collection: CollectionConfig, row: Record<string, unknown>): string {
         // Unaddressable falls back to a collection-level invalidation: single-row

package/src/utils/drizzle-conditions.ts

@@ -38,6 +38,160 @@ export interface DrizzleDynamicQuery {
  */
 export class DrizzleConditionBuilder {
 
+    /**
+     * Express "reachable from this parent through this relation" as a plain
+     * `WHERE` condition on the target table.
+     *
+     * This is the primitive that lets a relation be a *filter* rather than an
+     * addressing scheme. A nested listing used to be served by its own query
+     * builder — `fetchEntitiesUsingJoins`, which grew joins the root pipeline
+     * did not have and lost the options the root pipeline did have (offset,
+     * filter, orderBy, include). Reduced to a condition, the same listing runs
+     * through the ordinary collection query, so it inherits all of them and
+     * there is one read path instead of two.
+     *
+     * The shapes:
+     *   - inverse FK  → `target.<fk> = :parentId`, a column comparison.
+     *   - `through`   → `EXISTS (SELECT 1 FROM junction …)`, correlated on the
+     *                   target's key, so the junction never multiplies rows the
+     *                   way an `INNER JOIN` would.
+     *   - `joinPath`  → the same `EXISTS`, with the path's steps joined inside
+     *                   it and the final step correlating to the outer row.
+     */
+    static buildRelationScopeCondition(
+        relation: Relation,
+        /**
+         * Lazy: only `joinPath` and `localKey` relations need the parent's own
+         * table. An inverse foreign key and a junction are both expressible
+         * from the parent's *id* alone, and requiring the table for them would
+         * make a child listing fail on a parent whose table isn't registered.
+         */
+        parent: () => { table: PgTable<any>; idColumn: AnyPgColumn },
+        parentId: string | number,
+        targetTable: PgTable<any>,
+        targetIdColumn: AnyPgColumn,
+        registry: PostgresCollectionRegistry
+    ): SQL {
+        if (relation.joinPath && relation.joinPath.length > 0) {
+            const { table, idColumn } = parent();
+            return this.buildJoinPathScopeCondition(
+                relation.joinPath, table, idColumn, parentId, targetTable, registry
+            );
+        }
+
+        if (relation.through) {
+            const junctionTable = registry.getTable(relation.through.table);
+            if (!junctionTable) {
+                throw new Error(`Junction table not found: ${relation.through.table}`);
+            }
+            const sourceCol = junctionTable[relation.through.sourceColumn as keyof typeof junctionTable] as AnyPgColumn;
+            const targetCol = junctionTable[relation.through.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
+            if (!sourceCol || !targetCol) {
+                throw new Error(
+                    `Junction columns '${relation.through.sourceColumn}'/'${relation.through.targetColumn}' not found in '${relation.through.table}'`
+                );
+            }
+            return sql`EXISTS (SELECT 1 FROM ${junctionTable} WHERE ${targetCol} = ${targetIdColumn} AND ${sourceCol} = ${parentId})`;
+        }
+
+        if (relation.foreignKeyOnTarget) {
+            const fkColumn = targetTable[relation.foreignKeyOnTarget as keyof typeof targetTable] as AnyPgColumn;
+            if (!fkColumn) {
+                throw new Error(
+                    `Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of relation ` +
+                    `'${relation.relationName}'. A many-to-many relation needs \`through\` instead.`
+                );
+            }
+            return eq(fkColumn, parentId);
+        }
+
+        if (relation.localKey) {
+            // A to-one owning relation read as a scope: the single target row is
+            // the one the parent's foreign key points at.
+            const { table, idColumn } = parent();
+            return sql`${targetIdColumn} = (SELECT ${sql.identifier(relation.localKey)} FROM ${table} WHERE ${idColumn} = ${parentId})`;
+        }
+
+        throw new Error(
+            `Relation '${relation.relationName}' declares no \`foreignKeyOnTarget\`, \`through\`, \`joinPath\` or ` +
+            "`localKey`, so there is no way to tell which target rows belong to a parent."
+        );
+    }
+
+    /**
+     * `EXISTS` for an explicit `joinPath`.
+     *
+     * The path is declared source → target. The subquery replays every step but
+     * the last from inside, and turns the last one into the correlation with the
+     * outer target row — so the target table is never named twice and needs no
+     * alias. Each intermediate table is aliased positionally, which keeps a path
+     * that revisits a table (a self-referencing many-to-many) unambiguous.
+     */
+    private static buildJoinPathScopeCondition(
+        joinPath: JoinStep[],
+        parentTable: PgTable<any>,
+        parentIdColumn: AnyPgColumn,
+        parentId: string | number,
+        targetTable: PgTable<any>,
+        registry: PostgresCollectionRegistry
+    ): SQL {
+        const sourceAlias = "__rel_src";
+        const aliasFor = (index: number) => `__rel_j${index}`;
+
+        // Column reference against the previous hop: the aliased source for the
+        // first step, the previous aliased join table after that.
+        const fromRef = (stepIndex: number, column: string) =>
+            sql`${sql.identifier(stepIndex === 0 ? sourceAlias : aliasFor(stepIndex - 1))}.${sql.identifier(getColumnName(column))}`;
+
+        const pairs = (step: JoinStep): { from: string; to: string }[] => {
+            const from = Array.isArray(step.on.from) ? step.on.from : [step.on.from];
+            const to = Array.isArray(step.on.to) ? step.on.to : [step.on.to];
+            if (from.length !== to.length) {
+                throw new Error(`Join step on '${step.table}' has ${from.length} \`from\` columns and ${to.length} \`to\` columns`);
+            }
+            return from.map((f, i) => ({ from: f, to: to[i] }));
+        };
+
+        const inner = joinPath.slice(0, -1);
+        const last = joinPath[joinPath.length - 1];
+
+        const joins: SQL[] = inner.map((step, index) => {
+            const table = registry.getTable(step.table);
+            if (!table) throw new Error(`Join table not found: ${step.table}`);
+            const on = pairs(step).map(({ from, to }) =>
+                sql`${fromRef(index, from)} = ${sql.identifier(aliasFor(index))}.${sql.identifier(getColumnName(to))}`
+            );
+            return sql`JOIN ${table} AS ${sql.identifier(aliasFor(index))} ON ${sql.join(on, sql` AND `)}`;
+        });
+
+        // The last step correlates to the outer row instead of joining the
+        // target table into the subquery.
+        //
+        // On the step's own `to` column, which is not always the target's
+        // primary key: a one-step path like `{ table: "posts", on: { from:
+        // "id", to: "author_id" } }` correlates through a foreign key, and
+        // matching `authors.id = posts.id` there compares two unrelated
+        // identifiers — which returns nothing, quietly. Referencing the Drizzle
+        // column rather than a bare name also keeps it qualified, so it binds
+        // to the outer target and not to a table joined inside the EXISTS.
+        const targetColumn = (name: string): AnyPgColumn => {
+            const column = targetTable[getColumnName(name) as keyof typeof targetTable] as AnyPgColumn;
+            if (!column) {
+                throw new Error(`Join step column '${name}' not found in the target table of this joinPath`);
+            }
+            return column;
+        };
+
+        const correlation = sql.join(
+            pairs(last).map(({ from, to }) => sql`${fromRef(inner.length, from)} = ${targetColumn(to)}`),
+            sql` AND `
+        );
+
+        const joinsSql = joins.length > 0 ? sql` ${sql.join(joins, sql` `)}` : sql``;
+
+        return sql`EXISTS (SELECT 1 FROM ${parentTable} AS ${sql.identifier(sourceAlias)}${joinsSql} WHERE ${sql.identifier(sourceAlias)}.${sql.identifier(parentIdColumn.name)} = ${parentId} AND ${correlation})`;
+    }
+
     /**
      * Build filter conditions from FilterValues
      */