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

package/src/services/channel-history.ts

@@ -0,0 +1,343 @@
+/**
+ * Ordered, replayable per-channel message history.
+ *
+ * Broadcast on its own is fire-and-forget to whoever is connected at the
+ * instant it is sent: fine for presence and for "someone saved" notifications,
+ * not enough for op-based collaborative editing, where a client that blinks
+ * out for two seconds has to resync a whole document rather than catch up on
+ * the four operations it missed. This adds the missing half — every retained
+ * broadcast gets a per-channel sequence number, and a client can ask for
+ * everything after the last one it saw.
+ *
+ * Three decisions worth stating, because each rules out a simpler-looking one:
+ *
+ *  - **Retention is server-side and opt-in.** A channel is created by whoever
+ *    names it, so a client-supplied history depth would let any visitor commit
+ *    the backend to unbounded storage. And presence channels — the common case
+ *    — must not pay for this: with no rules configured nothing is written, no
+ *    table is created, and `broadcast` runs exactly the code it ran before.
+ *
+ *  - **Sequence numbers come from the database, not from a counter in this
+ *    process.** They have to survive a restart and be shared across instances;
+ *    an in-memory counter would restart at 1 after a deploy and hand a
+ *    reconnecting client a replay from the wrong era, silently.
+ *
+ *  - **The cursor row outlives the messages it numbered.** Pruning is what
+ *    makes retention affordable, but pruning the cursor along with the messages
+ *    would restart the sequence and make `sinceSeq` mean something different
+ *    before and after — the worst kind of bug, because replay would still
+ *    return rows and they would look plausible. Cursors are tiny and are kept
+ *    forever; see {@link prune}, which touches only `channel_messages`.
+ */
+
+import { sql } from "drizzle-orm";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ChannelHistoryEntry, ChannelRetentionRule } from "@rebasepro/types";
+import { logger } from "@rebasepro/server";
+
+/** How many messages a replay returns when the caller does not say. */
+const DEFAULT_REPLAY_LIMIT = 200;
+
+/**
+ * Hard ceiling on one replay, whatever the caller asks for.
+ *
+ * A reconnecting client names its own `limit`, so this is the only thing
+ * standing between a stale `sinceSeq` and a single frame carrying a channel's
+ * entire retained history. A client that is further behind than this is told so
+ * via `latestSeq` and can decide to resync wholesale instead of paging.
+ */
+const MAX_REPLAY_LIMIT = 1000;
+
+/** Minimum gap between two prunes of the same channel. */
+const PRUNE_THROTTLE_MS = 30_000;
+
+/**
+ * Parse a retention TTL into milliseconds.
+ *
+ * Accepts a raw millisecond count or a short duration string (`"30s"`, `"15m"`,
+ * `"24h"`, `"7d"`). Returns undefined for anything unparseable, which the
+ * caller treats as "no TTL" — a misspelt duration must not silently become an
+ * aggressive one.
+ */
+export function parseTtlMs(ttl: number | string | undefined): number | undefined {
+    if (ttl === undefined || ttl === null) return undefined;
+    if (typeof ttl === "number") return Number.isFinite(ttl) && ttl > 0 ? ttl : undefined;
+
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/i.exec(ttl);
+    if (!match) {
+        logger.warn(`⚠️ [ChannelHistory] Ignoring unparseable retention ttl "${ttl}" — expected e.g. "30s", "15m", "24h", "7d".`);
+        return undefined;
+    }
+    const value = parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    const multiplier = unit === "ms" ? 1
+        : unit === "s" ? 1_000
+            : unit === "m" ? 60_000
+                : unit === "h" ? 3_600_000
+                    : 86_400_000;
+    const ms = value * multiplier;
+    return ms > 0 ? ms : undefined;
+}
+
+/**
+ * Whether `channel` is covered by `rule`.
+ *
+ * Exact match, or a trailing `*` acting as a prefix. Not a general glob: this
+ * decides what reaches disk, and a pattern language whose reach is not obvious
+ * at a glance is the wrong tool for that job.
+ */
+export function channelMatchesRule(channel: string, rule: ChannelRetentionRule): boolean {
+    const pattern = rule.match;
+    if (pattern === "*") return true;
+    if (pattern.endsWith("*")) return channel.startsWith(pattern.slice(0, -1));
+    return channel === pattern;
+}
+
+/** A rule with its TTL already resolved to milliseconds. */
+export interface ResolvedRetention {
+    limit?: number;
+    ttlMs?: number;
+}
+
+/**
+ * Persistence and replay for retained channels.
+ *
+ * Inert unless constructed with at least one rule: {@link enabled} is false,
+ * {@link ensureTables} does nothing, and {@link retentionFor} answers undefined
+ * for every channel, so the realtime service never reaches the SQL below.
+ */
+export class ChannelHistoryStore {
+    private rules: ChannelRetentionRule[];
+    /** Resolved rule per channel name, so the match runs once per channel. */
+    private resolved = new Map<string, ResolvedRetention | null>();
+    /** Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}. */
+    private lastPruned = new Map<string, number>();
+    private tablesReady = false;
+
+    constructor(private db: NodePgDatabase<Record<string, unknown>>, rules: ChannelRetentionRule[] = []) {
+        this.rules = rules.filter(rule => {
+            if (!rule?.match) {
+                logger.warn("⚠️ [ChannelHistory] Ignoring a retention rule with no `match`.");
+                return false;
+            }
+            const hasBound = rule.limit !== undefined || rule.ttl !== undefined;
+            if (!hasBound) {
+                // Unbounded retention is almost never intended and cannot be
+                // walked back once the table has grown, so it is refused rather
+                // than honoured.
+                logger.warn(`⚠️ [ChannelHistory] Retention rule "${rule.match}" sets neither \`limit\` nor \`ttl\` — ignoring it, as it would retain forever.`);
+                return false;
+            }
+            return true;
+        });
+    }
+
+    /** Whether any channel retains anything at all. */
+    get enabled(): boolean {
+        return this.rules.length > 0;
+    }
+
+    /**
+     * The retention that applies to `channel`, or undefined when none does.
+     *
+     * First matching rule wins, so callers order them most-specific first.
+     */
+    retentionFor(channel: string): ResolvedRetention | undefined {
+        if (!this.enabled || !channel) return undefined;
+
+        const cached = this.resolved.get(channel);
+        if (cached !== undefined) return cached ?? undefined;
+
+        const rule = this.rules.find(r => channelMatchesRule(channel, r));
+        const resolved: ResolvedRetention | null = rule
+            ? { limit: rule.limit, ttlMs: parseTtlMs(rule.ttl) }
+            : null;
+
+        // Bounded by the number of distinct channel names seen, which is the
+        // same thing the in-memory channel and presence maps are bounded by.
+        this.resolved.set(channel, resolved);
+        return resolved ?? undefined;
+    }
+
+    /**
+     * Create the history tables. Idempotent, and a no-op when no rule is set —
+     * a deployment that never retains anything gets no schema for it.
+     */
+    async ensureTables(): Promise<void> {
+        if (!this.enabled || this.tablesReady) return;
+
+        await this.db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+
+        // The primary key is exactly the replay query's access path
+        // (`channel = $1 AND seq > $2 ORDER BY seq`), so it needs no further
+        // index of its own.
+        await this.db.execute(sql`
+            CREATE TABLE IF NOT EXISTS rebase.channel_messages (
+                channel TEXT NOT NULL,
+                seq BIGINT NOT NULL,
+                event TEXT NOT NULL,
+                payload JSONB,
+                sender_id TEXT,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                PRIMARY KEY (channel, seq)
+            )
+        `);
+
+        // Only for the TTL arm of pruning; the limit arm rides the primary key.
+        await this.db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_channel_messages_created
+            ON rebase.channel_messages (created_at)
+        `);
+
+        // Never pruned — see the note at the top of this file. One row per
+        // channel that has ever retained a message.
+        await this.db.execute(sql`
+            CREATE TABLE IF NOT EXISTS rebase.channel_cursors (
+                channel TEXT PRIMARY KEY,
+                last_seq BIGINT NOT NULL
+            )
+        `);
+
+        this.tablesReady = true;
+        logger.info(`✅ [ChannelHistory] Retained channels ready (${this.rules.length} rule(s)).`);
+    }
+
+    /**
+     * Append a broadcast and return the sequence number it was given.
+     *
+     * The sequence is allocated by the same statement that stores the message,
+     * so a crash between the two is not a possibility. `ON CONFLICT DO UPDATE`
+     * takes a row lock on the channel's cursor, which is what makes concurrent
+     * broadcasts to one channel line up in a single order — and what keeps
+     * different channels from contending with each other at all.
+     */
+    async append(
+        channel: string,
+        event: string,
+        payload: unknown,
+        senderId?: string
+    ): Promise<{ seq: number; at: string }> {
+        const result = await this.db.execute(sql`
+            WITH next AS (
+                INSERT INTO rebase.channel_cursors (channel, last_seq)
+                VALUES (${channel}, 1)
+                ON CONFLICT (channel)
+                DO UPDATE SET last_seq = rebase.channel_cursors.last_seq + 1
+                RETURNING last_seq
+            )
+            INSERT INTO rebase.channel_messages (channel, seq, event, payload, sender_id)
+            SELECT ${channel}, next.last_seq, ${event}, ${JSON.stringify(payload ?? null)}::jsonb, ${senderId ?? null}
+            FROM next
+            RETURNING seq, created_at
+        `);
+
+        const row = result.rows[0] as { seq: string | number; created_at: Date | string } | undefined;
+        if (!row) throw new Error(`Failed to append to channel history for "${channel}"`);
+
+        return {
+            // BIGINT comes back as a string from node-postgres; the wire type is
+            // a number, and a channel would need 2^53 messages to notice.
+            seq: Number(row.seq),
+            at: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at)
+        };
+    }
+
+    /**
+     * Everything retained for `channel` after `sinceSeq`, oldest first.
+     *
+     * `latestSeq` is reported whether or not the messages were capped, so a
+     * client that is further behind than one page can tell.
+     */
+    async replay(
+        channel: string,
+        sinceSeq = 0,
+        limit = DEFAULT_REPLAY_LIMIT
+    ): Promise<{ messages: ChannelHistoryEntry[]; latestSeq: number }> {
+        const capped = Math.max(1, Math.min(Math.floor(limit) || DEFAULT_REPLAY_LIMIT, MAX_REPLAY_LIMIT));
+        const after = Number.isFinite(sinceSeq) && sinceSeq > 0 ? Math.floor(sinceSeq) : 0;
+
+        const result = await this.db.execute(sql`
+            SELECT seq, event, payload, sender_id, created_at
+            FROM rebase.channel_messages
+            WHERE channel = ${channel} AND seq > ${after}
+            ORDER BY seq ASC
+            LIMIT ${capped}
+        `);
+
+        const messages = (result.rows as Array<{
+            seq: string | number;
+            event: string;
+            payload: unknown;
+            sender_id: string | null;
+            created_at: Date | string;
+        }>).map(row => ({
+            seq: Number(row.seq),
+            event: row.event,
+            payload: row.payload,
+            senderId: row.sender_id ?? undefined,
+            at: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at)
+        }));
+
+        // Read from the cursor rather than from the messages: the cursor is the
+        // authority on how far the channel has got, and still says so after
+        // pruning has removed the messages it counted.
+        const cursor = await this.db.execute(sql`
+            SELECT last_seq FROM rebase.channel_cursors WHERE channel = ${channel}
+        `);
+        const cursorRow = cursor.rows[0] as { last_seq: string | number } | undefined;
+        const latestSeq = cursorRow ? Number(cursorRow.last_seq) : 0;
+
+        return { messages, latestSeq };
+    }
+
+    /**
+     * Enforce a channel's retention bounds.
+     *
+     * Throttled per channel, so a burst of operations prunes once rather than
+     * once per message — the cost then tracks elapsed time instead of write
+     * volume, which is what makes retention affordable on a hot channel.
+     */
+    async prune(channel: string, retention: ResolvedRetention): Promise<number> {
+        const now = Date.now();
+        const last = this.lastPruned.get(channel) ?? 0;
+        if (now - last < PRUNE_THROTTLE_MS) return 0;
+        this.lastPruned.set(channel, now);
+
+        let deleted = 0;
+
+        if (retention.ttlMs !== undefined) {
+            const result = await this.db.execute(sql`
+                DELETE FROM rebase.channel_messages
+                WHERE channel = ${channel}
+                  AND created_at < NOW() - MAKE_INTERVAL(secs => ${retention.ttlMs / 1000})
+            `);
+            deleted += result.rowCount ?? 0;
+        }
+
+        if (retention.limit !== undefined && retention.limit > 0) {
+            // OFFSET past the newest `limit` rows to find the highest seq that
+            // is no longer wanted, then delete everything at or below it. Fewer
+            // rows than the limit leaves the subquery empty, and the comparison
+            // with NULL deletes nothing.
+            const result = await this.db.execute(sql`
+                DELETE FROM rebase.channel_messages
+                WHERE channel = ${channel}
+                  AND seq <= (
+                      SELECT seq FROM rebase.channel_messages
+                      WHERE channel = ${channel}
+                      ORDER BY seq DESC
+                      OFFSET ${Math.floor(retention.limit)} LIMIT 1
+                  )
+            `);
+            deleted += result.rowCount ?? 0;
+        }
+
+        return deleted;
+    }
+
+    /** Forget throttle and match caches. Called on shutdown. */
+    clear(): void {
+        this.resolved.clear();
+        this.lastPruned.clear();
+    }
+}

package/src/services/collection-helpers.ts

@@ -2,6 +2,15 @@ import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 import { CollectionConfig, Property } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { getTableName } from "@rebasepro/common";
+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 type { PrimaryKeyInfo } from "@rebasepro/common";
+import { buildCompositeId, COMPOSITE_ID_SEPARATOR, getDeclaredPrimaryKeys } from "@rebasepro/common";
+import type { PrimaryKeyInfo } from "@rebasepro/common";
 
 /**
  * Shared helper functions for row operations.
@@ -49,10 +58,27 @@ export function getTableForCollection(collection: CollectionConfig, registry: Po
     return table;
 }
 
-export function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): { fieldName: string; type: "string" | "number"; isUUID?: boolean }[] {
-    const table = getTableForCollection(collection, registry);
-
-    // Fallback to explicitly defined isId properties
+/**
+ * The key columns a collection's rows are addressed by.
+ *
+ * Three tiers, in order: properties marked `isId`, the primary keys of the
+ * drizzle schema, and finally a column literally named `id`. Only the first is
+ * visible to the browser, which is why a key known only to drizzle is reported
+ * at boot — see {@link warnOnKeysTheAdminCannotResolve}.
+ *
+ * Returns `[]` when nothing resolves, rather than throwing. It used to open by
+ * resolving the table, which throws when there is none — so the `isId` tier,
+ * which needs no table at all, was unreachable for exactly the collections
+ * most likely to have no table registered. Every caller that wanted "no keys"
+ * to mean "no keys" had to spell that out in a try/catch.
+ *
+ * Callers that cannot proceed without a key must say so themselves, naming the
+ * collection: an empty array here means "this collection has no address", which
+ * is a different answer in a notification (broadcast a wildcard) than in a save
+ * (fail).
+ */
+export function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[] {
+    // Explicitly declared `isId` properties win, and need no table.
     if (collection.properties) {
         const idProps = Object.entries(collection.properties)
             .filter(([_, prop]) => "isId" in (prop as object) && Boolean((prop as { isId?: unknown }).isId))
@@ -67,8 +93,14 @@ export function getPrimaryKeys(collection: CollectionConfig, registry: PostgresC
         }
     }
 
+    // The remaining tiers read the drizzle schema, so they need the table. A
+    // collection without one — another engine's, or simply unregistered — has
+    // nothing more to offer.
+    const table = registry.getTable(getTableName(collection));
+    if (!table) return [];
+
     // Otherwise infer from Drizzle schema
-    const keys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[] = [];
+    const keys: PrimaryKeyInfo[] = [];
     for (const [key, colRaw] of Object.entries(table)) {
         const col = colRaw as AnyPgColumn;
         if (col && typeof col === "object" && "primary" in col && col.primary) {
@@ -96,56 +128,141 @@ isUUID });
     return keys;
 }
 
-export function parseIdValues(idValue: string | number, primaryKeys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[]): Record<string, string | number> {
-    const result: Record<string, string | number> = {};
-
-    if (primaryKeys.length === 0) {
-        return result;
+/**
+ * The key columns, for callers that cannot do their job without one.
+ *
+ * {@link getPrimaryKeys} answers "what keys, if any" and returns `[]` for a
+ * collection with no address. Most of this driver, though, is building a WHERE
+ * clause and has no meaning without a key — for those, an empty array is not an
+ * answer, and indexing `[0]` into it produces `Cannot read properties of
+ * undefined` three frames from where the real problem is. This says what is
+ * wrong and which collection it is wrong about.
+ */
+export function requirePrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[] {
+    const keys = getPrimaryKeys(collection, registry);
+    if (keys.length === 0) {
+        throw new Error(
+            `Collection '${collection.slug}' has no primary key, so its rows cannot be addressed. ` +
+            `Mark the key property with \`isId\` in its config, or register a table whose schema declares one.`
+        );
     }
+    return keys;
+}
 
-    if (primaryKeys.length === 1) {
-        const pk = primaryKeys[0];
-        if (pk.type === "number" && !pk.isUUID) {
-            const parsed = typeof idValue === "number" ? idValue : parseInt(String(idValue), 10);
-            if (isNaN(parsed)) {
-                throw new Error(`Invalid numeric ID: ${idValue}`);
-            }
-            result[pk.fieldName] = parsed;
-        } else {
-            result[pk.fieldName] = String(idValue);
-        }
-        return result;
-    }
+/**
+ * Collections whose key the *browser* cannot resolve, and what it will do
+ * instead.
+ *
+ * The two sides resolve keys from different evidence. This driver reads, in
+ * order: properties marked `isId`, the primary keys of the Drizzle schema, then
+ * a column literally named `id`. The admin shares the `CollectionConfig` — it
+ * compiles the same collection files into its bundle — but never the Drizzle
+ * schema, so the middle tier is invisible to it.
+ *
+ * Nothing can normalize this at runtime: the server does not serve the admin
+ * its collections, so a key resolved here cannot be handed over there. The
+ * config files are the only thing both sides read, so the fix is an edit to
+ * them, and the most this can do is say exactly which edit.
+ *
+ * Two shapes, and the second is the dangerous one:
+ *
+ * - No `isId`, no `id` property → the admin resolves no address, warns in the
+ *   console, and rows cannot be opened or linked.
+ * - No `isId`, but an `id` property that is *not* the key → the admin addresses
+ *   rows by `id` while this driver reads the address as the real key. Nothing
+ *   errors: the addresses look right and route wrong.
+ */
+export function findUnresolvableKeyCollections(
+    collections: CollectionConfig[],
+    registry: PostgresCollectionRegistry
+): { collection: CollectionConfig; keys: PrimaryKeyInfo[]; shadowedByIdProperty: boolean }[] {
+    const findings: { collection: CollectionConfig; keys: PrimaryKeyInfo[]; shadowedByIdProperty: boolean }[] = [];
 
-    // Composite key - split by :::
-    const parts = String(idValue).split(":::");
-    if (parts.length !== primaryKeys.length) {
-        throw new Error(`Composite ID parts mismatch. Expected ${primaryKeys.length}, got ${parts.length} for ID: ${idValue}`);
-    }
+    for (const collection of collections) {
+        // Declared `isId` is the tier both sides share: if it is there, they agree.
+        if (getDeclaredPrimaryKeys(collection).length > 0) continue;
 
-    for (let i = 0; i < primaryKeys.length; i++) {
-        const pk = primaryKeys[i];
-        const val = parts[i];
-        if (pk.type === "number" && !pk.isUUID) {
-            const parsed = parseInt(val, 10);
-            if (isNaN(parsed)) {
-                throw new Error(`Invalid numeric ID component: ${val}`);
-            }
-            result[pk.fieldName] = parsed;
-        } else {
-            result[pk.fieldName] = val;
-        }
+        // No registered table resolves to no keys, and a collection this cannot
+        // resolve a key for is one it has nothing to say about.
+        const keys = getPrimaryKeys(collection, registry);
+        if (keys.length === 0) continue;
+
+        // A single key named `id` is the last tier on both sides: they agree
+        // without anything being declared.
+        if (keys.length === 1 && keys[0].fieldName === "id") continue;
+
+        findings.push({
+            collection,
+            keys,
+            shadowedByIdProperty: Boolean(collection.properties?.id)
+        });
     }
 
-    return result;
+    return findings;
 }
 
-export function buildCompositeId(values: Record<string, unknown>, primaryKeys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[]): string {
-    if (primaryKeys.length === 0) {
-        return "";
+/**
+ * Report the collections from {@link findUnresolvableKeyCollections} at boot,
+ * with the edit that fixes each one.
+ *
+ * Grouped by failure, not by collection: the shadowed case is a routing bug and
+ * the silent case is a missing feature, and they deserve different urgency.
+ */
+export function warnOnKeysTheAdminCannotResolve(
+    collections: CollectionConfig[],
+    registry: PostgresCollectionRegistry
+): void {
+    const findings = findUnresolvableKeyCollections(collections, registry);
+    if (findings.length === 0) return;
+
+    const edit = (f: { collection: CollectionConfig; keys: PrimaryKeyInfo[] }) =>
+        `${f.collection.slug}: mark ${f.keys.map(k => `\`${k.fieldName}\``).join(" and ")} with ` +
+        `\`isId: ${f.keys[0].isUUID ? "\"uuid\"" : f.keys[0].type === "number" ? "\"increment\"" : "true"}\``;
+
+    const shadowed = findings.filter(f => f.shadowedByIdProperty);
+    const silent = findings.filter(f => !f.shadowedByIdProperty);
+
+    if (shadowed.length > 0) {
+        logger.warn(
+            `⚠️ These collections declare no \`isId\`, and their key is only in the drizzle schema — but they ` +
+            `do have a property called \`id\`. The admin has no way to know \`id\` is not the key, so it will ` +
+            `address rows by it while this server reads the address as the real key: the links look right and ` +
+            `route wrong. Nothing will error.\n\n` +
+            shadowed.map(f => `  • ${edit(f)}`).join("\n") + "\n"
+        );
     }
-    if (primaryKeys.length === 1) {
-        return String(values[primaryKeys[0].fieldName] ?? "");
+
+    if (silent.length > 0) {
+        logger.warn(
+            `⚠️ These collections declare no \`isId\`, and their key is only in the drizzle schema, which the ` +
+            `admin never sees. It will resolve no address for their rows, so detail links, caching and ` +
+            `relations will not work for them:\n\n` +
+            silent.map(f => `  • ${edit(f)}`).join("\n") + "\n"
+        );
+    }
+}
+
+/**
+ * The address of a row: derived from the collection's primary keys, because a
+ * row does not carry one — it is exactly its columns.
+ *
+ * Falls back to a literal `id` column, for a row that reached us from somewhere
+ * other than this driver. Returns `""` when there is no key and no `id` —
+ * callers decide what that means, since "unaddressable" is a different answer
+ * in a notification (broadcast a wildcard) than in a save (fail).
+ */
+export function deriveRowAddress(
+    row: Record<string, unknown>,
+    collection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): string {
+    const composite = buildCompositeId(row, getPrimaryKeys(collection, registry));
+    // An all-empty composite is indistinguishable from a missing key, and
+    // `buildCompositeId` returns "" for no keys at all.
+    if (composite && composite.split(COMPOSITE_ID_SEPARATOR).some(part => part !== "")) {
+        return composite;
     }
-    return primaryKeys.map(pk => String(values[pk.fieldName] ?? "")).join(":::");
+    if (row.id !== undefined && row.id !== null) return String(row.id);
+    return "";
 }
+

package/src/services/dataService.ts

@@ -154,9 +154,10 @@ export class DataService implements DataRepository {
         collectionPath: string,
         values: Partial<M>,
         id?: string | number,
-        databaseId?: string
+        databaseId?: string,
+        options?: { upsert?: boolean }
     ): Promise<Record<string, unknown>> {
-        return this.persistService.save<M>(collectionPath, values, id, databaseId);
+        return this.persistService.save<M>(collectionPath, values, id, databaseId, options);
     }
 
     /**

package/src/services/index.ts

@@ -8,6 +8,7 @@ export {
     getCollectionByPath,
     getTableForCollection,
     getPrimaryKeys,
+    deriveRowAddress,
     parseIdValues,
     buildCompositeId
 } from "./collection-helpers";