@rebasepro/server-postgres 0.10.1-canary.ed8caed → 0.10.1-canary.g4db1bb1

package/src/services/FetchService.ts

@@ -1,6 +1,6 @@
 import { and, asc, count, desc, eq, getTableName, gt, lt, or, SQL, TableRelationalConfig, TablesRelationalConfig } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
-import { CollectionConfig, FilterValues, Relation, LogicalCondition } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, LogicalCondition, isManyToMany } from "@rebasepro/types";
 import type { VectorSearchParams } from "@rebasepro/types";
 import { resolveCollectionRelations, findRelation, createRelationRef, createRelationRefWithData } from "@rebasepro/common";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
@@ -73,7 +73,7 @@ export class FetchService {
         let orderByField = table[orderBy as keyof typeof table] as AnyPgColumn;
         if (!orderByField && collection) {
             const property = collection.properties[orderBy];
-            if (property && property.type === "relation" && "relation" in property && property.relation?.direction === "owning") {
+            if (property && property.type === "relation" && "relation" in property && property.resolvedRelation?.kind === "belongsTo") {
                 orderByField = table[`${orderBy}_id` as keyof typeof table] as AnyPgColumn;
             }
         }
@@ -106,7 +106,7 @@ export class FetchService {
             const drizzleRelName = relation.relationName || key;
 
             // Skip relations that use joinPath as they are not mapped in Drizzle schemas
-            if (relation.joinPath && relation.joinPath.length > 0) {
+            if (relation.kind === "via") {
                 continue;
             }
 
@@ -135,8 +135,8 @@ export class FetchService {
      * Get the Drizzle relation name on the junction table that points to the actual target row.
      * For example, for posts_tags junction, this returns "tag_id" (the relation pointing to tags).
      */
-    private getJunctionTargetRelationName(relation: Relation, _collection: CollectionConfig): string | null {
-        if (relation.through) {
+    private getJunctionTargetRelationName(relation: ResolvedRelation, _collection: CollectionConfig): string | null {
+        if (isManyToMany(relation)) {
             // The junction relation on the junction table pointing to the target
             // uses the targetColumn name as the Drizzle relation name
             return relation.through.targetColumn.replace(/_id$/, "_id");
@@ -159,7 +159,7 @@ export class FetchService {
         const resolvedRelations = resolveCollectionRelations(collection);
 
         const promises = Object.entries(resolvedRelations)
-            .filter(([key, relation]) => relation.joinPath && relation.joinPath.length > 0)
+            .filter(([key, relation]) => relation.kind === "via")
             .map(async ([key, relation]) => {
                 try {
                     const relatedRows = await this.relationService.fetchRelatedEntities(
@@ -204,7 +204,7 @@ export class FetchService {
             !include || include.length === 0 || include[0] === "*" || include.includes(key);
 
         const joinPathRelations = Object.entries(resolvedRelations)
-            .filter(([key, relation]) => relation.joinPath && relation.joinPath.length > 0 && propertyKeys.has(key) && shouldInclude(key));
+            .filter(([key, relation]) => relation.kind === "via" && propertyKeys.has(key) && shouldInclude(key));
 
         if (joinPathRelations.length === 0) return;
 
@@ -495,7 +495,7 @@ idColumn };
                 return flatRow;
             } catch (e) {
                 if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
-                    logger.error(`[FetchService] Relation inference error for collection '${collectionPath}': ${e.message}`);
+                    logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
                     logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
                 }
                 logger.warn(`[FetchService] db.query.findFirst failed for ${collectionPath}, falling back to db.select`, { error: e });
@@ -620,7 +620,7 @@ idColumn };
                 return rows;
             } catch (e) {
                 if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
-                    logger.error(`[FetchService] Relation inference error for collection '${collectionPath}': ${e.message}`);
+                    logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
                     logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
                 }
                 logger.warn(`[FetchService] db.query.findMany failed for ${collectionPath}, falling back to db.select`, { error: e });
@@ -1040,7 +1040,7 @@ relatedTo: hop }, include
                 return restRows;
             } catch (e) {
                 if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
-                    logger.error(`[FetchService] Relation inference error for collection '${collectionPath}': ${e.message}`);
+                    logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
                     logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
                 }
                 logger.warn(`[fetchCollectionForRest] db.query.findMany failed for ${collectionPath}, falling back`, { error: e });
@@ -1146,7 +1146,7 @@ relatedTo: hop }, include
                 return restRow;
             } catch (e) {
                 if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
-                    logger.error(`[FetchService] Relation inference error for collection '${collectionPath}': ${e.message}`);
+                    logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
                     logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
                 }
                 logger.warn(`[fetchOneForRest] db.query.findFirst failed for ${collectionPath}, falling back`, { error: e });
@@ -1424,7 +1424,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         const relation = resolvedRelations[relationKey];
 
         if (!relation) {
-            logger.warn(`[batchFetchManyRelatedRows] Relation '${relationKey}' not found, skipping`);
+            logger.warn(`[batchFetchManyRelatedRows] ResolvedRelation '${relationKey}' not found, skipping`);
             return new Map();
         }
 

package/src/services/PersistService.ts

@@ -1,7 +1,7 @@
 import { eq, and, sql, SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 // import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { CollectionConfig, Properties, Relation } from "@rebasepro/types";
+import { CollectionConfig, Properties, ResolvedRelation, type ResolvedManyToMany, isManyToMany } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations } from "@rebasepro/common";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
@@ -99,7 +99,7 @@ export class PersistService {
 
             if (isJunctionBackedRelation(hop.relation)) {
                 // Shared target: drop the link, not the row.
-                if (!hop.relation.through) {
+                if (!isManyToMany(hop.relation)) {
                     throw ApiError.badRequest(
                         `"${collectionPath}" reaches '${hop.targetCollection.slug}' through a multi-hop joinPath, ` +
                         `so there is no single link to remove. Delete the row at "${hop.targetCollection.slug}" ` +
@@ -159,30 +159,26 @@ export class PersistService {
      * do, and first — stamped the parent's own foreign key onto the child row.
      */
     private resolveParentForeignKeyColumn(hop: NestedPathHop): string | undefined {
-        const { relation, relationKey, targetCollection } = hop;
-
-        if (relation.foreignKeyOnTarget) return relation.foreignKeyOnTarget;
-
-        if (relation.joinPath && relation.joinPath.length === 1) {
-            const joinStep = relation.joinPath[0];
-            const targetTableName = getTableName(targetCollection);
-            if (joinStep.table !== targetTableName) {
-                logger.warn(`Join step for relation '${relationKey}' targets '${joinStep.table}', not the target table '${targetTableName}'.`);
-            }
-            return DrizzleConditionBuilder.getColumnNamesFromColumns(joinStep.on.to)[0];
+        const { relation } = hop;
+
+        switch (relation.kind) {
+            case "hasOne":
+            case "hasMany":
+                return relation.foreignKeyOnTarget;
+
+            case "via":
+                // The link lives in an intermediate table, not in a column on
+                // the target — nothing to stamp.
+                return relation.joinPath.length === 1
+                    ? DrizzleConditionBuilder.getColumnNamesFromColumns(relation.joinPath[0].on.to)[0]
+                    : undefined;
+
+            default:
+                // `belongsTo` names a column on the *parent*, and `manyToMany`
+                // is written as a junction row. Neither is a column here, and
+                // `assertWritableThrough` has already rejected the first.
+                return undefined;
         }
-
-        if (relation.joinPath && relation.joinPath.length > 1) {
-            // Multi-hop: the link lives in an intermediate table, not in a
-            // column on the target. Nothing to stamp.
-            return undefined;
-        }
-
-        throw ApiError.badRequest(
-            `Relation '${relationKey}' on '${hop.parentCollection.slug}' cannot be written through: it declares no ` +
-            "`foreignKeyOnTarget` (the column on " + `'${targetCollection.slug}'` + " that records the parent) and no `joinPath`.",
-            "RELATION_NOT_WRITABLE"
-        );
     }
 
     /**
@@ -204,7 +200,7 @@ export class PersistService {
         // If saving under a nested relation path, resolve the relation it ends in.
         let effectiveCollectionPath = collectionPath;
         const effectiveValues: Partial<M> = { ...values };
-        let junctionTableInfo: { parentCollection: CollectionConfig; parentId: string | number; relation: Relation; relationKey: string; } | undefined;
+        let junctionTableInfo: { parentCollection: CollectionConfig; parentId: string | number; relation: ResolvedManyToMany; relationKey: string; } | undefined;
 
         const hop = isNestedPath(collectionPath) ? resolveNestedPath(collectionPath, this.registry) : undefined;
 
@@ -217,7 +213,7 @@ export class PersistService {
                 return parseIdValues(hop.parentId, parentPks)[parentPks[0].fieldName];
             };
 
-            if (hop.relation.through) {
+            if (isManyToMany(hop.relation)) {
                 // A junction path addresses set membership, so a write through it
                 // asserts "this row is in this parent's set" — on create *and* on
                 // update. The junction row is written after the main write below,

package/src/services/RelationService.ts

@@ -1,8 +1,9 @@
 import { and, eq, inArray, or, sql, SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import { DrizzleClient } from "../interfaces";
-import { CollectionConfig, FilterValues, Relation } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations, findRelation } from "@rebasepro/common";
+import { hasForeignKeyOnTarget, isManyToMany, type ResolvedVia } from "@rebasepro/types";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
     getCollectionByPath,
@@ -181,7 +182,7 @@ export class RelationService {
     async fetchEntitiesUsingJoins<M extends Record<string, unknown>>(
         parentCollection: CollectionConfig,
         parentId: string | number,
-        relation: Relation,
+        relation: ResolvedRelation,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
             orderBy?: string;
@@ -206,7 +207,7 @@ export class RelationService {
         const parentIdCol = parentTable[parentIdInfo.fieldName as keyof typeof parentTable] as AnyPgColumn;
 
         // Handle join path relations
-        if (relation.joinPath && relation.joinPath.length > 0) {
+        if (relation.kind === "via") {
             let query = this.db.select().from(parentTable).$dynamic();
             let currentTable = parentTable;
 
@@ -349,7 +350,7 @@ export class RelationService {
     private async countRelatedRows(
         parentCollection: CollectionConfig,
         parentId: string | number,
-        relation: Relation,
+        relation: ResolvedRelation,
         additionalFilters: SQL[]
     ): Promise<number> {
         const targetCollection = relation.target();
@@ -424,10 +425,10 @@ export class RelationService {
         hop: NestedPathHop,
         targetId: string | number
     ): Promise<void> {
-        const through = hop.relation.through;
-        if (!through) {
+        if (!isManyToMany(hop.relation)) {
             throw new Error(`Relation '${hop.relationKey}' has no junction table to unlink through`);
         }
+        const through = hop.relation.through;
 
         const junctionTable = this.registry.getTable(through.table);
         if (!junctionTable) {
@@ -462,7 +463,7 @@ export class RelationService {
         parentCollectionPath: string,
         parentIds: (string | number)[],
         _relationKey: string,
-        relation: Relation
+        relation: ResolvedRelation
     ): Promise<Map<string, RelatedRow<Record<string, unknown>>>> {
         if (parentIds.length === 0) return new Map();
 
@@ -483,7 +484,7 @@ export class RelationService {
         const parsedParentIds = parentIds.map(id => parseIdValues(id, parentPks)[parentIdInfo.fieldName]);
 
         // Handle join path relations with batching
-        if (relation.joinPath && relation.joinPath.length > 0) {
+        if (relation.kind === "via") {
             let query = this.db.select().from(parentTable).$dynamic();
             let currentTable = parentTable;
 
@@ -542,7 +543,7 @@ export class RelationService {
         //   1. Fetch FK values from the parent table in a single query
         //   2. Query the target table with unique FK values
         //   3. Map results back to parent rows via their FK values
-        if (relation.direction === "owning" && relation.localKey) {
+        if (relation.kind === "belongsTo") {
             this.assertSingleKeyAddressable(parentCollection, parentPks, relation.localKey);
             const localKeyCol = parentTable[relation.localKey as keyof typeof parentTable] as AnyPgColumn;
             if (!localKeyCol) {
@@ -606,7 +607,7 @@ export class RelationService {
         this.assertSingleKeyAddressable(
             parentCollection,
             parentPks,
-            relation.foreignKeyOnTarget ?? `${relation.inverseRelationName}_id`
+            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName
         );
         let query = this.db.select().from(targetTable).$dynamic();
 
@@ -639,11 +640,13 @@ export class RelationService {
             // Determine the parent ID this result belongs to based on the relation type
             let parentId: string | number | undefined;
 
-            if (relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+            // The parent's key is on the target row, in the relation's own
+            // column. There used to be a second branch here that guessed the
+            // column by appending `_id` to `inverseRelationName`, reached only
+            // when the foreign key had not been resolved — which cannot happen
+            // now that resolution fills it in.
+            if (hasForeignKeyOnTarget(relation)) {
                 parentId = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
-            } else if (relation.direction === "inverse" && relation.cardinality === "one" && relation.inverseRelationName) {
-                const inferredForeignKeyName = `${relation.inverseRelationName}_id`;
-                parentId = targetRow[inferredForeignKeyName] as string | number | undefined;
             }
 
             if (parentId !== undefined && parentIdSet.has(String(parentId))) {
@@ -663,7 +666,7 @@ export class RelationService {
         parentCollectionPath: string,
         parentIds: (string | number)[],
         _relationKey: string,
-        relation: Relation
+        relation: ResolvedRelation
     ): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>> {
         if (parentIds.length === 0) return new Map();
 
@@ -683,7 +686,7 @@ export class RelationService {
         const parsedParentIds = parentIds.map(id => parseIdValues(id, parentPks)[parentIdInfo.fieldName]);
 
         // Handle join path relations (many-to-many through junction tables)
-        if (relation.joinPath && relation.joinPath.length > 0) {
+        if (relation.kind === "via") {
             let query = this.db.select().from(parentTable).$dynamic();
             let currentTable = parentTable;
 
@@ -725,7 +728,7 @@ export class RelationService {
         // Handle many-to-many owning relations with junction table (relation.through)
         // This is the standard path for posts→tags style relations where
         // sanitizeRelation populated the `through` config.
-        if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
+        if (relation.kind === "manyToMany") {
             // The junction names its parent with one column, so the same
             // single-key limit applies as for a direct foreign key.
             this.assertSingleKeyAddressable(parentCollection, parentPks, `${relation.through.table}.${relation.through.sourceColumn}`);
@@ -775,7 +778,7 @@ export class RelationService {
         this.assertSingleKeyAddressable(
             parentCollection,
             parentPks,
-            relation.foreignKeyOnTarget ?? `${relation.inverseRelationName}_id`
+            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName
         );
         let query = this.db.select().from(targetTable).$dynamic();
 
@@ -805,16 +808,10 @@ export class RelationService {
 
             let parentId: string | number | undefined;
 
-            if (relation.through && relation.direction === "inverse") {
-                // Inverse many-to-many via junction table: the junction's targetColumn
-                // references the parent (since from the inverse perspective, source/target are swapped).
-                const junctionData = (row[relation.through.table] || row) as Record<string, unknown>;
-                parentId = junctionData[relation.through.targetColumn] as string | number | undefined;
-            } else if (relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+            // Junction-backed relations returned earlier in this method, so
+            // what reaches here names the parent with a column on the target.
+            if (hasForeignKeyOnTarget(relation)) {
                 parentId = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
-            } else if (relation.direction === "inverse" && relation.inverseRelationName) {
-                const inferredForeignKeyName = `${relation.inverseRelationName}_id`;
-                parentId = targetRow[inferredForeignKeyName] as string | number | undefined;
             }
 
             if (parentId !== undefined && parentIdSet.has(String(parentId))) {
@@ -847,7 +844,7 @@ export class RelationService {
             const targetCollection = relation.target();
 
             // Use joinPath if available
-            if (relation.joinPath && relation.joinPath.length > 0) {
+            if (relation.kind === "via") {
                 const parentTableName = getTableName(collection);
                 const targetTableName = getTableName(targetCollection);
 
@@ -913,7 +910,7 @@ export class RelationService {
                         await tx.insert(junctionTable).values(newLinks);
                     }
                 }
-            } else if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
+            } else if (relation.kind === "manyToMany") {
                 // Handle many-to-many relations with junction table using 'through' property
                 const junctionTable = this.registry.getTable(relation.through.table);
                 if (!junctionTable) {
@@ -951,11 +948,7 @@ export class RelationService {
                         await tx.insert(junctionTable).values(newLinks);
                     }
                 }
-            } else if (relation.through && relation.cardinality === "many" && relation.direction === "inverse") {
-                // Inverse M2M relations should be saved from the owning side.
-                // The owning collection manages the junction table rows.
-                logger.warn(`[updateRelationsUsingJoins] Inverse M2M relation '${key}' in collection '${collection.slug}' should be saved from the owning side. Skipping.`);
-            } else if (relation.cardinality === "many" && relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+            } else if (relation.cardinality === "many" && hasForeignKeyOnTarget(relation)) {
                 // Handle one-to-many (inverse) by updating target FK to point to parent
                 const targetTable = getTableForCollection(targetCollection, this.registry);
                 const targetPks = requirePrimaryKeys(targetCollection, this.registry);
@@ -1008,7 +1001,7 @@ export class RelationService {
         sourceEntityId: string | number,
         inverseRelationUpdates: Array<{
             relationKey: string;
-            relation: Relation;
+            relation: ResolvedRelation;
             newValue: unknown;
         }>
     ) {
@@ -1023,8 +1016,7 @@ export class RelationService {
                 const sourcePks = requirePrimaryKeys(sourceCollection, this.registry);
                 const sourceIdInfo = sourcePks[0];
 
-                // Handle inverse relations with joinPath
-                if (relation.direction === "inverse" && relation.joinPath && relation.joinPath.length > 0) {
+                if (relation.kind === "via") {
                     await this.updateInverseJoinPathRelation(
                         tx,
                         sourceCollection,
@@ -1036,42 +1028,31 @@ export class RelationService {
                     continue;
                 }
 
-                // Check if this is a many-to-many inverse relation
-                if (relation.cardinality === "many" && relation.direction === "inverse") {
-                    const targetCollectionRelations = resolveCollectionRelations(targetCollection);
-                    let junctionInfo: { table: string; sourceColumn: string; targetColumn: string } | null = null;
-
-                    for (const [relationKey, targetRelation] of Object.entries(targetCollectionRelations)) {
-                        if (targetRelation.cardinality === "many" &&
-                            targetRelation.direction === "owning" &&
-                            targetRelation.through &&
-                            (targetRelation.relationName === relation.inverseRelationName || relationKey === relation.inverseRelationName)) {
-                            junctionInfo = {
-                                table: targetRelation.through.table,
-                                sourceColumn: targetRelation.through.targetColumn,
-                                targetColumn: targetRelation.through.sourceColumn
-                            };
-                            break;
+                // A many-to-many names its own junction. This used to walk the
+                // *target's* relations looking for an owning side whose
+                // `relationName` matched `inverseRelationName`, and swap its
+                // source/target columns — a search that silently did nothing
+                // when the far side was declared differently than expected.
+                if (isManyToMany(relation)) {
+                    await this.updateManyToManyInverseRelation(
+                        tx,
+                        sourceCollection,
+                        sourceEntityId,
+                        targetCollection,
+                        relation,
+                        newValue,
+                        {
+                            table: relation.through.table,
+                            sourceColumn: relation.through.sourceColumn,
+                            targetColumn: relation.through.targetColumn
                         }
-                    }
-
-                    if (junctionInfo) {
-                        await this.updateManyToManyInverseRelation(
-                            tx,
-                            sourceCollection,
-                            sourceEntityId,
-                            targetCollection,
-                            relation,
-                            newValue,
-                            junctionInfo
-                        );
-                        continue;
-                    }
+                    );
+                    continue;
                 }
 
-                // Handle simple inverse relations
-                if (!relation.foreignKeyOnTarget) {
-                    logger.warn(`Inverse relation '${relation.relationName}' is missing foreignKeyOnTarget property. Skipping.`);
+                // What is left names the parent with a column on the target.
+                if (!hasForeignKeyOnTarget(relation)) {
+                    logger.warn(`Relation '${relation.relationName}' has no column on the target to write. Skipping.`);
                     continue;
                 }
 
@@ -1120,14 +1101,10 @@ export class RelationService {
         sourceCollection: CollectionConfig,
         sourceEntityId: string | number,
         targetCollection: CollectionConfig,
-        relation: Relation,
+        relation: ResolvedVia,
         newValue: unknown
     ) {
         try {
-            if (!relation.joinPath || relation.joinPath.length === 0) {
-                logger.warn(`Inverse relation '${relation.relationName}' missing joinPath`);
-                return;
-            }
 
             const sourceTableName = getTableName(sourceCollection);
             const targetTableName = getTableName(targetCollection);
@@ -1230,7 +1207,7 @@ export class RelationService {
         sourceCollection: CollectionConfig,
         sourceEntityId: string | number,
         targetCollection: CollectionConfig,
-        relation: Relation,
+        relation: ResolvedRelation,
         newValue: unknown,
         junctionInfo: { table: string; sourceColumn: string; targetColumn: string }
     ) {
@@ -1288,7 +1265,9 @@ export class RelationService {
         parentId: string | number,
         updates: Array<{
             relationKey: string;
-            relation: Relation;
+            // Only a `via` relation has a join path to write through, and the
+            // caller only collects those.
+            relation: ResolvedVia;
             newTargetId: string | number | null;
         }>
     ) {
@@ -1366,7 +1345,7 @@ export class RelationService {
      */
     resolveJoinPathWriteMapping(
         parentCollection: CollectionConfig,
-        relation: Relation
+        relation: ResolvedVia
     ): { targetFKColName: string; parentSourceColName: string } {
         if (!relation.joinPath || relation.joinPath.length === 0) {
             throw new Error("resolveJoinPathWriteMapping requires a joinPath relation");
@@ -1405,7 +1384,10 @@ parentSourceColName };
         junctionTableInfo: {
             parentCollection: CollectionConfig;
             parentId: string | number;
-            relation: Relation;
+            // Only a junction-backed relation has a link to write, and the
+            // caller only builds this for one — stated here so the body needs
+            // no narrowing.
+            relation: ResolvedManyToMany;
             relationKey: string;
         }
     ) {
@@ -1413,14 +1395,14 @@ parentSourceColName };
         const targetCollection = relation.target();
 
         try {
-            const junctionTable = this.registry.getTable(relation.through!.table);
+            const junctionTable = this.registry.getTable(relation.through.table);
             if (!junctionTable) {
-                logger.warn(`Junction table '${relation.through!.table}' not found for relation '${relationKey}'`);
+                logger.warn(`Junction table '${relation.through.table}' not found for relation '${relationKey}'`);
                 return;
             }
 
-            const sourceJunctionColumn = junctionTable[relation.through!.sourceColumn as keyof typeof junctionTable] as AnyPgColumn;
-            const targetJunctionColumn = junctionTable[relation.through!.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
+            const sourceJunctionColumn = junctionTable[relation.through.sourceColumn as keyof typeof junctionTable] as AnyPgColumn;
+            const targetJunctionColumn = junctionTable[relation.through.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
 
             if (!sourceJunctionColumn || !targetJunctionColumn) {
                 logger.warn(`Junction columns not found for relation '${relationKey}'`);

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

@@ -0,0 +1,91 @@
+import { CollectionConfig, ResolvedRelation, isManyToMany } 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, ResolvedRelation>;
+        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)) {
+            if (!isManyToMany(relation)) continue;
+            const through = relation.through;
+
+            // 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;
+}