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

package/dist/services/FetchService.d.ts

@@ -1,5 +1,5 @@
 import { SQL } from "drizzle-orm";
-import { PgTable } from "drizzle-orm/pg-core";
+import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import { FilterValues, OrderByTuple, LogicalCondition } from "@rebasepro/types";
 import type { IncludeSpec, VectorSearchParams } from "@rebasepro/types";
 import { RelationService } from "./RelationService.js";
@@ -218,6 +218,18 @@ export declare class FetchService {
      * no related row, so a typo in an `include` looked like empty data.
      */
     private resolveIncludeLevel;
+    /**
+     * Resolve every level of an include tree against the collections, without
+     * loading anything — the 400 for an unknown relation, decided before the
+     * read rather than by it.
+     *
+     * {@link loadIncludes} resolves a level only once it has rows to load it
+     * onto. On its own that made the refusal depend on the data: a typo in
+     * `include` against an empty table, under a filter that matched nothing,
+     * or below a relation that loaded no rows answered 200, and the same
+     * request became a 400 the first time a row matched.
+     */
+    private assertIncludeResolvable;
     /**
      * The extra `WHERE` an include's own `where`/`logical` puts on the target.
      *
@@ -227,14 +239,25 @@ export declare class FetchService {
      */
     private includeNarrowing;
     /**
-     * Sort, cap and project the rows of ONE to-many relation, per parent.
+     * Refuse a `count` the loader cannot serve honestly, before anything runs.
      *
-     * `orderBy` and `limit` are applied here rather than in SQL because a limit
-     * on a batched relation load is *per parent*, and expressing that needs a
-     * LATERAL or a window function per relation kind — four of them, each with
-     * its own join shape. The rows were already narrowed by
-     * {@link includeNarrowing} in SQL, so what this sorts and cuts is the set
-     * the caller asked for and not the table.
+     * - On a to-one relation: there is nothing to count past a row or none,
+     *   and answering 0 or 1 under `_count` would invent a shape for it.
+     * - On a collection with a property named `_count`: the total would be
+     *   written over that column's value. A silent overwrite answers 200 with
+     *   the column gone, so it is a 400 naming why.
+     */
+    private assertCountsAllowed;
+    /**
+     * Cap and project the rows of ONE relation, per parent.
+     *
+     * The order and the limit are Postgres's: the batch loader ranks each
+     * parent's related rows by the include's `orderBy` and reads back only the
+     * ones within its `limit` (see
+     * {@link RelationService.batchFetchRelatedEntitiesMany}), so `rows`
+     * arrives sorted and already cut. The slice here is what holds the limit
+     * where a `via` chain reaches one target along two paths — those rows share
+     * a rank — and it costs nothing where nothing is left to cut.
      */
     private shapeRelatedRows;
     /**
@@ -313,9 +336,10 @@ export declare class FetchService {
      * Extract cursor pagination conditions from startAfter options.
      *
      * "Every row that sorts after this one", written out as a comparison over
-     * the same keys the `ORDER BY` uses and ending on the same `id DESC`. With
-     * one key that is the familiar `k > v OR (k = v AND id < cursorId)`; with
-     * several it nests, each key's tie handing the decision to the next.
+     * the same keys the `ORDER BY` uses and ending on the same primary key,
+     * descending. With one sort key that is the familiar
+     * `k > v OR (k = v AND id < cursorId)`; with several it nests, each key's
+     * tie handing the decision to the next.
      */
     private buildCursorConditions;
     /** The table's primary key columns, in key order. */
@@ -359,7 +383,7 @@ export declare class FetchService {
      */
     private preciseCursorValue;
     /**
-     * "Sorts strictly after the cursor row", over `keys` and then the id.
+     * "Sorts strictly after the cursor row", over `keys` and then the primary key.
      *
      * Built by recursion rather than as a row-value comparison — `(a, b) > (x, y)`
      * would be shorter, but it is only correct when every key runs the same
@@ -645,6 +669,33 @@ export declare class FetchService {
         /** See `FetchCollectionProps.withDeleted`. */
         withDeleted?: WithDeleted;
     }): Promise<Record<string, unknown> | null>;
+    /**
+     * {@link fetchOneForRest}'s read of a row an INSERT just wrote, taken from
+     * the INSERT's own `RETURNING` instead of a second statement — or
+     * `undefined` when the two could answer differently.
+     *
+     * A write answers with `fetchOneForRest(slug, id, undefined, …, { withDeleted: true })`
+     * (see `PersistService.save`): the row's visible columns, rendered by
+     * `toRestRow`. For a row the statement itself wrote, with nothing written
+     * after it, `RETURNING` those same columns is that row — the same values
+     * through the same column decoders, in the same order, rendered the same
+     * way. Two things narrow the read and not the statement, and either one
+     * keeps the read:
+     *
+     *  - a `beforeQuery` adds conditions to the read (and runs application
+     *    code): a row outside them is no answer today, and would be one from
+     *    `RETURNING`;
+     *  - per-field read access, which projects the read for the viewer.
+     *
+     * Row-level security is the same either way. `INSERT … RETURNING` holds
+     * the new row to the table's SELECT policies and refuses one they hide
+     * (42501) — which the INSERT's `RETURNING <key>` already did, so returning
+     * more columns changes nothing about who may write or read what.
+     */
+    insertReturning(collectionPath: string): {
+        columns: Record<string, AnyPgColumn>;
+        render: (returned: Record<string, unknown>) => Record<string, unknown>;
+    } | undefined;
     /**
      * Fetch raw rows without any relation processing (for REST fast path)
      */

package/dist/services/PersistService.d.ts

@@ -75,6 +75,21 @@ export declare class PersistService {
      * for why a zero-row write cannot be reported as success.
      */
     private explainZeroRowWrite;
+    /**
+     * Lock one row against every other write to it until this transaction
+     * ends: `FOR NO KEY UPDATE`, the lock an UPDATE of it takes anyway.
+     *
+     * For a conditional write (`If-Match`): taken before the row is read and
+     * compared, so a write that lands meanwhile is either already committed and
+     * read, or waits for this one. Without it two writes carrying the same tag
+     * both read the old row, both passed, and the second overwrote the first.
+     *
+     * Under row-level security the lock reads through the caller's UPDATE
+     * policies as well as their SELECT ones, so a row they may read but not
+     * update is simply not locked — and their write is refused by the database
+     * all the same. A nested address locks the row it ends in.
+     */
+    lockRow(collectionPath: string, id: string | number): Promise<void>;
     /**
      * Delete an row by ID
      */

package/dist/services/RelationService.d.ts

@@ -1,5 +1,5 @@
 import { SQL } from "drizzle-orm";
-import { PgTable } from "drizzle-orm/pg-core";
+import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import { DrizzleClient } from "../interfaces.js";
 import { CollectionConfig, FilterValues, OrderByTuple, ResolvedRelation, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
@@ -16,6 +16,70 @@ import { type ReadCallContextProvider } from "./read-scope.js";
  * the same claim about the same drizzle behaviour in a second spelling.
  */
 export declare function applyDynamicJoin<T>(query: T, joinTable: PgTable, condition: SQL): T;
+/**
+ * The ON condition of one `joinPath` step: every `from` column equal to its
+ * `to` column, or `undefined` naming the first column either table lacks.
+ *
+ * `on.from`/`on.to` are a column or a tuple, and a tuple is how a step joins on
+ * a composite key. Comparing the first pair alone joined each row to every row
+ * sharing that column — every locale of a translation, not the one addressed.
+ */
+export declare function joinStepCondition(currentTable: PgTable, joinTable: PgTable, step: {
+    on: {
+        from: string | string[];
+        to: string | string[];
+    };
+}): {
+    condition: SQL;
+} | {
+    missing: string;
+};
+/**
+ * What an include asks of ONE to-many relation's rows, per parent: how many,
+ * and in what order. See {@link RelationService.batchFetchRelatedEntitiesMany}.
+ */
+export interface RelatedRowWindow {
+    /** Rows to keep per parent. */
+    limit?: number;
+    /** Their order, by the target's own columns. */
+    orderBy?: OrderByTuple[];
+    /**
+     * Filled, when given and a `limit` is set, with each parent's number of
+     * matching related rows *before* the limit — what `include: { x: { limit,
+     * count: true } }` serves under `_count`. Counted in the ranking subquery,
+     * so it is the same statement, the same conditions and the same RLS
+     * context as the rows. A parent with no related row is absent (zero).
+     * Without a limit nothing is cut, and the caller counts what it got.
+     */
+    totals?: Map<string, number>;
+}
+/**
+ * How the batch loaders render a target row.
+ *
+ * - `"admin"` — the view model the admin panel reads: declared types parsed
+ *   (`parseDataFromServer`), the target's own to-one relations as
+ *   `{ __type: "relation" }` refs, undeclared columns dropped.
+ * - `"rest"` — the row the target's own route serves (`toRestRow`): what an
+ *   `include` embeds. The REST contract is that a developer never sees a ref,
+ *   and an included row is rendered exactly as the same row is at the top
+ *   level.
+ */
+export type RelatedRowStyle = "admin" | "rest";
+/**
+ * The order one parent's related rows come in: the include's own keys, then
+ * the target's key ascending.
+ *
+ * The key ascending is the order an unordered batch read handed rows back in
+ * on an append-only table, and so the rows a `limit` with no `orderBy` kept —
+ * stated now rather than left to the plan. A key that names no column of the
+ * target sorts nothing, as it sorted nothing when the sort ran over the
+ * returned rows in JavaScript; the caller's field access on it was already
+ * judged at the route.
+ *
+ * NULLs go where a top-level `orderBy` puts them: the stated placement, else
+ * Postgres's own (last ascending, first descending).
+ */
+export declare function relatedRowOrder(targetTable: PgTable, targetKeys: AnyPgColumn[], orderBy: OrderByTuple[] | undefined): SQL[];
 /**
  * Service for handling all relation-related operations.
  * Handles fetching, updating, and managing row relations.
@@ -101,6 +165,21 @@ export declare class RelationService {
      * nobody was comparing.
      */
     private toRelatedRow;
+    /**
+     * A target row as its own REST route serves it, for the `"rest"` style.
+     *
+     * The loaders read the target with `SELECT *`, so the columns a REST read
+     * never selects — a generated search vector — are dropped first; then
+     * `toRestRow` renders the rest, which applies the target's field access.
+     * Built once per batch: the hidden set is a property of the table.
+     *
+     * It replaces a second pass. An include used to render each target row as
+     * the admin's view model (`parseDataFromServer`, which also minted a
+     * `{ __type: "relation" }` ref for the target's own to-one relations) and
+     * then re-render that for REST: 3.4 µs a row against 1.4 µs for the row
+     * itself, and an envelope in a response whose contract has none.
+     */
+    private restRendering;
     /**
      * The junction row's own columns, as the caller may see them.
      *
@@ -224,13 +303,37 @@ export declare class RelationService {
      * the rows that come back, because filtering afterwards reads every related
      * row of every parent in order to discard most of them.
      */
-    batchFetchRelatedEntities(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation, narrow?: SQL): Promise<Map<string, RelatedRow<Record<string, unknown>>>>;
+    batchFetchRelatedEntities(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation, narrow?: SQL, options?: {
+        /** How each target row is rendered; see {@link RelatedRowStyle}. */
+        style?: RelatedRowStyle;
+        /**
+         * The parent rows themselves, in `parentIds` order, when the caller
+         * holds them. A `belongsTo` reads each one's foreign key off its
+         * row rather than selecting it again.
+         */
+        parentRows?: Record<string, unknown>[];
+    }): 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.
+     *
+     * `window` is an include's own `limit` and `orderBy`, and both are applied
+     * by Postgres. A limit is *per parent*, so it is a rank within each
+     * parent's rows rather than a `LIMIT`: a subquery ranks the keys of every
+     * matching row — under the same relation condition, `narrow`, soft delete
+     * and `beforeQuery` the unlimited read applies — and the read joins back to
+     * the ones ranked within the limit. It used to read every related row of
+     * every parent and cut the list in JavaScript: 200 rows served out of
+     * 200,000 read, parsed and rendered for `{ messages: { limit: 2 } }` on a
+     * page of 100 threads. Rows come back in the window's order, so the
+     * per-parent lists are already sorted.
      */
     batchFetchRelatedEntitiesMany(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation, 
     /** An extra condition on the target — see {@link batchFetchRelatedEntities}. */
-    narrow?: SQL): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
+    narrow?: SQL, window?: RelatedRowWindow, 
+    /** `style` — how each target row is rendered; see {@link RelatedRowStyle}. */
+    options?: {
+        style?: RelatedRowStyle;
+    }): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
 }

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

@@ -1,25 +1,38 @@
+import { type PgNotifyListenerStatus } from "../pg-notify-listener.js";
 /**
  * A single database change captured by the CDC triggers and delivered over the
- * `rebase_cdc` NOTIFY channel.
+ * `rebase_cdc` NOTIFY channel — one row of a notification, which may name many.
  */
 export interface CdcChangeEvent {
     schema: string;
     table: string;
-    op: "INSERT" | "UPDATE" | "DELETE";
+    /** `TRUNCATE` changed every row, and `row` is empty. */
+    op: "INSERT" | "UPDATE" | "DELETE" | "TRUNCATE";
     /**
-     * The changed tuple (NEW for insert/update, OLD for delete). May be a
-     * partial identity-only object when the full row overflowed the pg_notify
-     * size cap — see {@link truncated}.
+     * The changed row's identity, by column: its key, and for a junction table
+     * the two ids naming the child list (from NEW for insert/update, OLD for
+     * delete). Never the row's other values — any login can LISTEN; see
+     * `buildCdcFunctionSql`.
      */
     row: Record<string, unknown>;
-    /** True when the row was reduced to its identity because it was too large to notify. */
+    /** True when even the key was too large to notify, so `row` is empty. */
     truncated?: boolean;
 }
 /**
- * Parse a `rebase_cdc` NOTIFY payload. Returns `null` for anything malformed so
- * a single bad message can never crash the listener.
+ * Parse a `rebase_cdc` NOTIFY payload into the changes it names, one per row.
+ * Returns `null` for anything malformed so a single bad message can never
+ * crash the listener.
+ *
+ * Reads every shape a capture trigger sends, whichever version installed it —
+ * during a rolling deploy the database's triggers and this instance need not
+ * be the same version:
+ *  - `{ schema, table, op, row }` — one row: the row trigger, and a statement
+ *    that changed one row;
+ *  - `{ schema, table, op, cols, keys }` — a statement's rows in a batch. With
+ *    one column a key is the value; with several, an array in `cols` order;
+ *  - `{ schema, table, op: "TRUNCATE" }`.
  */
-export declare function parseCdcPayload(payload: string): CdcChangeEvent | null;
+export declare function parseCdcPayload(payload: string): CdcChangeEvent[] | null;
 /**
  * Dedicated Postgres LISTEN client for database-level CDC.
  *
@@ -36,7 +49,7 @@ export declare class CdcListener {
      *        drop. Every change committed in the gap was notified to nobody, so
      *        this is where subscribers are told to look again.
      */
-    constructor(connectionString: string, onEvent: (event: CdcChangeEvent) => void | Promise<void>, onReconnect?: () => void);
+    constructor(connectionString: string, onEvents: (events: CdcChangeEvent[]) => void | Promise<void>, onReconnect?: () => void, applicationName?: string);
     /**
      * Connect and begin listening. Idempotent.
      *
@@ -49,4 +62,7 @@ export declare class CdcListener {
     start(): Promise<void>;
     /** Stop listening and release the connection. */
     stop(): Promise<void>;
+    /** Listening on a connection that answered its last heartbeat — see {@link PgNotifyListener}. */
+    get connected(): boolean;
+    status(): PgNotifyListenerStatus;
 }

package/dist/services/cdc/identity-columns.d.ts

@@ -0,0 +1,19 @@
+import type { CollectionConfig } from "@rebasepro/types";
+import type { PostgresCollectionRegistry } from "../../collections/PostgresCollectionRegistry.js";
+/** One key field of a collection, and the column it is stored in. */
+export interface KeyColumn {
+    fieldName: string;
+    columnName: string;
+}
+/**
+ * The columns a collection's rows are addressed by.
+ *
+ * A change notification names its row by column — that is all a trigger sees —
+ * and an address is built from the key's *field* names. Both ends read the
+ * mapping from here: the provisioner, to attach the trigger with exactly these
+ * columns (and nothing else leaves the database), and the consumer, to turn the
+ * captured columns back into an address. A key declared as `userId` over
+ * `user_id` used to be looked up by field name on the captured row, never
+ * found, and every external write reached no single-row subscriber.
+ */
+export declare function collectionKeyColumns(collection: CollectionConfig, registry: PostgresCollectionRegistry): KeyColumn[];

package/dist/services/cdc/trigger-cdc.d.ts

@@ -6,9 +6,13 @@ import type { RawSqlRunner } from "../../security/rls-enforcement.js";
  * — like Supabase Realtime — sees *every* commit regardless of how it was made.
  * When logical replication is unavailable (managed Postgres without
  * `wal_level=logical`, no replication privilege, no `REPLICA IDENTITY`), this
- * trigger-based fallback provides the same guarantee at the row level:
+ * trigger-based fallback provides the same guarantee:
  *
- *   AFTER INSERT/UPDATE/DELETE trigger  →  pg_notify('rebase_cdc', payload)
+ *   AFTER INSERT/UPDATE/DELETE/TRUNCATE statement trigger  →  pg_notify('rebase_cdc', payload)
+ *
+ * once per statement, naming the changed rows by key in batches of about a
+ * thousand — a 1M-row UPDATE is ~1,000 notifications, where a row trigger sent
+ * a million into Postgres's shared notification queue, to every instance.
  *
  * A single dedicated LISTEN client per backend instance consumes the channel
  * (see {@link CdcListener}) and feeds the change into the existing
@@ -21,29 +25,127 @@ import type { RawSqlRunner } from "../../security/rls-enforcement.js";
  */
 /** Postgres NOTIFY channel carrying database-level change events. */
 export declare const CDC_CHANNEL = "rebase_cdc";
-/** Schema-qualified name of the generic trigger function. */
+/**
+ * Schema-qualified name of the row-level trigger function: one notification
+ * per changed row. What every version before statement-level capture attached
+ * everywhere, and still what a partitioned or foreign table gets — see
+ * {@link levelForRelkind}.
+ */
 export declare const CDC_TRIGGER_FUNCTION = "rebase.rebase_cdc_notify";
-/** Name of the per-table trigger (unqualified — triggers are namespaced by table). */
+/**
+ * Schema-qualified name of the statement-level trigger function: one
+ * notification per ~1,000 changed rows. See {@link buildCdcFunctionSql}.
+ *
+ * A function of its own rather than a new body for the row function, because
+ * an instance of an older version replaces the row function's body every time
+ * it boots: a statement trigger calling it would then run a row trigger's body,
+ * for every write, until the next boot of this version.
+ */
+export declare const CDC_STATEMENT_FUNCTION = "rebase.rebase_cdc_notify_statement";
+/** Name of the per-table row-level trigger (unqualified — triggers are namespaced by table). */
 export declare const CDC_TRIGGER_NAME = "rebase_cdc_trigger";
+/** How a table is instrumented: one notification per statement's ~1,000 rows, or one per row. */
+export type CdcTriggerLevel = "statement" | "row";
+/** One trigger this module creates, as `pg_trigger` describes it. */
+interface CdcTriggerSpec {
+    name: string;
+    /** The function it calls. */
+    fn: "row" | "statement";
+    /** `CREATE TRIGGER` between the name and `ON`. */
+    timing: string;
+    /** `CREATE TRIGGER` between the table and `EXECUTE`. */
+    forEach: string;
+    /** `tgtype`: ROW (1), BEFORE (2), INSERT (4), DELETE (8), UPDATE (16), TRUNCATE (32), INSTEAD (64). */
+    type: number;
+    /** `tgnewtable` / `tgoldtable`: the transition tables it captures. */
+    newTable: string | null;
+    oldTable: string | null;
+}
+/**
+ * The statement-level triggers a plain table gets. One per event, because
+ * Postgres refuses transition tables on a trigger with more than one event.
+ * The TRUNCATE one is new with them: a row trigger never fires on `TRUNCATE`,
+ * so a truncated table used to be announced to nobody.
+ */
+export declare const CDC_STATEMENT_TRIGGERS: readonly CdcTriggerSpec[];
+/**
+ * The level a table is instrumented at, by `pg_class.relkind`.
+ *
+ * A plain table gets statement triggers. A partitioned table keeps the row
+ * trigger: Postgres clones a row trigger onto every partition, so a write made
+ * straight to a partition is still captured, while a statement trigger on the
+ * parent fires only for statements against the parent. A foreign table
+ * cannot have transition tables at all.
+ */
+export declare const levelForRelkind: (relkind: string | null | undefined) => CdcTriggerLevel;
 /**
- * SQL that (re)creates the generic CDC trigger function. Safe to run repeatedly:
- * `CREATE OR REPLACE` updates in place without dropping dependent triggers.
- *
- * The function emits `{ schema, table, op, row }`. The `row` is the full changed
- * tuple (NEW for insert/update, OLD for delete) so the consumer can route it to
- * a collection and extract the primary key. It is *not* trusted for delivery:
- * the consumer marks the row invalidated and each subscriber re-reads it under
- * its own RLS context, so a subscriber never receives a row it cannot read.
+ * How long after a boot first converts a table from the row trigger, the
+ * statement triggers still announce every change one row per notification.
+ *
+ * The triggers are the database's, and an instance of the previous version
+ * still running beside this one — a rolling deploy, a rollback — reads the
+ * same channel with a parser that knows one row per notification: given a
+ * batch it sees no key, so its lists refetch but its single-row and
+ * many-to-many subscribers hear nothing. While any such instance may be up,
+ * the statement triggers speak its protocol; after this window they batch.
+ * Every version that batches reads both. A boot of the older version re-attaches its row trigger (it
+ * creates a missing one), and the next boot of this one converts it back and
+ * re-opens the window, so a rollback is covered the same way.
  */
-export declare function buildCdcFunctionSql(): string;
+export declare const CDC_ROW_COMPAT_MS: number;
 /**
- * SQL that (re)attaches the CDC trigger to a single table. `DROP ... IF EXISTS`
- * before `CREATE` keeps it idempotent and picks up any function signature change.
+ * SQL that (re)creates both CDC trigger functions. Safe to run repeatedly:
+ * `CREATE OR REPLACE` updates in place without dropping dependent triggers —
+ * which is also how a database instrumented by an older version gets these
+ * bodies on its next boot, for every table at once, re-attached or not.
+ *
+ * Both functions emit `{ schema, table, op, ... }`, and the rows are named by
+ * **identity, never the tuple**. Postgres puts no privilege on `LISTEN`: any
+ * role that can connect can listen on this channel, whatever it may `SELECT`.
+ * When `row` was `to_jsonb(NEW)`, a login with no grant on anything received
+ * every changed row of every instrumented table — `password_hash` and
+ * verification tokens from the auth table included — past RLS and column
+ * grants. The consumer never read anything but the key: every subscriber
+ * re-reads the row under its own scope.
+ *
+ * The identity is, in order:
+ *  - the columns the trigger was attached with (`TG_ARGV`) — the key the
+ *    consumer addresses the row by, and for a junction table the two ids that
+ *    name the child list it changed; see {@link buildCdcTriggerSql};
+ *  - otherwise the table's primary key, read from the catalogue — a trigger
+ *    attached with no columns, by an older boot or on a table no collection
+ *    maps any more;
+ *  - otherwise `id`, if the table has one, and else nothing: a change the
+ *    consumer can only treat as collection-wide.
+ *
+ * `compatUntil` is the end of the window in which the statement function
+ * still sends one row per notification — see {@link CDC_ROW_COMPAT_MS}. A
+ * timestamp, or `-infinity` for none.
  */
-export declare function buildCdcTriggerSql(schema: string, table: string): string;
+export declare function buildCdcFunctionSql(options?: {
+    compatUntil?: string;
+}): string;
+/**
+ * SQL that (re)attaches the CDC triggers to a single table, at `level`.
+ * Every trigger this module owns is dropped first, whichever level it was
+ * created at, so a table moves between levels — a row trigger left by an
+ * older version becomes the statement triggers — in one transaction, with no
+ * moment at which a write is announced by neither.
+ *
+ * `identityColumns` are what the payload names the changed rows by — see
+ * {@link buildCdcFunctionSql}. Passed as trigger arguments, so one shared
+ * function serves every table. Empty means "the primary key".
+ */
+export declare function buildCdcTriggerSql(schema: string, table: string, identityColumns?: readonly string[], level?: CdcTriggerLevel): string;
 export interface CdcTableRef {
     schema: string;
     table: string;
+    /**
+     * The columns a change to this table is announced by — the collection's
+     * key columns, or a junction's two id columns. Absent means the primary
+     * key. Nothing else ever leaves the trigger; see {@link buildCdcFunctionSql}.
+     */
+    identityColumns?: string[];
 }
 export interface ProvisionResult {
     /** Tables the trigger was successfully attached to. */
@@ -54,11 +156,71 @@ export interface ProvisionResult {
     }>;
 }
 /**
- * Idempotently install the CDC trigger function and per-table triggers.
+ * Replace the already-installed trigger functions with the current bodies, and
+ * install nothing where there is none.
+ *
+ * For a process that owns the schema but is not provisioning capture on this
+ * boot — `REALTIME_CDC=off`, or no direct URL to listen on. The triggers an
+ * earlier boot attached keep firing whether anything consumes them or not, so
+ * a database instrumented by a version whose function put whole rows on the
+ * channel kept doing so, for every login that cares to `LISTEN`, until capture
+ * was switched back on. The statement function keeps its compatibility
+ * window. Returns whether a function was there to replace.
+ */
+export declare function refreshInstalledCdcFunction(run: RawSqlRunner): Promise<boolean>;
+/**
+ * Take change capture off the database: detach every capture trigger and drop
+ * both functions. Returns how many triggers were attached.
+ *
+ * For `REALTIME_CDC=off`. Capture switched off used to leave the triggers in
+ * place, so every write to every instrumented table still ran one and sent a
+ * notification on a channel nothing listened to. Nothing depends on them once
+ * capture is off: a process without capture announces its own writes on the
+ * cross-instance channel, and the instances that serve realtime listen there.
+ *
+ * `DROP FUNCTION … CASCADE` takes the triggers with it in one statement. It
+ * waits for each table's lock like any trigger DDL, so it runs with the boot's
+ * lock budget and is retried on a lock timeout; a database still contended
+ * after that keeps its triggers and the caller reports it.
+ */
+export declare function removeTriggerCdc(run: RawSqlRunner): Promise<number>;
+/**
+ * What a boot that does not provision capture does with capture an earlier
+ * boot installed.
+ *
+ *  - `capture: "off"` — `REALTIME_CDC=off` — removes it ({@link removeTriggerCdc}).
+ *  - `capture: "not-provisioned"` — capture is wanted but this boot could not
+ *    install it (no direct URL, `auto` fell back) — leaves the triggers and
+ *    brings the functions up to date ({@link refreshInstalledCdcFunction}),
+ *    since they keep firing.
+ */
+export declare function settleInstalledCapture(run: RawSqlRunner, options: {
+    capture: "off" | "not-provisioned";
+}): Promise<{
+    removed: number;
+} | {
+    refreshed: boolean;
+}>;
+/**
+ * Idempotently install the CDC trigger functions and per-table triggers.
+ *
+ * A plain table gets the statement-level triggers, a partitioned or foreign
+ * one the row trigger ({@link levelForRelkind}). A table whose triggers are
+ * already exactly the ones this would create — same function, same events,
+ * enabled, same identity arguments — is left alone; one with a trigger
+ * missing, disabled, attached with different arguments or at the other level
+ * is (re-)attached, all of it in one transaction.
+ *
+ * Converting a table from a row trigger an older version attached opens the
+ * statement function's compatibility window ({@link CDC_ROW_COMPAT_MS}): the
+ * instances that attached it may still be listening.
  *
  * Runs as the owner (server) connection at bootstrap. A table that does not yet
  * exist in the database (schema drift) is skipped with a warning rather than
  * aborting the whole install, so one un-migrated collection cannot disable CDC
  * for the rest.
  */
-export declare function provisionTriggerCdc(run: RawSqlRunner, tables: CdcTableRef[]): Promise<ProvisionResult>;
+export declare function provisionTriggerCdc(run: RawSqlRunner, tables: CdcTableRef[], options?: {
+    now?: number;
+}): Promise<ProvisionResult>;
+export {};

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

@@ -6,13 +6,15 @@
  * 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.
+ *    scene snapshot does not. A message on a *retained* channel never travels
+ *    here at all, whatever its size: the statement that numbers it notifies a
+ *    pointer — the body is already in `rebase.channel_messages` with a sequence
+ *    number, so the receiver reads it back (`ChannelHistoryStore.append`). That
+ *    is the same trick the entity path uses (notify an address, refetch the
+ *    row), applied to a different table, and for the same reason: any database
+ *    login can `LISTEN`. On an ephemeral channel there is nothing to point at,
+ *    so the frame carries the message, and an oversized one 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 —
@@ -26,6 +28,7 @@
  *    than correctness. That is what makes coalescing safe.
  */
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { type PgNotifyListenerStatus } from "../pg-notify-listener.js";
 import { ChannelBus, ChannelBusFrame, ChannelBusHandler } from "./ChannelBus.js";
 /** NOTIFY channel carrying channel-bus frames. */
 export declare const CHANNEL_BUS_NOTIFY_CHANNEL = "rebase_channel_bus";
@@ -79,6 +82,8 @@ export declare class PostgresChannelBus implements ChannelBus {
      * still holds.
      */
     publish(frame: ChannelBusFrame): Promise<void>;
+    /** The LISTEN connection's state, for `/health` — see {@link PgNotifyListener}. */
+    status(): PgNotifyListenerStatus | undefined;
     stop(): Promise<void>;
     private openWindow;
     /** Send everything queued and settle the promises waiting on it. */