@rebasepro/server-postgres 0.12.1-canary.gf5f1d39 → 0.13.0

package/src/services/RelationService.ts

@@ -1,7 +1,7 @@
 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, ResolvedRelation, ResolvedManyToMany } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations, findRelation } from "@rebasepro/common";
 import { hasForeignKeyOnTarget, isManyToMany, type ResolvedVia } from "@rebasepro/types";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
@@ -11,6 +11,8 @@ import {
     requirePrimaryKeys,
     parseIdValues,
     buildCompositeId,
+    joinsOnNaturalKey,
+    sourceKeyField,
     type PrimaryKeyInfo
 } from "./collection-helpers";
 import { parseDataFromServer } from "../data-transformer";
@@ -18,6 +20,39 @@ import { PostgresCollectionRegistry } from "../collections/PostgresCollectionReg
 import { logger } from "@rebasepro/server";
 import type { NestedPathHop } from "./nested-path";
 
+/**
+ * The ids in a to-many relation write, whatever shape the caller sent.
+ *
+ * A membership list is written as either the related rows (`[{ id: 1 }]`, what
+ * the admin UI sends back after reading them) or as bare keys (`[1]`, `["t-1"]`,
+ * what anyone writing the API by hand sends). Only the first was read, via a
+ * blind `.map(rel => rel.id)`, and a bare key therefore became `undefined`:
+ * on a numeric-keyed target that surfaced as `Invalid numeric ID: undefined`,
+ * and on a string-keyed one it did not surface at all — `String(undefined)`
+ * wrote a junction row pointing at the literal `"undefined"`, which no read
+ * would ever match. Both shapes are accepted here, in one place, because both
+ * call sites had the same assumption.
+ *
+ * An element that carries no key is refused rather than skipped: dropping it
+ * would silently write a shorter membership list than the caller asked for.
+ */
+function relationTargetIds(value: unknown, relationName: string, collectionSlug: string): (string | number)[] {
+    if (!Array.isArray(value)) return [];
+
+    return value.map((element, index) => {
+        if (typeof element === "string" || typeof element === "number") return element;
+        if (element && typeof element === "object") {
+            const id = (element as { id?: unknown }).id;
+            if (typeof id === "string" || typeof id === "number") return id;
+        }
+        throw new Error(
+            `Cannot write relation "${relationName}" on "${collectionSlug}": element ${index} carries no id. ` +
+            "Pass either the related rows (`[{ id: … }]`) or their keys (`[1, 2]`), not " +
+            `${element === null ? "null" : typeof element}.`
+        );
+    });
+}
+
 /**
  * Typed wrapper for Drizzle dynamic query innerJoin.
  * Drizzle's `$dynamic()` queries lose the `innerJoin` method from
@@ -135,18 +170,122 @@ export class RelationService {
     private assertSingleKeyAddressable(
         parentCollection: CollectionConfig,
         parentPks: PrimaryKeyInfo[],
-        via: string
+        via: string,
+        relation?: ResolvedRelation
     ): void {
+        // A `sourceKey` names the single column the link actually points at, so
+        // the parent's key can be as wide as it likes — nothing here references
+        // it. That is the one way out of this error, and the message below now
+        // has to say so.
+        if (relation && hasForeignKeyOnTarget(relation) && relation.sourceKey) return;
+
         if (parentPks.length > 1) {
             throw new Error(
                 `Relation on '${parentCollection.slug}' uses '${via}', a single foreign-key column, but ` +
                 `'${parentCollection.slug}' is keyed on ${parentPks.map(k => `'${k.fieldName}'`).join(" + ")}. ` +
-                `One column cannot reference a composite key — express this relation with \`joinPath\`, whose ` +
+                `One column cannot reference a composite key — give the relation a \`sourceKey\` naming ` +
+                `a single unique column to point at, or express it with \`joinPath\`, whose ` +
                 `\`on.from\`/\`on.to\` take every key column.`
             );
         }
     }
 
+    /**
+     * What the target's foreign key holds, for each of these parent rows.
+     *
+     * Ordinarily the parent's id, and then this is free. When the relation
+     * declares a `sourceKey` the two are different values, and the mapping
+     * between them lives in the source table — so it costs one SELECT, issued
+     * once for the whole batch rather than per parent.
+     *
+     * Both directions come back because both are needed and deriving one from
+     * the other by hand is how a batch loader ends up attributing a child to the
+     * wrong parent: reads translate id → key to build the WHERE, and then
+     * translate key → id to attribute each row that comes back.
+     */
+    /**
+     * The value a related row's foreign key must hold to belong to this parent.
+     *
+     * `undefined` when the parent's source key is null — which is not an error
+     * here, only in the callers that were about to write it. Exposed for
+     * {@link PersistService}, which stamps this onto a child created under a
+     * nested path and would otherwise write the id and lose the row.
+     */
+    async parentKeyValue(
+        parentCollection: CollectionConfig,
+        relation: ResolvedHasOne | ResolvedHasMany,
+        parentId: string | number,
+        db: DrizzleClient = this.db
+    ): Promise<string | number | undefined> {
+        const { keyByParentId } = await this.resolveSourceKeys(parentCollection, relation, [parentId], db);
+        return keyByParentId.get(String(parentId));
+    }
+
+    private async resolveSourceKeys(
+        parentCollection: CollectionConfig,
+        relation: ResolvedHasOne | ResolvedHasMany,
+        parentIds: (string | number)[],
+        // Writes pass their transaction: reading the source key on the pool
+        // while the same transaction is holding an uncommitted change to it
+        // would translate the id against a stale value.
+        db: DrizzleClient = this.db
+    ): Promise<{ keyByParentId: Map<string, string | number>; parentIdByKey: Map<string, string | number> }> {
+        const keyByParentId = new Map<string, string | number>();
+        const parentIdByKey = new Map<string, string | number>();
+
+        const parentPks = requirePrimaryKeys(parentCollection, this.registry);
+
+        if (!joinsOnNaturalKey(relation, parentCollection, this.registry)) {
+            // The ordinary case, and it must stay free of a round-trip: the
+            // key IS the id. Parsed, not passed through — an id arrives as the
+            // string from a URL, and comparing "7" against an integer column is
+            // how this returns nothing at all.
+            for (const id of parentIds) {
+                const value = parseIdValues(id, parentPks)[parentPks[0].fieldName];
+                keyByParentId.set(String(id), value);
+                parentIdByKey.set(String(value), id);
+            }
+            return { keyByParentId, parentIdByKey };
+        }
+
+        const field = sourceKeyField(relation, parentCollection, this.registry);
+        const parentTable = getTableForCollection(parentCollection, this.registry);
+        const keyColumn = parentTable[field as keyof typeof parentTable] as AnyPgColumn;
+        if (!keyColumn) {
+            throw new Error(
+                `\`sourceKey: "${field}"\` on relation '${relation.relationName}' is not a column on ` +
+                `'${parentCollection.slug}'. It names a column on the source table, not on the target.`
+            );
+        }
+
+        const rows = await db
+            .select()
+            .from(parentTable)
+            .where(this.parentKeyCondition(parentTable, parentPks, parentIds));
+
+        for (const row of rows as Array<Record<string, unknown>>) {
+            const keyValue = row[field] as string | number | null;
+            if (keyValue === null || keyValue === undefined) continue;
+            const parentId = buildCompositeId(row, parentPks);
+            keyByParentId.set(String(parentId), keyValue);
+            // A duplicate here means the source key is not unique, which makes
+            // "which parent does this child belong to" unanswerable. Refuse
+            // rather than pick the last one seen.
+            const existing = parentIdByKey.get(String(keyValue));
+            if (existing !== undefined && String(existing) !== String(parentId)) {
+                throw new Error(
+                    `\`sourceKey: "${field}"\` on relation '${relation.relationName}' is not unique on ` +
+                    `'${parentCollection.slug}': rows '${existing}' and '${parentId}' both hold ` +
+                    `'${keyValue}'. Add a unique constraint — a link that addresses more than one source ` +
+                    `row cannot say which one a related row belongs to.`
+                );
+            }
+            parentIdByKey.set(String(keyValue), parentId);
+        }
+
+        return { keyByParentId, parentIdByKey };
+    }
+
     /**
      * Fetch rows related to a parent row through a specific relation
      */
@@ -259,7 +398,21 @@ export class RelationService {
             return rows;
         }
 
-        // Handle other relation types
+        // Handle other relation types.
+        //
+        // The query builder compares the target's foreign key against a value,
+        // and for a link on a natural key that value is not the id in the URL.
+        // Resolved first, before anything is built, so a parent that reaches
+        // nothing costs one statement rather than two.
+        const matchValue = hasForeignKeyOnTarget(relation)
+            ? (await this.resolveSourceKeys(parentCollection, relation, [parentId]))
+                .keyByParentId.get(String(parentId))
+            : parsedParentId;
+
+        // A parent whose source key is null reaches nothing: NULL never equals
+        // a foreign key. Say so with an empty list rather than an `= NULL`.
+        if (matchValue === undefined) return [];
+
         let query = this.db.select().from(targetTable).$dynamic();
 
         // Build additional filter conditions
@@ -289,7 +442,7 @@ export class RelationService {
             query,
             query,
             relation,
-            parsedParentId,
+            matchValue,
             targetTable,
             parentTable,
             parentIdCol,
@@ -367,6 +520,16 @@ export class RelationService {
         if (!parentTable) throw new Error("Parent table not found");
         const parentIdCol = parentTable[parentIdInfo.fieldName as keyof typeof parentTable] as AnyPgColumn;
 
+        // Same translation the listing does, and it has to be: `isRelated`
+        // gates writes on this count, so a count built from a different value
+        // than the read would authorise rows the read never returned.
+        const matchValue = hasForeignKeyOnTarget(relation)
+            ? (await this.resolveSourceKeys(parentCollection, relation, [parentId]))
+                .keyByParentId.get(String(parentId))
+            : parsedParentId;
+
+        if (matchValue === undefined) return 0;
+
         // Start count with distinct to avoid duplicates from junction tables
         let query = this.db.select({ count: sql<number>`count(distinct ${targetIdField})` }).from(targetTable).$dynamic();
 
@@ -374,7 +537,7 @@ export class RelationService {
         query = DrizzleConditionBuilder.buildRelationCountQuery(
             query,
             relation,
-            parsedParentId,
+            matchValue,
             targetTable,
             parentTable,
             parentIdCol,
@@ -607,8 +770,22 @@ export class RelationService {
         this.assertSingleKeyAddressable(
             parentCollection,
             parentPks,
-            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName
+            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName,
+            relation
         );
+
+        // One lookup for the whole batch, both directions: the WHERE is built
+        // from the source-key values, and each row that comes back carries one
+        // of those values rather than a parent id.
+        const { keyByParentId, parentIdByKey } = hasForeignKeyOnTarget(relation)
+            ? await this.resolveSourceKeys(parentCollection, relation, parentIds)
+            : { keyByParentId: new Map<string, string | number>(), parentIdByKey: new Map<string, string | number>() };
+
+        const matchValues = hasForeignKeyOnTarget(relation)
+            ? [...keyByParentId.values()]
+            : parsedParentIds;
+        if (matchValues.length === 0) return new Map();
+
         let query = this.db.select().from(targetTable).$dynamic();
 
         // Build the relation query with ALL parent IDs
@@ -616,7 +793,7 @@ export class RelationService {
             query,
             query,
             relation,
-            parsedParentIds, // Pass array instead of single ID
+            matchValues, // Pass array instead of single ID
             targetTable,
             parentTable,
             parentIdCol,
@@ -628,28 +805,24 @@ export class RelationService {
         const results = await query;
         const resultMap = new Map<string, RelatedRow<Record<string, unknown>>>();
 
-        // Build a Set<string> for O(1) parent-ID lookups that is immune to
-        // number-vs-string type mismatches (Drizzle may return either depending
-        // on the column type and driver).
-        const parentIdSet = new Set(parsedParentIds.map(String));
-
         // Map results back to parent rows
         for (const row of results as Array<Record<string, unknown>>) {
             const targetRow = (row[getTableName(targetCollection)] || row) as Record<string, unknown>;
 
-            // Determine the parent ID this result belongs to based on the relation type
-            let parentId: string | number | undefined;
-
             // 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;
-            }
+            if (!hasForeignKeyOnTarget(relation)) continue;
+
+            // Keyed by string throughout: Drizzle returns a numeric column as a
+            // number or a string depending on the column type and the driver.
+            const foreignKeyValue = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
+            if (foreignKeyValue === undefined || foreignKeyValue === null) continue;
 
-            if (parentId !== undefined && parentIdSet.has(String(parentId))) {
+            const parentId = parentIdByKey.get(String(foreignKeyValue));
+            if (parentId !== undefined) {
                 resultMap.set(String(parentId), await this.toRelatedRow(targetRow, targetCollection, targetPks));
             }
         }
@@ -778,15 +951,26 @@ export class RelationService {
         this.assertSingleKeyAddressable(
             parentCollection,
             parentPks,
-            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName
+            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName,
+            relation
         );
+
+        const { keyByParentId, parentIdByKey } = hasForeignKeyOnTarget(relation)
+            ? await this.resolveSourceKeys(parentCollection, relation, parentIds)
+            : { keyByParentId: new Map<string, string | number>(), parentIdByKey: new Map<string, string | number>() };
+
+        const matchValues = hasForeignKeyOnTarget(relation)
+            ? [...keyByParentId.values()]
+            : parsedParentIds;
+        if (matchValues.length === 0) return new Map();
+
         let query = this.db.select().from(targetTable).$dynamic();
 
         query = applyDynamicRelationQuery(
             query,
             query,
             relation,
-            parsedParentIds,
+            matchValues,
             targetTable,
             parentTable,
             parentIdCol,
@@ -798,23 +982,18 @@ export class RelationService {
         const results = await query;
         const resultMap = new Map<string, RelatedRow<Record<string, unknown>>[]>();
 
-        // Build a Set<string> for O(1) parent-ID lookups that is immune to
-        // number-vs-string type mismatches (Drizzle may return either depending
-        // on the column type and driver).
-        const parentIdSet = new Set(parsedParentIds.map(String));
-
         for (const row of results as Array<Record<string, unknown>>) {
             const targetRow = (row[getTableName(targetCollection)] || row) as Record<string, unknown>;
 
-            let parentId: string | number | undefined;
-
             // 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;
-            }
+            if (!hasForeignKeyOnTarget(relation)) continue;
 
-            if (parentId !== undefined && parentIdSet.has(String(parentId))) {
+            const foreignKeyValue = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
+            if (foreignKeyValue === undefined || foreignKeyValue === null) continue;
+
+            const parentId = parentIdByKey.get(String(foreignKeyValue));
+            if (parentId !== undefined) {
                 const key = String(parentId);
                 const arr = resultMap.get(key) || [];
                 arr.push(await this.toRelatedRow(targetRow, targetCollection, targetPks));
@@ -840,7 +1019,7 @@ export class RelationService {
             const relation = findRelation(resolvedRelations, key);
             if (!relation || relation.cardinality !== "many") continue;
 
-            const targetEntityIds = (value && Array.isArray(value)) ? value.map((rel: { id: string | number }) => rel.id) : [];
+            const targetEntityIds = relationTargetIds(value, key, collection.slug);
             const targetCollection = relation.target();
 
             // Use joinPath if available
@@ -961,10 +1140,19 @@ export class RelationService {
                     continue;
                 }
 
-                const parentPks = requirePrimaryKeys(collection, this.registry);
-                const parentIdInfo = parentPks[0];
-                const parsedParentIdObj = parseIdValues(id, parentPks);
-                const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
+                // What the children's foreign key must hold — the parent's id
+                // unless the link declares a `sourceKey`, and then the value of
+                // that column on this parent row.
+                const parentKeyValue = (await this.resolveSourceKeys(collection, relation, [id], tx))
+                    .keyByParentId.get(String(id));
+
+                if (parentKeyValue === undefined) {
+                    throw new Error(
+                        `Cannot write relation '${key}' on '${collection.slug}': row '${id}' has no value in ` +
+                        `\`sourceKey: "${sourceKeyField(relation, collection, this.registry)}"\`, so there is ` +
+                        "nothing for the related rows to point at."
+                    );
+                }
 
                 // Clear existing links not in the new set
                 if (targetEntityIds.length > 0) {
@@ -972,19 +1160,19 @@ export class RelationService {
                     await tx
                         .update(targetTable)
                         .set({ [relation.foreignKeyOnTarget]: null })
-                        .where(and(eq(fkCol, parsedParentId), sql`${targetIdCol} NOT IN (${sql.join(parsedTargetIds)})`));
+                        .where(and(eq(fkCol, parentKeyValue), sql`${targetIdCol} NOT IN (${sql.join(parsedTargetIds)})`));
 
                     // Set FK for the provided targets
                     await tx
                         .update(targetTable)
-                        .set({ [relation.foreignKeyOnTarget]: parsedParentId })
+                        .set({ [relation.foreignKeyOnTarget]: parentKeyValue })
                         .where(inArray(targetIdCol as AnyPgColumn, parsedTargetIds as unknown[]));
                 } else {
                     // If empty array provided, clear all existing links for this parent
                     await tx
                         .update(targetTable)
                         .set({ [relation.foreignKeyOnTarget]: null })
-                        .where(eq(fkCol, parsedParentId));
+                        .where(eq(fkCol, parentKeyValue));
                 }
             } else {
                 logger.warn(`Many relation '${key}' in collection '${collection.slug}' lacks write configuration and will be skipped during save.`);
@@ -1062,14 +1250,25 @@ export class RelationService {
                     continue;
                 }
 
-                const parsedSourceIdObj = parseIdValues(sourceEntityId, sourcePks);
-                const parsedSourceId = parsedSourceIdObj[sourceIdInfo.fieldName];
+                // The value the target's foreign key holds: this row's id, or
+                // the column named by `sourceKey` when the link joins on one.
+                const sourceKeyValue = (await this.resolveSourceKeys(sourceCollection, relation, [sourceEntityId], tx))
+                    .keyByParentId.get(String(sourceEntityId));
+
+                if (sourceKeyValue === undefined) {
+                    throw new Error(
+                        `Cannot write relation '${relation.relationName}' on '${sourceCollection.slug}': row ` +
+                        `'${sourceEntityId}' has no value in \`sourceKey: ` +
+                        `"${sourceKeyField(relation, sourceCollection, this.registry)}"\`, so there is nothing ` +
+                        "for the related row to point at."
+                    );
+                }
 
                 if (newValue === null || newValue === undefined) {
                     await tx
                         .update(targetTable)
                         .set({ [relation.foreignKeyOnTarget!]: null })
-                        .where(eq(foreignKeyColumn, parsedSourceId));
+                        .where(eq(foreignKeyColumn, sourceKeyValue));
                 } else {
                     const parsedNewTargetIdObj = parseIdValues(newValue as string | number, targetPks);
                     const parsedNewTargetId = parsedNewTargetIdObj[targetIdInfo.fieldName];
@@ -1079,12 +1278,12 @@ export class RelationService {
                     await tx
                         .update(targetTable)
                         .set({ [relation.foreignKeyOnTarget!]: null })
-                        .where(eq(foreignKeyColumn, parsedSourceId));
+                        .where(eq(foreignKeyColumn, sourceKeyValue));
 
                     // Then, update the new target row to point to this source row
                     await tx
                         .update(targetTable)
-                        .set({ [relation.foreignKeyOnTarget!]: parsedSourceId })
+                        .set({ [relation.foreignKeyOnTarget!]: sourceKeyValue })
                         .where(eq(targetIdField, parsedNewTargetId));
                 }
             } catch (e) {
@@ -1166,7 +1365,9 @@ export class RelationService {
                 if (newValue && Array.isArray(newValue) && newValue.length > 0) {
                     const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                     const targetIdInfo = targetPks[0];
-                    const targetEntityIds = (newValue as Array<{ id: string | number } | string | number>).map((rel) => typeof rel === "object" && rel !== null ? rel.id : rel);
+                    // This path already read both shapes; the other two did not.
+                    // Same helper now, so the three cannot drift again.
+                    const targetEntityIds = relationTargetIds(newValue, relation.relationName, sourceCollection.slug);
                     const parsedTargetIds = targetEntityIds.map(id => parseIdValues(id, targetPks)[targetIdInfo.fieldName]);
 
                     const newLinks = parsedTargetIds.map(targetId => ({
@@ -1238,7 +1439,7 @@ export class RelationService {
             if (newValue && Array.isArray(newValue) && newValue.length > 0) {
                 const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                 const targetIdInfo = targetPks[0];
-                const targetEntityIds = (newValue as Array<{ id: string | number }>).map((rel) => rel.id);
+                const targetEntityIds = relationTargetIds(newValue, relation.relationName, sourceCollection.slug);
                 const parsedTargetIds = targetEntityIds.map(id => parseIdValues(id, targetPks)[targetIdInfo.fieldName]);
 
                 const newLinks = parsedTargetIds.map(targetId => ({

package/src/services/channel-bus/index.ts

@@ -80,15 +80,6 @@ export function resolveChannelBusSetting(configured?: ChannelBusSetting): Channe
     return raw === "memory" ? { type: "memory" } : { type: "postgres" };
 }
 
-/**
- * @deprecated Use {@link resolveChannelBusSetting}, which also accepts a
- * supplied {@link ChannelBus} instance. Kept as a narrow alias so existing
- * config-only callers keep their exact types.
- */
-export function resolveChannelBusConfig(configured?: ChannelBusConfig): ChannelBusConfig {
-    return resolveChannelBusSetting(configured) as ChannelBusConfig;
-}
-
 /**
  * Produce the bus a setting asks for.
  *

package/src/services/collection-helpers.ts

@@ -1,5 +1,5 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
-import { CollectionConfig, Property } from "@rebasepro/types";
+import { CollectionConfig, Property, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { getTableName } from "@rebasepro/common";
 import { logger } from "@rebasepro/server";
@@ -7,9 +7,9 @@ import { logger } from "@rebasepro/server";
 // Row identity is derived on both sides of the wire — the driver parses an
 // incoming address into key columns, the admin derives one from a served row —
 // so the implementation lives in `common` and both agree by construction.
-export { buildCompositeId, parseIdValues, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
+export { buildCompositeId, parseIdValues, isAddressableId, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
 export type { PrimaryKeyInfo } from "@rebasepro/common";
-import { buildCompositeId, COMPOSITE_ID_SEPARATOR, getDeclaredPrimaryKeys } from "@rebasepro/common";
+import { buildCompositeId, COMPOSITE_ID_SEPARATOR, getDeclaredPrimaryKeys, isAddressableId } from "@rebasepro/common";
 import type { PrimaryKeyInfo } from "@rebasepro/common";
 
 /**
@@ -40,6 +40,33 @@ export function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta {
     };
 }
 
+/**
+ * Whether an address could name a row in this table, judged by the columns.
+ *
+ * {@link getPrimaryKeys} lets a config's `isId: "uuid"` win over the schema, so
+ * its `isUUID` is a claim rather than a fact — right for deriving addresses,
+ * wrong for refusing a query. Here the Drizzle column type decides, because it
+ * is what Postgres will enforce: a `uuid` column meets `/c/products/new` with
+ * `22P02`, which aborts the surrounding transaction and turns every later
+ * statement into an unrelated-looking `25P02`.
+ */
+export function idCanAddressTable(
+    id: string | number,
+    table: PgTable,
+    idInfoArray: PrimaryKeyInfo[]
+): boolean {
+    const columnBacked = idInfoArray.map(info => {
+        const col = table[info.fieldName as keyof typeof table] as AnyPgColumn | undefined;
+        const meta = col ? getColumnMeta(col) : undefined;
+        // No column to ask (a key the schema does not carry) leaves the id
+        // addressable: refusing on a guess would 404 rows that do exist.
+        if (!meta?.columnType) return info;
+        return { ...info,
+            isUUID: meta.columnType === "PgUUID" };
+    });
+    return isAddressableId(id, columnBacked);
+}
+
 export function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): CollectionConfig {
     const collection = registry.getCollectionByPath(collectionPath);
     if (!collection) {
@@ -149,6 +176,45 @@ export function requirePrimaryKeys(collection: CollectionConfig, registry: Postg
     return keys;
 }
 
+/**
+ * The column on the *source* table that a `hasOne`/`hasMany` link points at.
+ *
+ * `sourceKey` is authored when the two sides join on a natural key — an
+ * external identity id, a SKU — and left off when they join on the row id,
+ * which is the overwhelming majority. That makes `undefined` the only optional
+ * field on a resolved relation, so it gets exactly one reader: this function.
+ * Every consumer that needs the column asks here, and none of them re-derives
+ * "or else the primary key" for itself. That is the whole point — the fallback
+ * chains this codebase removed from relation resolution were dangerous because
+ * they were *duplicated* and could disagree, not because they existed.
+ */
+export function sourceKeyField(
+    relation: ResolvedHasOne | ResolvedHasMany,
+    sourceCollection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): string {
+    if (relation.sourceKey) return relation.sourceKey;
+    return requirePrimaryKeys(sourceCollection, registry)[0].fieldName;
+}
+
+/**
+ * Whether this link joins on something other than the source's primary key.
+ *
+ * Callers that hold a parent *id* — which is most of them, since an id is what
+ * a URL carries — must translate it to the source key's value before it can be
+ * compared with the target's foreign key. Those that hold the parent *row*, or
+ * that build a correlated subquery over the source table, can read the column
+ * directly and skip the lookup.
+ */
+export function joinsOnNaturalKey(
+    relation: ResolvedHasOne | ResolvedHasMany,
+    sourceCollection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): boolean {
+    if (!relation.sourceKey) return false;
+    return relation.sourceKey !== requirePrimaryKeys(sourceCollection, registry)[0].fieldName;
+}
+
 /**
  * Collections whose key the *browser* cannot resolve, and what it will do
  * instead.

package/src/services/dataService.ts

@@ -1,5 +1,5 @@
 // import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { FilterValues } from "@rebasepro/types";
+import { FilterValues, LogicalCondition } from "@rebasepro/types";
 import type { VectorSearchParams } from "@rebasepro/types";
 import { FetchService } from "./FetchService";
 import { PersistService } from "./PersistService";
@@ -97,6 +97,8 @@ export class DataService implements DataRepository {
         collectionPath: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
+            /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
+            logical?: LogicalCondition;
             searchString?: string;
             databaseId?: string;
         } = {}

package/src/services/realtimeService.ts

@@ -4,7 +4,7 @@ import { Client as PgClient } from "pg";
 import { randomUUID } from "crypto";
 import { DataService } from "./dataService";
 
-import { FetchCollectionProps, ListenCollectionProps, ListenOneProps, DataDriver, CollectionUpdateMessage, SingleUpdateMessage, CollectionPatchMessage, WebSocketMessage, FilterValues, CollectionConfig, RebaseCallContext, resolveClientListLimit } from "@rebasepro/types";
+import { ANONYMOUS_USER_ID, FetchCollectionProps, ListenCollectionProps, ListenOneProps, DataDriver, CollectionUpdateMessage, SingleUpdateMessage, CollectionPatchMessage, WebSocketMessage, FilterValues, CollectionConfig, RebaseCallContext, resolveClientListLimit } from "@rebasepro/types";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { sql as drizzleSql } from "drizzle-orm";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces";
@@ -751,7 +751,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             // Always wrap in a transaction with session vars, defaulting to anonymous context if missing.
             // Refetches are reads: apply the same GUCs + reader-role downgrade as the
             // driver's read path, so realtime cannot leak rows the initial fetch hid.
-            const activeAuth = authContext || { uid: "anon",
+            const activeAuth = authContext || { uid: ANONYMOUS_USER_ID,
 roles: ["anon"] };
             return await this.db.transaction(async (tx) => {
                 await applyAuthContext(tx, { uid: activeAuth.uid, roles: activeAuth.roles }, this.rlsUserRole);
@@ -931,7 +931,7 @@ roles: activeAuth.roles },
 
             // Always wrap in a transaction with session vars, defaulting to anonymous context if missing.
             // Same read isolation as collection refetches: GUCs + reader-role downgrade.
-            const activeAuth = authContext || { uid: "anon",
+            const activeAuth = authContext || { uid: ANONYMOUS_USER_ID,
 roles: ["anon"] };
             return await this.db.transaction(async (tx) => {
                 await applyAuthContext(tx, { uid: activeAuth.uid, roles: activeAuth.roles }, this.rlsUserRole);

package/src/services/row-pipeline.ts

@@ -164,7 +164,7 @@ export function relationTargetAddress(
  * expects real types. The row's own address is *not* among the columns — it is
  * derived by the consumer from the collection's primary keys.
  */
-export function toCmsRow(
+export function toFlatRow(
     row: Record<string, unknown>,
     collection: CollectionConfig,
     registry: PostgresCollectionRegistry