@rebasepro/server-postgres 0.10.1-canary.6f89f77 → 0.10.1-canary.7801eed

package/dist/schema/ensure-collection-tables.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Bringing a database up to date with a bundle's collections, additively.
+ *
+ * ## Why this exists
+ *
+ * A managed runtime boots someone else's compiled project against a database it
+ * has never seen. Auth tables are ensured at boot already, but collection tables
+ * were not created by anything: the platform ran the app and every `/api/data/*`
+ * request answered 500 on a missing relation. `rebase db push` cannot help — it
+ * is an Atlas-driven CLI command, and the runtime image ships no CLI.
+ *
+ * ## Why additive-only, forever
+ *
+ * This runs unattended, against a database with customers' data in it, with no
+ * human reading a diff. So it may only ever do things that cannot lose data:
+ * create a missing table, add a missing column, create a missing enum type.
+ *
+ * It will **never** drop a table or a column, narrow a type, or alter a
+ * constraint. A removed field leaves its column behind; a renamed field looks
+ * like an addition and the old column stays. That is the correct trade for an
+ * automated path — the alternative is an unattended process that can silently
+ * destroy a column, which is precisely the failure `db push` was hardened
+ * against. Destructive changes stay a deliberate, human-reviewed migration.
+ *
+ * Because of that, this is safe to run on every boot, and re-running it is a
+ * no-op.
+ */
+import { type CollectionConfig } from "@rebasepro/types";
+/**
+ * The subset of a database handle this needs: run a statement, get rows back.
+ *
+ * Deliberately parameterless. Everything here is DDL or catalogue reads keyed by
+ * schema name, and schema names are identifiers — they cannot be bound as
+ * parameters anyway. They are validated against {@link SAFE_IDENTIFIER} before
+ * they reach a statement, so a config that somehow carried a quote is refused
+ * rather than concatenated.
+ */
+export interface Queryable {
+    query<T = unknown>(sql: string): Promise<{
+        rows: T[];
+    }>;
+}
+/** What the database currently has, as the planner needs it. */
+export interface ExistingSchema {
+    /** `schema.table` → set of column names. */
+    tables: Map<string, Set<string>>;
+    /** `schema.typename` of every enum type that already exists. */
+    enums: Set<string>;
+}
+export interface EnsureAction {
+    kind: "create-enum" | "create-table" | "add-column";
+    /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
+    target: string;
+    sql: string;
+}
+export interface EnsurePlan {
+    actions: EnsureAction[];
+    /** Every statement, in dependency order. Empty when the schema is current. */
+    statements: string[];
+}
+/**
+ * Decide what to add. Pure — the caller supplies what exists and runs the result.
+ *
+ * Ordering matters and is deliberate: enum types before the tables and columns
+ * that reference them, tables before the columns added to other tables (a new
+ * table may be the target of a relation), and nothing is emitted twice.
+ */
+export declare function planCollectionSchemaEnsure(collections: CollectionConfig[], existing: ExistingSchema): EnsurePlan;
+/** Read what the database has, for the schemas the collections live in. */
+export declare function readExistingSchema(client: Queryable, schemas: string[]): Promise<ExistingSchema>;
+/**
+ * Bring the database up to date. Returns what it did.
+ *
+ * Each statement runs on its own rather than in one transaction: they are all
+ * independently safe and idempotent, and a single failure (an enum label that
+ * cannot be added, say) should not roll back the tables that were created fine.
+ * The error is surfaced with the statement that caused it.
+ */
+export declare function ensureCollectionTables(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void): Promise<EnsurePlan>;

package/dist/schema/generate-postgres-ddl-logic.d.ts

@@ -1,4 +1,7 @@
-import { CollectionConfig } from "@rebasepro/types";
+import { CollectionConfig, Property } from "@rebasepro/types";
+export declare const resolveColumnName: (propName: string, prop?: Property | null) => string;
+export declare const isIdProperty: (propName: string, prop: Property, collection: CollectionConfig) => boolean;
+export declare const getSqlColumnType: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string;
 export declare const generatePostgresDdl: (collections: CollectionConfig[], options?: {
     includePolicies?: boolean;
 }) => Promise<string>;

package/dist/services/FetchService.d.ts

@@ -5,6 +5,7 @@ import type { VectorSearchParams } from "@rebasepro/types";
 import { RelationService } from "./RelationService";
 import { DrizzleClient } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import { type NestedPathHop } from "./nested-path";
 /**
  * Service for handling all row read operations.
  * Handles fetching, searching, counting, and filtering rows.
@@ -65,6 +66,22 @@ export declare class FetchService {
      * Extract cursor pagination conditions from startAfter options.
      */
     private buildCursorConditions;
+    /**
+     * Compile "rows reachable from this parent" into a `WHERE` condition on the
+     * target table, so a nested listing can run as an ordinary collection query.
+     */
+    private buildRelationScope;
+    /**
+     * Whether `id` is actually reachable at `collectionPath`.
+     *
+     * Trivially true for a root path. For a nested one it is a real question:
+     * the path resolves to the target collection, and matching on the primary
+     * key alone made the parent segment decorative — `authors/1/posts/43`
+     * returned post 43 whoever wrote it, and the REST layer's delete then
+     * deleted it. A row that is not under this parent is reported as absent,
+     * which is what a caller addressing it through the parent should see.
+     */
+    private isAddressableUnder;
     /**
      * Fetch a single row by ID
      */
@@ -83,6 +100,8 @@ export declare class FetchService {
         databaseId?: string;
         vectorSearch?: VectorSearchParams;
         logical?: LogicalCondition;
+        /** Narrow to the rows reachable from a parent through a relation. */
+        relatedTo?: NestedPathHop;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Fallback path used when db.query is unavailable.
@@ -118,10 +137,6 @@ export declare class FetchService {
         limit?: number;
         databaseId?: string;
     }): Promise<Record<string, unknown>[]>;
-    /**
-     * Fetch collection from multi-segment path
-     */
-    private fetchCollectionFromPath;
     /**
      * Count rows in a collection
      */
@@ -130,10 +145,6 @@ export declare class FetchService {
         searchString?: string;
         databaseId?: string;
     }): Promise<number>;
-    /**
-     * Count rows from multi-segment path
-     */
-    private countEntitiesFromPath;
     /**
      * Check if a field value is unique
      */
@@ -160,6 +171,8 @@ export declare class FetchService {
         searchString?: string;
         databaseId?: string;
         vectorSearch?: VectorSearchParams;
+        /** Narrow to the rows reachable from a parent through a relation. */
+        relatedTo?: NestedPathHop;
     }, include?: string[]): Promise<Record<string, unknown>[]>;
     /**
      * Fetch a single row with optional relation includes for REST API.

package/dist/services/PersistService.d.ts

@@ -38,6 +38,18 @@ export declare class PersistService {
      * Delete all rows from a collection
      */
     deleteAll(collectionPath: string, _databaseId?: string): Promise<void>;
+    /**
+     * The column on the *target* table that records the parent, for a create
+     * under a nested one-to-many path.
+     *
+     * Returns `undefined` when the link is not a column at all (a multi-hop
+     * `joinPath`), so the caller writes the row without stamping anything.
+     *
+     * `relation.localKey` is deliberately not consulted: it names a column on
+     * the *source* table. Falling back to it here — which is what this used to
+     * do, and first — stamped the parent's own foreign key onto the child row.
+     */
+    private resolveParentForeignKeyColumn;
     /**
      * Save an row (create or update)
      *

package/dist/services/RelationService.d.ts

@@ -1,6 +1,8 @@
 import { DrizzleClient } from "../interfaces";
-import { CollectionConfig, FilterValues, Relation } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany } from "@rebasepro/types";
+import { type ResolvedVia } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import type { NestedPathHop } from "./nested-path";
 /**
  * Service for handling all relation-related operations.
  * Handles fetching, updating, and managing row relations.
@@ -69,7 +71,7 @@ export declare class RelationService {
     /**
      * Fetch rows using join paths for complex relations
      */
-    fetchEntitiesUsingJoins<M extends Record<string, unknown>>(parentCollection: CollectionConfig, parentId: string | number, relation: Relation, options?: {
+    fetchEntitiesUsingJoins<M extends Record<string, unknown>>(parentCollection: CollectionConfig, parentId: string | number, relation: ResolvedRelation, options?: {
         filter?: FilterValues<Extract<keyof M, string>>;
         orderBy?: string;
         order?: "desc" | "asc";
@@ -85,16 +87,45 @@ export declare class RelationService {
         filter?: FilterValues<Extract<keyof M, string>>;
         databaseId?: string;
     }): Promise<number>;
+    /**
+     * Count the target rows a parent reaches through `relation`, narrowed by
+     * `additionalFilters` (conditions on the target table).
+     *
+     * Shared by the public count and by {@link isRelated}, so "how many children
+     * does this parent have" and "is this row one of them" are answered by the
+     * same join — a membership test that reconstructed the join separately would
+     * be free to disagree with the listing it is supposed to gate.
+     */
+    private countRelatedRows;
+    /**
+     * Whether `targetId` is actually reachable from the parent named in `hop`.
+     *
+     * A nested address like `authors/1/posts/43` used to resolve to the target
+     * collection and then match on the primary key alone, so the parent segment
+     * decided nothing: the row came back, and was updated or deleted, whoever it
+     * belonged to. Reads, updates and deletes now all gate on this.
+     */
+    isRelated(hop: NestedPathHop, targetId: string | number): Promise<boolean>;
+    /**
+     * Remove the junction row linking a parent to `targetId`, leaving the target
+     * row itself alone.
+     *
+     * This is what `DELETE authors/1/tags/5` has to mean for a many-to-many: the
+     * target is shared, so deleting the row would remove the tag from every other
+     * post that uses it. It used to do exactly that — resolve the path to the
+     * `tags` table and delete by primary key.
+     */
+    unlinkRelatedEntity(tx: DrizzleClient, hop: NestedPathHop, targetId: string | number): Promise<void>;
     /**
      * Batch fetch related rows for multiple parent rows to avoid N+1 queries
      */
-    batchFetchRelatedEntities(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: Relation): Promise<Map<string, RelatedRow<Record<string, unknown>>>>;
+    batchFetchRelatedEntities(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation): Promise<Map<string, RelatedRow<Record<string, unknown>>>>;
     /**
      * Batch fetch many-cardinality related rows for multiple parent rows.
      * Returns a Map<parentId, RelatedRow[]> instead of Map<parentId, RelatedRow>.
      * Uses a single SQL query with IN clause to avoid N+1.
      */
-    batchFetchRelatedEntitiesMany(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: Relation): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
+    batchFetchRelatedEntitiesMany(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
     /**
      * Update many-to-many and junction relations
      */
@@ -104,7 +135,7 @@ export declare class RelationService {
      */
     updateInverseRelations(tx: DrizzleClient, sourceCollection: CollectionConfig, sourceEntityId: string | number, inverseRelationUpdates: Array<{
         relationKey: string;
-        relation: Relation;
+        relation: ResolvedRelation;
         newValue: unknown;
     }>): Promise<void>;
     /**
@@ -120,13 +151,13 @@ export declare class RelationService {
      */
     updateJoinPathOneToOneRelations(tx: DrizzleClient, parentCollection: CollectionConfig, parentId: string | number, updates: Array<{
         relationKey: string;
-        relation: Relation;
+        relation: ResolvedVia;
         newTargetId: string | number | null;
     }>): Promise<void>;
     /**
      * Resolve joinPath write mapping for one-to-one relations
      */
-    resolveJoinPathWriteMapping(parentCollection: CollectionConfig, relation: Relation): {
+    resolveJoinPathWriteMapping(parentCollection: CollectionConfig, relation: ResolvedVia): {
         targetFKColName: string;
         parentSourceColName: string;
     };
@@ -136,7 +167,7 @@ export declare class RelationService {
     handleJunctionTableCreation(tx: DrizzleClient, newEntityId: string | number, junctionTableInfo: {
         parentCollection: CollectionConfig;
         parentId: string | number;
-        relation: Relation;
+        relation: ResolvedManyToMany;
         relationKey: string;
     }): Promise<void>;
 }

package/dist/services/cdc/CdcListener.d.ts

@@ -23,19 +23,14 @@ export declare function parseCdcPayload(payload: string): CdcChangeEvent | null;
 /**
  * Dedicated Postgres LISTEN client for database-level CDC.
  *
- * Mirrors the resilience of the RealtimeService cross-instance LISTEN client: a
- * standalone `pg.Client` (outside the Drizzle pool) that stays connected, and
- * transparently reconnects on error/disconnect. Each backend instance runs one,
- * so every instance observes every committed change regardless of which
- * instance (or external process) made the write.
+ * A {@link PgNotifyListener} — a connection outside the Drizzle pool that stays
+ * open and repairs itself — plus the parsing that turns a `rebase_cdc` payload
+ * into a change event. Each backend instance runs one, so every instance
+ * observes every committed change regardless of which instance (or external
+ * process) made the write.
  */
 export declare class CdcListener {
-    private readonly connectionString;
-    private readonly onEvent;
-    private client?;
-    private running;
-    private reconnectTimer?;
-    private static readonly RECONNECT_DELAY_MS;
+    private readonly listener;
     constructor(connectionString: string, onEvent: (event: CdcChangeEvent) => void | Promise<void>);
     /**
      * Connect and begin listening. Idempotent.
@@ -44,11 +39,9 @@ export declare class CdcListener {
      * established (or `LISTEN` is refused), this rejects so callers — notably
      * `REALTIME_CDC=auto` — can detect an unusable connection and fall back to
      * app-level realtime. Once the initial connection succeeds, later drops
-     * self-heal via {@link scheduleReconnect}.
+     * self-heal in the background.
      */
     start(): Promise<void>;
     /** Stop listening and release the connection. */
     stop(): Promise<void>;
-    private connect;
-    private scheduleReconnect;
 }

package/dist/services/cdc/junction-tables.d.ts

@@ -0,0 +1,38 @@
+import { CollectionConfig } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../../collections/PostgresCollectionRegistry";
+/**
+ * One end of a many-to-many, as seen from the junction table.
+ *
+ * A junction table is not a collection, so nothing in the registry maps it to
+ * one — which is why a change to it was invisible to change capture. But its
+ * rows are exactly the contents of a parent's child list, so a write to it is a
+ * change to `<parentSlug>/<sourceId>/<relationKey>` and to nothing else.
+ */
+export interface JunctionLink {
+    schema: string;
+    /** The junction table itself, e.g. `posts_tags`. */
+    table: string;
+    /** The collection whose relation this is, e.g. `posts`. */
+    parentCollection: CollectionConfig;
+    /** The relation's key — the path segment a child list is addressed by. */
+    relationKey: string;
+    /** Junction column holding the parent's id. */
+    sourceColumn: string;
+    /** Junction column holding the target's id. */
+    targetColumn: string;
+}
+/**
+ * Every junction table reachable from a registered collection, once per
+ * relation that uses it.
+ *
+ * A junction is listed once per *direction* when both sides declare it, because
+ * each direction addresses a different child list: `posts/1/tags` and
+ * `tags/t/posts` both change when one link is written.
+ */
+export declare function collectJunctionLinks(registry: PostgresCollectionRegistry): JunctionLink[];
+/**
+ * Index {@link collectJunctionLinks} by table, under both the qualified and the
+ * bare name — a change event carries whatever the trigger reports, and a
+ * collection need not declare a schema.
+ */
+export declare function buildJunctionLinkMap(registry: PostgresCollectionRegistry): Map<string, JunctionLink[]>;

package/dist/services/channel-bus/ChannelBus.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Runtime pieces of the channel bus that are not the contract itself.
+ *
+ * The interface, the frame shape and the implementer's contract live in
+ * `@rebasepro/types` (`types/channel_bus.ts`), so a transport shipped as its own
+ * package — a Redis one, say — depends on the contract and not on this database
+ * adapter. They are re-exported here for convenience: code already importing
+ * from the adapter should not have to know where the types are declared.
+ */
+import type { ChannelBusFrame } from "@rebasepro/types";
+export type { ChannelBus, ChannelBusFrame, ChannelBusHandler, ChannelBusConfig, ChannelBusSetting } from "@rebasepro/types";
+export { isChannelBusInstance } from "@rebasepro/types";
+/**
+ * The default: no cross-instance delivery at all.
+ *
+ * This is what every deployment ran before the bus existed, and what a
+ * single-instance deployment should keep running — `publish` resolves without
+ * touching the network, so the broadcast path is the same handful of `ws.send`
+ * calls it always was.
+ */
+export declare class MemoryChannelBus {
+    readonly kind: "memory";
+    readonly maxFrameBytes: number;
+    start(): Promise<void>;
+    publish(): Promise<void>;
+    stop(): Promise<void>;
+}
+/** Encoded size of a frame, for a transport's size check. */
+export declare function frameByteLength(frame: ChannelBusFrame): number;

package/dist/services/channel-bus/PostgresChannelBus.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Channel bus over Postgres LISTEN/NOTIFY.
+ *
+ * Chosen because it needs nothing that a Rebase deployment does not already
+ * have — the same database, the same direct URL the CDC listener uses. Three
+ * properties of `NOTIFY` shape everything below:
+ *
+ *  - **8000 bytes per payload.** Presence and cursors fit with room to spare; a
+ *    scene snapshot does not. Rather than truncate or drop, an oversized frame
+ *    on a *retained* channel is published as a pointer — the body is already in
+ *    `rebase.channel_messages` with a sequence number, so the receiver reads it
+ *    back. That is the same trick the entity path uses (notify an address,
+ *    refetch the row), applied to a different table. On an ephemeral channel
+ *    there is nothing to point at, so the publish is refused loudly instead of
+ *    reaching some instances and not others.
+ *
+ *  - **A notify is a query on the primary database.** Not a slow one, but it
+ *    competes with the application's real queries, and that — not throughput —
+ *    is what actually limits this transport. Measured, it carried ~10k
+ *    cross-instance messages/second and stayed flat out to eight instances; what
+ *    it should not do is spend 10k queries/second of the database's budget on
+ *    cursor movement. Hence the batching below.
+ *
+ *  - **Delivery is best-effort.** Retained channels repair themselves through
+ *    the client's history replay, so a lost frame costs a live update rather
+ *    than correctness. That is what makes coalescing safe.
+ */
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { ChannelBus, ChannelBusFrame, ChannelBusHandler } from "./ChannelBus";
+/** NOTIFY channel carrying channel-bus frames. */
+export declare const CHANNEL_BUS_NOTIFY_CHANNEL = "rebase_channel_bus";
+/**
+ * Postgres refuses a NOTIFY payload of 8000 bytes or more. The margin below it
+ * is for nothing in particular — it is there so that a payload which passes this
+ * check cannot fail at the server for being a few bytes over.
+ */
+export declare const PG_NOTIFY_MAX_PAYLOAD_BYTES = 7500;
+/**
+ * How long a batching window stays open.
+ *
+ * Ten milliseconds is below the threshold where a human notices a cursor lag,
+ * and it is the difference between one query per message and one query per
+ * window under load. Set to 0 to disable coalescing entirely.
+ */
+export declare const DEFAULT_BATCH_WINDOW_MS = 10;
+export declare class PostgresChannelBus implements ChannelBus {
+    private readonly db;
+    private readonly connectionString;
+    readonly kind: "postgres";
+    readonly maxFrameBytes = 7500;
+    private listener?;
+    private readonly batchWindowMs;
+    /**
+     * Frames waiting for the current window to close.
+     *
+     * The window is opened by a publish that found none open, and that publish
+     * is sent *immediately* rather than joining a batch — see {@link publish}.
+     */
+    private pending;
+    private pendingBytes;
+    private windowTimer?;
+    private stopped;
+    constructor(db: NodePgDatabase<Record<string, unknown>>, connectionString: string, options?: {
+        batchWindowMs?: number;
+    });
+    start(handler: ChannelBusHandler): Promise<void>;
+    /**
+     * Publish, coalescing under load.
+     *
+     * The window is *leading edge*: a publish arriving when no window is open is
+     * sent straight away and opens one, so an idle channel pays no added latency
+     * at all. Frames arriving while it is open are collected and leave together
+     * when it closes. The effect is that cost tracks elapsed time rather than
+     * message count — one query per window instead of one per message — which is
+     * the same shape as the retention pruning throttle, for the same reason.
+     *
+     * The returned promise settles when the frame has actually left, not when it
+     * was queued, so the contract ("reaches the other instances, or rejects")
+     * still holds.
+     */
+    publish(frame: ChannelBusFrame): Promise<void>;
+    stop(): Promise<void>;
+    private openWindow;
+    /** Send everything queued and settle the promises waiting on it. */
+    private flush;
+    /**
+     * One NOTIFY.
+     *
+     * A single frame goes out in the plain, unwrapped shape. That is not just
+     * economy: during a rolling deploy an instance running the previous build
+     * understands only that shape, and low-rate traffic — presence, the tail of
+     * a session — is exactly what is flowing while pods restart. Batching only
+     * appears under load, which shrinks the mixed-version window to almost
+     * nothing.
+     */
+    private send;
+}
+/**
+ * Parse a bus payload into the frames it carries.
+ *
+ * Accepts both wire shapes — a bare frame and a `{ batch: [...] }` envelope —
+ * so an instance on the new build understands one on the old. Returns an empty
+ * array for anything unrecognisable: a malformed or future-versioned message
+ * must never take the listener down.
+ */
+export declare function parseChannelBusPayload(payload: string): ChannelBusFrame[];
+/**
+ * Parse a single bus frame, returning null for anything that is not a frame we
+ * understand.
+ */
+export declare function parseChannelBusFrame(payload: string): ChannelBusFrame | null;

package/dist/services/channel-bus/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Resolution of the channel bus from config, environment, or a supplied instance.
+ *
+ * Opt-in, like every other cross-cutting realtime switch here: with nothing
+ * configured a deployment gets the memory bus and behaves exactly as it did
+ * before this existed. Unlike `REALTIME_CDC=auto`, there is no "try it and see"
+ * default — a bus changes where messages go, and quietly turning on a Postgres
+ * NOTIFY per broadcast because a direct URL happened to be set is not a
+ * decision to make on the user's behalf.
+ *
+ * Two transports ship, and neither adds a service to a deployment. A third is
+ * not a code change here: `realtime.bus` also accepts an already-constructed
+ * {@link ChannelBus}, so a transport published as its own package plugs in
+ * without this file learning about it. See `@rebasepro/types` →
+ * `types/channel_bus.ts` for the contract such a package implements.
+ */
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { type ChannelBus, type ChannelBusConfig, type ChannelBusSetting } from "@rebasepro/types";
+export * from "./ChannelBus";
+export { PostgresChannelBus, CHANNEL_BUS_NOTIFY_CHANNEL, PG_NOTIFY_MAX_PAYLOAD_BYTES, DEFAULT_BATCH_WINDOW_MS, parseChannelBusFrame, parseChannelBusPayload } from "./PostgresChannelBus";
+export interface ChannelBusDeps {
+    db: NodePgDatabase<Record<string, unknown>>;
+    /**
+     * Direct (non-pooled) Postgres URL for the LISTEN client. `LISTEN` is
+     * session state, so behind PgBouncer in transaction mode this must be the
+     * database itself and not the pooler.
+     */
+    directUrl?: string;
+}
+/**
+ * Merge `REALTIME_CHANNEL_BUS` into the configured bus.
+ *
+ * The environment wins over a *named* built-in, so the transport can be changed
+ * per deployment without a rebuild — the same reason `REALTIME_CDC` is an env
+ * var. It does **not** win over a supplied instance: the env var can only name
+ * transports this package knows how to construct, so honouring it there would
+ * mean silently discarding the object the application handed us.
+ */
+export declare function resolveChannelBusSetting(configured?: ChannelBusSetting): ChannelBusSetting;
+/**
+ * @deprecated Use {@link resolveChannelBusSetting}, which also accepts a
+ * supplied {@link ChannelBus} instance. Kept as a narrow alias so existing
+ * config-only callers keep their exact types.
+ */
+export declare function resolveChannelBusConfig(configured?: ChannelBusConfig): ChannelBusConfig;
+/**
+ * Produce the bus a setting asks for.
+ *
+ * An instance is handed straight back — constructing it was the application's
+ * job, and this function has nothing to add. A named built-in that turns out to
+ * be unusable degrades to the memory bus, with the reason logged, rather than
+ * throwing: a misconfigured bus should cost a deployment its cross-instance
+ * fan-out, not its ability to boot.
+ */
+export declare function createChannelBus(setting: ChannelBusSetting, deps: ChannelBusDeps): ChannelBus;

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

@@ -105,6 +105,17 @@ export declare class ChannelHistoryStore {
         messages: ChannelHistoryEntry[];
         latestSeq: number;
     }>;
+    /**
+     * One retained message by its address.
+     *
+     * This is what makes the cross-instance pointer path work: a broadcast too
+     * large to travel inside a `pg_notify` payload is already stored here, so
+     * the notification carries `(channel, seq)` and each receiving instance
+     * reads the body back. Returns null when the message has since been pruned
+     * — a receiver that is that far behind has nothing useful to deliver, and
+     * the client's own `channel_history` replay is the repair path.
+     */
+    getBySeq(channel: string, seq: number): Promise<ChannelHistoryEntry | null>;
     /**
      * Enforce a channel's retention bounds.
      *

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

@@ -0,0 +1,66 @@
+/**
+ * The shared presence roster.
+ *
+ * Broadcast only ever needed *fan-out* to work across instances — a frame goes
+ * out, whoever is connected receives it. Presence needs more than that, because
+ * `presence_state` is a question ("who is in this document?") and a per-process
+ * `Map` can only answer for the clients that happen to share a replica with the
+ * asker. Two people editing the same scene through different pods would each
+ * see an empty room while broadcasting cursors at each other perfectly.
+ *
+ * So presence gets one row per tracked client, in Postgres, readable by every
+ * instance. Three consequences worth stating:
+ *
+ *  - **The table is the roster; the in-process map is a cache of our own
+ *    clients.** Reads answer from the table when this store is active, so the
+ *    answer is the same whichever instance is asked.
+ *
+ *  - **`last_seen` is the liveness signal, and it is already there.** The client
+ *    heartbeats presence every ~20 s against a 30 s window; the sweep that has
+ *    always reaped local stale entries now also reaps rows belonging to
+ *    instances that stopped writing — which is exactly what a crashed pod looks
+ *    like. Crash recovery is a property of the TTL, not a separate mechanism.
+ *
+ *  - **The sweep deletes with `RETURNING`.** Whichever instance wins the delete
+ *    is the one that announces the departures, so a stale client produces one
+ *    `presence_diff` for the cluster rather than one per replica.
+ */
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+/** A tracked client, as any instance sees it. */
+export interface PresenceRow {
+    channel: string;
+    clientId: string;
+    state: Record<string, unknown>;
+}
+export declare class ChannelPresenceStore {
+    private readonly db;
+    private readonly instanceId;
+    private tablesReady;
+    constructor(db: NodePgDatabase<Record<string, unknown>>, instanceId: string);
+    /** Create the roster table. Idempotent. */
+    ensureTables(): Promise<void>;
+    /** Record (or refresh) a client's presence. */
+    track(channel: string, clientId: string, state: Record<string, unknown>): Promise<void>;
+    /** Drop one client's presence in one channel. */
+    remove(channel: string, clientId: string): Promise<void>;
+    /** Drop a client from every channel — used when its socket closes. */
+    removeClient(clientId: string): Promise<void>;
+    /** The global roster for a channel. */
+    roster(channel: string): Promise<Record<string, Record<string, unknown>>>;
+    /**
+     * Reap rows this instance is not responsible for and that have gone quiet.
+     *
+     * Own rows are excluded because the in-process sweep already handles them —
+     * and handles them better, since it can tell "the socket is gone" from "the
+     * heartbeat is late". What is left is precisely the interesting case: rows
+     * written by an instance that is no longer writing.
+     *
+     * Returns what was removed, so the caller can announce it.
+     */
+    sweepStale(ttlMs: number): Promise<PresenceRow[]>;
+    /**
+     * Remove every row this instance owns. Called on graceful shutdown so a
+     * rolling deploy does not leave a TTL window of ghosts in every roster.
+     */
+    removeInstance(): Promise<void>;
+}