@rebasepro/server-postgres 0.9.1-canary.1d2d8b5 → 0.9.1-canary.29ed165

package/dist/schema/auth-bootstrap-sql.d.ts

@@ -21,4 +21,4 @@
  * `DROP SCHEMA "rebase" CASCADE` on the next diff. The `auth` schema is safe
  * because the generated schema.sql declares it.
  */
-export declare const AUTH_BOOTSTRAP_SQL = "-- Auth schema + RLS helper functions (required by the policies below)\nCREATE SCHEMA IF NOT EXISTS auth;\n\nCREATE OR REPLACE FUNCTION auth.uid() RETURNS text AS $$\n    SELECT NULLIF(current_setting('app.user_id', true), '');\n$$ LANGUAGE sql STABLE;\n\nCREATE OR REPLACE FUNCTION auth.jwt() RETURNS jsonb AS $$\n    SELECT COALESCE(\n        NULLIF(current_setting('app.jwt', true), ''),\n        '{}'\n    )::jsonb;\n$$ LANGUAGE sql STABLE;\n\nCREATE OR REPLACE FUNCTION auth.roles() RETURNS text AS $$\n    SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');\n$$ LANGUAGE sql STABLE;\n";
+export declare const AUTH_BOOTSTRAP_SQL = "-- Auth schema + RLS helper functions (required by the policies below)\nCREATE SCHEMA IF NOT EXISTS auth;\n\n-- Falls back to the pre-rename `app.user_id` so a database that has taken the\n-- new schema but is still served by an older backend keeps resolving the\n-- principal. Drop the COALESCE once no such deployment remains.\nCREATE OR REPLACE FUNCTION auth.uid() RETURNS text AS $$\n    SELECT COALESCE(\n        NULLIF(current_setting('app.uid', true), ''),\n        NULLIF(current_setting('app.user_id', true), '')\n    );\n$$ LANGUAGE sql STABLE;\n\nCREATE OR REPLACE FUNCTION auth.jwt() RETURNS jsonb AS $$\n    SELECT COALESCE(\n        NULLIF(current_setting('app.jwt', true), ''),\n        '{}'\n    )::jsonb;\n$$ LANGUAGE sql STABLE;\n\nCREATE OR REPLACE FUNCTION auth.roles() RETURNS text AS $$\n    SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');\n$$ LANGUAGE sql STABLE;\n";

package/dist/schema/auth-schema.d.ts

@@ -290,8 +290,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "refresh_tokens";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -422,8 +422,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "password_reset_tokens";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -593,8 +593,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "user_identities";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -723,8 +723,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "mfa_factors";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -983,8 +983,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "recovery_codes";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -1077,8 +1077,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "magic_link_tokens";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -1456,8 +1456,8 @@ export declare const refreshTokens: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "refresh_tokens";
             dataType: "string";
             columnType: "PgUUID";
@@ -1588,8 +1588,8 @@ export declare const passwordResetTokens: import("drizzle-orm/pg-core").PgTableW
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "password_reset_tokens";
             dataType: "string";
             columnType: "PgUUID";
@@ -1759,8 +1759,8 @@ export declare const userIdentities: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "user_identities";
             dataType: "string";
             columnType: "PgUUID";
@@ -1889,8 +1889,8 @@ export declare const mfaFactors: import("drizzle-orm/pg-core").PgTableWithColumn
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "mfa_factors";
             dataType: "string";
             columnType: "PgUUID";
@@ -2149,8 +2149,8 @@ export declare const recoveryCodes: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "recovery_codes";
             dataType: "string";
             columnType: "PgUUID";
@@ -2243,8 +2243,8 @@ export declare const magicLinkTokens: import("drizzle-orm/pg-core").PgTableWithC
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "magic_link_tokens";
             dataType: "string";
             columnType: "PgUUID";

package/dist/schema/doctor.d.ts

@@ -2,7 +2,7 @@ import { CollectionConfig, Property } from "@rebasepro/types";
 export type IssueSeverity = "error" | "warning" | "info";
 export interface DoctorIssue {
     severity: IssueSeverity;
-    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale";
+    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale" | "sdk_not_generated";
     table?: string;
     column?: string;
     expected?: string;

package/dist/schema/introspect-db-logic.d.ts

@@ -32,11 +32,6 @@ export interface TableMeta {
     fks: ForeignKeyRow[];
 }
 export declare function singularize(word: string): string;
-/**
- * Convert a snake_case name to a human-readable Title Case label.
- * e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
- */
-export declare function humanize(snakeName: string): string;
 /**
  * Convert a snake_case table name to a camelCase + "Collection" variable name.
  * e.g. "company_token" -> "companyTokenCollection"

package/dist/schema/introspect-db-naming.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Naming helpers shared by the introspection modules. These live apart from
+ * `introspect-db-logic.ts` because the inference pass needs them too, and
+ * importing them from there would close a cycle back through this module.
+ */
+/**
+ * Convert a snake_case name to a human-readable Title Case label.
+ * e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
+ */
+export declare function humanize(snakeName: string): string;

package/dist/security/policy-drift.d.ts

@@ -26,6 +26,14 @@ export interface PolicyRef {
     hasUsing: boolean;
     /** Whether a WITH CHECK clause is present at all (not what it says). */
     hasWithCheck: boolean;
+    /**
+     * The live clause text, when read from `pg_policies`. Present only for live
+     * policies (the expected side is parsed from DDL and does not carry it).
+     * Used solely for the insecure-tautology scan, not for divergence — Postgres
+     * rewrites this text, so it is not safe to diff against expected.
+     */
+    qual?: string | null;
+    withCheck?: string | null;
 }
 export interface PolicyDrift {
     /** Described by the collections, absent from the database. */
@@ -38,6 +46,22 @@ export interface PolicyDrift {
         actual: PolicyRef;
         differences: string[];
     }[];
+    /**
+     * A live policy whose expression is the known-permissive tautology
+     * `auth.uid() IS NOT NULL` — true for anonymous visitors too, because the
+     * user path coerces a blank id to the `'anonymous'` sentinel. This is what
+     * `policy.authenticated()` used to compile to, so a database pushed before
+     * that fix carries it, and neither the name, roles, command nor clause
+     * *presence* differs from the corrected policy — the only thing that changed
+     * is the expression text, which this checker otherwise (correctly) ignores.
+     * So it is the one drift that hides from every other check here.
+     *
+     * @see reason  a sentence naming the clause and what to do.
+     */
+    insecure: {
+        policy: PolicyRef;
+        reason: string;
+    }[];
 }
 export interface Queryable {
     query<R>(text: string, values?: unknown[]): Promise<{
@@ -63,6 +87,36 @@ export declare function parseExpectedPolicies(ddl: string): PolicyRef[];
  * of reads. The same blindness would hide a policy that fails open.
  */
 export declare function checkPolicyDrift(client: Queryable, collections: CollectionConfig[]): Promise<PolicyDrift>;
+/**
+ * Does this name look like one the generator produced for this table?
+ *
+ * Unnamed rules compile to `<table>_<op>_<sha1[0:7]>` (plus `_<idx>` when one
+ * rule spans several operations), and the hash covers the rule's semantics — so
+ * *editing* a rule renames its policy. The policy under the old name is left
+ * behind by `db push`, which only DROPs the names it is about to CREATE, and
+ * Postgres ORs PERMISSIVE policies together: a superseded `USING (true)` keeps
+ * granting everything no matter how tight its replacement is.
+ *
+ * Matching the shape is what makes dropping them safe. A hand-written policy
+ * would have to collide with a 7-hex digest to be mistaken for generated one;
+ * a policy named anything else is left alone and merely reported, because a
+ * custom name is indistinguishable from one someone wrote in SQL on purpose.
+ */
+export declare function isGeneratedPolicyName(name: string, table: string): boolean;
+export interface OrphanCleanup {
+    /** Superseded generated policies that were dropped. */
+    dropped: PolicyRef[];
+    /** Orphans left in place because their names are not generator-shaped. */
+    kept: PolicyRef[];
+}
+/**
+ * Drop the policies an earlier push superseded but never removed.
+ *
+ * Only touches tables the collections describe — a table with no expected
+ * policy is not ours to reconcile, and scanning by schema alone would sweep up
+ * policies belonging to something else sharing the database.
+ */
+export declare function dropOrphanedPolicies(client: Queryable, drift: PolicyDrift, collections: CollectionConfig[]): Promise<OrphanCleanup>;
 export declare const hasDrift: (d: PolicyDrift) => boolean;
 /** Human-readable report; empty string when the database matches the config. */
 export declare function formatPolicyDrift(drift: PolicyDrift): string;

package/dist/security/rls-enforcement.d.ts

@@ -51,7 +51,7 @@ export interface ConnectionPosture {
     privileged: boolean;
 }
 export interface AuthContext {
-    userId: string;
+    uid: string;
     /** Raw roles as carried on the user (strings or `{ id }` objects). */
     roles: unknown[];
 }
@@ -93,7 +93,7 @@ export declare function ensureAppRole(run: RawSqlRunner, schemas: string[]): Pro
  * SECURITY: this function is only ever called on the **user** path (the server
  * context uses the base/owner driver and never calls it). The default policies
  * treat `auth.uid() IS NULL` as the trusted server context, and `auth.uid()`
- * is `NULLIF(current_setting('app.user_id'), '')` — so an EMPTY user id would
+ * is `NULLIF(current_setting('app.uid'), '')` — so an EMPTY user id would
  * be read as NULL and silently escalate a user request to server privileges.
  * Coerce empty/blank ids to `ANONYMOUS_USER_ID` here, at the single chokepoint,
  * rather than trusting every caller (e.g. realtime subscription auth) to do it.

package/dist/services/FetchService.d.ts

@@ -40,44 +40,22 @@ export declare class FetchService {
      * the target relation so actual row data is returned.
      */
     private buildWithConfig;
-    /**
-     * Detect if a many-to-many relation uses a junction table in the Drizzle schema.
-     */
-    private isJunctionRelation;
     /**
      * Get the Drizzle relation name on the junction table that points to the actual target row.
      * For example, for posts_tags junction, this returns "tag_id" (the relation pointing to tags).
      */
     private getJunctionTargetRelationName;
-    /**
-     * Convert a db.query result row (with nested relation objects) to a flat row.
-     * Handles:
-     * - Placing `id` at the top level as a string
-     * - Type normalization (dates, numbers, NaN) via normalizeDbValues
-     * - Converting nested relation objects to { id, path, __type: "relation" } for CMS
-     * - Flattening junction-table many-to-many results
-     */
-    private drizzleResultToRow;
     /**
      * Post-fetch joinPath relations for a single flat row.
      * joinPath relations cannot be expressed via Drizzle's `with` config,
      * so they must be loaded separately after the primary query.
      */
     private resolveJoinPathRelations;
-    /**
-     * Post-fetch joinPath relations for a batch of flat rows.
-     * Uses batch fetching to avoid N+1 queries for list views.
-     */
-    private resolveJoinPathRelationsBatch;
     /**
      * Resolves joinPath relations for raw REST rows and directly injects them.
      * Uses RelationService to query the database and maps results back to the flattened objects.
      */
     private resolveJoinPathRelationsBatchRest;
-    /**
-     * Convert a db.query result row to a flat REST-style object with populated relations.
-     */
-    private drizzleResultToRestRow;
     /**
      * Build db.query-compatible options from standard fetch options.
      * Handles filter, search, orderBy, limit, and cursor-based pagination.
@@ -108,8 +86,10 @@ export declare class FetchService {
     }): Promise<Record<string, unknown>[]>;
     /**
      * Fallback path used when db.query is unavailable.
-     * The primary path uses drizzleResultToRow which handles relation
-     * mapping without N+1 queries.
+     *
+     * The primary path runs the results through `toCmsRow`, which maps
+     * relations from what drizzle already nested — no query per row. This one
+     * has no nesting to read, so it resolves relations itself, in batches.
      *
      * Process raw database results into flat rows with relations.
      */

package/dist/services/PersistService.d.ts

@@ -40,8 +40,16 @@ export declare class PersistService {
     deleteAll(collectionPath: string, _databaseId?: string): Promise<void>;
     /**
      * Save an row (create or update)
+     *
+     * With `options.upsert`, the row is written with INSERT ... ON CONFLICT DO
+     * UPDATE against the primary key rather than a plain UPDATE. That is one
+     * statement, so it cannot lose a race the way a read-then-write can, and it
+     * does not care whether the row already exists — which is what a re-runnable
+     * import needs.
      */
-    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string): Promise<Record<string, unknown>>;
+    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
+        upsert?: boolean;
+    }): Promise<Record<string, unknown>>;
     /**
      * Get the RelationService instance for external use
      */

package/dist/services/RelationService.d.ts

@@ -20,6 +20,40 @@ export declare class RelationService {
     private db;
     private registry;
     constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    /**
+     * One target row, as the {@link RelatedRow} everything here returns.
+     *
+     * Eight sites built this by hand, which is how the address came to be the
+     * target's first key column in all eight — one edit, eight places to miss.
+     *
+     * `resolveNested` is the one thing they did not agree on, and the
+     * disagreement was invisible: the single-parent fetches pass `db` and
+     * `registry` to `parseDataFromServer`, so the target's *own* relations get
+     * resolved too, while the batch paths deliberately do not — a query per
+     * target row is the N+1 the batching exists to avoid. Naming the parameter
+     * makes that a decision rather than a difference between two call sites
+     * nobody was comparing.
+     */
+    private toRelatedRow;
+    /**
+     * A WHERE matching any of `parentIds`, by the whole key.
+     *
+     * A single key is an `IN (…)`. A composite one cannot be: matching
+     * `tenant_id IN (1, 1)` collects every row of tenant 1, so two parents that
+     * share their first column each receive the other's relations. It becomes
+     * an OR of ANDs — one exact address per parent — which Postgres indexes the
+     * same way it would a multi-column key lookup.
+     */
+    private parentKeyCondition;
+    /**
+     * Reject a relation that cannot express a composite-keyed parent.
+     *
+     * `localKey` and `foreignKeyOnTarget` are single column names: one column
+     * cannot reference a two-column key, so such a relation has no correct
+     * reading. Left alone it would silently match on the first key column and
+     * hand a tenant's rows to its neighbour — say so instead.
+     */
+    private assertSingleKeyAddressable;
     /**
      * Fetch rows related to a parent row through a specific relation
      */
@@ -72,7 +106,6 @@ export declare class RelationService {
         relationKey: string;
         relation: Relation;
         newValue: unknown;
-        currentId?: string | number;
     }>): Promise<void>;
     /**
      * Handle inverse relations with joinPath

package/dist/services/channel-history.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ChannelHistoryEntry, ChannelRetentionRule } from "@rebasepro/types";
+/**
+ * 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 declare function parseTtlMs(ttl: number | string | undefined): number | 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 declare function channelMatchesRule(channel: string, rule: ChannelRetentionRule): boolean;
+/** 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 declare class ChannelHistoryStore {
+    private db;
+    private rules;
+    /** Resolved rule per channel name, so the match runs once per channel. */
+    private resolved;
+    /** Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}. */
+    private lastPruned;
+    private tablesReady;
+    constructor(db: NodePgDatabase<Record<string, unknown>>, rules?: ChannelRetentionRule[]);
+    /** Whether any channel retains anything at all. */
+    get enabled(): boolean;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    ensureTables(): Promise<void>;
+    /**
+     * 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.
+     */
+    append(channel: string, event: string, payload: unknown, senderId?: string): Promise<{
+        seq: number;
+        at: string;
+    }>;
+    /**
+     * 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.
+     */
+    replay(channel: string, sinceSeq?: number, limit?: number): Promise<{
+        messages: ChannelHistoryEntry[];
+        latestSeq: number;
+    }>;
+    /**
+     * 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.
+     */
+    prune(channel: string, retention: ResolvedRetention): Promise<number>;
+    /** Forget throttle and match caches. Called on shutdown. */
+    clear(): void;
+}

package/dist/services/collection-helpers.d.ts

@@ -1,6 +1,9 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 import { CollectionConfig } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+export { buildCompositeId, parseIdValues, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
+export type { PrimaryKeyInfo } from "@rebasepro/common";
+import type { PrimaryKeyInfo } from "@rebasepro/common";
 /**
  * Shared helper functions for row operations.
  * These are used by FetchService, PersistService, and RelationService.
@@ -21,18 +24,80 @@ export interface DrizzleColumnMeta {
 export declare function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta;
 export declare function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): CollectionConfig;
 export declare function getTableForCollection(collection: CollectionConfig, registry: PostgresCollectionRegistry): PgTable<any>;
-export declare function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): {
-    fieldName: string;
-    type: "string" | "number";
-    isUUID?: boolean;
+/**
+ * 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 declare function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[];
+/**
+ * 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 declare function requirePrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[];
+/**
+ * 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 declare function findUnresolvableKeyCollections(collections: CollectionConfig[], registry: PostgresCollectionRegistry): {
+    collection: CollectionConfig;
+    keys: PrimaryKeyInfo[];
+    shadowedByIdProperty: boolean;
 }[];
-export declare function parseIdValues(idValue: string | number, primaryKeys: {
-    fieldName: string;
-    type: "string" | "number";
-    isUUID?: boolean;
-}[]): Record<string, string | number>;
-export declare function buildCompositeId(values: Record<string, unknown>, primaryKeys: {
-    fieldName: string;
-    type: "string" | "number";
-    isUUID?: boolean;
-}[]): string;
+/**
+ * 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 declare function warnOnKeysTheAdminCannotResolve(collections: CollectionConfig[], registry: PostgresCollectionRegistry): void;
+/**
+ * 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 declare function deriveRowAddress(row: Record<string, unknown>, collection: CollectionConfig, registry: PostgresCollectionRegistry): string;

package/dist/services/dataService.d.ts

@@ -82,7 +82,9 @@ export declare class DataService implements DataRepository {
     /**
      * Save an row (create or update)
      */
-    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string): Promise<Record<string, unknown>>;
+    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
+        upsert?: boolean;
+    }): Promise<Record<string, unknown>>;
     /**
      * Delete an row by ID
      */

package/dist/services/index.d.ts

@@ -1,4 +1,4 @@
 export { FetchService } from "./FetchService";
 export { PersistService } from "./PersistService";
 export { RelationService } from "./RelationService";
-export { getCollectionByPath, getTableForCollection, getPrimaryKeys, parseIdValues, buildCompositeId } from "./collection-helpers";
+export { getCollectionByPath, getTableForCollection, getPrimaryKeys, deriveRowAddress, parseIdValues, buildCompositeId } from "./collection-helpers";