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

package/dist/schema/plan/diff-plan.d.ts

@@ -81,7 +81,83 @@ export interface ExistingSchema {
     columnTypes?: Map<string, string>;
     /** `schema.table.trigger` of every trigger that already exists. */
     triggers?: Set<string>;
+    /**
+     * `schema.name` of every index (any relation of kind `i`/`I`) that already
+     * exists. Absent means unknown, and every index is planned as before —
+     * `IF NOT EXISTS` makes that correct, just not free.
+     */
+    indexes?: Set<string>;
+    /**
+     * `schema.name` of every index whose `pg_index.indisvalid` is false — the
+     * husk a `CREATE INDEX CONCURRENTLY` leaves behind when it is cancelled,
+     * times out, or loses a race with a peer. Such an index is in
+     * {@link indexes} too, maintained on every write and used by no query, and
+     * `IF NOT EXISTS` skips it by name forever. Absent means unknown.
+     */
+    invalidIndexes?: Set<string>;
+    /**
+     * Names of the extensions installed in the database. `CREATE EXTENSION IF
+     * NOT EXISTS` skips by name whatever schema the extension is in, so the name
+     * is the whole test. Absent means unknown.
+     */
+    extensions?: Set<string>;
+    /**
+     * {@link HELPER_FUNCTIONS} as they are in the catalogue: `schema.name(args)`
+     * → {@link describeHelperFunction} of what `CREATE OR REPLACE` would set.
+     * Absent means unknown, and every helper is re-created as before.
+     */
+    functions?: Map<string, string>;
 }
+/**
+ * The functions the plan creates with `CREATE OR REPLACE`, which the catalogue
+ * reader looks up so a boot that finds them unchanged plans nothing.
+ *
+ * A helper missing from this list is not wrong, only re-created on every boot,
+ * which is what all of them were before.
+ */
+export declare const HELPER_FUNCTIONS: readonly string[];
+/**
+ * Everything `CREATE OR REPLACE FUNCTION` sets on a function, as one string.
+ *
+ * Built from the catalogue by the reader and from the statement by
+ * {@link parseHelperFunction}, so the two meet in one shape. It covers every
+ * attribute a `CREATE OR REPLACE` resets — body, language, volatility,
+ * strictness, parallel safety, security, leakproofness, cost and `SET` options —
+ * so a function someone altered by hand (`ALTER FUNCTION … VOLATILE`) still
+ * compares unequal and is re-created, exactly as the unconditional statement
+ * used to re-create it.
+ */
+export interface HelperFunctionFacts {
+    returns: string;
+    language: string;
+    /** `provolatile`: `i`mmutable, `s`table, `v`olatile. */
+    volatility: string;
+    strict: boolean;
+    /** `proparallel`: `s`afe, `r`estricted, `u`nsafe. */
+    parallel: string;
+    securityDefiner: boolean;
+    leakproof: boolean;
+    cost: number;
+    /** Whether the function carries any `SET` options (`proconfig`). */
+    hasConfig: boolean;
+    /** `prosrc`: the text between the dollar quotes, exactly. */
+    body: string;
+}
+export declare const helperFunctionKey: (schema: string, name: string, args: string) => string;
+export declare const describeHelperFunction: (facts: HelperFunctionFacts) => string;
+/**
+ * What a helper's `CREATE OR REPLACE FUNCTION` statement would leave in the
+ * catalogue, or `undefined` for a statement this does not recognise — which is
+ * then planned unconditionally, as every statement was before.
+ *
+ * Only ever given statements this package renders (`searchHelperFunctions`,
+ * `setUpdatedAtFunction`), so a strict pattern is the right tool: anything it
+ * does not match exactly falls back to the safe behaviour.
+ */
+export declare function parseHelperFunction(statement: string): {
+    key: string;
+    definition: string;
+} | undefined;
 /**
  * How far the planner may go in making the database's constraints match the
  * configuration.
@@ -100,6 +176,18 @@ export type ConstraintPolicy = "additive" | "converge";
 export interface DiffOptions {
     /** Defaults to `additive`. See {@link ConstraintPolicy}. */
     constraints?: ConstraintPolicy;
+    /**
+     * Plan every index a table that already exists needs — declared, search
+     * and vector, missing or left INVALID under its name — as a
+     * {@link DeferredIndexBuild} rather than an action, as the derived
+     * foreign-key indexes always are. `ensureCollectionTables` sets it: it
+     * hands them to `buildDeferredIndexes`, which builds them on a connection
+     * of its own with no `statement_timeout`, and drops and rebuilds a husk.
+     *
+     * Absent — the live schema editor, which applies `statements` as text —
+     * they stay `CREATE INDEX CONCURRENTLY IF NOT EXISTS` actions, as before.
+     */
+    deferLiveIndexes?: boolean;
 }
 export interface EnsureAction {
     kind: "create-enum" | "create-table" | "enable-rls" | "add-column" | "add-constraint" | "rename-column" | "create-extension" | "create-function" | "create-index" | "comment-column" | "add-enum-value" | "set-not-null" | "drop-not-null" | "set-default" | "create-trigger";
@@ -166,6 +254,42 @@ export interface LegacyForeignKey {
     /** The name the old rule derived, which the table already has. */
     legacy: string;
 }
+/**
+ * An index a table that already exists is missing, or holds INVALID — a
+ * derived foreign-key index always, and under
+ * {@link DiffOptions.deferLiveIndexes} a declared, search or vector one too.
+ *
+ * Not an {@link EnsureAction}, because it must not hold the boot: on a table
+ * with millions of rows `CREATE INDEX CONCURRENTLY` takes minutes, and every
+ * minute of it would be a minute the deployment is not serving. The caller
+ * builds these after the fact — boot in the background once it serves, every
+ * other caller inline after the actions — through `buildDeferredIndexes`. A
+ * {@link unique} one is the exception: it is built before the ensure returns.
+ *
+ * Kept out of {@link EnsurePlan.statements} for the same reason: a caller that
+ * applies statements as text (the live schema editor) may run them inside a
+ * transaction, which `CONCURRENTLY` refuses.
+ */
+export interface DeferredIndexBuild {
+    schema: string;
+    /** Bare table name. */
+    table: string;
+    indexName: string;
+    /** `CREATE [UNIQUE] INDEX CONCURRENTLY IF NOT EXISTS …;` */
+    sql: string;
+    /**
+     * The catalogue already holds an INVALID index under this name, which has
+     * to be dropped before the build — `IF NOT EXISTS` would skip it.
+     */
+    invalid: boolean;
+    /**
+     * A declared `unique: true` index. Not an optimization but the collection
+     * promising two rows cannot share a value, so `ensureCollectionTables`
+     * builds it before it returns — never after the server is serving — and
+     * fails when it cannot, as it did when this was an action. Absent is false.
+     */
+    unique?: boolean;
+}
 export interface EnsurePlan {
     actions: EnsureAction[];
     /** Every statement, in dependency order. Empty when the schema is current. */
@@ -217,5 +341,7 @@ export interface EnsurePlan {
      * exactly once, which is not a decision to take unattended.
      */
     orphanedRequiredColumns: OrphanedRequiredColumn[];
+    /** @see DeferredIndexBuild */
+    deferredIndexes: DeferredIndexBuild[];
 }
 export declare function diffPlanAgainstCatalogue(plan: SchemaPlan, existing: ExistingSchema, options?: DiffOptions): EnsurePlan;

package/dist/schema/plan/types.d.ts

@@ -280,6 +280,14 @@ export interface PolicyPlan {
      * what `securityRules` reads like — `policies.sql` says so in a comment.
      */
     injected: boolean;
+    /**
+     * Policy names, as Postgres stored them, that this policy replaces — set
+     * only on the first policy of a rule whose per-operation names used to
+     * collide at 63 bytes (see `getPolicySupersededNames`). Rendered as a
+     * `DROP POLICY IF EXISTS` ahead of the policy, so a boot or push swaps the
+     * one truncated survivor for a policy per operation. Absent otherwise.
+     */
+    supersedes?: string[];
 }
 /** A `BEFORE UPDATE` trigger stamping `now()` onto an `on_update` column. */
 export interface TriggerPlan {

package/dist/schema/push-index-prebuild.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The foreign-key indexes `rebase db push` builds before Atlas plans.
+ *
+ * Rebase derives a btree for every `belongsTo` key and every junction's target
+ * column (15b00afcd). On a table that already exists — every table of a
+ * project upgraded across that release — the index is missing, and a push left
+ * it to Atlas, which builds it inside the push's one transaction: a plain
+ * `CREATE INDEX`, holding writes to the table for the whole build, about 0.4 s
+ * at a million rows and 6 s at ten million. Atlas's own concurrent mode would
+ * run the entire apply outside a transaction, which the push relies on.
+ *
+ * So the push builds those first, `CONCURRENTLY`, with the builder the boot
+ * uses for the same indexes (`deferred-index-build.ts`: one at a time, a lock
+ * budget for getting the table, an INVALID leftover dropped and rebuilt, a
+ * claim shared with booting instances). Atlas then finds them and plans
+ * nothing for them. One it could not build is still Atlas's, as before.
+ *
+ * Only an index whose columns are already there: a column this push adds is
+ * created by Atlas, and its index with it, on a column that holds no values.
+ */
+import { type CollectionConfig } from "@rebasepro/types";
+import { type DeferredIndexBuild } from "./plan/diff-plan.js";
+import { type Queryable } from "./ensure-collection-tables.js";
+/** The derived foreign-key indexes a live table lacks (or holds INVALID) whose columns it already has. */
+export declare function missingForeignKeyIndexes(client: Queryable, collections: CollectionConfig[]): Promise<DeferredIndexBuild[]>;

package/dist/schema/push-legacy-renames.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The relation columns an aged database still holds under the name Rebase
+ * derived before 0.13 (`categorie_id`, `people_id`), for `db push` to rename
+ * before Atlas plans.
+ *
+ * Boot renames them losslessly (`diff-plan.ts`, `renameLegacyColumn`). Push
+ * runs Atlas, which sees only "drop `categorie_id`, add `category_id` NOT
+ * NULL": it listed the links as destructive changes to approve, and with
+ * `--allow-destructive` dropped them. A pipeline that runs only `db push`
+ * could not upgrade an aged database at all. Renaming first — the same
+ * metadata-only statement boot runs — leaves Atlas nothing to plan.
+ */
+import { type CollectionConfig } from "@rebasepro/types";
+import { type LegacyForeignKey } from "./plan/diff-plan.js";
+import { type Queryable } from "./ensure-collection-tables.js";
+export interface LegacyRename extends LegacyForeignKey {
+    /** `ALTER TABLE … RENAME COLUMN …;` */
+    sql: string;
+}
+export declare function legacyForeignKeyRenames(client: Queryable, collections: CollectionConfig[]): Promise<LegacyRename[]>;

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

@@ -45,6 +45,21 @@
  * a parser for a problem that does not need one.
  */
 export declare const RLS_BOOTSTRAP_STATEMENTS: readonly string[];
+/**
+ * Whether the `rebase` schema and every RLS helper function are exactly what
+ * {@link RLS_BOOTSTRAP_STATEMENTS} would make them — one catalogue read.
+ *
+ * The boot ran those statements unconditionally, on every boot and on every
+ * source: four `CREATE OR REPLACE FUNCTION`s in a transaction under an
+ * advisory lock. Replacing a function rewrites its `pg_proc` row even when
+ * nothing changed, and every cached plan that inlined it — every plan of every
+ * statement a policy applies to, on every connection — is invalidated by it.
+ * A function that differs in anything `CREATE OR REPLACE` sets (body,
+ * language, volatility, strictness, parallel safety, security, leakproofness,
+ * cost, `SET` options), or is missing, answers `false`, and the statements run
+ * as before.
+ */
+export declare function rlsRuntimeIsCurrent(run: (sql: string) => Promise<Record<string, unknown>[]>): Promise<boolean>;
 /** The same statements as one script, for migration files and raw clients. */
 export declare const RLS_BOOTSTRAP_SQL: string;
 /**

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

@@ -31,8 +31,9 @@ import { REBASE_USER_ROLE } from "@rebasepro/common";
  *     SELECT/INSERT/UPDATE/DELETE grants (+ default privileges so future
  *     tables stay covered).
  *  3. {@link applyAuthContext} — per-transaction: set the `app.*` GUCs the
- *     policies read (`rebase.uid()` etc.) and `SET LOCAL ROLE rebase_user` so
- *     RLS binds. Transaction-scoped, so it composes with poolers.
+ *     policies read (`rebase.uid()` etc.) and the transaction-local role
+ *     `rebase_user` so RLS binds, in one statement. Transaction-scoped, so it
+ *     composes with poolers.
  *
  * Provisioning runs from the framework's own bootstrap/migrate (which already
  * self-creates the `auth` schema and functions) — enforcement is default-on,
@@ -203,11 +204,38 @@ export declare function appRoleSetupInstructions(connectionRole: string, schemas
  * connection cannot create it.
  */
 export declare function ensureAppRole(run: RawSqlRunner, schemas: string[]): Promise<void>;
+/**
+ * The grant tier of {@link ensureAppRole} on its own: `USAGE` on each existing
+ * schema in `schemas`, DML on its tables and `USAGE, SELECT` on its
+ * sequences, the default privileges that cover what this role creates later,
+ * and Rebase's own tables taken back — for a role and membership already
+ * provisioned.
+ *
+ * Every statement is issued only when the catalogue says it would change
+ * something. They used to run unconditionally, twice per boot (at connect, and
+ * again in the final posture check): a `GRANT … ON ALL TABLES` rewrites every
+ * table's `pg_class` row whether or not the ACL changes, which invalidates
+ * every table's cached plans on every connection, and the internal-table sweep
+ * ran 23 `REVOKE`s per schema. A boot against a database whose grants already
+ * hold now reads one catalogue query and writes nothing; one that is missing
+ * any of them runs exactly the statements it always ran.
+ *
+ * Table owners (the expected non-superuser posture) can always grant on their
+ * own objects, so this needs no extra privilege.
+ */
+export declare function ensureAppRoleGrants(run: RawSqlRunner, schemas: string[]): Promise<void>;
+/**
+ * Rebase's own RLS-off tables in `schema` that a `revokeInternalTableAccess`
+ * sweep would change — the user role holds a privilege on them, or their ACL
+ * has never been written. One read; the sweep it narrows is one `DO` per
+ * table name.
+ */
+export declare function internalTablesGrantedToUserRole(run: RawSqlRunner, schema: string): Promise<string[]>;
 /**
  * Apply the authenticated context to a transaction: the `app.*` GUCs that RLS
  * policies read via `rebase.uid()` / `rebase.roles()` / `rebase.jwt()`, and — when
- * `userRole` is set — `SET LOCAL ROLE` so RLS binds every statement in this
- * transaction (reads *and* writes).
+ * `userRole` is set — the `LOCAL` role switch, in the same statement, so RLS
+ * binds every statement in this transaction (reads *and* writes).
  *
  * GUCs are set with `is_local = true` and the role switch is `LOCAL`: both
  * reset at commit/rollback, so pooled connections are never polluted.

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;
     /**
@@ -646,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";
@@ -34,6 +34,52 @@ export declare function joinStepCondition(currentTable: PgTable, joinTable: PgTa
 } | {
     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.
@@ -119,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.
      *
@@ -242,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,12 +1,13 @@
 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 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
@@ -18,10 +19,20 @@ export interface CdcChangeEvent {
     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.
  *
@@ -38,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.
      *