@rebasepro/server-postgres 0.9.1-canary.1d2d8b5 → 0.9.1-canary.26fe4b2

package/src/services/FetchService.ts

@@ -7,15 +7,18 @@ import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
     getCollectionByPath,
     getTableForCollection,
-    getPrimaryKeys,
+    requirePrimaryKeys,
+    deriveRowAddress,
     parseIdValues,
-    buildCompositeId
+    buildCompositeId,
+    COMPOSITE_ID_SEPARATOR
 } from "./collection-helpers";
 import { parseDataFromServer, normalizeDbValues } from "../data-transformer";
 import { RelationService } from "./RelationService";
 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 { logger } from "@rebasepro/server";
 
 /** Type-safe accessor for Drizzle's relational query API via dynamic table name */
@@ -109,7 +112,7 @@ export class FetchService {
             // Detect many-to-many junction tables:
             // If the relation goes through a junction table (relation.through exists or
             // the Drizzle schema maps to a junction table), we need two-level with.
-            if (relation.cardinality === "many" && this.isJunctionRelation(relation, collection)) {
+            if (relation.cardinality === "many" && isJunctionRelation(relation)) {
                 // The Drizzle relation points to the junction table.
                 // We need: { [junctionRelName]: { with: { [targetFkName]: true } } }
                 // The target FK name is the relation on the junction table that points to the actual target.
@@ -127,17 +130,6 @@ export class FetchService {
         return withConfig;
     }
 
-    /**
-     * Detect if a many-to-many relation uses a junction table in the Drizzle schema.
-     */
-    private isJunctionRelation(relation: Relation, _collection: CollectionConfig): boolean {
-        // If `through` is defined, it's explicitly a junction relation
-        if (relation.through) return true;
-        // If joinPath has an intermediate table, it's likely junction-based
-        if (relation.joinPath && relation.joinPath.length > 1) return true;
-        return false;
-    }
-
     /**
      * 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).
@@ -151,88 +143,6 @@ export class FetchService {
         return null;
     }
 
-    /**
-     * Convert a db.query result row (with nested relation objects) to a flat row.
-     * Handles:
-     * - Placing `id` at the top level as a string
-     * - Type normalization (dates, numbers, NaN) via normalizeDbValues
-     * - Converting nested relation objects to { id, path, __type: "relation" } for CMS
-     * - Flattening junction-table many-to-many results
-     */
-    private drizzleResultToRow<M extends Record<string, unknown>>(
-        row: Record<string, unknown>,
-        collection: CollectionConfig,
-        _collectionPath: string,
-        idInfo: { fieldName: string; type: "string" | "number" },
-        _databaseId?: string,
-        idInfoArray?: { fieldName: string; type: "string" | "number" }[]
-    ): Record<string, unknown> {
-        const resolvedRelations = resolveCollectionRelations(collection);
-
-        // Normalize non-relation values (dates, numbers, etc.)
-        const normalizedValues = normalizeDbValues(row as M, collection) as Record<string, unknown>;
-
-        // Convert nested relation objects to CMS-style { id, path, __type: "relation" }
-        for (const [key, relation] of Object.entries(resolvedRelations)) {
-            const drizzleRelName = relation.relationName || key;
-            const relData = row[drizzleRelName];
-
-            if (relData === undefined || relData === null) continue;
-
-            if (relation.cardinality === "many" && Array.isArray(relData)) {
-                const targetCollection = relation.target();
-                const targetPath = targetCollection.slug;
-                const targetPks = getPrimaryKeys(targetCollection, this.registry);
-                const targetIdField = targetPks[0].fieldName;
-
-                normalizedValues[key] = relData.map((item: Record<string, unknown>) => {
-                    // Handle junction table flattening:
-                    // Junction rows look like { post_id: 1, tag_id: { id: 5, name: "ts" } }
-                    let targetRow = item;
-                    if (this.isJunctionRelation(relation, collection)) {
-                        // Find the nested target object in the junction row
-                        const nestedKey = Object.keys(item).find(
-                            nk => typeof item[nk] === "object" && item[nk] !== null && !Array.isArray(item[nk])
-                        );
-                        if (nestedKey) {
-                            targetRow = item[nestedKey] as Record<string, unknown>;
-                        }
-                    }
-
-                    const relId = String(targetRow[targetIdField] ?? targetRow.id ?? targetRow[Object.keys(targetRow)[0]]);
-                    const targetValues = normalizeDbValues(targetRow, targetCollection);
-
-                    return createRelationRefWithData(relId, targetPath, {
-                        id: relId,
-                        path: targetPath,
-                        values: targetValues
-                    });
-                });
-            } else if (relation.cardinality === "one" && typeof relData === "object" && !Array.isArray(relData)) {
-                const targetCollection = relation.target();
-                const targetPath = targetCollection.slug;
-                const targetPks = getPrimaryKeys(targetCollection, this.registry);
-                const targetIdField = targetPks[0].fieldName;
-                const relObj = relData as Record<string, unknown>;
-
-                const relId = String(relObj[targetIdField] ?? relObj.id ?? relObj[Object.keys(relObj)[0]]);
-                const targetValues = normalizeDbValues(relObj, targetCollection);
-
-                normalizedValues[key] = createRelationRefWithData(relId, targetPath, {
-                    id: relId,
-                    path: targetPath,
-                    values: targetValues
-                });
-            }
-        }
-
-        return {
-            ...normalizedValues,
-            // Spread the canonical id last so it wins over a raw `id` column
-            id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, unknown>, idInfoArray) : String(row[idInfo.fieldName])
-        };
-    }
-
     /**
      * Post-fetch joinPath relations for a single flat row.
      * joinPath relations cannot be expressed via Drizzle's `with` config,
@@ -274,57 +184,6 @@ export class FetchService {
         await Promise.all(promises);
     }
 
-    /**
-     * Post-fetch joinPath relations for a batch of flat rows.
-     * Uses batch fetching to avoid N+1 queries for list views.
-     */
-    private async resolveJoinPathRelationsBatch<M extends Record<string, unknown>>(
-        rows: Record<string, unknown>[],
-        collection: CollectionConfig,
-        collectionPath: string,
-        idInfo: { fieldName: string; type: "string" | "number" },
-        _databaseId?: string
-    ): Promise<void> {
-        if (rows.length === 0) return;
-
-        const resolvedRelations = resolveCollectionRelations(collection);
-
-        const joinPathRelations = Object.entries(resolvedRelations)
-            .filter(([key, relation]) => relation.joinPath && relation.joinPath.length > 0);
-
-        if (joinPathRelations.length === 0) return;
-
-        for (const [key, relation] of joinPathRelations) {
-            try {
-                const rowIds = rows.map(r => {
-                    const parsed = parseIdValues(String(r.id), [idInfo]);
-                    return parsed[idInfo.fieldName] as string | number;
-                });
-
-                const resultMap = await this.relationService.batchFetchRelatedEntities(
-                    collectionPath,
-                    rowIds,
-                    key,
-                    relation
-                );
-
-                for (const row of rows) {
-                    const parsed = parseIdValues(String(row.id), [idInfo]);
-                    const id = parsed[idInfo.fieldName] as string | number;
-                    const relatedRow = resultMap.get(String(id));
-
-                    if (relatedRow) {
-                        if (relation.cardinality === "one") {
-                            row[key] = createRelationRefWithData(relatedRow.id, relatedRow.path, relatedRow);
-                        }
-                    }
-                }
-            } catch (e) {
-                logger.warn(`Could not batch resolve joinPath relation '${key}'`, { error: e });
-            }
-        }
-    }
-
     /**
      * Resolves joinPath relations for raw REST rows and directly injects them.
      * Uses RelationService to query the database and maps results back to the flattened objects.
@@ -348,15 +207,25 @@ export class FetchService {
 
         if (joinPathRelations.length === 0) return;
 
-        const idInfo = idInfoArray[0];
+        // These rows carry their key columns verbatim, so the parent's address
+        // is derived from them. It used to be parsed back out of a synthesized
+        // `id` — which no longer exists on a row, and threw (composite: parts
+        // mismatch; numeric: NaN) into the catch below, where a warning is all
+        // that separates "no relations" from "relations dropped".
+        //
+        // The whole key, because that is what the batch groups its results by:
+        // both sides derive the token the same way, so they agree by
+        // construction rather than by both happening to pick column zero.
+        const parentIdOf = (row: Record<string, unknown>): string | undefined => {
+            const address = buildCompositeId(row, idInfoArray);
+            return address && address.split(COMPOSITE_ID_SEPARATOR).some(part => part !== "") ? address : undefined;
+        };
 
         for (const [key, relation] of joinPathRelations) {
             try {
-                // Determine the parent IDs based on the parsed string ID from the REST row
-                const rowIds = rows.map(r => {
-                    const parsed = parseIdValues(String(r.id), idInfoArray);
-                    return parsed[idInfo.fieldName] as string | number;
-                });
+                const addressable = rows.filter(r => parentIdOf(r) !== undefined && parentIdOf(r) !== null);
+                if (addressable.length === 0) continue;
+                const rowIds = addressable.map(r => parentIdOf(r) as string | number);
 
                 if (relation.cardinality === "one") {
                     const resultMap = await this.relationService.batchFetchRelatedEntities(
@@ -366,19 +235,11 @@ export class FetchService {
                         relation
                     );
 
-                    for (const row of rows) {
-                        const parsed = parseIdValues(String(row.id), idInfoArray);
-                        const id = parsed[idInfo.fieldName] as string | number;
-                        const relatedRow = resultMap.get(String(id));
-
-                        if (relatedRow) {
-                            row[key] = {
-                                ...relatedRow.values,
-                                id: relatedRow.id
-                            };
-                        } else {
-                            row[key] = null;
-                        }
+                    for (const row of addressable) {
+                        const relatedRow = resultMap.get(String(parentIdOf(row)));
+                        // Columns only: the target's address is the consumer's to
+                        // derive, and merging it last overwrote a real `id` column.
+                        row[key] = relatedRow ? { ...relatedRow.values } : null;
                     }
                 } else if (relation.cardinality === "many") {
                     const resultMap = await this.relationService.batchFetchRelatedEntitiesMany(
@@ -388,14 +249,9 @@ export class FetchService {
                         relation
                     );
 
-                    for (const row of rows) {
-                        const parsed = parseIdValues(String(row.id), idInfoArray);
-                        const id = parsed[idInfo.fieldName] as string | number;
-                        const relatedList = resultMap.get(String(id)) || [];
-                        row[key] = relatedList.map(e => ({
-                            ...e.values,
-                            id: e.id
-                        }));
+                    for (const row of addressable) {
+                        const relatedList = resultMap.get(String(parentIdOf(row))) || [];
+                        row[key] = relatedList.map(e => ({ ...e.values }));
                     }
                 }
             } catch (e) {
@@ -404,50 +260,6 @@ export class FetchService {
         }
     }
 
-    /**
-     * Convert a db.query result row to a flat REST-style object with populated relations.
-     */
-    private drizzleResultToRestRow(
-        row: Record<string, unknown>,
-        collection: CollectionConfig,
-        idInfo: { fieldName: string; type: "string" | "number" },
-        idInfoArray?: { fieldName: string; type: "string" | "number" }[]
-    ): Record<string, unknown> {
-        const flat: Record<string, unknown> = { id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, unknown>, idInfoArray) : String(row[idInfo.fieldName]) };
-        const resolvedRelations = resolveCollectionRelations(collection);
-
-        for (const [k, v] of Object.entries(row)) {
-            if (k === idInfo.fieldName) continue;
-
-            const relation = findRelation(resolvedRelations, k);
-            if (Array.isArray(v) && relation) {
-                // Many relation — flatten each nested row, handling junction tables
-                flat[k] = v.map((item: Record<string, unknown>) => {
-                    if (this.isJunctionRelation(relation, collection)) {
-                        const nestedKey = Object.keys(item).find(
-                            nk => typeof item[nk] === "object" && item[nk] !== null && !Array.isArray(item[nk])
-                        );
-                        if (nestedKey) {
-                            const nested = item[nestedKey] as Record<string, unknown>;
-                            return { ...nested,
-id: String(nested.id ?? nested[Object.keys(nested)[0]]) };
-                        }
-                    }
-                    return { ...item,
-id: String(item.id ?? item[Object.keys(item)[0]]) };
-                });
-            } else if (typeof v === "object" && v !== null && !Array.isArray(v) && relation) {
-                // One-to-one relation — inline the object
-                const relObj = v as Record<string, unknown>;
-                flat[k] = { ...relObj,
-id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]) };
-            } else {
-                flat[k] = v;
-            }
-        }
-        return flat;
-    }
-
     /**
      * Build db.query-compatible options from standard fetch options.
      * Handles filter, search, orderBy, limit, and cursor-based pagination.
@@ -589,7 +401,7 @@ id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]) };
     ): Promise<Record<string, unknown> | undefined> {
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
-        const idInfoArray = getPrimaryKeys(collection, this.registry);
+        const idInfoArray = requirePrimaryKeys(collection, this.registry);
         const idInfo = idInfoArray[0];
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
 
@@ -616,7 +428,7 @@ id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]) };
 
                 if (!row) return undefined;
 
-                const flatRow = this.drizzleResultToRow<M>(row, collection, collectionPath, idInfo, databaseId, idInfoArray);
+                const flatRow = toCmsRow(row, collection, this.registry);
 
                 // Post-fetch joinPath relations that Drizzle's `with` can't express
                 await this.resolveJoinPathRelations<M>(flatRow, collection, collectionPath, parsedId, databaseId);
@@ -708,7 +520,7 @@ id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]) };
     ): Promise<Record<string, unknown>[]> {
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
-        const idInfoArray = getPrimaryKeys(collection, this.registry);
+        const idInfoArray = requirePrimaryKeys(collection, this.registry);
         const idInfo = idInfoArray[0];
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
 
@@ -740,7 +552,7 @@ id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]) };
                 const results = await qb.findMany(queryOpts as Parameters<NonNullable<typeof qb>["findMany"]>[0]);
 
                 const rows = (results as Record<string, unknown>[]).map(row =>
-                    this.drizzleResultToRow<M>(row, collection, collectionPath, idInfo, options.databaseId, idInfoArray)
+                    toCmsRow(row, collection, this.registry)
                 );
 
                 return rows;
@@ -840,8 +652,10 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
 
     /**
      * Fallback path used when db.query is unavailable.
-     * The primary path uses drizzleResultToRow which handles relation
-     * mapping without N+1 queries.
+     *
+     * The primary path runs the results through `toCmsRow`, which maps
+     * relations from what drizzle already nested — no query per row. This one
+     * has no nesting to read, so it resolves relations itself, in batches.
      *
      * Process raw database results into flat rows with relations.
      */
@@ -864,11 +678,9 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         // relation type, avoiding the N+1 that plagued the old path.
         const parsedRows = await Promise.all(results.map(async (rawRow: Record<string, unknown>) => {
             const values = await parseDataFromServer(rawRow as M, collection) as Record<string, unknown>;
-            const id = (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(rawRow as Record<string, unknown>, idInfoArray!) : String(rawRow[idInfo.fieldName]);
             return {
                 rawRow,
-                values,
-                id
+                values
             };
         }));
 
@@ -938,10 +750,8 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             }
         }
 
-        return parsedRows.map(item => ({
-            ...item.values,
-            id: item.id
-        }));
+        // Columns only — the address is the consumer's to derive.
+        return parsedRows.map(item => item.values);
     }
 
     /**
@@ -1030,11 +840,12 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
                     relationKey,
                     options
                 );
-                // Convert RelatedRow[] from RelationService to flat rows
-                return rows.map(row => ({
-                    ...row.values as Record<string, unknown>,
-                    id: row.id
-                }));
+                // 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) {
@@ -1148,7 +959,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
 
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
-        const idInfoArray = getPrimaryKeys(collection, this.registry);
+        const idInfoArray = requirePrimaryKeys(collection, this.registry);
         const idInfo = idInfoArray[0];
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
         const field = table[fieldName as keyof typeof table] as AnyPgColumn;
@@ -1208,7 +1019,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
     ): Promise<Record<string, unknown>[]> {
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
-        const idInfoArray = getPrimaryKeys(collection, this.registry);
+        const idInfoArray = requirePrimaryKeys(collection, this.registry);
         const idInfo = idInfoArray[0];
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
 
@@ -1235,7 +1046,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
                 const results = await qb.findMany(queryOpts as Parameters<NonNullable<typeof qb>["findMany"]>[0]);
 
                 const restRows = (results as Record<string, unknown>[]).map(row =>
-                    this.drizzleResultToRestRow(row, collection, idInfo, idInfoArray)
+                    toRestRow(row, collection, this.registry)
                 );
 
                 // Drizzle relational query API doesn't resolve joinPath relations, fetch manually
@@ -1255,10 +1066,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         const rows = await this.fetchRowsWithConditionsRaw<M>(collectionPath, options);
 
         if (!include || include.length === 0) {
-            return rows.map(row => ({
-                ...row,
-                id: (idInfoArray.length > 1) ? buildCompositeId(row as Record<string, unknown>, idInfoArray) : String(row[idInfo.fieldName])
-            }));
+            return rows;
         }
 
         // Fallback relation loading via batch
@@ -1279,8 +1087,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
                     const eid = row[idInfo.fieldName] as string | number;
                     const related = batchResults.get(String(eid));
                     if (related) {
-                        (row as Record<string, unknown>)[key] = { ...related.values,
-id: related.id };
+                        (row as Record<string, unknown>)[key] = { ...related.values };
                     }
                 }
             } catch (e) {
@@ -1304,10 +1111,7 @@ id: related.id };
             }
         }
 
-        return rows.map(row => ({
-            ...row,
-            id: (idInfoArray.length > 1) ? buildCompositeId(row as Record<string, unknown>, idInfoArray) : String(row[idInfo.fieldName])
-        }));
+        return rows;
     }
 
     /**
@@ -1321,7 +1125,7 @@ id: related.id };
     ): Promise<Record<string, unknown> | null> {
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
-        const idInfoArray = getPrimaryKeys(collection, this.registry);
+        const idInfoArray = requirePrimaryKeys(collection, this.registry);
         const idInfo = idInfoArray[0];
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
 
@@ -1347,7 +1151,7 @@ id: related.id };
 
                 if (!row) return null;
 
-                const restRow = this.drizzleResultToRestRow(row, collection, idInfo, idInfoArray);
+                const restRow = toRestRow(row, collection, this.registry);
 
                 // Drizzle relational query API doesn't resolve joinPath relations, fetch manually
                 await this.resolveJoinPathRelationsBatchRest([restRow], collection, collectionPath, idInfoArray, include);
@@ -1371,9 +1175,7 @@ id: related.id };
 
         if (result.length === 0) return null;
 
-        const raw = result[0] as Record<string, unknown>;
-        const flatEntity: Record<string, unknown> = { ...raw,
-id: (idInfoArray.length > 1) ? buildCompositeId(raw as Record<string, unknown>, idInfoArray) : String(raw[idInfo.fieldName]) };
+        const flatEntity: Record<string, unknown> = { ...(result[0] as Record<string, unknown>) };
 
         if (!include || include.length === 0) {
             return flatEntity;
@@ -1431,7 +1233,7 @@ id: (idInfoArray.length > 1) ? buildCompositeId(raw as Record<string, unknown>,
     ): Promise<Record<string, unknown>[]> {
         const collection = getCollectionByPath(collectionPath, this.registry);
         const table = getTableForCollection(collection, this.registry);
-        const idInfoArray = getPrimaryKeys(collection, this.registry);
+        const idInfoArray = requirePrimaryKeys(collection, this.registry);
         const idInfo = idInfoArray[0];
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
 
@@ -1581,31 +1383,24 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
 
             const results = await queryTarget.findMany(queryOpts as Parameters<NonNullable<typeof queryTarget>["findMany"]>[0]);
 
-            // Flatten the nested Drizzle results into REST format
+            // Inline the nested Drizzle results, columns only — no synthesized id.
             return results.map((row: Record<string, unknown>) => {
-                const flat: Record<string, unknown> = { id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, unknown>, idInfoArray) : String(row[idInfo.fieldName]) };
+                const flat: Record<string, unknown> = {};
                 for (const [k, v] of Object.entries(row)) {
-                    if (k === idInfo.fieldName) continue;
                     if (Array.isArray(v)) {
-                        // Many relation — flatten each nested row
+                        // Many relation — inline each nested row
                         flat[k] = v.map((item: Record<string, unknown>) => {
-                            // Junction table rows may have the target nested, flatten those
+                            // Junction table rows may have the target nested, unwrap those
                             const keys = Object.keys(item);
-                            // If it looks like a junction row (only FKs + nested objects), extract nested
                             const nestedObj = keys.find(nk => typeof item[nk] === "object" && item[nk] !== null && !Array.isArray(item[nk]));
                             if (nestedObj && keys.length <= 3) {
-                                const nested = item[nestedObj] as Record<string, unknown>;
-                                return { ...nested,
-id: String(nested.id ?? nested[Object.keys(nested)[0]]) };
+                                return { ...(item[nestedObj] as Record<string, unknown>) };
                             }
-                            return { ...item,
-id: String(item.id ?? item[Object.keys(item)[0]]) };
+                            return { ...item };
                         });
                     } else if (typeof v === "object" && v !== null) {
-                        // One-to-one relation — inline the object
-                        const relObj = v as Record<string, unknown>;
-                        flat[k] = { ...relObj,
-id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]) };
+                        // One-to-one relation — inline the target's columns
+                        flat[k] = { ...(v as Record<string, unknown>) };
                     } else {
                         flat[k] = v;
                     }

package/src/services/PersistService.ts

@@ -115,12 +115,19 @@ export class PersistService {
 
     /**
      * Save an row (create or update)
+     *
+     * With `options.upsert`, the row is written with INSERT ... ON CONFLICT DO
+     * UPDATE against the primary key rather than a plain UPDATE. That is one
+     * statement, so it cannot lose a race the way a read-then-write can, and it
+     * does not care whether the row already exists — which is what a re-runnable
+     * import needs.
      */
     async save<M extends Record<string, unknown>>(
         collectionPath: string,
         values: Partial<M>,
         id?: string | number,
-        databaseId?: string
+        databaseId?: string,
+        options?: { upsert?: boolean }
     ): Promise<Record<string, unknown>> {
         // If saving under a nested relation path, resolve the parent and inject FK
         let effectiveCollectionPath = collectionPath;
@@ -255,7 +262,7 @@ export class PersistService {
             savedId = await this.db.transaction(async (tx) => {
                 let currentId: string | number;
 
-                if (id) {
+                if (id && !options?.upsert) {
                     // Update existing row
                     currentId = id; // `id` is already the formatted composite or singular string
                     const idValues = parseIdValues(id, idInfoArray);
@@ -295,6 +302,12 @@ export class PersistService {
                 } else {
                     const dataForInsert = { ...(entityData as Record<string, unknown>) };
 
+                    // An explicit id given alongside upsert is the conflict target,
+                    // so fold it into the row before the empty-key strip below.
+                    if (id && options?.upsert) {
+                        Object.assign(dataForInsert, parseIdValues(id, idInfoArray));
+                    }
+
                     // Strip empty primary keys so the database defaults (e.g. uuid_gen(), auto-increment) can trigger
                     for (const info of idInfoArray) {
                         if (dataForInsert[info.fieldName] === "" || dataForInsert[info.fieldName] === null || dataForInsert[info.fieldName] === undefined) {
@@ -302,13 +315,46 @@ export class PersistService {
                         }
                     }
 
-                    const result = await tx
-                        .insert(table)
-                        .values(dataForInsert)
-                        .returning(returningKeys);
+                    const insertQuery = tx.insert(table).values(dataForInsert);
+
+                    // ON CONFLICT needs a real conflict target, and the only one
+                    // guaranteed to exist is the primary key. Without every key
+                    // column present there is nothing to match on, so the row is a
+                    // plain insert and a duplicate should still raise.
+                    const hasFullKey = idInfoArray.length > 0
+                        && idInfoArray.every((info) => dataForInsert[info.fieldName] !== undefined);
+
+                    let result;
+                    if (options?.upsert && hasFullKey) {
+                        const target = idInfoArray.map((info) => table[info.fieldName as keyof typeof table] as AnyPgColumn);
+                        const set = { ...dataForInsert };
+                        // Never reassign the key columns to themselves in the UPDATE
+                        // branch; Postgres rejects that against the conflict target.
+                        for (const info of idInfoArray) delete set[info.fieldName];
+
+                        result = Object.keys(set).length > 0
+                            ? await insertQuery.onConflictDoUpdate({ target, set }).returning(returningKeys)
+                            : await insertQuery.onConflictDoNothing({ target }).returning(returningKeys);
+                    } else {
+                        result = await insertQuery.returning(returningKeys);
+                    }
 
+                    // DO NOTHING returns no row when it skipped, and an upsert whose
+                    // UPDATE branch is filtered by RLS returns none either. Fall back
+                    // to the id we were given rather than reading undefined.
                     const resultRow = result[0];
-                    currentId = buildCompositeId(resultRow, idInfoArray);
+                    if (!resultRow) {
+                        if (id) {
+                            currentId = id;
+                        } else {
+                            throw ApiError.forbidden(
+                                `Not allowed to write to "${effectiveCollectionPath}": the row was rejected by a row-level security policy.`,
+                                "WRITE_DENIED"
+                            );
+                        }
+                    } else {
+                        currentId = buildCompositeId(resultRow, idInfoArray);
+                    }
 
                     // For inserts, apply joinPath after since the parent row didn't exist before
                     if (joinPathRelationUpdates.length > 0) {
@@ -337,8 +383,15 @@ export class PersistService {
             throw this.toUserFriendlyError(error, collection.slug);
         }
 
-        // Fetch the updated/created row to return with proper relation objects
-        const finalEntity = await this.fetchService.fetchOne<M>(collection.slug, savedId, databaseId);
+        // Fetch the saved row back through the same walk `GET /:id` serves, so a
+        // write's answer is the read that follows it. This used to be `fetchOne`
+        // — the admin view-model walk — whose `__type: "relation"` refs then
+        // leaked into REST responses, afterSave callbacks, history records and
+        // app-level realtime payloads, none of which see that shape from any
+        // read path. The admin does not need them here either: its rows arrive
+        // over the realtime subscription refetch, which still serves the
+        // view-model walk.
+        const finalEntity = await this.fetchService.fetchOneForRest(collection.slug, savedId, undefined, databaseId);
         if (!finalEntity) throw new Error("Could not fetch row after save.");
         return finalEntity;
     }