@rebasepro/server-postgres 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/services/realtimeService.d.ts

@@ -5,7 +5,7 @@ import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
 import { ChannelBus } from "./channel-bus/index.js";
-import type { ChannelRetentionRule } from "@rebasepro/types";
+import type { ChannelRetentionRule, RealtimeListenerHealth } from "@rebasepro/types";
 /**
  * Auth context stored per-subscription so real-time refetches respect RLS.
  * Mirrors the session variables set by PostgresBackendDriver.withAuth().
@@ -95,6 +95,13 @@ type StoredCollectionRequest = {
     fields?: string[];
     /** `SELECT DISTINCT` over the projection. */
     distinct?: boolean;
+    /**
+     * A subscription to the count alone (`listenCount`): no rows are read,
+     * and each frame carries `rows: []` and the `meta` with the total. A
+     * server that predates it reads the rows it was asked for (the SDK asks
+     * for one) and counts them as usual, so the same frame answers it.
+     */
+    countOnly?: boolean;
 };
 /**
  * What an in-process listener asks for: the read, and who it reads as.
@@ -111,6 +118,7 @@ export type DataDriverSubscriptionRequest = {
 } | {
     type: "single";
     id: string | number;
+    include?: IncludeSpec;
 });
 /**
  * A registered subscription, plus the two counters that order its deliveries.
@@ -133,11 +141,22 @@ export type DataDriverSubscriptionRequest = {
  * last delivery *started* the last one *delivered*.
  */
 type Subscription = {
+    /** The id the client named it by — what every frame for it carries. */
+    subscriptionId: string;
     clientId: string;
+    /** The {@link SubscriptionGroup} whose refetch answers it. */
+    groupKey: string;
     type: "collection" | "single";
     path: string;
     id?: string | number;
     collectionRequest?: StoredCollectionRequest;
+    /**
+     * The relations a single-row subscription loads into every frame — the
+     * `include` a `findById` takes. A list keeps its own in `collectionRequest`.
+     */
+    include?: IncludeSpec;
+    /** A single-row subscriber that asked for the row's `ETag` on every frame. */
+    etag?: boolean;
     authContext?: SubscriptionAuthContext;
     /**
      * An in-process listener's error callback, called when a refetch fails.
@@ -149,7 +168,65 @@ type Subscription = {
     started: number;
     /** The highest started-sequence that has already reached the subscriber. */
     delivered: number;
+    /**
+     * A socket subscriber's last data frame, as {@link frameDigest} of what
+     * follows its subscription id; unset before the first and after an error
+     * frame. A refetch that reads the same rows sends it nothing — see
+     * {@link sendDataFrame}.
+     */
+    lastFrame?: string;
 };
+/**
+ * How many group refetches may run at once: a quarter of the connection pool
+ * the service shares with every REST request, and never fewer than two.
+ *
+ * One write to a list watched by many different principals arms a refetch
+ * per principal, and they all came due in the same tick. Started together,
+ * 200 of them were 200 transactions queued on a 20-connection pool, and an
+ * unrelated request arriving meanwhile waited behind every one (measured: a
+ * `SELECT 1` took 521 ms). Capped, the refetches queue here instead, and
+ * three quarters of the pool stays free for the requests. A pool this cannot
+ * read (a test double, a client that is not a `pg` pool) is taken to be the
+ * default 20-connection one.
+ */
+export declare function refetchConcurrencyFor(db: object): number;
+/**
+ * The default ceiling on subscriptions one socket may hold.
+ *
+ * Each collection subscription is a refetch on every write to its collection;
+ * without a ceiling one socket could open tens of thousands and turn every
+ * write anyone made into as many transactions. The SDK shares identical
+ * subscriptions on a socket, so a real page holds one per distinct list or
+ * record on screen — the admin panel's tables, forms and reference previews
+ * stay well under this. See `REALTIME_MAX_SUBSCRIPTIONS_PER_SOCKET`.
+ */
+export declare const DEFAULT_MAX_SUBSCRIPTIONS_PER_SOCKET = 1000;
+/**
+ * Read a subscription ceiling, refusing anything that is not a positive whole
+ * number. A typo here does not fall back to a default: the ceiling is a limit
+ * someone chose, and silently running with another one is how it stops
+ * meaning anything.
+ */
+export declare function parseMaxSubscriptionsPerSocket(value: unknown, source: string): number;
+/**
+ * The smallest last total at which a group's count is reused under
+ * `REALTIME_RECOUNT_INTERVAL_MS`, unless `REALTIME_RECOUNT_MIN_ROWS` says
+ * otherwise. Below it a count is cheap, and stays exact.
+ */
+export declare const DEFAULT_RECOUNT_MIN_ROWS = 100000;
+/**
+ * Read one of the realtime tuning numbers (`REALTIME_REFETCH_MAX_WAIT_MS`,
+ * `REALTIME_RECOUNT_INTERVAL_MS`, `REALTIME_RECOUNT_MIN_ROWS` and their
+ * `realtime.*` options). A value someone set and mistyped stops the boot
+ * rather than quietly becoming the default.
+ */
+export declare function parseRealtimeTuning(value: unknown, source: string, unit: string): number;
+/**
+ * Read `REALTIME_MAX_SOCKETS_PER_USER` / `realtime.maxSocketsPerUser`. Like the
+ * subscription ceiling, a value someone set and mistyped stops the boot rather
+ * than quietly becoming no ceiling.
+ */
+export declare function parseMaxSocketsPerUser(value: unknown, source: string): number;
 /**
  * PostgreSQL-specific realtime service.
  * Handles WebSocket connections and subscriptions for real-time row updates.
@@ -166,8 +243,19 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     readonly supportsChannels = true;
     private clients;
+    /** What each socket opted into when it opened — see `socket-opt-ins.ts`. */
+    private clientOptIns;
     private channels;
     private presence;
+    /**
+     * The reverse of {@link channels} and {@link presence}: the channels each
+     * client is a member of, and those it has a presence entry in. Kept in
+     * step wherever either map gains or loses a client, so a disconnect visits
+     * what the client was in. It used to walk every channel on the instance:
+     * with a channel per document, 5.4 ms per disconnect at 50k channels.
+     */
+    private channelsByClient;
+    private presenceByClient;
     /**
      * Ordered, replayable history for channels that opt into it.
      *
@@ -188,6 +276,8 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * wait on each other.
      */
     private channelSendQueues;
+    /** The receiving half of the same ordering: retained bus frames per channel, one at a time. */
+    private channelReceiveQueues;
     /**
      * Cross-instance transport for channel frames and presence.
      *
@@ -206,9 +296,17 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private presenceStore?;
     /** Sweeps roster rows left behind by instances that stopped heartbeating. */
     private presenceSweepInterval?;
+    /**
+     * The clients that have tracked presence through this instance — the only
+     * ones with roster rows to delete when their socket closes. Most sockets
+     * never track presence, and each of their closes was a `DELETE` too.
+     */
+    private presenceTrackers;
     /**
      * Channels whose oversized ephemeral broadcasts have already been reported,
      * so a hot channel logs the problem once rather than once per message.
+     * Forgotten with the channel, so it holds live channels only — not every
+     * name a client ever broadcast on.
      */
     private oversizedBroadcastWarned;
     /**
@@ -228,34 +326,135 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private foreignInstanceSeen;
     /** So the multi-pod memory-bus warning is emitted once, not once per join. */
     private memoryBusWarned;
+    /** When the database was last asked whether another instance listens — see {@link warnIfMemoryBusOnMultiplePods}. */
+    private otherInstancesCheckedAt?;
+    /** The check in flight, so a burst of joins asks once. Awaited by tests. */
+    private otherInstancesCheck?;
+    private static readonly OTHER_INSTANCES_CHECK_INTERVAL_MS;
     private presenceInterval?;
     private static readonly PRESENCE_TIMEOUT_MS;
     /** How often stale roster rows from other instances are reaped. */
     private static readonly PRESENCE_SWEEP_INTERVAL_MS;
     private dataService;
+    /**
+     * Every subscription, by {@link subscriptionKey} — the client's own id
+     * qualified by the client that chose it.
+     *
+     * Keyed by the bare id, this was one namespace for every socket: two raw
+     * clients that both counted from `"sub-1"` replaced each other's
+     * subscription without a word, and either one's `unsubscribe` ended the
+     * other's.
+     */
     private _subscriptions;
+    /** In-process listeners' callbacks, by subscription key. */
     private subscriptionCallbacks;
+    /** Each client's subscriptions, by key — for its ceiling and its disconnect. */
+    private subscriptionsByClient;
+    /**
+     * The in-process subscriptions — started by `startDataDriverSubscription`,
+     * `subscribeToCollection` or `subscribeToOne` — by the id their caller
+     * gave them, for {@link unsubscribe}, which has nothing else to go on. It
+     * used to walk every subscription on the server, sockets' included.
+     */
+    private inProcessKeysById;
+    /** Subscriptions one refetch answers — see {@link SubscriptionGroup}. */
+    private groups;
+    /**
+     * Groups whose refetch is due and waiting for a slot, in the order they
+     * came due. A group is in it at most once; changes that arrive while it
+     * waits join the read it is waiting for, which starts after them.
+     */
+    private refetchQueue;
+    /** Group refetches running now — at most {@link maxConcurrentRefetches}. */
+    private refetchesRunning;
+    /** See {@link refetchConcurrencyFor}. */
+    maxConcurrentRefetches: number;
+    /**
+     * The collection groups on each path, and the single-row groups at each
+     * `path` + id: what a change looks up, instead of walking every
+     * subscription on the server once per changed row.
+     */
+    private collectionGroupsByPath;
+    private singleGroupsByAddress;
+    /** The single-row groups on each path, for a change that names no row ({@link ANY_ROW}). */
+    private singleGroupsByPath;
+    /**
+     * When something on each path a list group reads last changed: the
+     * debounce clock those groups share, moved once per changed row instead
+     * of once per row per group. See {@link notifyPathUpdate}.
+     */
+    private listPathChangedAt;
+    /**
+     * The list groups on each path that a change still has to schedule: new
+     * ones, and those whose last refetch has started. The rest already have a
+     * refetch for every member pending, which the next change only has to
+     * keep waiting — the clock above does that.
+     */
+    private unscheduledListGroups;
+    /**
+     * Every path a subscription holds, with the collection it lands on and how
+     * many hold it — the candidates `aliasPaths` considers, resolved once.
+     */
+    private subscribedPaths;
+    /**
+     * How many subscriptions one socket may hold; set from config at boot. See
+     * {@link DEFAULT_MAX_SUBSCRIPTIONS_PER_SOCKET}.
+     */
+    maxSubscriptionsPerSocket: number;
+    /**
+     * The longest a change waits for its refetch, in ms; set from config at
+     * boot (`REALTIME_REFETCH_MAX_WAIT_MS`). See {@link REFETCH_MAX_WAIT_MS},
+     * the default.
+     */
+    refetchMaxWaitMs: number;
+    /**
+     * How long a list's total may be reused before it is counted again, in ms
+     * (`REALTIME_RECOUNT_INTERVAL_MS`). Unset, the default, counts with every
+     * frame. Only for a group whose last total was at least
+     * {@link recountMinRows}: a count is cheap on a small set, and exact there.
+     */
+    recountIntervalMs: number | undefined;
+    /** See {@link recountIntervalMs} (`REALTIME_RECOUNT_MIN_ROWS`). */
+    recountMinRows: number;
     private driver?;
     /** Unique identifier for this process instance, used to skip own notifications. */
     private readonly instanceId;
-    /** Dedicated pg.Client for LISTEN (outside the Drizzle pool). */
-    private listenClient?;
-    /** Connection string used for reconnecting the LISTEN client. */
-    private listenConnectionString?;
+    /** What this instance's LISTEN connections report in `pg_stat_activity`. */
+    private readonly listenerApplicationName;
+    /** The LISTEN connection on {@link PG_NOTIFY_CHANNEL}, outside the Drizzle pool. */
+    private crossInstanceListener?;
     /** Whether cross-instance broadcasting is active. */
     private broadcasting;
-    /** Reconnection timer handle. */
-    private reconnectTimer?;
-    /** Debounce timers for collection refetches to prevent refetch storms. */
-    private refetchTimers;
+    /**
+     * Changes waiting to be announced on {@link PG_NOTIFY_CHANNEL}, and the
+     * send that will announce them — see {@link broadcastChange}.
+     */
+    private pendingBroadcasts;
+    private broadcastFlush?;
     /** Debounce window (ms) for coalescing rapid row updates into a single correctness refetch. */
     private static readonly REFETCH_DEBOUNCE_MS;
+    /**
+     * The longest a change waits for its refetch, quiet window or not.
+     *
+     * A pure debounce waits for 300 ms without a change, and a collection
+     * written more often than that — an orders, events or chat table at a few
+     * writes a second — never went quiet: its subscribers received nothing for
+     * as long as the writes continued. Under a steady stream a group now
+     * refetches once per this interval, which is the whole cost.
+     */
+    private static readonly REFETCH_MAX_WAIT_MS;
     /** Dedicated LISTEN client for DB-level change events (undefined unless CDC is enabled). */
     private cdcListener?;
     /** Whether database-level CDC is the active cross-instance change source. */
     private cdcActive;
     /** Junction table → the child lists its rows belong to, built when CDC starts. */
     private junctionLinkMap?;
+    /** Changes waiting for a turn of the event loop — see {@link handleCdcEvents}. */
+    private cdcBacklog;
+    /** Changes handled in the current turn. */
+    private cdcTurnRows;
+    /** How many changed rows one turn of the event loop routes: ~5–10 ms of work. */
+    private static readonly CDC_ROWS_PER_TURN;
     /** Reverse lookup: `schema.table` (and bare `table`) → collection, built when CDC starts. */
     private cdcTableMap?;
     /**
@@ -300,8 +499,75 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * redaction lives.
      */
     private debugLog;
+    /**
+     * {@link rawQueryLoggingEnabled}, read at most once a second.
+     *
+     * It reads two environment variables, and `process.env` is a getenv per
+     * read: called three or four times per changed row, it was the largest
+     * cost of a change notification here — 1.4 µs of every ~3.5 µs per row,
+     * so ~1.4 s of event loop for a 1M-row statement. A switch flipped at run
+     * time is honoured within a second.
+     */
+    private debugEnabled;
+    private debugFlag;
+    private debugCheckedAt;
     setDataDriver(driver: DataDriver): void;
-    get subscriptions(): Map<string, Subscription>;
+    /**
+     * The live subscriptions by the id their client gave them — for tests and
+     * diagnostics. Two clients may use one id; this view shows the last.
+     */
+    get subscriptions(): ReadonlyMap<string, Subscription>;
+    /** The internal key of `subscriptionId` as `clientId` named it. */
+    private subscriptionKey;
+    /**
+     * The group a subscription's refetch belongs to. Socket subscriptions that
+     * would run the same read as the same principal share one; an in-process
+     * listener is always alone — see {@link SubscriptionGroup}.
+     */
+    private groupKeyFor;
+    /**
+     * Register (or replace) a subscription under `key`, in its group and in
+     * every index that finds it.
+     */
+    private registerSubscription;
+    /** Remember an in-process subscription by its caller's id — see {@link inProcessKeysById}. */
+    private indexInProcess;
+    /** Remove the subscription under `key` from everything that holds it. */
+    private dropSubscription;
+    /** Take `subscription` out of its group and path count; a group left empty goes, timer and all. */
+    private leaveGroup;
+    /** See {@link unscheduledListGroups}. */
+    private markListGroupUnscheduled;
+    /**
+     * Ask for a refetch of `group` once changes have been quiet for the
+     * debounce window — for every member, or only for `member` — and in any
+     * case no later than {@link REFETCH_MAX_WAIT_MS} after the first of them.
+     *
+     * The window is measured from the last change, as a debounce is, but the
+     * timer is not re-armed per change: a 10k-row statement is 10k changes,
+     * and re-arming a timer per change per group was work in proportion to
+     * both. A change only moves the timestamp; the timer, when it fires early,
+     * waits out the rest.
+     */
+    private scheduleGroupRefetch;
+    private armGroupTimer;
+    /**
+     * Start queued group refetches while fewer than
+     * {@link maxConcurrentRefetches} are running. Each one that settles starts
+     * the next, so the fan-out of one write waits its turn here rather than
+     * in the pool, ahead of every REST request.
+     */
+    private drainRefetchQueue;
+    /**
+     * One read for the group, delivered to each member it is for.
+     *
+     * Each member still claims its own delivery slot before the read and
+     * checks it after (see {@link beginDelivery}), so a member that left, was
+     * replaced or was overtaken while the read ran is skipped exactly as it
+     * was when it had a read of its own. A socket frame is serialised once and
+     * only its subscription id differs per member.
+     */
+    private refetchGroup;
     /**
      * Claim a delivery slot for a subscription, before doing the work.
      *
@@ -355,13 +621,32 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     subscribeToOne(subscriptionId: string, config: SingleSubscriptionConfig, callback?: (row: Record<string, unknown> | null) => void, onError?: (error: unknown) => void): void;
     /**
-     * Unsubscribe from a subscription (RealtimeProvider interface)
+     * Unsubscribe an in-process subscription (RealtimeProvider interface).
+     *
+     * By id alone, because the in-process callers hold nothing else — so a
+     * socket's subscription under the same id is not this one, and is left
+     * alone. A socket ends its own through the `unsubscribe` frame.
      */
     unsubscribe(subscriptionId: string): void;
     addClient(clientId: string, ws: WebSocket): void;
     handleClientMessage(clientId: string, message: WebSocketMessage, authContext?: SubscriptionAuthContext): Promise<void>;
+    /** Record what a socket opted into when it opened. See `socket-opt-ins.ts`. */
+    setClientOptIns(clientId: string, optIns: ReadonlySet<string>): void;
     removeClient(clientId: string): Promise<void>;
+    /** Record that `clientId` is in `channel`, in a reverse index — see {@link channelsByClient}. */
+    private indexClientChannel;
+    private unindexClientChannel;
     private handleMessage;
+    /**
+     * Refuse a new subscription past the socket's ceiling, and say so.
+     *
+     * Every collection subscription is a refetch on every write to its
+     * collection, so a socket allowed to open them without limit could turn
+     * each write anyone makes into tens of thousands of transactions. Replacing
+     * a subscription the socket already holds — the same id again — is not a
+     * new one and always passes. Returns whether the subscription may go ahead.
+     */
+    private admitSubscription;
     private handleCollectionSubscription;
     private handleEntitySubscription;
     /**
@@ -397,6 +682,10 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * again, when one is installed, and left when it refuses.
      */
     rescopeClient(clientId: string, authContext: SubscriptionAuthContext): Promise<void>;
+    /**
+     * End a socket's own subscription. Only its own: the id is the client's,
+     * so another socket's subscription under the same id is a different one.
+     */
     private handleUnsubscribe;
     /**
      * Enhanced notification method that handles nested relation updates.
@@ -446,15 +735,6 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * whether this subscriber may see the row at all.
      */
     private notifyPathUpdate;
-    /**
-     * Debounce a collection refetch for a WebSocket subscription.
-     * Coalesces rapid row mutations into a single database query.
-     */
-    private debouncedCollectionRefetch;
-    /**
-     * Debounce a collection refetch for a DataDriver callback subscription.
-     */
-    private debouncedDriverRefetch;
     /**
      * Tell an in-process listener its refetch failed, through the slot the
      * rows would have used.
@@ -468,13 +748,20 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private reportDriverFetchFailure;
     /**
-     * Fetch a collection with optional RLS auth context.
+     * Fetch a collection with optional RLS auth context, and with `meta: true`
+     * the `meta` a socket frame carries beside the rows.
+     *
      * When authContext is provided, the fetch runs inside a transaction
-     * with set_config calls so PostgreSQL RLS policies are enforced.
+     * with set_config calls so PostgreSQL RLS policies are enforced. The count
+     * behind `meta` runs in that same transaction — one pool acquisition and
+     * one `applyAuthContext` per refetch, where it used to take a second
+     * transaction of its own — see {@link collectionMeta}.
      */
     private fetchCollectionWithAuth;
     /**
-     * The `meta` a `collection_update` frame carries beside its rows.
+     * The `meta` a `collection_update` frame carries beside its rows, counted
+     * through `service` — the subscriber's own transaction, read only, with
+     * its auth context and `beforeQuery` narrowing already bound.
      *
      * Frames used to carry rows and primary keys and nothing else, so the
      * client issued a `GET /count` **per push** to fill in a total it needed to
@@ -482,22 +769,61 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * write, per subscriber, forever. The refetch already knows the query; it
      * counts once, here, under the same RLS transaction that read the rows, so
      * the total describes the same set they came from.
+     *
+     * A first page that came back short of its limit *is* the whole set — the
+     * same filter, the same narrowing, read as the same principal — so its
+     * length is the total and nothing is counted. Not for a later page, a
+     * cursor page, a search (whose page and count are not the same query) or
+     * a `distinct` read (whose count counts rows, not values): those count.
      */
-    private collectionMetaWithAuth;
-    /**
-     * Debounce an row refetch for a WebSocket subscription.
-     */
-    private debouncedSingleRefetch;
+    private collectionMeta;
     /**
-     * Debounce an row refetch for a Driver callback subscription.
+     * A `single_update` frame's row, and — when the subscriber asked — the
+     * `ETag` a `GET /:id` of the same row answers.
+     *
+     * The tag names the row, not the read: `GET` hashes the row as
+     * `restFetchService.fetchOneForRest` serves it with no `include`, and a
+     * write's `If-Match` is compared against that same rendering. A frame
+     * whose relations are loaded therefore takes its tag from a second read
+     * without them, read first — as `GET /:id?include=` does — so a write
+     * landing between the two leaves the tag older than the body (a 412 the
+     * client recovers from) and never newer, which would let an edit made
+     * against the older body pass over a change it never saw.
      */
-    private debouncedSingleDriverRefetch;
+    private fetchEntityFrame;
     /**
      * Fetch a single row with optional RLS auth context.
      */
     private fetchEntityWithAuth;
-    private sendCollectionUpdate;
-    private sendSingleUpdate;
+    /**
+     * Everything in a `collection_update` frame after its subscription id,
+     * serialised once for every member of a group: the rows, the collection's
+     * key columns, and the `meta` beside them (see {@link CollectionUpdateMeta}
+     * for the round trip that removes). The order is the one
+     * {@link CollectionUpdateMessage} declares.
+     */
+    private collectionFrameTail;
+    /** Everything in a `single_update` frame after its subscription id. */
+    private singleFrameTail;
+    /** A frame tail with its {@link frameDigest}, computed once for every member it goes to. */
+    private dataFrame;
+    /**
+     * What a subscriber was last sent, in 44 bytes: holding the frames
+     * themselves would keep a page of rows per subscriber in memory.
+     */
+    private frameDigest;
+    /**
+     * Send a data frame to a socket subscriber — unless it is exactly the one
+     * the subscriber was last sent.
+     *
+     * A write anywhere in a collection refetches every list of it, and the
+     * first 50 rows of a 10k-row list come back the same for 99.5% of writes.
+     * Each of those frames was sent anyway: ~30 KB per viewer per write,
+     * parsed, merged and re-rendered by every client to change nothing. The
+     * comparison is per subscriber, because the members of one group need not
+     * have been sent the same frame last — one may have joined since.
+     */
+    private sendDataFrame;
     /**
      * Send a lightweight row-level patch to a collection subscriber.
      * The client can merge this into its cached data for instant feedback.
@@ -524,6 +850,15 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private sendError;
     private sendMessage;
+    /**
+     * Send an already-serialised frame to a client, if it is still connected.
+     *
+     * Every frame to a socket goes through here, so this is where a client
+     * that does not read what it is sent is let go of — see
+     * {@link terminateIfBacklogged}. Terminated, it closes like any other
+     * socket, and {@link removeClient} drops what it held.
+     */
+    private sendRaw;
     /**
      * Extract parent paths from a nested path like "posts/70/tags"
      * Returns ["posts", "posts/70"] for the example above
@@ -601,6 +936,21 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * fraction of the room. The evidence is already in the process, so use it.
      */
     private warnIfMemoryBusOnMultiplePods;
+    /**
+     * Ask the database whether another process holds a realtime LISTEN
+     * connection on it, at most once per {@link OTHER_INSTANCES_CHECK_INTERVAL_MS}.
+     *
+     * The legacy entity channel proves a second instance with every foreign
+     * `sid`, but under change capture — the default — nothing crosses that
+     * channel, so the warning above could never fire on exactly the
+     * deployments it was written for. Every LISTEN connection names itself
+     * (`application_name`, which `pg_stat_activity` shows to any role), so
+     * the count is one cheap query. Only a process that listens is asked: a
+     * single process with no LISTEN connection has nothing to compare with.
+     */
+    private checkForOtherInstances;
+    /** Drop a channel its last local member left, and what was kept per channel for it. */
+    private forgetChannel;
     /** Leave a broadcast channel */
     leaveChannel(clientId: string, channel: string): void;
     /**
@@ -668,6 +1018,7 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * its own `sid`.
      */
     private handleBusFrame;
+    private deliverBusFrame;
     /**
      * Install retention rules and create the tables they need.
      *
@@ -757,8 +1108,16 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      *     does not answer the close frame is dropped after a short grace.
      */
     destroy(): Promise<void>;
-    /** Whether database-level change capture is currently the active source. */
+    /**
+     * Whether database-level change capture is the source and is listening.
+     *
+     * Configured is not enough: a CDC connection that went half-open used to
+     * leave this `true` while nothing arrived. False while the connection is
+     * down and being replaced.
+     */
     isCdcActive(): boolean;
+    /** The LISTEN connections this service depends on — see `RealtimeProvider.health`. */
+    health(): RealtimeListenerHealth[];
     /**
      * Enable database-level change capture as the realtime source.
      *
@@ -802,13 +1161,26 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     /**
      * Route a captured database change into the realtime pipeline.
      *
-     * Delivery is RLS-safe by construction: the raw tuple from the WAL/trigger is
-     * NOT forwarded to subscribers. Instead the change is marked invalidated, so
+     * Delivery is RLS-safe by construction: the event carries the changed row's
+     * key and nothing else, and even that is NOT forwarded to subscribers. Instead the change is marked invalidated, so
      * every matching subscription re-reads the row under its own auth context via
      * {@link fetchCollectionWithAuth} / {@link fetchEntityWithAuth}. A subscriber
      * therefore only ever receives rows its RLS policies permit — filtering is per
      * subscriber, never per publisher.
      */
+    /**
+     * Route the rows one notification names — a statement's batch, or one row.
+     *
+     * Each is handled as a change on its own (the app-emit de-duplication and
+     * single-row addressing are per row), at most {@link CDC_ROWS_PER_TURN} in
+     * one turn of the event loop; the rest wait in order for the next turns. A
+     * socket read hands the listener up to 2 MB of notifications at once, and
+     * batched that is ~250k rows: handled in one go, the event loop stalled
+     * for ~400 ms. Sliced, a 1M-row statement is ~200 short turns that timers,
+     * sockets and requests run between.
+     */
+    private handleCdcEvents;
+    private drainCdcBacklog;
     private handleCdcEvent;
     /**
      * Deliver a change on a many-to-many junction table as a change to the child
@@ -827,7 +1199,11 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * Returns whether the table was recognised as a junction.
      */
     private handleJunctionCdcEvent;
-    /** Compute the canonical (possibly composite) id string from a captured row. */
+    /**
+     * Compute the canonical (possibly composite) id string from a captured row,
+     * or {@link ANY_ROW} when it names none — a key too large to notify, a
+     * table with no key.
+     */
     private extractIdFromCdcRow;
     /**
      * A captured row with its key under the key's *field* names.
@@ -840,14 +1216,32 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private cdcRowByKeyFields;
     private dedupKey;
-    /** Record that this instance just delivered `key` via the app path. */
+    /**
+     * Record that this instance just delivered `key` via the app path.
+     *
+     * Expired entries are purged so the map cannot grow unbounded under write
+     * load — once it holds over 1,000, and at most once per dedup window. The
+     * purge walks the whole map, and it used to run on every write past 1,000:
+     * inside one window nothing has expired yet, so a burst of writes walked
+     * all of it each time (703 ms of event loop for 20,000 marks). Once a
+     * window, the map holds at most two windows' writes.
+     */
     private markAppEmit;
+    /** When {@link markAppEmit} may next purge expired entries. */
+    private nextAppEmitPurgeAt;
     /** Consume a matching app-emit record if present and unexpired; true ⇒ suppress the CDC echo. */
     private consumeAppEmit;
     /**
      * Enable cross-instance realtime broadcasting via Postgres LISTEN/NOTIFY.
-     * Creates a dedicated pg.Client (outside the Drizzle pool) that stays
-     * connected and listens for change notifications from other instances.
+     * Listens on a dedicated connection (outside the Drizzle pool) for the
+     * changes other instances publish, through a {@link PgNotifyListener}: it
+     * proves itself with a heartbeat, is replaced when it drops or stops
+     * answering, and every subscription is refetched once it is back, since
+     * whatever was published meanwhile reached nobody here.
+     *
+     * A database that cannot be reached at boot does not fail this call: the
+     * listener reports itself down (see {@link health}) and keeps dialling.
+     * There is no other cross-instance path to fall back to.
      *
      * This is an **optional** feature — if never called, the backend operates
      * in single-instance mode (the default, perfectly fine for most setups).
@@ -856,27 +1250,47 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     startListening(connectionString: string): Promise<void>;
     /**
-     * Stop listening and clean up the dedicated LISTEN connection.
+     * Announce this process's writes on {@link PG_NOTIFY_CHANNEL} without
+     * listening for anyone else's.
+     *
+     * For a process that serves no websockets (`worker`, `functions`) while
+     * change capture is not in effect. It has no subscriber of its own, so it
+     * holds no LISTEN connection — but without capture the announcement is
+     * the only way the `api` hears that a cron or a function wrote a row.
+     * Sending needs only the pool.
      */
-    stopListening(): Promise<void>;
+    startPublishing(): void;
     /**
-     * Broadcast a change notification to other instances via pg_notify.
-     * Uses the main Drizzle connection (pooled) — NOT the LISTEN client.
+     * Stop listening and clean up the dedicated LISTEN connection.
      */
-    private broadcastChange;
+    stopListening(): Promise<void>;
     /**
-     * Create and connect the dedicated LISTEN client with auto-reconnect.
+     * Announce a change to the other instances on {@link PG_NOTIFY_CHANNEL},
+     * with the rest of its burst. Resolves once the notification carrying it
+     * has been sent. Uses the main Drizzle connection (pooled), not the LISTEN
+     * client.
      *
-     * @param reconnect Set when the client is coming back from a drop: every
-     *        notification published in the gap is gone, so the subscriptions
-     *        are refetched once it is listening again.
-     */
-    private connectListenClient;
-    /**
-     * Schedule a reconnection attempt with a fixed 3s delay.
+     * Changes queued in the same turn of the event loop go out together, as
+     * many to a notification as fit under the NOTIFY ceiling: a 1,000-row save
+     * used to be 1,000 round trips. A burst of one keeps the single-change
+     * shape `{ sid, p, eid, db }`, which an older instance in a rolling deploy
+     * still reads; a batch is `{ sid, c: [[p, eid, db], …] }`. Both carry
+     * addresses and nothing else.
      */
-    private scheduleReconnect;
+    private broadcastChange;
+    private flushBroadcasts;
+    /** One notification another instance published on {@link PG_NOTIFY_CHANNEL}: one change, or a batch. */
+    private handleCrossInstanceNotification;
 }
+/**
+ * Pack `changes` into as few payloads as fit under
+ * {@link ENTITY_NOTIFY_MAX_BYTES}. One change keeps the single-change shape.
+ */
+export declare function packEntityChanges(sid: string, changes: Array<{
+    p: string;
+    eid: string;
+    db: string | null;
+}>): string[];
 /**
  * Alias for RealtimeService for consistent naming with other database implementations.
  * This allows code to use PostgresRealtimeProvider alongside future MongoRealtimeProvider, etc.