@rebasepro/server-postgres 0.9.1-canary.73476f2 → 0.9.1-canary.74adfbe

package/src/services/realtimeService.ts

@@ -14,7 +14,9 @@ import { applyAuthContext } from "../security/rls-enforcement";
 import { logger } from "@rebasepro/server";
 import { sanitizeErrorForClient } from "../utils/pg-error-utils";
 import { CdcListener, type CdcChangeEvent } from "./cdc/CdcListener";
-import { getPrimaryKeys, buildCompositeId } from "./collection-helpers";
+import { deriveRowAddress, getPrimaryKeys, type PrimaryKeyInfo } from "./collection-helpers";
+import { ChannelHistoryStore, type ResolvedRetention } from "./channel-history";
+import type { ChannelHistoryEntry, ChannelRetentionRule } from "@rebasepro/types";
 
 /** Channel name used for Postgres LISTEN/NOTIFY cross-instance realtime. */
 const PG_NOTIFY_CHANNEL = "rebase_entity_changes";
@@ -24,7 +26,7 @@ const PG_NOTIFY_CHANNEL = "rebase_entity_changes";
  * Mirrors the session variables set by PostgresBackendDriver.withAuth().
  */
 export interface SubscriptionAuthContext {
-    userId: string;
+    uid: string;
     roles: string[];
 }
 
@@ -52,6 +54,28 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
 
     // Presence: channel → Map<clientId, { state, lastSeen }>
     private presence = new Map<string, Map<string, { state: Record<string, unknown>; lastSeen: number }>>();
+
+    /**
+     * Ordered, replayable history for channels that opt into it.
+     *
+     * Undefined until {@link configureChannelHistory} is called, and inert even
+     * then unless retention rules were supplied — so presence and ephemeral
+     * notification channels never touch it. See `channel-history.ts`.
+     */
+    private channelHistory?: ChannelHistoryStore;
+
+    /**
+     * One promise chain per retained channel, so that assigning a sequence
+     * number and fanning the message out happen in the same order for every
+     * message on that channel.
+     *
+     * Without it, two concurrent broadcasts can be numbered 4 and 5 by the
+     * database and still reach subscribers as 5 then 4 — live order and replay
+     * order would disagree, which is exactly the divergence sequence numbers
+     * are supposed to rule out. Keyed by channel, so unrelated channels never
+     * wait on each other.
+     */
+    private channelSendQueues = new Map<string, Promise<void>>();
     private presenceInterval?: ReturnType<typeof setInterval>;
     private static readonly PRESENCE_TIMEOUT_MS = 30000; // 30s
     private dataService: DataService;
@@ -73,7 +97,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             searchString?: string;
         };
         // Auth context for RLS — when set, refetches run in a transaction
-        // with set_config('app.user_id', ...) / set_config('app.user_roles', ...)
+        // with set_config('app.uid', ...) / set_config('app.user_roles', ...)
         authContext?: SubscriptionAuthContext;
     }>();
 
@@ -322,6 +346,14 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                     payload?.payload
                 );
                 break;
+            case "channel_history":
+                await this.handleChannelHistoryRequest(
+                    clientId,
+                    payload?.channel as string,
+                    payload?.sinceSeq as number | undefined,
+                    payload?.limit as number | undefined
+                );
+                break;
 
             // ── Presence ──
             case "presence_track":
@@ -390,7 +422,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 authContext
             );
 
-            this.sendCollectionUpdate(clientId, subscriptionId, rows);
+            this.sendCollectionUpdate(clientId, subscriptionId, rows, request.path);
 
         } catch (error) {
             const sanitized = sanitizeErrorForClient(error, request.path);
@@ -554,7 +586,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                     // Phase 1: Send instant row-level patch (no DB query)
                     // This gives immediate cross-tab feedback
                     if (!row || !(row as Record<string, unknown>)?._rebase_invalidated) {
-                        this.sendCollectionPatch(subscription.clientId, subscriptionId, id, row);
+                        this.sendCollectionPatch(subscription.clientId, subscriptionId, id, row, notifyPath);
                     }
 
                     // Phase 2: Schedule a deferred full refetch for correctness
@@ -609,7 +641,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             if (!this._subscriptions.has(subscriptionId)) return;
             try {
                 const rows = await this.fetchCollectionWithAuth(notifyPath, subscription.collectionRequest!, subscription.authContext);
-                this.sendCollectionUpdate(subscription.clientId, subscriptionId, rows);
+                this.sendCollectionUpdate(subscription.clientId, subscriptionId, rows, notifyPath);
             } catch (error) {
                 const sanitized = sanitizeErrorForClient(error, notifyPath);
                 this.sendError(subscription.clientId, sanitized.message, subscriptionId, sanitized.code);
@@ -669,10 +701,10 @@ 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 || { userId: "anon",
+            const activeAuth = authContext || { uid: "anon",
 roles: ["anon"] };
             return await this.db.transaction(async (tx) => {
-                await applyAuthContext(tx, { userId: activeAuth.userId, roles: activeAuth.roles }, this.rlsUserRole);
+                await applyAuthContext(tx, { uid: activeAuth.uid, roles: activeAuth.roles }, this.rlsUserRole);
                 const txEntityService = new DataService(tx, this.registry);
                 let fetchedEntities;
                 if (collectionRequest.searchString) {
@@ -711,7 +743,7 @@ roles: ["anon"] };
 
                 if (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead) {
                     const contextForCallback = {
-                        user: { uid: activeAuth.userId,
+                        user: { uid: activeAuth.uid,
 roles: activeAuth.roles },
                         driver: this.driver,
                         data: (this.driver && "data" in this.driver) ? (this.driver as DataDriverWithData).data : undefined
@@ -849,10 +881,10 @@ 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 || { userId: "anon",
+            const activeAuth = authContext || { uid: "anon",
 roles: ["anon"] };
             return await this.db.transaction(async (tx) => {
-                await applyAuthContext(tx, { userId: activeAuth.userId, roles: activeAuth.roles }, this.rlsUserRole);
+                await applyAuthContext(tx, { uid: activeAuth.uid, roles: activeAuth.roles }, this.rlsUserRole);
                 const txEntityService = new DataService(tx, this.registry);
                 let processedEntity = await txEntityService.fetchOne(notifyPath, id, collection?.databaseId);
 
@@ -867,7 +899,7 @@ roles: ["anon"] };
 
                     if (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead) {
                         const contextForCallback = {
-                            user: { uid: activeAuth.userId,
+                            user: { uid: activeAuth.uid,
 roles: activeAuth.roles },
                             driver: this.driver,
                             data: (this.driver && "data" in this.driver) ? (this.driver as DataDriverWithData).data : undefined
@@ -910,11 +942,12 @@ roles: activeAuth.roles },
         return await this.dataService.fetchOne(notifyPath, id);
     }
 
-    private sendCollectionUpdate(clientId: string, subscriptionId: string, rows: Record<string, unknown>[]) {
+    private sendCollectionUpdate(clientId: string, subscriptionId: string, rows: Record<string, unknown>[], path: string) {
         const message: CollectionUpdateMessage = {
             type: "collection_update",
             subscriptionId,
-            rows: rows
+            rows: rows,
+            pks: this.primaryKeysForPath(path)
         };
         this.sendMessage(clientId, message);
     }
@@ -931,17 +964,45 @@ roles: activeAuth.roles },
     /**
      * Send a lightweight row-level patch to a collection subscriber.
      * The client can merge this into its cached data for instant feedback.
+     *
+     * The key columns ride along: the patch names a row by address, and the
+     * client has to find that row among the ones it cached — which carry
+     * columns and no address. The SDK holds no collection config to derive one
+     * from, so this is the only place the mapping can come from.
      */
-    private sendCollectionPatch(clientId: string, subscriptionId: string, id: string, row: Record<string, unknown> | null) {
+    private sendCollectionPatch(
+        clientId: string,
+        subscriptionId: string,
+        id: string,
+        row: Record<string, unknown> | null,
+        notifyPath: string
+    ) {
         const message: CollectionPatchMessage = {
             type: "collection_patch",
             subscriptionId,
             id,
-            row: row
+            row: row,
+            pks: this.primaryKeysForPath(notifyPath)
         };
         this.sendMessage(clientId, message);
     }
 
+    /** The key columns of the collection at `path`, if they can be resolved. */
+    private primaryKeysForPath(path: string): PrimaryKeyInfo[] | undefined {
+        try {
+            const collection = this.registry.getCollectionByPath(path);
+            if (!collection) return undefined;
+            const keys = getPrimaryKeys(collection, this.registry);
+            return keys.length > 0 ? keys : undefined;
+        } catch {
+            // `getCollectionByPath` throws on a path it cannot walk — and this
+            // is called for parent paths too, which include entity paths like
+            // `posts/1` that name no collection. Telling the subscriber nothing
+            // is right here; letting it throw would drop the notification.
+            return undefined;
+        }
+    }
+
     private sendError(clientId: string, error: string, subscriptionId?: string, code?: string) {
         const message = {
             type: "error" as const,
@@ -1010,8 +1071,85 @@ roles: activeAuth.roles },
         this.removePresence(clientId, channel);
     }
 
-    /** Broadcast a message to all clients in a channel except sender */
+    /**
+     * Broadcast a message to all clients in a channel except the sender.
+     *
+     * On a channel with no retention rule this is what it always was: a
+     * synchronous fan-out to whoever is connected, with no sequence number, no
+     * SQL and no await — the body below runs to completion before returning.
+     *
+     * On a retained channel the message is durably numbered first and only then
+     * delivered, through a per-channel queue so that delivery order matches
+     * sequence order. That ordering is the whole point: a client that catches up
+     * with `sinceSeq` has to arrive at the same state as one that never
+     * disconnected.
+     */
     broadcastToChannel(clientId: string, channel: string, event: string, payload: unknown): void {
+        const retention = this.channelHistory?.retentionFor(channel);
+        if (!retention) {
+            this.fanOutBroadcast(clientId, channel, event, payload);
+            return;
+        }
+
+        const previous = this.channelSendQueues.get(channel) ?? Promise.resolve();
+        const next = previous
+            // A failed predecessor must not poison the chain — the next message
+            // on this channel is independent and still deserves to be sent.
+            .catch(() => { /* already reported below */ })
+            .then(() => this.persistAndFanOut(clientId, channel, event, payload, retention));
+
+        this.channelSendQueues.set(channel, next);
+        void next.finally(() => {
+            // Only clear if nothing has queued behind us in the meantime.
+            if (this.channelSendQueues.get(channel) === next) this.channelSendQueues.delete(channel);
+        });
+    }
+
+    /**
+     * Number a broadcast, store it, then deliver it.
+     *
+     * A message that cannot be stored is **not** delivered. Delivering it would
+     * put it in front of live subscribers while leaving it absent from every
+     * future replay — the two views of the channel would disagree permanently,
+     * and no later message could repair the gap. Failing loudly to the sender
+     * instead lets it retry, which for an operation stream is the only outcome
+     * that keeps clients convergent.
+     */
+    private async persistAndFanOut(
+        clientId: string,
+        channel: string,
+        event: string,
+        payload: unknown,
+        retention: ResolvedRetention
+    ): Promise<void> {
+        let seq: number;
+        try {
+            ({ seq } = await this.channelHistory!.append(channel, event, payload, clientId));
+        } catch (error) {
+            logger.error(`❌ [ChannelHistory] Could not persist broadcast on "${channel}" — message dropped`, { error });
+            this.sendError(
+                clientId,
+                `Could not persist broadcast on retained channel "${channel}"`,
+                undefined,
+                "CHANNEL_HISTORY_WRITE_FAILED"
+            );
+            return;
+        }
+
+        this.fanOutBroadcast(clientId, channel, event, payload, seq);
+
+        try {
+            await this.channelHistory!.prune(channel, retention);
+        } catch (error) {
+            // Retention is a housekeeping concern; the message is already
+            // delivered and durable, so a failed prune must not surface as a
+            // broadcast failure. It will be retried on the next message.
+            logger.warn(`⚠️ [ChannelHistory] Prune failed for "${channel}"`, { error });
+        }
+    }
+
+    /** Deliver a broadcast frame to every member of a channel but the sender. */
+    private fanOutBroadcast(clientId: string, channel: string, event: string, payload: unknown, seq?: number): void {
         const members = this.channels.get(channel);
         if (!members) return;
 
@@ -1019,7 +1157,8 @@ roles: activeAuth.roles },
             type: "broadcast",
             channel,
             event,
-            payload
+            payload,
+            ...(seq !== undefined ? { seq } : {})
         });
 
         for (const memberId of members) {
@@ -1031,6 +1170,79 @@ roles: activeAuth.roles },
         }
     }
 
+    // =============================================================================
+    // Channel History
+    // =============================================================================
+
+    /**
+     * Install retention rules and create the tables they need.
+     *
+     * Safe to call with no rules (and safe not to call at all): the store stays
+     * inert, no schema is created, and broadcast keeps its original
+     * fire-and-forget path.
+     */
+    async configureChannelHistory(rules: ChannelRetentionRule[] | undefined): Promise<void> {
+        this.channelHistory = new ChannelHistoryStore(this.db, rules ?? []);
+        if (!this.channelHistory.enabled) return;
+        await this.channelHistory.ensureTables();
+    }
+
+    /** Whether any channel is configured to retain messages. */
+    public isChannelHistoryEnabled(): boolean {
+        return this.channelHistory?.enabled ?? false;
+    }
+
+    /**
+     * Answer a client's catch-up request.
+     *
+     * A channel with no retention rule is answered with `retained: false`
+     * rather than an empty list, so the client can tell "you missed nothing"
+     * apart from "this channel never keeps anything" — the second means its
+     * reconnect strategy has to be a full resync, and silence would leave it
+     * guessing.
+     */
+    private async handleChannelHistoryRequest(
+        clientId: string,
+        channel: string,
+        sinceSeq?: number,
+        limit?: number
+    ): Promise<void> {
+        if (!channel) return;
+
+        const retention = this.channelHistory?.retentionFor(channel);
+        if (!retention) {
+            this.sendChannelHistory(clientId, channel, [], false);
+            return;
+        }
+
+        try {
+            const { messages, latestSeq } = await this.channelHistory!.replay(channel, sinceSeq, limit);
+            this.sendChannelHistory(clientId, channel, messages, true, latestSeq);
+        } catch (error) {
+            logger.error(`❌ [ChannelHistory] Replay failed for "${channel}"`, { error });
+            this.sendError(clientId, `Could not replay history for channel "${channel}"`, undefined, "CHANNEL_HISTORY_READ_FAILED");
+        }
+    }
+
+    private sendChannelHistory(
+        clientId: string,
+        channel: string,
+        messages: ChannelHistoryEntry[],
+        retained: boolean,
+        latestSeq?: number
+    ): void {
+        const ws = this.clients.get(clientId);
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({
+                type: "channel_history",
+                channel,
+                messages,
+                retained,
+                ...(latestSeq !== undefined ? { latestSeq } : {})
+            }));
+        }
+    }
+
     // =============================================================================
     // Presence
     // =============================================================================
@@ -1162,6 +1374,11 @@ lastSeen: Date.now() });
         // 3. Clear broadcast channels and presence
         this.channels.clear();
         this.presence.clear();
+        // Pending history writes hold the pool open; let them settle before the
+        // caller closes it, but never let a rejected one break shutdown.
+        await Promise.allSettled([...this.channelSendQueues.values()]);
+        this.channelSendQueues.clear();
+        this.channelHistory?.clear();
         if (this.presenceInterval) {
             clearInterval(this.presenceInterval);
             this.presenceInterval = undefined;
@@ -1294,17 +1511,9 @@ lastSeen: Date.now() });
 
     /** Compute the canonical (possibly composite) id string from a captured row. */
     private extractIdFromCdcRow(collection: CollectionConfig, row: Record<string, unknown>): string {
-        try {
-            const primaryKeys = getPrimaryKeys(collection, this.registry);
-            const composite = buildCompositeId(row, primaryKeys);
-            if (composite && composite !== ":::") return composite;
-        } catch {
-            /* fall through to id-field / wildcard */
-        }
-        // Fallbacks: a plain `id` column (common), else a collection-level
-        // invalidation ("*") — single-row subs won't match but collection subs refetch.
-        if (row.id !== undefined && row.id !== null) return String(row.id);
-        return "*";
+        // Unaddressable falls back to a collection-level invalidation: single-row
+        // subs won't match, but collection subs still refetch.
+        return deriveRowAddress(row, collection, this.registry) || "*";
     }
 
     // ── App/CDC de-duplication ──

package/src/services/row-pipeline.ts

@@ -0,0 +1,239 @@
+import { CollectionConfig, Property, Relation } from "@rebasepro/types";
+import { resolveCollectionRelations, findRelation, createRelationRefWithData } from "@rebasepro/common";
+import { normalizeDbValues } from "../data-transformer";
+import { deriveRowAddress } from "./collection-helpers";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+
+/**
+ * Turning a drizzle result into a row we serve.
+ *
+ * There are two shapes, and they are the same walk. Both take a row whose
+ * relation fields hold nested objects, both unwrap junction rows to reach the
+ * target behind them, and both leave every other column alone. They differ only
+ * in what they put where the relation was:
+ *
+ * - `"ref"` — a `{ id, path, __type: "relation" }` reference carrying the
+ *   target's values. This is what the admin renders.
+ * - `"inline"` — the target's own columns, flat. This is what REST serves.
+ *
+ * They used to be two functions that happened to agree, and the agreement was
+ * not enforced by anything: the row-identity bug had to be fixed five times
+ * across differently-shaped copies of this walk, and one of the copies was
+ * dead code nobody had noticed. Whatever the next cross-cutting change is, it
+ * is one edit here.
+ */
+export type RelationStyle = "ref" | "inline";
+
+/**
+ * Whether a many-relation reaches its target through a junction table.
+ *
+ * Also used to build the drizzle `with` config, which is why it is exported:
+ * the query has to nest one level deeper for a junction, and the row walk has
+ * to unwrap that same level back out.
+ */
+export function isJunctionRelation(relation: Relation): boolean {
+    // An explicit `through` says so outright.
+    if (relation.through) return true;
+    // A joinPath with an intermediate table is the same thing, spelled longhand.
+    if (relation.joinPath && relation.joinPath.length > 1) return true;
+    return false;
+}
+
+/**
+ * Reach the target row inside a junction row.
+ *
+ * A junction row looks like `{ post_id: 1, tag_id: { id: 5, name: "ts" } }` —
+ * the foreign keys, and the target nested under one of them. The target is the
+ * only object among them, so that is how it is found. A junction row that has
+ * not been nested (no `with` on the join) has no object and is returned as-is.
+ */
+function unwrapJunctionRow(item: Record<string, unknown>): Record<string, unknown> {
+    const nestedKey = Object.keys(item).find(
+        key => typeof item[key] === "object" && item[key] !== null && !Array.isArray(item[key])
+    );
+    return nestedKey ? item[nestedKey] as Record<string, unknown> : item;
+}
+
+/**
+ * Give back the number a `number` property was declared to be.
+ *
+ * Postgres returns NUMERIC as a string and drizzle keeps it that way, since a
+ * numeric can hold more precision than a double. But the collection declared
+ * this property `number` and the OpenAPI spec this server publishes says
+ * `type: number`, so serving `"9.99"` breaks its own contract — and breaks it
+ * asymmetrically, because a create answers with the number and the read that
+ * follows answers with the string. Any client that multiplies a price works
+ * until the first refresh.
+ *
+ * Declaring a property `number` already accepts double precision — that is what
+ * the admin has always parsed it to. Columns REST serves that no property
+ * declares are left exactly as the database returned them.
+ */
+function coerceDeclaredNumber(value: unknown, property: Property | undefined): unknown {
+    if (property?.type !== "number" || typeof value !== "string") return value;
+    const parsed = parseFloat(value);
+    return isNaN(parsed) ? null : parsed;
+}
+
+/** Apply {@link coerceDeclaredNumber} across a row, leaving every other column alone. */
+function coerceDeclaredNumbers(
+    row: Record<string, unknown>,
+    collection: CollectionConfig
+): Record<string, unknown> {
+    const properties = collection.properties;
+    if (!properties) return row;
+
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(row)) {
+        out[key] = coerceDeclaredNumber(value, properties[key] as Property | undefined);
+    }
+    return out;
+}
+
+/** Render one target row in the requested style. */
+/**
+ * Drop every column the collection marked `excludeFromApi`.
+ *
+ * Password hashes and verification tokens have to be readable server-side but
+ * must never reach a client — and "never" has to mean every exit from this
+ * pipeline, including relation targets, or a secret leaks through whichever
+ * path was overlooked. Keyed by both the property name and its column name,
+ * since a row can arrive keyed either way depending on the caller.
+ */
+function stripExcluded(
+    row: Record<string, unknown>,
+    collection: CollectionConfig
+): Record<string, unknown> {
+    const properties = collection.properties as Record<string, Property> | undefined;
+    if (!properties) return row;
+
+    for (const [key, property] of Object.entries(properties)) {
+        if (!property?.excludeFromApi) continue;
+        delete row[key];
+        if (property.columnName) delete row[property.columnName];
+    }
+    return row;
+}
+
+function renderTarget(
+    targetRow: Record<string, unknown>,
+    targetCollection: CollectionConfig,
+    style: RelationStyle,
+    registry: PostgresCollectionRegistry
+): unknown {
+    if (style === "inline") {
+        // The target's columns, and only those: its address is the consumer's
+        // to derive, and merging one in overwrites a real `id` column.
+        return stripExcluded(coerceDeclaredNumbers({ ...targetRow }, targetCollection), targetCollection);
+    }
+
+    const address = relationTargetAddress(targetRow, targetCollection, registry);
+    const path = targetCollection.slug;
+    return createRelationRefWithData(address, path, {
+        id: address,
+        path,
+        values: normalizeDbValues(targetRow, targetCollection)
+    });
+}
+
+/**
+ * The address a relation ref points at.
+ *
+ * The whole key, not its first column: a composite-keyed target addressed by
+ * `tenant_id` alone points at every row that shares it. A target whose key
+ * cannot be resolved at all used to throw here — reading `[0]` of an empty
+ * array — taking down the parent's fetch over a relation it may not even have
+ * asked for. The first column is a guess, but a ref that resolves to nothing
+ * beats no rows at all.
+ */
+export function relationTargetAddress(
+    targetRow: Record<string, unknown>,
+    targetCollection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): string {
+    const address = deriveRowAddress(targetRow, targetCollection, registry);
+    if (address) return address;
+    return String(targetRow[Object.keys(targetRow)[0]] ?? "");
+}
+
+/**
+ * The row the admin renders: every column, with relations as references.
+ *
+ * Values are normalized (dates, numbers, NaN) because the admin's view-model
+ * 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(
+    row: Record<string, unknown>,
+    collection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): Record<string, unknown> {
+    const resolvedRelations = resolveCollectionRelations(collection);
+    const normalized = normalizeDbValues(row, collection) as Record<string, unknown>;
+
+    // Keyed by relation, reading the drizzle relation name off the raw row: the
+    // relation's property key and the name drizzle nested it under are not
+    // always the same, and the value is written back under the property key.
+    for (const [key, relation] of Object.entries(resolvedRelations)) {
+        const relData = row[relation.relationName || key];
+        if (relData === undefined || relData === null) continue;
+
+        if (relation.cardinality === "many" && Array.isArray(relData)) {
+            const targetCollection = relation.target();
+            normalized[key] = relData.map((item: Record<string, unknown>) =>
+                renderTarget(
+                    isJunctionRelation(relation) ? unwrapJunctionRow(item) : item,
+                    targetCollection,
+                    "ref",
+                    registry
+                ));
+        } else if (relation.cardinality === "one" && typeof relData === "object" && !Array.isArray(relData)) {
+            normalized[key] = renderTarget(relData as Record<string, unknown>, relation.target(), "ref", registry);
+        }
+    }
+
+    return stripExcluded(normalized, collection);
+}
+
+/**
+ * The row REST serves: every column under its own name, with the value Postgres
+ * returned, and relations inlined as the target's columns.
+ *
+ * Values are the ones the database returned, except where that contradicts the
+ * declared type: a `number` property is served as a number (see
+ * {@link coerceDeclaredNumber}). Dates stay as the database returned them —
+ * JSON has its own opinions about dates that the admin's view-model does not
+ * share.
+ *
+ * Keyed by the row rather than by the relation list — a REST fetch only loads
+ * the relations `include` asked for, so the row is the authority on which are
+ * actually there.
+ */
+export function toRestRow(
+    row: Record<string, unknown>,
+    collection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): Record<string, unknown> {
+    const resolvedRelations = resolveCollectionRelations(collection);
+    const flat: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(row)) {
+        const relation = findRelation(resolvedRelations, key);
+
+        if (relation && Array.isArray(value)) {
+            flat[key] = value.map((item: Record<string, unknown>) =>
+                renderTarget(
+                    isJunctionRelation(relation) ? unwrapJunctionRow(item) : item,
+                    relation.target(),
+                    "inline",
+                    registry
+                ));
+        } else if (relation && typeof value === "object" && value !== null) {
+            flat[key] = renderTarget(value as Record<string, unknown>, relation.target(), "inline", registry);
+        } else {
+            flat[key] = coerceDeclaredNumber(value, collection.properties?.[key] as Property | undefined);
+        }
+    }
+
+    return stripExcluded(flat, collection);
+}

package/src/utils/drizzle-conditions.ts

@@ -1126,6 +1126,19 @@ export class DrizzleConditionBuilder {
             throw new Error(`Vector column '${vectorSearch.property}' not found in table`);
         }
 
+        // The vector is interpolated as a raw SQL literal below (pgvector has no
+        // bind form for the `::vector` cast), so every element must be a finite
+        // number. The REST query parser already enforces this, but this builder
+        // is a shared entry point — validate here too so no future caller can
+        // turn an unchecked value into SQL injection.
+        if (
+            !Array.isArray(vectorSearch.vector) ||
+            vectorSearch.vector.length === 0 ||
+            !vectorSearch.vector.every((n) => typeof n === "number" && Number.isFinite(n))
+        ) {
+            throw new Error("Vector search requires a non-empty array of finite numbers");
+        }
+
         const vectorLiteral = `'[${vectorSearch.vector.join(",")}]'::vector`;
         const distanceFn = vectorSearch.distance || "cosine";