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

package/src/services/FetchService.ts

@@ -19,6 +19,7 @@ import { RelationalQueryBuilder } from "drizzle-orm/pg-core/query-builders/query
 import { DrizzleClient } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { toCmsRow, toRestRow, isJunctionRelation } from "./row-pipeline";
+import { isNestedPath, resolveNestedPath, type NestedPathHop } from "./nested-path";
 import { logger } from "@rebasepro/server";
 
 /** Type-safe accessor for Drizzle's relational query API via dynamic table name */
@@ -279,7 +280,8 @@ export class FetchService {
             logical?: LogicalCondition;
         },
         collectionPath: string,
-        withConfig?: Record<string, unknown>
+        withConfig?: Record<string, unknown>,
+        scopeCondition?: SQL
     ): Record<string, unknown> {
         const queryOpts: Record<string, unknown> = {};
 
@@ -288,6 +290,8 @@ export class FetchService {
         // Build where conditions
         const allConditions: SQL[] = [];
 
+        if (scopeCondition) allConditions.push(scopeCondition);
+
         if (options.searchString) {
             const collection = getCollectionByPath(collectionPath, this.registry);
             const searchConditions = DrizzleConditionBuilder.buildSearchConditions(
@@ -391,6 +395,59 @@ export class FetchService {
         return [];
     }
 
+    /**
+     * Compile "rows reachable from this parent" into a `WHERE` condition on the
+     * target table, so a nested listing can run as an ordinary collection query.
+     */
+    private buildRelationScope(hop: NestedPathHop): SQL {
+        const parentPks = requirePrimaryKeys(hop.parentCollection, this.registry);
+        const parentIdInfo = parentPks[0];
+        const parsedParentId = parseIdValues(hop.parentId, parentPks)[parentIdInfo.fieldName];
+
+        const parent = () => {
+            const table = getTableForCollection(hop.parentCollection, this.registry);
+            const idColumn = table[parentIdInfo.fieldName as keyof typeof table] as AnyPgColumn;
+            if (!idColumn) {
+                throw new Error(`ID field '${parentIdInfo.fieldName}' not found in table for collection '${hop.parentCollection.slug}'`);
+            }
+            return { table,
+idColumn };
+        };
+
+        const targetTable = getTableForCollection(hop.targetCollection, this.registry);
+        const targetPks = requirePrimaryKeys(hop.targetCollection, this.registry);
+        const targetIdColumn = targetTable[targetPks[0].fieldName as keyof typeof targetTable] as AnyPgColumn;
+        if (!targetIdColumn) {
+            throw new Error(`ID field '${targetPks[0].fieldName}' not found in table for collection '${hop.targetCollection.slug}'`);
+        }
+
+        return DrizzleConditionBuilder.buildRelationScopeCondition(
+            hop.relation,
+            parent,
+            parsedParentId as string | number,
+            targetTable,
+            targetIdColumn,
+            this.registry
+        );
+    }
+
+    /**
+     * Whether `id` is actually reachable at `collectionPath`.
+     *
+     * Trivially true for a root path. For a nested one it is a real question:
+     * the path resolves to the target collection, and matching on the primary
+     * key alone made the parent segment decorative — `authors/1/posts/43`
+     * returned post 43 whoever wrote it, and the REST layer's delete then
+     * deleted it. A row that is not under this parent is reported as absent,
+     * which is what a caller addressing it through the parent should see.
+     */
+    private async isAddressableUnder(collectionPath: string, id: string | number): Promise<boolean> {
+        if (!isNestedPath(collectionPath)) return true;
+        const hop = resolveNestedPath(collectionPath, this.registry);
+        if (!hop) return true;
+        return this.relationService.isRelated(hop, id);
+    }
+
     /**
      * Fetch a single row by ID
      */
@@ -399,6 +456,8 @@ export class FetchService {
         id: string | number,
         databaseId?: string
     ): Promise<Record<string, unknown> | undefined> {
+        if (!await this.isAddressableUnder(collectionPath, id)) return undefined;
+
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
         const idInfoArray = requirePrimaryKeys(collection, this.registry);
@@ -516,8 +575,11 @@ export class FetchService {
             databaseId?: string;
             vectorSearch?: VectorSearchParams;
             logical?: LogicalCondition;
+            /** Narrow to the rows reachable from a parent through a relation. */
+            relatedTo?: NestedPathHop;
         } = {}
     ): Promise<Record<string, unknown>[]> {
+        const scopeCondition = options.relatedTo ? this.buildRelationScope(options.relatedTo) : undefined;
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
         const idInfoArray = requirePrimaryKeys(collection, this.registry);
@@ -545,7 +607,7 @@ export class FetchService {
         if (qb && !options.searchString && !hasRelations && !options.vectorSearch) {
             try {
                 const queryOpts = this.buildDrizzleQueryOptions<M>(
-                    table, idField, idInfo, options, collectionPath, undefined
+                    table, idField, idInfo, options, collectionPath, undefined, scopeCondition
                 );
 
 
@@ -578,6 +640,8 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             : this.db.select().from(table).$dynamic();
         const allConditions: SQL[] = [];
 
+        if (scopeCondition) allConditions.push(scopeCondition);
+
         if (options.searchString) {
             const searchConditions = DrizzleConditionBuilder.buildSearchConditions(
                 options.searchString, collection.properties, table
@@ -771,9 +835,13 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             vectorSearch?: VectorSearchParams;
         } = {}
     ): Promise<Record<string, unknown>[]> {
-        // Handle multi-segment paths by resolving through relations
-        if (collectionPath.includes("/")) {
-            return this.fetchCollectionFromPath<M>(collectionPath, options);
+        // A nested path is the target collection narrowed by a relation — the
+        // same query, one condition heavier. It used to be a separate builder
+        // that honoured `limit` and nothing else.
+        const hop = isNestedPath(collectionPath) ? resolveNestedPath(collectionPath, this.registry) : undefined;
+        if (hop) {
+            return this.fetchRowsWithConditions<M>(hop.targetCollection.slug, { ...options,
+relatedTo: hop });
         }
 
         return this.fetchRowsWithConditions<M>(collectionPath, options);
@@ -799,65 +867,6 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         });
     }
 
-    /**
-     * Fetch collection from multi-segment path
-     */
-    private async fetchCollectionFromPath<M extends Record<string, unknown>>(
-        path: string,
-        options: {
-            filter?: FilterValues<Extract<keyof M, string>>;
-            orderBy?: string;
-            order?: "desc" | "asc";
-            limit?: number;
-            startAfter?: Record<string, unknown>;
-            searchString?: string;
-            databaseId?: string;
-        } = {}
-    ): Promise<Record<string, unknown>[]> {
-        const pathSegments = path.split("/").filter(p => p && p !== "undefined");
-
-        if (pathSegments.length < 3 || pathSegments.length % 2 === 0) {
-            throw new Error(`Invalid relation path: ${path}. Expected format: collection/id/relation`);
-        }
-
-        const rootCollectionPath = pathSegments[0];
-        let currentCollection = getCollectionByPath(rootCollectionPath, this.registry);
-        let currentId: string | number = pathSegments[1];
-
-        for (let i = 2; i < pathSegments.length; i += 2) {
-            const relationKey = pathSegments[i];
-            const resolvedRelations = resolveCollectionRelations(currentCollection);
-            const relation = findRelation(resolvedRelations, relationKey);
-
-            if (!relation) {
-                throw new Error(`Relation '${relationKey}' not found in collection '${currentCollection.slug}'`);
-            }
-
-            if (i === pathSegments.length - 1) {
-                const rows = await this.relationService.fetchRelatedEntities<M>(
-                    currentCollection.slug,
-                    currentId,
-                    relationKey,
-                    options
-                );
-                // Flatten RelatedRow[] to rows: the target's columns, and only
-                // those. Merging `row.id` in last overwrote a real `id` column,
-                // and the address is derivable without it — a consumer resolves
-                // this path ("posts/1/comments") to the target collection and
-                // reads the key columns, which `values` carries.
-                return rows.map(row => ({ ...row.values as Record<string, unknown> }));
-            }
-
-            if (i + 1 < pathSegments.length) {
-                const nextEntityId = pathSegments[i + 1];
-                currentCollection = relation.target();
-                currentId = nextEntityId;
-            }
-        }
-
-        throw new Error(`Unable to resolve path: ${path}`);
-    }
-
     /**
      * Count rows in a collection
      */
@@ -869,16 +878,20 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             databaseId?: string;
         } = {}
     ): Promise<number> {
-        if (collectionPath.includes("/")) {
-            return this.countEntitiesFromPath<M>(collectionPath, options);
-        }
+        // Same narrowing as the listing — and, unlike the count it replaces,
+        // the same `filter` and `searchString` too, so `total` describes the
+        // rows that were actually served.
+        const hop = isNestedPath(collectionPath) ? resolveNestedPath(collectionPath, this.registry) : undefined;
+        const effectivePath = hop ? hop.targetCollection.slug : collectionPath;
 
-        const collection = getCollectionByPath(collectionPath, this.registry);
+        const collection = getCollectionByPath(effectivePath, this.registry);
         const table = getTableForCollection(collection, this.registry);
 
         let query = this.db.select({ count: count() }).from(table).$dynamic();
         const allConditions: SQL[] = [];
 
+        if (hop) allConditions.push(this.buildRelationScope(hop));
+
         if (options.searchString) {
             const searchConditions = DrizzleConditionBuilder.buildSearchConditions(
                 options.searchString, collection.properties, table
@@ -888,7 +901,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         }
 
         if (options.filter) {
-            const filterConditions = this.buildFilterConditions(options.filter, table, collectionPath);
+            const filterConditions = this.buildFilterConditions(options.filter, table, effectivePath);
             if (filterConditions.length > 0) allConditions.push(...filterConditions);
         }
 
@@ -901,50 +914,6 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         return Number(result[0]?.count || 0);
     }
 
-    /**
-     * Count rows from multi-segment path
-     */
-    private async countEntitiesFromPath<M extends Record<string, unknown>>(
-        path: string,
-        options: { filter?: FilterValues<Extract<keyof M, string>>; databaseId?: string } = {}
-    ): Promise<number> {
-        const pathSegments = path.split("/").filter(p => p && p !== "undefined");
-
-        if (pathSegments.length < 3 || pathSegments.length % 2 === 0) {
-            throw new Error(`Invalid relation path: ${path}`);
-        }
-
-        const rootCollectionPath = pathSegments[0];
-        let currentCollection = getCollectionByPath(rootCollectionPath, this.registry);
-        let currentId: string | number = pathSegments[1];
-
-        for (let i = 2; i < pathSegments.length; i += 2) {
-            const relationKey = pathSegments[i];
-            const resolvedRelations = resolveCollectionRelations(currentCollection);
-            const relation = findRelation(resolvedRelations, relationKey);
-
-            if (!relation) {
-                throw new Error(`Relation '${relationKey}' not found`);
-            }
-
-            if (i === pathSegments.length - 1) {
-                return this.relationService.countRelatedEntities(
-                    currentCollection.slug,
-                    currentId,
-                    relationKey,
-                    options
-                );
-            }
-
-            if (i + 1 < pathSegments.length) {
-                currentCollection = relation.target();
-                currentId = pathSegments[i + 1];
-            }
-        }
-
-        throw new Error(`Unable to count for path: ${path}`);
-    }
-
     /**
      * Check if a field value is unique
      */
@@ -1014,9 +983,25 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             searchString?: string;
             databaseId?: string;
             vectorSearch?: VectorSearchParams;
+            /** Narrow to the rows reachable from a parent through a relation. */
+            relatedTo?: NestedPathHop;
         } = {},
         include?: string[]
     ): Promise<Record<string, unknown>[]> {
+        // Resolve a nested path here rather than at the route, so `include`,
+        // `offset` and the rest reach a child listing by the same route they
+        // reach a root one.
+        if (isNestedPath(collectionPath)) {
+            const hop = resolveNestedPath(collectionPath, this.registry);
+            if (hop) {
+                return this.fetchCollectionForRest<M>(
+                    hop.targetCollection.slug, { ...options,
+relatedTo: hop }, include
+                );
+            }
+        }
+
+        const scopeCondition = options.relatedTo ? this.buildRelationScope(options.relatedTo) : undefined;
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
         const idInfoArray = requirePrimaryKeys(collection, this.registry);
@@ -1039,7 +1024,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
                     : undefined;
 
                 const queryOpts = this.buildDrizzleQueryOptions<M>(
-                    table, idField, idInfo, options, collectionPath, withConfig
+                    table, idField, idInfo, options, collectionPath, withConfig, scopeCondition
                 );
 
 
@@ -1123,6 +1108,8 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         include?: string[],
         databaseId?: string
     ): Promise<Record<string, unknown> | null> {
+        if (!await this.isAddressableUnder(collectionPath, id)) return null;
+
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
         const idInfoArray = requirePrimaryKeys(collection, this.registry);
@@ -1229,6 +1216,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             startAfter?: Record<string, unknown>;
             searchString?: string;
             vectorSearch?: VectorSearchParams;
+            relatedTo?: NestedPathHop;
         } = {}
     ): Promise<Record<string, unknown>[]> {
         const collection = getCollectionByPath(collectionPath, this.registry);
@@ -1248,6 +1236,8 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             : this.db.select().from(table).$dynamic();
         const allConditions: SQL[] = [];
 
+        if (options.relatedTo) allConditions.push(this.buildRelationScope(options.relatedTo));
+
         if (options.searchString) {
             const searchConditions = DrizzleConditionBuilder.buildSearchConditions(
                 options.searchString, collection.properties, table

package/src/services/PersistService.ts

@@ -2,7 +2,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 { getTableName, resolveCollectionRelations, findRelation } from "@rebasepro/common";
+import { getTableName, resolveCollectionRelations } from "@rebasepro/common";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
     getCollectionByPath,
@@ -16,6 +16,13 @@ import { RelationService } from "./RelationService";
 import { FetchService } from "./FetchService";
 import { DrizzleClient } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import {
+    assertWritableThrough,
+    isJunctionBackedRelation,
+    isNestedPath,
+    resolveNestedPath,
+    type NestedPathHop
+} from "./nested-path";
 import { ApiError, logger } from "@rebasepro/server";
 import { extractPgError, extractCauseMessage, pgErrorToFriendlyMessage } from "../utils/pg-error-utils";
 
@@ -80,6 +87,33 @@ export class PersistService {
      * Delete an row by ID
      */
     async delete(collectionPath: string, id: string | number, _databaseId?: string): Promise<void> {
+        // A nested address deletes *through* a relation, and what that removes
+        // depends on who owns the target row.
+        const hop = isNestedPath(collectionPath) ? resolveNestedPath(collectionPath, this.registry) : undefined;
+        if (hop) {
+            assertWritableThrough(hop, collectionPath);
+
+            if (!await this.relationService.isRelated(hop, id)) {
+                throw ApiError.notFound(`No row "${id}" in "${collectionPath}" to delete.`);
+            }
+
+            if (isJunctionBackedRelation(hop.relation)) {
+                // Shared target: drop the link, not the row.
+                if (!hop.relation.through) {
+                    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}" ` +
+                        "directly if that is what you meant.",
+                        "RELATION_NOT_UNLINKABLE"
+                    );
+                }
+                await this.relationService.unlinkRelatedEntity(this.db, hop, id);
+                return;
+            }
+            // Owned child (inverse FK): deleting the row is the right meaning,
+            // and membership above has established it is this parent's child.
+        }
+
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
         const idInfoArray = getPrimaryKeys(collection, this.registry);
@@ -113,6 +147,44 @@ export class PersistService {
         await this.db.delete(table);
     }
 
+    /**
+     * The column on the *target* table that records the parent, for a create
+     * under a nested one-to-many path.
+     *
+     * Returns `undefined` when the link is not a column at all (a multi-hop
+     * `joinPath`), so the caller writes the row without stamping anything.
+     *
+     * `relation.localKey` is deliberately not consulted: it names a column on
+     * the *source* table. Falling back to it here — which is what this used to
+     * 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];
+        }
+
+        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"
+        );
+    }
+
     /**
      * Save an row (create or update)
      *
@@ -129,93 +201,59 @@ export class PersistService {
         databaseId?: string,
         options?: { upsert?: boolean }
     ): Promise<Record<string, unknown>> {
-        // If saving under a nested relation path, resolve the parent and inject FK
+        // 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;
 
-        if (collectionPath.includes("/")) {
-            const segments = collectionPath.split("/").filter(Boolean);
-            if (segments.length >= 3 && segments.length % 2 === 1) {
-                const rootSegment = segments[0];
-                let currentCollection = getCollectionByPath(rootSegment, this.registry);
-                let currentId: string | number = segments[1];
-
-                for (let i = 2; i < segments.length; i += 2) {
-                    const relationKey = segments[i];
-                    const resolvedRelations = resolveCollectionRelations(currentCollection);
-                    const relation = findRelation(resolvedRelations, relationKey);
-
-                    if (!relation) {
-                        const available = Object.keys(resolvedRelations).join(", ") || "(none)";
-                        throw new Error(`Relation '${relationKey}' not found in collection '${currentCollection.slug}'. Available relations: [${available}]`);
-                    }
-
-                    if (i === segments.length - 1) {
-                        const targetCollection = relation.target();
-                        effectiveCollectionPath = targetCollection.slug;
-
-                        // Handle many-to-many with junction table
-                        if (relation.cardinality === "many" && relation.through) {
-                            const parentIdInfoArray = getPrimaryKeys(currentCollection, this.registry);
-                            const parentIdInfo = parentIdInfoArray[0];
-                            const parsedParentIdObj = parseIdValues(currentId, parentIdInfoArray);
-                            const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
-
-                            junctionTableInfo = {
-                                parentCollection: currentCollection,
-                                parentId: parsedParentId,
-                                relation: relation,
-                                relationKey: relationKey
-                            };
-                            break;
-                        }
-
-                        // Find the FK column that should store the parent ID
-                        let targetColumnName: string;
-
-                        if (relation.localKey) {
-                            targetColumnName = relation.localKey;
-                        } else if (relation.foreignKeyOnTarget) {
-                            targetColumnName = relation.foreignKeyOnTarget;
-                        } else if (relation.joinPath && relation.joinPath.length === 1) {
-                            const targetTableName = getTableName(targetCollection);
-                            const relevantJoinStep = relation.joinPath.find(joinStep => joinStep.table === targetTableName);
-
-                            if (relevantJoinStep) {
-                                const targetColumnNames = DrizzleConditionBuilder.getColumnNamesFromColumns(relevantJoinStep.on.to);
-                                targetColumnName = targetColumnNames[0];
-                            } else {
-                                logger.warn(`Could not find specific join step for target table ${targetTableName} in relation '${relationKey}'.`);
-                                const targetColumnNames = DrizzleConditionBuilder.getColumnNamesFromColumns(relation.joinPath[0].on.to);
-                                targetColumnName = targetColumnNames[0];
-                            }
-                        } else if (relation.joinPath && relation.joinPath.length > 1) {
-                            // For multi-hop relations (like many-to-many through a junction table),
-                            // there is no direct foreign key on the target table pointing to the parent.
-                            // The relationship is managed via the junction table.
-                            // We shouldn't inject the parent ID directly into the target row payload.
-                            break;
-                        } else {
-                            throw new Error(`Relation '${relationKey}' lacks configuration for path-based saving.`);
-                        }
-
-                        const parentIdInfoArray = getPrimaryKeys(currentCollection, this.registry);
-                        const parentIdInfo = parentIdInfoArray[0];
-                        const parsedParentIdObj = parseIdValues(currentId, parentIdInfoArray);
-                        const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
-
-                        const existingValue = (effectiveValues as Record<string, unknown>)[targetColumnName];
-                        if (existingValue !== undefined && existingValue !== null && existingValue !== parsedParentId) {
-                            logger.warn(`Overriding provided value '${existingValue}' for FK '${targetColumnName}' with path parent id '${parsedParentId}'.`);
-                        }
-                        (effectiveValues as Record<string, unknown>)[targetColumnName] = parsedParentId;
-                        break;
-                    } else {
-                        const nextEntityId = segments[i + 1];
-                        currentCollection = relation.target();
-                        currentId = nextEntityId;
+        const hop = isNestedPath(collectionPath) ? resolveNestedPath(collectionPath, this.registry) : undefined;
+
+        if (hop) {
+            assertWritableThrough(hop, collectionPath);
+            effectiveCollectionPath = hop.targetCollection.slug;
+
+            const parentIdForWrite = () => {
+                const parentPks = getPrimaryKeys(hop.parentCollection, this.registry);
+                return parseIdValues(hop.parentId, parentPks)[parentPks[0].fieldName];
+            };
+
+            if (hop.relation.through) {
+                // 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,
+                // idempotently, which is what makes `PUT parent/id/child/childId`
+                // able to attach a row that already exists.
+                //
+                // Unlike an owning foreign key, this takes the row from nobody:
+                // its other parents keep it. That is why linking is safe here
+                // where reparenting (below) is not.
+                junctionTableInfo = {
+                    parentCollection: hop.parentCollection,
+                    parentId: parentIdForWrite(),
+                    relation: hop.relation,
+                    relationKey: hop.relationKey
+                };
+            } else if (id !== undefined) {
+                // Updating an existing row *through* an owning parent. The parent
+                // segment is an assertion about where the row already lives, not
+                // an instruction to move it there: injecting the FK here silently
+                // reparented whatever id was named, so `PUT authors/1/posts/43`
+                // stole post 43 from its real author. Check membership instead,
+                // and leave the FK to an explicit value in the body.
+                if (!await this.relationService.isRelated(hop, id)) {
+                    throw ApiError.notFound(`No row "${id}" in "${collectionPath}" to update.`);
+                }
+            } else {
+                // One-to-many create: stamp the parent's id onto the child's FK.
+                const targetColumnName = this.resolveParentForeignKeyColumn(hop);
+
+                if (targetColumnName) {
+                    const parsedParentId = parentIdForWrite();
+                    const existingValue = (effectiveValues as Record<string, unknown>)[targetColumnName];
+                    if (existingValue !== undefined && existingValue !== null && existingValue !== parsedParentId) {
+                        logger.warn(`Overriding provided value '${existingValue}' for FK '${targetColumnName}' with path parent id '${parsedParentId}'.`);
                     }
+                    (effectiveValues as Record<string, unknown>)[targetColumnName] = parsedParentId;
                 }
             }
         }
@@ -372,8 +410,12 @@ export class PersistService {
                     await this.relationService.updateRelationsUsingJoins(tx, collection, currentId, relationValues);
                 }
 
-                // Handle junction table creation for many-to-many path-based saves
-                if (junctionTableInfo && !id) {
+                // Attach the row to the parent's set. Runs for updates as well as
+                // creates — it used to be gated on `!id`, which is why a row that
+                // already existed could never be added to a parent through its
+                // path. The insert is idempotent, so re-asserting a link is a
+                // no-op rather than a duplicate-key error.
+                if (junctionTableInfo) {
                     await this.relationService.handleJunctionTableCreation(tx, currentId, junctionTableInfo);
                 }