@rebasepro/types 0.10.0 → 0.10.1-canary.14e53ae

package/dist/types/storage_authorize.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The storage access-control contract.
+ *
+ * Lives here rather than in `@rebasepro/server` because a project declares its
+ * `storageAuthorize` hook from its **config package**, and a config package
+ * depends on `@rebasepro/types` alone. A type the contract requires but the
+ * contract's author cannot import is not much of a contract.
+ *
+ * `@rebasepro/server` re-exports all of this, so existing imports keep working.
+ */
+export type StorageOperation = "read" | "write" | "delete" | "list";
+/** The caller, as resolved by whichever auth middleware ran. */
+export interface StorageAuthorizeUser {
+    uid: string;
+    email?: string;
+    roles?: string[];
+}
+export interface StorageAuthorizeContext {
+    /** Object key, bucket prefix stripped and traversal already sanitized. */
+    key: string;
+    bucket: string;
+    operation: StorageOperation;
+    /** Null when the route allows unauthenticated access. */
+    user: StorageAuthorizeUser | null;
+    /** Named backend the request targeted, when one was given. */
+    storageId?: string;
+    /**
+     * Trusted, RLS-bypassing data access, so the hook can answer the question it
+     * actually has to answer: *who owns this object?*
+     *
+     * Without it the hook can only do prefix arithmetic on the key, which
+     * expresses no real multi-tenant rule — ownership lives in a row, not in a
+     * string. And it cannot simply import the server to get one: a project
+     * declares this hook from its **config** package, which depends on
+     * `@rebasepro/types` alone and cannot resolve `@rebasepro/server` at
+     * runtime. So the accessor is handed in.
+     *
+     * It bypasses row-level security on purpose. The hook IS the authorization
+     * decision; asking it to make that decision through a reader that has
+     * already been narrowed by the caller's own permissions is circular.
+     */
+    data?: StorageAuthorizeData;
+}
+/**
+ * The slice of the data API a storage hook needs: read a collection, in the
+ * trusted server context.
+ *
+ * Deliberately read-only and deliberately tiny. A hook that can write is a hook
+ * that can be tricked into writing, and an authorization check has no business
+ * mutating anything.
+ */
+export interface StorageAuthorizeData {
+    collection(slug: string): {
+        find(query?: Record<string, unknown>): Promise<{
+            data: Record<string, unknown>[];
+        }>;
+        findById(id: string): Promise<Record<string, unknown> | null>;
+    };
+}
+/**
+ * Per-object access control for storage, the analogue of an RLS policy on a
+ * collection.
+ *
+ * Without it, storage routes authenticate but do not authorize: `requireAuth`
+ * and `publicRead` are global switches, so any signed-in user could read any
+ * key they could name. That is fine for a single-tenant app and useless for a
+ * multi-tenant one, where the only thing separating two tenants' files would be
+ * key unguessability — not an access-control model. Multi-tenant apps were
+ * left to route every byte through a custom function to get an ownership check
+ * in, and each of them had to invent it.
+ *
+ * Return false (or throw) to deny. Denials surface as 403.
+ */
+export type StorageAuthorize = (ctx: StorageAuthorizeContext) => boolean | Promise<boolean>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.10.1-canary.14e53ae",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"

package/src/controllers/client.ts

@@ -384,9 +384,10 @@ export interface RebaseServerClient<DB = unknown> extends RebaseClient<DB> {
 
     /**
      * Execute raw SQL against the database. Always present server-side for SQL
-     * engines.
+     * engines. Values interpolated into the query should be passed via
+     * `params`, referenced as `$1`, `$2`, … placeholders in the query text.
      */
-    sql(query: string, options?: { database?: string; role?: string }): Promise<Record<string, unknown>[]>;
+    sql(query: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;
 }
 
 // ─── RebaseBrowserClient ─────────────────────────────────────────────────────

package/src/controllers/data_driver.ts

@@ -40,6 +40,62 @@ export interface VectorSearchParams {
     threshold?: number;
 }
 
+// ── List pagination bounds ────────────────────────────────────────────────
+//
+// Client-driven list reads (REST `GET /<collection>` and the WebSocket
+// `subscribe_collection` message) accept a client-supplied `limit`. Without
+// bounds, an ABSENT limit streams the entire table into memory — a trivial
+// OOM/DoS — and `limit=100000000` (or `limit=0`, historically an unlimited
+// bypass) is honoured verbatim. `resolveClientListLimit` is the single shared
+// enforcement point so every untrusted ingress behaves identically. Trusted
+// server-side callers build fetch options directly and are intentionally NOT
+// bounded here (migrations, admin exports, and CDC refetches may need the full
+// set).
+
+/** Rows returned for a plain / text-search list read when the client sends no `limit`. */
+export const DEFAULT_LIST_LIMIT = 50;
+/** Rows returned for a vector-search list read when the client sends no `limit`. */
+export const DEFAULT_VECTOR_LIST_LIMIT = 10;
+/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
+export const MAX_LIST_LIMIT = 1000;
+
+/** Overridable bounds for {@link resolveClientListLimit}. */
+export interface ListLimitBounds {
+    /** Default page size for plain and text-search reads. */
+    defaultLimit?: number;
+    /** Default page size for vector-search reads. */
+    vectorDefaultLimit?: number;
+    /** Upper bound clamped onto any client-supplied limit. */
+    maxLimit?: number;
+}
+
+/**
+ * Resolve a client-supplied list `limit` into a safe, always-defined value.
+ *
+ * - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
+ *   so `0`, negatives, and absurd values can never bypass the cap.
+ * - An absent / blank / non-numeric limit falls back to the mode default:
+ *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+ *
+ * The return is never `undefined` — no ingress that routes its client limit
+ * through this can produce an unbounded read.
+ */
+export function resolveClientListLimit(
+    rawLimit: number | string | null | undefined,
+    opts: ListLimitBounds & { vectorSearch?: boolean } = {}
+): number {
+    const maxLimit = opts.maxLimit ?? MAX_LIST_LIMIT;
+    if (rawLimit != null && String(rawLimit).trim() !== "") {
+        const parsed = typeof rawLimit === "number" ? rawLimit : parseInt(String(rawLimit), 10);
+        if (Number.isFinite(parsed)) {
+            return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);
+        }
+    }
+    return opts.vectorSearch
+        ? (opts.vectorDefaultLimit ?? DEFAULT_VECTOR_LIST_LIMIT)
+        : (opts.defaultLimit ?? DEFAULT_LIST_LIMIT);
+}
+
 /**
  * @internal
  */

package/src/types/backend.ts

@@ -1,6 +1,7 @@
 import type { CollectionConfig, FilterValues, WhereFilterOp } from "./collections";
 import type { AuthAdapter } from "./auth_adapter";
 import type { HistoryConfig } from "../controllers/client";
+import type { ChannelBusSetting } from "./channel_bus";
 
 // =============================================================================
 // DATABASE CONNECTION INTERFACES
@@ -272,13 +273,23 @@ export interface ChannelRetentionRule {
     ttl?: number | string;
 }
 
-/** Server-side realtime options. */
+/**
+ * Server-side realtime options.
+ *
+ * The channel bus contract and its config live in `./channel_bus` so that a
+ * transport shipped as its own package depends on the contract alone.
+ */
 export interface RealtimeChannelsConfig {
     /**
      * Retention rules, most specific first — the first match wins. Omitted or
      * empty means no channel retains anything.
      */
     channels?: ChannelRetentionRule[];
+    /**
+     * How channel broadcast and presence reach other backend instances.
+     * Defaults to `{ type: "memory" }` — i.e. they don't.
+     */
+    bus?: ChannelBusSetting;
 }
 
 /**
@@ -766,6 +777,27 @@ export interface BackendBootstrapper {
      */
     getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;
 
+    /**
+     * Bring the database's collection tables up to date, additively.
+     *
+     * Optional because it is only meaningful for schema-ful drivers. A managed
+     * runtime boots a compiled project against a database it has never seen; auth
+     * tables are ensured on boot but collection tables were created by nothing,
+     * so every data request answered 500 on a missing relation. The CLI's `db
+     * push` cannot fill the gap — it needs Atlas, and the runtime image ships no
+     * CLI.
+     *
+     * Implementations MUST be additive-only: create missing tables, columns and
+     * enum types, and never drop, narrow or rewrite anything. This runs
+     * unattended against live customer data with nobody reading a diff, so the
+     * destructive half stays a deliberate migration.
+     */
+    ensureCollectionSchema?(
+        collections: unknown[],
+        driverResult: InitializedDriver,
+        log?: (message: string) => void
+    ): Promise<{ applied: number }>;
+
     /**
      * Initialize WebSocket server for realtime operations.
      */

package/src/types/channel_bus.ts

@@ -0,0 +1,202 @@
+/**
+ * The cross-instance transport for channel broadcast and presence, and the
+ * contract anyone implementing one has to meet.
+ *
+ * These types live in `@rebasepro/types` rather than in the Postgres adapter on
+ * purpose: a transport package should depend on the contract, not on the
+ * database driver that happens to ship the default implementation. A
+ * `@rebasepro/channel-bus-<something>` package needs this file and nothing else.
+ *
+ * Why a transport exists at all: entity/collection realtime already spans
+ * instances (CDC, or per-mutation LISTEN/NOTIFY). Channel broadcast and presence
+ * did not — they fanned out from per-process maps, so two clients served by
+ * different replicas could not see each other, and nothing errored. The bus is
+ * the missing hop, and deliberately *only* that hop: which local clients receive
+ * a frame stays in the realtime service, so a transport never has to know what a
+ * subscription, a WebSocket or a presence roster is.
+ */
+
+/**
+ * A frame in flight between instances.
+ *
+ * `sid` identifies the publishing instance. The realtime service drops frames
+ * carrying its own `sid` on arrival — local fan-out already happened before the
+ * publish — so a transport that echoes a publisher's own messages back to it is
+ * still correct, merely wasteful.
+ *
+ * Keys are spelled out rather than abbreviated. The one shipped transport with a
+ * size limit has a pointer path for anything that would approach it, so shaving
+ * bytes off key names buys nothing worth the opacity.
+ */
+export type ChannelBusFrame =
+    /** A broadcast carrying its payload. */
+    | {
+        kind: "broadcast";
+        sid: string;
+        channel: string;
+        event: string;
+        /** Originating client, echoed so receivers can skip it if it is theirs. */
+        from?: string;
+        /** Sequence number, present only on retained channels. */
+        seq?: number;
+        payload: unknown;
+    }
+    /**
+     * A broadcast too large for the transport to carry inline: the body is
+     * already durable in `rebase.channel_messages`, so the frame carries only
+     * its address and each receiver reads it back. Only ever emitted for
+     * retained channels, and only by a transport with a finite
+     * {@link ChannelBus.maxFrameBytes}.
+     */
+    | {
+        kind: "broadcast_ref";
+        sid: string;
+        channel: string;
+        from?: string;
+        seq: number;
+    }
+    /** A presence join/leave/update, small by construction. */
+    | {
+        kind: "presence_diff";
+        sid: string;
+        channel: string;
+        joins: Record<string, Record<string, unknown>>;
+        leaves: Record<string, Record<string, unknown>>;
+    };
+
+/** Receives frames published by *other* instances. */
+export type ChannelBusHandler = (frame: ChannelBusFrame) => void | Promise<void>;
+
+/**
+ * A cross-instance transport.
+ *
+ * ## What an implementation must guarantee
+ *
+ * - **`start()` rejects if the transport is unusable.** The caller falls back to
+ *   in-process delivery when it does. Resolving while disconnected produces a
+ *   cluster that believes it is connected and silently is not, which is the
+ *   exact failure this whole mechanism exists to remove.
+ * - **`publish()` reaches every *other* instance, or rejects.** Delivery back to
+ *   the publisher is permitted but pointless (see {@link ChannelBusFrame.sid}).
+ * - **`stop()` is idempotent** and releases everything, including anything
+ *   holding the event loop open.
+ * - **A malformed message never throws out of the transport.** Parsing happens
+ *   inside the implementation; drop and log what you cannot understand, so one
+ *   bad frame cannot take the listener down.
+ *
+ * ## What it does *not* have to guarantee
+ *
+ * - **Ordering.** Retained channels carry `seq`, and the client SDK orders by
+ *   it. Unsequenced broadcasts are cursor-grade traffic where order is not
+ *   meaningful.
+ * - **Durability.** A frame lost in transit is a missed live update; retained
+ *   channels repair themselves through the client's `channel_history` replay.
+ * - **Exactly-once.** Duplicates are tolerated — retained frames are deduped by
+ *   `seq`, and presence diffs are idempotent by construction.
+ */
+export interface ChannelBus {
+    /**
+     * Identifies the transport in logs and in `getChannelBusKind()`. Use your
+     * own name; the framework only compares against `"memory"` to decide
+     * whether publishing is worth attempting at all.
+     */
+    readonly kind: string;
+
+    /**
+     * Largest frame this transport will carry, in bytes of encoded JSON, or
+     * `Infinity` when there is no meaningful ceiling.
+     *
+     * A broadcast that exceeds it is published as a `broadcast_ref` pointer when
+     * the channel is retained, and refused with an error to the sender when it
+     * is not. Implementations with no limit should return `Infinity` rather than
+     * a large number, so the pointer path is never taken needlessly.
+     */
+    readonly maxFrameBytes: number;
+
+    /** Connect and begin delivering remote frames to `handler`. */
+    start(handler: ChannelBusHandler): Promise<void>;
+
+    /** Publish a frame to the other instances. */
+    publish(frame: ChannelBusFrame): Promise<void>;
+
+    /** Disconnect and release resources. Idempotent. */
+    stop(): Promise<void>;
+}
+
+/**
+ * Which transport to use, for the two that ship with the Postgres adapter.
+ *
+ * To use one that does not ship here — a Redis package, or your own class —
+ * pass the {@link ChannelBus} instance itself instead of a config object.
+ *
+ * There are deliberately only two built in, and neither adds a service to a
+ * deployment. Rebase deploys as Postgres + backend + frontend; a bus that
+ * required a message broker would put a second stateful service into every
+ * `docker-compose.yml` the CLI scaffolds, for a feature most applications never
+ * use. Measured across two backend instances against one Postgres container,
+ * the Postgres bus carried ~10k cross-instance messages/second with no losses,
+ * and stayed flat out to eight instances — comfortably past what live-cursor
+ * collaboration generates. The extension point below is the answer for anyone
+ * who does outgrow it.
+ */
+export type ChannelBusConfig =
+    /**
+     * In-process only — the historical behaviour. Broadcast and presence reach
+     * the clients connected to *this* instance and no further.
+     */
+    | { type: "memory" }
+    /**
+     * Postgres LISTEN/NOTIFY, reusing infrastructure the deployment already has.
+     *
+     * `pg_notify` caps a payload at 8000 bytes, so a broadcast larger than that
+     * is delivered cross-instance only on a *retained* channel, where the
+     * notification carries a pointer (`seq`) instead of the message and each
+     * receiver reads the body back from `rebase.channel_messages`. An oversized
+     * broadcast on an ephemeral channel is refused rather than silently
+     * delivered to half the cluster.
+     *
+     * NOTE: `LISTEN` needs a session-mode connection. Behind PgBouncer in
+     * transaction mode this must point at the database directly
+     * (`DATABASE_DIRECT_URL`), not at the pooler.
+     */
+    | {
+        type: "postgres";
+        /** Direct connection for the LISTEN client. Defaults to `DATABASE_DIRECT_URL`. */
+        connectionString?: string;
+        /**
+         * How long to coalesce outgoing frames into a single notification, in
+         * milliseconds. Defaults to 10.
+         *
+         * A notify is a query on your primary database, so under load this is
+         * the difference between one query per message and one per window. The
+         * window is leading-edge: a frame arriving when none is open goes out
+         * immediately, so an idle channel pays no added latency and only a
+         * sustained stream is batched.
+         *
+         * Set to 0 to disable coalescing and send every frame on its own.
+         */
+        batchWindowMs?: number;
+    };
+
+/**
+ * What `realtime.bus` accepts: a built-in transport by name, or any
+ * {@link ChannelBus} instance.
+ *
+ * ```typescript
+ * realtime: { bus: { type: "postgres" } }        // shipped
+ * realtime: { bus: new MyRedisChannelBus(url) }  // a separate package, or your own
+ * ```
+ */
+export type ChannelBusSetting = ChannelBusConfig | ChannelBus;
+
+/**
+ * Whether `setting` is an already-constructed transport rather than a request
+ * for a built-in one.
+ *
+ * Structural rather than nominal so that an instance from a *different copy* of
+ * `@rebasepro/types` — an entirely normal outcome of a separately versioned
+ * transport package — is still recognised.
+ */
+export function isChannelBusInstance(setting: ChannelBusSetting | undefined): setting is ChannelBus {
+    return typeof (setting as ChannelBus | undefined)?.publish === "function";
+}

package/src/types/collection_contract.ts

@@ -0,0 +1,249 @@
+import type { CollectionConfig } from "./collections";
+
+/**
+ * Serializing collections so they survive a network hop.
+ *
+ * A collection definition is not plain data. Relations point at their target
+ * with a *function* (`target: () => usersCollection`) so two collections can
+ * reference each other without an import cycle, and collections also carry
+ * callbacks, custom views and component references. `JSON.stringify` silently
+ * drops every one of those, which matters because the SDK generator *calls*
+ * `relation.target()` to decide whether a foreign key is a string or a number.
+ * Serialize naively and remote SDK generation produces subtly wrong types
+ * instead of failing — the worst possible outcome.
+ *
+ * So relation targets are resolved to a slug reference on the way out and
+ * rebuilt into functions on the way in. Everything else that cannot cross a wire
+ * is dropped deliberately: an SDK is generated from the *shape* of the data, and
+ * server-side behaviour is neither useful to a client nor safe to publish.
+ */
+
+/** Marker replacing a relation's `target` function in serialized form. */
+export interface SerializedCollectionRef {
+    __collectionRef: string;
+}
+
+export function isSerializedCollectionRef(value: unknown): value is SerializedCollectionRef {
+    return typeof value === "object"
+        && value !== null
+        && typeof (value as SerializedCollectionRef).__collectionRef === "string";
+}
+
+/** Depth limit for the walk — deep enough for real configs, finite for cyclic ones. */
+const MAX_DEPTH = 64;
+
+/**
+ * Resolve whatever a `target` thunk returns down to a collection.
+ *
+ * A target may be the collection, a module namespace (when the authoring file
+ * used `import * as`), or a default-export wrapper. All three appear in real
+ * projects, and the SDK generator already unwraps them the same way.
+ */
+function unwrapTarget(value: unknown): CollectionConfig | undefined {
+    if (!value || typeof value !== "object") return undefined;
+    const candidate = value as { default?: unknown; __esModule?: boolean; properties?: unknown };
+    if (candidate.default || candidate.__esModule) {
+        const inner = candidate.default;
+        if (inner && typeof inner === "object") return inner as CollectionConfig;
+    }
+    if (candidate.properties) return value as CollectionConfig;
+    return undefined;
+}
+
+/** The identity a serialized reference uses. Slug first — it is the routing key. */
+function refFor(collection: CollectionConfig | undefined): string | undefined {
+    if (!collection) return undefined;
+    const withPath = collection as CollectionConfig & { path?: string };
+    return collection.slug || withPath.path || collection.name;
+}
+
+/**
+ * Deep-copy a value into something JSON can carry.
+ *
+ * `target` keys are special-cased into refs. Other functions vanish, cycles are
+ * cut, and everything else is copied structurally.
+ */
+/** Shared walk state: the memo, plus a count of depth-cap hits. */
+interface WalkState {
+    memo: WeakMap<object, unknown>;
+    /**
+     * How many times the walk has truncated a subtree — by hitting the depth
+     * cap, or by cutting a cycle.
+     *
+     * Either kind of truncation makes a result valid only at the *position* it
+     * was produced at, so caching it and serving it elsewhere silently drops
+     * content that would have been included. Comparing this counter before and
+     * after a node's children tells us whether its result is position-
+     * independent and therefore safe to memoize.
+     *
+     * The cycle case is the subtle one: with `a.b = b` and `b.a = a`, serializing
+     * `{ first: b, second: a }` visits `a` beneath `b` — where the cycle back to
+     * `b` is cut — and would then reuse that truncated `a` for `second`, where
+     * nothing needed cutting.
+     */
+    truncations: number;
+}
+
+function toSerializable(
+    value: unknown,
+    seen: WeakSet<object>,
+    depth: number,
+    state: WalkState,
+    key?: string
+): unknown {
+    if (depth > MAX_DEPTH) {
+        state.truncations++;
+        return undefined;
+    }
+
+    if (typeof value === "function") {
+        // Only a relation target carries information a client needs. Calling it
+        // is safe here — this runs on the server, where the target module is
+        // already loaded — and a throwing target simply yields no reference,
+        // which degrades the generated FK type rather than failing the request.
+        if (key === "target") {
+            try {
+                const resolved = unwrapTarget((value as () => unknown)());
+                const ref = refFor(resolved);
+                return ref ? { __collectionRef: ref } : undefined;
+            } catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+
+    if (value instanceof Date) return value.toISOString();
+    if (value instanceof RegExp) return value.source;
+
+    if (seen.has(value as object)) {
+        state.truncations++;
+        return undefined;
+    }
+
+    // A shared (non-cyclic) subgraph is reachable by many paths, and `seen` is a
+    // *path* set — released in the `finally` below so a node referenced twice in
+    // different branches is emitted twice rather than dropped as a false cycle.
+    // Without memoization that makes the walk exponential in depth: a diamond
+    // graph 20 levels deep took ~400ms, and each further level doubled it. The
+    // result is a plain data tree, so handing back the same converted object for
+    // a repeat visit is indistinguishable after JSON.stringify.
+    const cached = state.memo.get(value as object);
+    if (cached !== undefined) return cached;
+
+    seen.add(value as object);
+    const truncationsBefore = state.truncations;
+    const memoize = (result: unknown): unknown => {
+        // Only cache a result that nothing was cut from.
+        if (result !== undefined && state.truncations === truncationsBefore) {
+            state.memo.set(value as object, result);
+        }
+        return result;
+    };
+
+    try {
+        if (Array.isArray(value)) {
+            const items = value
+                .map(item => toSerializable(item, seen, depth + 1, state))
+                .filter(item => item !== undefined);
+            // A container that had content, none of which can be represented, is
+            // itself unrepresentable — see the note below.
+            return memoize(value.length > 0 && items.length === 0 ? undefined : items);
+        }
+
+        // A React element or component reference has no meaning to a client and
+        // will not survive JSON anyway.
+        if ("$$typeof" in (value as Record<string, unknown>)) return undefined;
+
+        const entries = Object.entries(value as Record<string, unknown>);
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of entries) {
+            const converted = toSerializable(v, seen, depth + 1, state, k);
+            if (converted !== undefined) out[k] = converted;
+        }
+
+        // Drop a container whose entire content was dropped.
+        //
+        // `callbacks: { beforeSave() {…} }` would otherwise serialize to
+        // `callbacks: {}` — an empty husk that carries no information but is not
+        // *nothing*, so it lands in the payload and, worse, in the schema hash.
+        // Editing a hook would then change every client's schema version and
+        // report perfectly current SDKs as stale.
+        //
+        // A container that started empty stays empty: `properties: {}` is a
+        // deliberate statement, not a casualty.
+        if (entries.length > 0 && Object.keys(out).length === 0) return undefined;
+
+        return memoize(out);
+    } finally {
+        // Released so a collection referenced twice in different branches is
+        // emitted twice rather than being dropped as a false cycle.
+        seen.delete(value as object);
+    }
+}
+
+/**
+ * Serialize collections for transport over the contract endpoint.
+ *
+ * Sorted by slug so the output — and therefore the schema hash computed from it
+ * — does not depend on filesystem ordering.
+ */
+export function serializeCollections(collections: CollectionConfig[]): unknown[] {
+    return [...collections]
+        .sort((a, b) => String(a.slug ?? "").localeCompare(String(b.slug ?? "")))
+        .map(collection => toSerializable(collection, new WeakSet(), 0, {
+            memo: new WeakMap(),
+            truncations: 0
+        }))
+        .filter((c): c is Record<string, unknown> => c !== undefined);
+}
+
+/**
+ * Rebuild collections received from a contract endpoint.
+ *
+ * Relation refs become real thunks resolving through the returned set, so
+ * downstream consumers — the SDK generator above all — see exactly the shape
+ * they would have seen had the collections been imported from source.
+ *
+ * A ref naming a collection that is not in the payload resolves to `undefined`
+ * rather than throwing: the generator already tolerates an unresolvable target
+ * by falling back to a permissive key type, and a partial contract should still
+ * produce a usable SDK.
+ */
+export function deserializeCollections(payload: unknown[]): CollectionConfig[] {
+    const collections = payload
+        .filter((c): c is Record<string, unknown> => typeof c === "object" && c !== null)
+        .map(c => ({ ...c })) as unknown as CollectionConfig[];
+
+    const bySlug = new Map<string, CollectionConfig>();
+    for (const collection of collections) {
+        const ref = refFor(collection);
+        if (ref) bySlug.set(ref, collection);
+    }
+
+    const rehydrate = (value: unknown, depth: number): void => {
+        if (depth > MAX_DEPTH || !value || typeof value !== "object") return;
+
+        if (Array.isArray(value)) {
+            for (const item of value) rehydrate(item, depth + 1);
+            return;
+        }
+
+        const record = value as Record<string, unknown>;
+        for (const [key, child] of Object.entries(record)) {
+            if (key === "target" && isSerializedCollectionRef(child)) {
+                const slug = child.__collectionRef;
+                record.target = () => bySlug.get(slug);
+                continue;
+            }
+            rehydrate(child, depth + 1);
+        }
+    };
+
+    for (const collection of collections) rehydrate(collection, 0);
+    return collections;
+}