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

package/dist/search-column-BM-GV6vH.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-column-BM-GV6vH.js","names":[],"sources":["../src/schema/search-column.ts"],"sourcesContent":["/**\n * The one place a collection's `search` block becomes SQL.\n *\n * Four things describe a Postgres table in this codebase — the DDL generator,\n * the Drizzle schema generator, the runtime table builder for BaaS mode, and\n * the boot-time schema ensure — and each of them has, at some point, described\n * a column differently from the others. The `varchar(255)` note in\n * `generate-postgres-ddl-logic` is one such scar: the same property produced a\n * capped column down one path and an uncapped one down the other, and nothing\n * failed until a user hit the cap.\n *\n * So the search column is not implemented four times. It is computed once,\n * here, and every generator renders the same {@link SearchColumnSpec}. There is\n * a test asserting exactly that (`search-column-contract.test.ts`); the point of\n * this module is that the test has something to assert *about*.\n *\n * ## Why the expressions look the way they do\n *\n * A `GENERATED ALWAYS AS … STORED` expression must be strictly IMMUTABLE, and\n * Postgres is stricter here than intuition. Verified against PostgreSQL 18:\n *\n * | expression                              | immutable |\n * |-----------------------------------------|-----------|\n * | `to_tsvector('spanish', col)`           | yes       |\n * | `to_tsvector(col)` (1-arg)              | **no** — depends on `default_text_search_config` |\n * | `array_to_string(col, ' ')`             | **no**    |\n * | `col::text` on `text[]`                 | **no**    |\n * | `to_jsonb(col)`                         | **no**    |\n * | `unaccent(col)`                         | **no** — dictionary lookup is STABLE |\n * | `jsonb_to_tsvector('spanish', j, '[\"string\"]')` | yes |\n * | `setweight(...) || setweight(...)`      | yes       |\n *\n * Three of the four things a real search column needs are therefore unavailable\n * directly, which is why {@link searchHelperFunctions} exists: each wraps a\n * stable built-in in an SQL function declared IMMUTABLE. That declaration is a\n * promise, and it is a true one for these three — array joining, JSON string\n * extraction and accent folding are all deterministic for a given input; the\n * built-ins are marked stable only because they must account for element types\n * and dictionaries in general.\n *\n * The alternative was to skip `unaccent` and text arrays entirely. That is not\n * a real option in an accented language: Postgres stems `auditoría` to\n * `auditor` and `auditoria` to `auditori` — *different lexemes* — so a query\n * typed without accents misses every row that carries them.\n */\nimport {\n    CollectionConfig,\n    Property,\n    StringProperty,\n    ArrayProperty,\n    MapProperty,\n    SearchConfig,\n    SearchField,\n    SearchMode,\n    SearchWeight,\n    isPostgresCollectionConfig,\n    DEFAULT_SEARCH_COLUMN,\n    DEFAULT_SEARCH_MODE,\n    DEFAULT_SEARCH_LANGUAGE,\n    DEFAULT_SEARCH_WEIGHT,\n    DEFAULT_FUZZY_THRESHOLD\n} from \"@rebasepro/types\";\nimport { createHash } from \"node:crypto\";\nimport { getTableName } from \"@rebasepro/common\";\nimport { toSnakeCase, toPostgresIdentifier } from \"@rebasepro/utils\";\n\n/** Schema-qualified so a collection outside `public` still resolves them. */\nconst HELPER_SCHEMA = \"public\";\n\n/**\n * Names of the helper functions. Frozen: they are recorded in the stored\n * generation expression of every search column ever created, so renaming one\n * orphans every table that already has a search column.\n */\nexport const SEARCH_TEXT_FN = `${HELPER_SCHEMA}.rebase_search_text`;\nexport const SEARCH_UNACCENT_FN = `${HELPER_SCHEMA}.rebase_search_unaccent`;\n\n/** How a declared path reaches text, which decides the SQL that extracts it. */\ntype FieldKind = \"text\" | \"text_array\" | \"jsonb\";\n\n/** One resolved field: where it lives, how to read it, what it is worth. */\nexport interface ResolvedSearchField {\n    /** The path exactly as the author wrote it, for error messages. */\n    path: string;\n    /** The physical column the path starts at. */\n    column: string;\n    /** Dotted remainder addressed inside a JSONB column, if any. */\n    jsonPath: string[];\n    kind: FieldKind;\n    weight: SearchWeight;\n    /** The `setweight(to_tsvector(…), 'X')` term this field contributes. */\n    sql: string;\n    /** The plain-text term this field contributes, for the fuzzy column. */\n    textSql: string;\n    /**\n     * The same text with accents folded **unconditionally**, for the substring\n     * half of {@link SearchMode} `\"hybrid\"`.\n     *\n     * Separate from {@link textSql} rather than replacing it, and that\n     * separation is the whole migration story for `mode`. `textSql` feeds the\n     * *stored* generated columns, so changing it changes their generation\n     * expression, which changes the fingerprint, which makes the next boot\n     * refuse (see `searchStampGuards`). This one is only ever interpolated into\n     * a WHERE clause, so a collection can switch to `\"hybrid\"` — and gain\n     * accent folding on the substring half — without rebuilding a column or\n     * taking an ACCESS EXCLUSIVE lock.\n     */\n    foldedTextSql: string;\n}\n\n/** Everything the generators need to render one collection's search column. */\nexport interface SearchColumnSpec {\n    schema: string;\n    table: string;\n    /** The generated `tsvector` column. */\n    column: string;\n    language: string;\n    unaccent: boolean;\n    /**\n     * How the query side matches. Deliberately absent from\n     * {@link SearchColumnSpec.expression} and from every fingerprint: it\n     * describes the WHERE clause, not the column.\n     */\n    mode: SearchMode;\n    fields: ResolvedSearchField[];\n    /** Body of `GENERATED ALWAYS AS ( … ) STORED` for the tsvector column. */\n    expression: string;\n    indexName: string;\n    /** Extensions that must exist before the column can be created. */\n    extensions: string[];\n    fuzzy?: {\n        column: string;\n        expression: string;\n        indexName: string;\n        threshold: number;\n    };\n}\n\n/** Raised when a `search` block names something that cannot be searched. */\nexport class SearchConfigError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = \"SearchConfigError\";\n    }\n}\n\n/** The `search` block of a collection, or undefined when it has none. */\nexport const getSearchConfig = (collection: CollectionConfig): SearchConfig | undefined =>\n    isPostgresCollectionConfig(collection) ? collection.search : undefined;\n\n/**\n * Refuse a `search` block on a collection this engine does not store.\n *\n * The type only permits one on a `PostgresCollectionConfig`, so TypeScript\n * already stops the ordinary case. This catches the rest — a JS config, a cast,\n * a collection whose `engine` was changed after the block was written — because\n * the alternative is the exact failure the block exists to prevent: a developer\n * who declared what to index, saw no error, and got the substring fallback.\n *\n * Called with *every* collection, before the Postgres ones are filtered out.\n */\nexport const assertSearchIsPostgresOnly = (collections: CollectionConfig[]): void => {\n    for (const collection of collections) {\n        if (isPostgresCollectionConfig(collection)) continue;\n        if (!(collection as { search?: unknown }).search) continue;\n        const engine = (collection as { engine?: string }).engine ?? \"non-postgres\";\n        throw new SearchConfigError(\n            `${collection.slug}.search: full-text search is a Postgres feature, and this collection is served by \\`${engine}\\`. ` +\n            \"Remove the block — it would otherwise look configured while `.search()` kept using the default substring match.\"\n        );\n    }\n};\n\nconst columnNameOf = (propName: string, prop?: Property | null): string =>\n    prop && \"columnName\" in prop && typeof prop.columnName === \"string\" ? prop.columnName : toSnakeCase(propName);\n\n/**\n * Classify a property for search purposes.\n *\n * Deliberately narrower than the schema plan's `PgType`: search only cares\n * whether a value reaches text, and the mapping from property to *physical*\n * type is asserted against the plan in the contract test rather than duplicated\n * here.\n *\n * Returns null for anything that is not text-bearing, which the caller turns\n * into a boot error naming the property.\n */\nconst classify = (prop: Property): { kind: FieldKind; reason?: string } | null => {\n    switch (prop.type) {\n        case \"string\": {\n            const sp = prop as StringProperty;\n            if (sp.enum) {\n                return { kind: \"text\", reason: \"enum\" };\n            }\n            if (sp.isId === \"uuid\" || sp.columnType === \"uuid\") {\n                return { kind: \"text\", reason: \"uuid\" };\n            }\n            return { kind: \"text\" };\n        }\n        case \"map\": {\n            const mp = prop as MapProperty;\n            // A `json` column is not `jsonb`, and the cast between them is not\n            // immutable. Declaring `columnType: \"json\"` puts the value out of\n            // reach of a generated column.\n            if (mp.columnType === \"json\") return { kind: \"jsonb\", reason: \"json\" };\n            return { kind: \"jsonb\" };\n        }\n        case \"array\": {\n            const ap = prop as ArrayProperty;\n            let colType = ap.columnType;\n            if (!colType && ap.of && !Array.isArray(ap.of)) {\n                const of = ap.of as Property;\n                if (of.type === \"string\") colType = \"text[]\";\n                else if (of.type === \"number\") colType = of.validation?.integer ? \"integer[]\" : \"numeric[]\";\n                else if (of.type === \"boolean\") colType = \"boolean[]\";\n            }\n            if (colType === \"text[]\") return { kind: \"text_array\" };\n            if (colType === \"json\") return { kind: \"jsonb\", reason: \"json\" };\n            if (colType === \"integer[]\" || colType === \"boolean[]\" || colType === \"numeric[]\") {\n                return { kind: \"text_array\", reason: \"non_text_array\" };\n            }\n            // Everything else lands in JSONB, which the JSON extractor handles.\n            return { kind: \"jsonb\" };\n        }\n        default:\n            return null;\n    }\n};\n\nconst normalize = (inner: string, unaccent: boolean): string =>\n    unaccent ? `${SEARCH_UNACCENT_FN}(${inner})` : inner;\n\n/** SQL reading one field as plain text, before normalization. */\nconst rawTextSql = (field: { column: string; jsonPath: string[]; kind: FieldKind }): string => {\n    const col = `\"${field.column}\"`;\n    if (field.kind === \"text\") return `coalesce(${col}, '')`;\n    if (field.kind === \"text_array\") return `${SEARCH_TEXT_FN}(coalesce(${col}, '{}'::text[]))`;\n    // JSONB, optionally addressed at a path inside the document.\n    const target = field.jsonPath.length === 0\n        ? col\n        : field.jsonPath.length === 1\n            ? `${col} -> ${quote(field.jsonPath[0])}`\n            : `${col} #> ${quote(`{${field.jsonPath.join(\",\")}}`)}`;\n    return `${SEARCH_TEXT_FN}(coalesce(${target}, '{}'::jsonb))`;\n};\n\nconst quote = (v: string): string => `'${v.replace(/'/g, \"''\")}'`;\n\n/**\n * Resolve and validate one declared field path.\n *\n * A path that does not resolve throws. The whole point of an explicit block is\n * that the author knows what is indexed; a silently dropped field would make it\n * a guess again, and the failure — a search that returns nothing for content\n * that is plainly in the row — is invisible from the outside.\n */\nconst resolveField = (\n    entry: string | SearchField,\n    collection: CollectionConfig,\n    cfg: SearchConfig\n): ResolvedSearchField => {\n    const path = typeof entry === \"string\" ? entry : entry.path;\n    const weight = (typeof entry === \"string\" ? undefined : entry.weight) ?? DEFAULT_SEARCH_WEIGHT;\n    const where = `${collection.slug}.search`;\n\n    if (!path || typeof path !== \"string\") {\n        throw new SearchConfigError(`${where}: every entry in \\`fields\\` needs a property path.`);\n    }\n\n    const [head, ...rest] = path.split(\".\");\n    const prop = collection.properties?.[head] as Property | undefined;\n    if (!prop) {\n        const known = Object.keys(collection.properties ?? {}).join(\", \");\n        throw new SearchConfigError(\n            `${where}: \"${path}\" starts at property \"${head}\", which this collection does not declare. Known properties: ${known}.`\n        );\n    }\n\n    const classified = classify(prop);\n    if (!classified) {\n        throw new SearchConfigError(\n            `${where}: \"${path}\" is a \\`${prop.type}\\` property, which holds no text to search. ` +\n            `Searchable kinds are \\`string\\`, \\`string[]\\` and \\`map\\` (or a path inside one).`\n        );\n    }\n    if (classified.reason === \"enum\") {\n        throw new SearchConfigError(\n            `${where}: \"${path}\" is an enum. Enums are a fixed vocabulary — filter on them with \\`where\\` instead, which is exact and uses an index.`\n        );\n    }\n    if (classified.reason === \"uuid\") {\n        throw new SearchConfigError(\n            `${where}: \"${path}\" is a UUID column. Look it up by id rather than searching it.`\n        );\n    }\n    if (classified.reason === \"json\") {\n        throw new SearchConfigError(\n            `${where}: \"${path}\" is a \\`json\\` column, and the cast from \\`json\\` to \\`jsonb\\` is not immutable, so it cannot feed a generated column. Declare the property as \\`jsonb\\` (the default) to search it.`\n        );\n    }\n    if (classified.reason === \"non_text_array\") {\n        throw new SearchConfigError(\n            `${where}: \"${path}\" is an array of numbers or booleans. Only \\`string[]\\` carries text to search.`\n        );\n    }\n\n    if (rest.length > 0 && classified.kind !== \"jsonb\") {\n        throw new SearchConfigError(\n            `${where}: \"${path}\" addresses a path inside \"${head}\", but \"${head}\" is a \\`${prop.type}\\` property, not a \\`map\\`. Only map properties have paths inside them.`\n        );\n    }\n\n    const column = columnNameOf(head, prop);\n    const field = { column, jsonPath: rest, kind: classified.kind };\n    const raw = rawTextSql(field);\n    const textSql = normalize(raw, cfg.unaccent === true);\n    const language = cfg.language ?? DEFAULT_SEARCH_LANGUAGE;\n\n    return {\n        path,\n        column,\n        jsonPath: rest,\n        kind: classified.kind,\n        weight,\n        sql: `setweight(to_tsvector(${quote(language)}, ${textSql}), ${quote(weight)})`,\n        textSql,\n        foldedTextSql: normalize(raw, true)\n    };\n};\n\n/**\n * Build the full spec for a collection, or undefined when it has not opted in.\n *\n * Throws {@link SearchConfigError} on a config that cannot be honoured. Callers\n * at boot surface that as a startup failure — a search block that half-works is\n * worse than one that refuses.\n */\nexport const buildSearchColumnSpec = (collection: CollectionConfig): SearchColumnSpec | undefined => {\n    const cfg = getSearchConfig(collection);\n    if (!cfg) return undefined;\n\n    if (!Array.isArray(cfg.fields) || cfg.fields.length === 0) {\n        throw new SearchConfigError(\n            `${collection.slug}.search: \\`fields\\` is empty. Name the properties to index, or remove the \\`search\\` block to keep the default ILIKE behaviour.`\n        );\n    }\n\n    const table = getTableName(collection);\n    const schema = isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : \"public\";\n    const column = cfg.column ?? DEFAULT_SEARCH_COLUMN;\n\n    if (collection.properties?.[column]) {\n        throw new SearchConfigError(\n            `${collection.slug}.search: the generated column \"${column}\" collides with a declared property of the same name. Set \\`search.column\\` to something else.`\n        );\n    }\n\n    const fields = cfg.fields.map(entry => resolveField(entry, collection, cfg));\n\n    const seen = new Set<string>();\n    for (const f of fields) {\n        if (seen.has(f.path)) {\n            throw new SearchConfigError(`${collection.slug}.search: \"${f.path}\" is listed twice.`);\n        }\n        seen.add(f.path);\n    }\n\n    const mode = cfg.mode ?? DEFAULT_SEARCH_MODE;\n\n    const extensions: string[] = [];\n    // `hybrid` folds accents on its substring half whatever `unaccent` says, so\n    // it needs the dictionary and the helper even on a block that never asked\n    // for folding in the stored column. Both statements are idempotent, which\n    // is what keeps turning the mode on out of the column-rebuild business.\n    if (cfg.unaccent || mode === \"hybrid\") extensions.push(\"unaccent\");\n    if (cfg.fuzzy) extensions.push(\"pg_trgm\");\n\n    const spec: SearchColumnSpec = {\n        schema,\n        table,\n        column,\n        language: cfg.language ?? DEFAULT_SEARCH_LANGUAGE,\n        unaccent: cfg.unaccent === true,\n        mode,\n        fields,\n        expression: fields.map(f => f.sql).join(\" || \"),\n        indexName: toPostgresIdentifier(`${table}_${column}_gin`),\n        extensions\n    };\n\n    if (cfg.fuzzy) {\n        const fuzzyColumn = `${column}_text`;\n        if (collection.properties?.[fuzzyColumn]) {\n            throw new SearchConfigError(\n                `${collection.slug}.search: \\`fuzzy\\` needs the column \"${fuzzyColumn}\", which collides with a declared property. Set \\`search.column\\` to something else.`\n            );\n        }\n        spec.fuzzy = {\n            column: fuzzyColumn,\n            // Concatenated with spaces so a trigram never spans two fields.\n            expression: fields.map(f => f.textSql).join(\" || ' ' || \"),\n            indexName: toPostgresIdentifier(`${table}_${fuzzyColumn}_trgm`),\n            threshold: cfg.fuzzyThreshold ?? DEFAULT_FUZZY_THRESHOLD\n        };\n    }\n\n    return spec;\n};\n\n/**\n * The IMMUTABLE wrappers the generated expressions call.\n *\n * `CREATE OR REPLACE` so a boot against an existing database is a no-op rather\n * than an error, and idempotent for the same reason every other boot-time DDL\n * statement here is.\n *\n * The bodies are stable built-ins wrapped in an immutable promise — see the\n * module comment for why that promise is sound. `STRICT` matters: it makes NULL\n * in mean NULL out without executing the body, which is what the `coalesce` at\n * each call site then absorbs.\n */\nexport const searchHelperFunctions = (spec: SearchColumnSpec): string[] => {\n    const statements: string[] = [\n        // text[] → \" \"-joined text.\n        `CREATE OR REPLACE FUNCTION ${SEARCH_TEXT_FN}(text[]) RETURNS text\\n` +\n        `    LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE AS\\n` +\n        `    $$ SELECT array_to_string($1, ' ') $$;`,\n        // jsonb → every string value at or below the node, space-joined. Keys\n        // are not values: indexing them would make `certifications` itself a\n        // search term on every row that has the field at all.\n        `CREATE OR REPLACE FUNCTION ${SEARCH_TEXT_FN}(jsonb) RETURNS text\\n` +\n        `    LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE AS\\n` +\n        `    $$ SELECT coalesce(string_agg(v, ' '), '')\\n` +\n        `       FROM jsonb_array_elements_text(jsonb_path_query_array($1, 'strict $.**?(@.type() == \"string\")')) AS v $$;`\n    ];\n    if (spec.unaccent || spec.mode === \"hybrid\") {\n        // The two-argument form with an explicit dictionary is the one that can\n        // honestly be called immutable: the single-argument form resolves the\n        // dictionary through the current search_path at call time.\n        statements.push(\n            `CREATE OR REPLACE FUNCTION ${SEARCH_UNACCENT_FN}(text) RETURNS text\\n` +\n            `    LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE AS\\n` +\n            `    $$ SELECT ${HELPER_SCHEMA}.unaccent('${HELPER_SCHEMA}.unaccent'::regdictionary, $1) $$;`\n        );\n    }\n    return statements;\n};\n\n/**\n * `CREATE EXTENSION` statements the spec's expressions depend on.\n *\n * `WITH SCHEMA public` is load-bearing, not tidiness. An unqualified\n * `CREATE EXTENSION` installs into the first schema on `search_path`, which\n * defaults to `\"$user\", public` — and the scaffold's database role is named\n * `rebase`, the same as the schema the generator creates one statement earlier.\n * So the moment that schema exists, `CREATE EXTENSION unaccent` puts the\n * dictionary in `rebase`, and every reference to `public.unaccent` below fails\n * with \"text search dictionary does not exist\". Observed, not theorised.\n */\nexport const searchExtensionStatements = (spec: SearchColumnSpec): string[] =>\n    spec.extensions.map(e => `CREATE EXTENSION IF NOT EXISTS ${e} WITH SCHEMA ${HELPER_SCHEMA};`);\n\n/**\n * Everything after the column name — the type and the generation expression.\n *\n * Split out because four emitters need it and only two of them have a place to\n * put the name: `CREATE TABLE` and `ADD COLUMN` write `\"col\" <this>`, while the\n * schema plan carries it as the column's SQL definition and the boot-time\n * rebuild statement interpolates it on its own.\n */\nexport const searchColumnTypeSql = (expression: string, kind: \"tsvector\" | \"text\"): string =>\n    `${kind} GENERATED ALWAYS AS (${expression}) STORED`;\n\n/** The column definition as it appears inside `CREATE TABLE`. */\nexport const searchColumnDefinition = (spec: SearchColumnSpec): string =>\n    `\"${spec.column}\" ${searchColumnTypeSql(spec.expression, \"tsvector\")}`;\n\n/** The fuzzy column definition, when the spec asks for one. */\nexport const fuzzyColumnDefinition = (spec: SearchColumnSpec): string | undefined =>\n    spec.fuzzy ? `\"${spec.fuzzy.column}\" ${searchColumnTypeSql(spec.fuzzy.expression, \"text\")}` : undefined;\n\n/**\n * Index statements for the spec.\n *\n * `CONCURRENTLY` is deliberately *not* used here. This form is emitted into a\n * SQL file replayed as one unit — a migration, or `search.sql` — where a\n * concurrent build is not allowed. The boot-time ensure path runs statement by\n * statement against tables that are live and populated, and uses the\n * concurrent form instead; see `ensureSearchColumns`.\n */\nexport const searchIndexStatements = (spec: SearchColumnSpec): string[] => {\n    const statements = [\n        `CREATE INDEX IF NOT EXISTS \"${spec.indexName}\" ON \"${spec.schema}\".\"${spec.table}\" USING GIN (\"${spec.column}\");`\n    ];\n    if (spec.fuzzy) {\n        statements.push(\n            // The operator class is resolved through `search_path` like any\n            // other object, so it is qualified for the same reason the\n            // extension is installed explicitly.\n            `CREATE INDEX IF NOT EXISTS \"${spec.fuzzy.indexName}\" ON \"${spec.schema}\".\"${spec.table}\" USING GIN (\"${spec.fuzzy.column}\" ${HELPER_SCHEMA}.gin_trgm_ops);`\n        );\n    }\n    return statements;\n};\n\n// ── Telling a changed `search` block from an unchanged one ──────────────────\n\n/**\n * Marker on the comment of every generated search column this module creates.\n *\n * Versioned because the fingerprint below is only comparable against itself: a\n * future change to how it is computed has to read as \"not stamped by this\n * version\" rather than as drift on every existing column.\n */\nexport const SEARCH_STAMP_PREFIX = \"rebase:search:v1:\";\n\n/**\n * A stable fingerprint of one generated column's expression.\n *\n * Why a stamp rather than reading the expression back: Postgres stores a\n * generated column's expression *parsed*, and hands it back deparsed — casts\n * made explicit, identifiers requoted, schema qualifications added or dropped\n * according to `search_path`. Comparing that text to the text we generated\n * would report drift on wording, and this comparison decides whether a boot\n * refuses, so a false positive is an outage. The stamp is written by the same\n * code that writes the column, so equality means what it says.\n */\nexport const searchExpressionFingerprint = (expression: string): string =>\n    `${SEARCH_STAMP_PREFIX}${createHash(\"sha256\").update(expression).digest(\"hex\").slice(0, 16)}`;\n\n/** One generated column, with the fingerprint that identifies its expression. */\nexport interface SearchColumnStamp {\n    column: string;\n    /** The expression the column is generated from. */\n    expression: string;\n    fingerprint: string;\n    /** `COMMENT ON COLUMN …`, which is where the fingerprint is recorded. */\n    sql: string;\n}\n\n/**\n * The stamps for a spec's generated columns — one per column, never shared.\n *\n * Per column on purpose: turning `fuzzy` on adds a second column and changes\n * nothing about the first, and a spec-wide fingerprint would report the\n * untouched `tsvector` column as drifted and refuse a boot over a change that\n * is purely additive.\n */\nexport const searchColumnStamps = (spec: SearchColumnSpec): SearchColumnStamp[] => {\n    const stamp = (column: string, expression: string): SearchColumnStamp => {\n        const fingerprint = searchExpressionFingerprint(expression);\n        return {\n            column,\n            expression,\n            fingerprint,\n            sql: `COMMENT ON COLUMN \"${spec.schema}\".\"${spec.table}\".\"${column}\" IS ${quote(fingerprint)};`\n        };\n    };\n    const stamps = [stamp(spec.column, spec.expression)];\n    if (spec.fuzzy) stamps.push(stamp(spec.fuzzy.column, spec.fuzzy.expression));\n    return stamps;\n};\n\n/**\n * The same drift check as the boot ensure, for the SQL file.\n *\n * Needed because {@link searchColumnStamps} would otherwise *launder* drift on\n * the migration path: `ADD COLUMN IF NOT EXISTS` does nothing to a column that\n * exists, so a re-generated `search.sql` would stamp a stale column with the\n * new block's fingerprint and the next boot would find them in agreement.\n * Guarding first means the file refuses instead — `rebase db push` is attended,\n * and the operator reading the failure is the person who changed the block.\n */\nexport const searchStampGuards = (spec: SearchColumnSpec): string[] =>\n    searchColumnStamps(spec).map(stamp => {\n        const relation = quote(`\"${spec.schema}\".\"${spec.table}\"`);\n        return `DO $rebase_search$\nDECLARE recorded text;\nBEGIN\n    SELECT col_description(a.attrelid, a.attnum) INTO recorded\n    FROM pg_attribute a\n    WHERE a.attrelid = ${relation}::regclass AND a.attname = ${quote(stamp.column)} AND NOT a.attisdropped;\n    IF recorded LIKE ${quote(`${SEARCH_STAMP_PREFIX}%`)} AND recorded <> ${quote(stamp.fingerprint)} THEN\n        RAISE EXCEPTION 'Rebase: the search block for ${spec.schema}.${spec.table} changed after the generated column \"${stamp.column}\" was built (recorded %, expected ${stamp.fingerprint}). Postgres cannot alter a generated expression in place. Drop the column and re-apply this file — it rewrites the table and rebuilds the index: ALTER TABLE ${relation.slice(1, -1)} DROP COLUMN \"${stamp.column}\";', recorded;\n    END IF;\nEND\n$rebase_search$;`;\n    });\n\n/**\n * The index names the spec creates.\n *\n * Needed by name, not just by statement, so Atlas can be told to exclude them\n * from its diff — see `searchExcludePatterns`.\n */\nexport const searchIndexNames = (spec: SearchColumnSpec): string[] =>\n    spec.fuzzy ? [spec.indexName, spec.fuzzy.indexName] : [spec.indexName];\n\n// ── Keeping the generated columns out of responses ──────────────────────────\n\n/**\n * The generated column names a collection's search block adds, if any.\n *\n * These are physical columns on the table, so `SELECT *` returns them. They are\n * an index in column form — a list of lexeme positions, or a concatenation of\n * every searchable field on the row — and nothing outside the query planner has\n * any use for them. Left in, every list response carries a second, larger copy\n * of the row's text.\n */\nexport const searchColumnNames = (collection: CollectionConfig): string[] => {\n    let spec: SearchColumnSpec | undefined;\n    try {\n        spec = buildSearchColumnSpec(collection);\n    } catch {\n        // A malformed block is reported at boot, loudly. A read is the wrong\n        // place to raise it a second time, and returning the row without the\n        // exclusion would be worse than returning it with.\n        return [];\n    }\n    if (!spec) return [];\n    return spec.fuzzy ? [spec.column, spec.fuzzy.column] : [spec.column];\n};\n\n/**\n * True for a column whose type only ever holds a search index.\n *\n * Independent of any collection config on purpose: an introspected database\n * (BaaS mode) can carry a `tsvector` column this framework never created —\n * Pagila's `film.fulltext` is the canonical one — and it should not be returned\n * to callers either. `isDerivedIndexColumn` already keeps such a column out of\n * the *properties*; this keeps it out of the *rows*.\n */\nexport const isSearchIndexColumn = (column: { getSQLType?: () => string }): boolean => {\n    const sqlType = typeof column?.getSQLType === \"function\" ? column.getSQLType().toLowerCase() : \"\";\n    return sqlType === \"tsvector\" || sqlType === \"tsquery\";\n};\n\n/**\n * A drizzle select projection over `table` with the search columns dropped.\n *\n * Returns undefined when nothing needs dropping, so the common case keeps using\n * a plain `select()` and this stays invisible in the generated SQL.\n */\nexport const visibleColumnProjection = (\n    tableColumns: Record<string, { getSQLType?: () => string }> | undefined,\n    collection?: CollectionConfig\n): Record<string, unknown> | undefined => {\n    const excluded = excludedColumnNames(tableColumns, collection);\n    if (!tableColumns || excluded.length === 0) return undefined;\n    const projection: Record<string, unknown> = {};\n    for (const [name, column] of Object.entries(tableColumns)) {\n        if (!excluded.includes(name)) projection[name] = column;\n    }\n    return projection;\n};\n\n/** The same exclusion as a drizzle `db.query` `columns` denylist. */\nexport const hiddenColumnsOption = (\n    tableColumns: Record<string, { getSQLType?: () => string }> | undefined,\n    collection?: CollectionConfig\n): Record<string, false> | undefined => {\n    const excluded = excludedColumnNames(tableColumns, collection);\n    if (excluded.length === 0) return undefined;\n    return Object.fromEntries(excluded.map(name => [name, false as const]));\n};\n\n/**\n * The columns to keep out of a response, by name.\n *\n * `tableColumns` is whatever `getTableColumns` returned, which is `undefined`\n * for anything that is not a real drizzle table — a stub in a test, a derived\n * or nested path with no table behind it. Nothing to exclude is the right\n * answer there, and it has to be an answer rather than a throw: this runs on\n * the read path of every collection, opted in or not.\n */\nconst excludedColumnNames = (\n    tableColumns: Record<string, { getSQLType?: () => string }> | undefined,\n    collection?: CollectionConfig\n): string[] => {\n    if (!tableColumns || typeof tableColumns !== \"object\") return [];\n    const byName = new Set(collection ? searchColumnNames(collection) : []);\n    return Object.keys(tableColumns).filter(\n        name => byName.has(name) || isSearchIndexColumn(tableColumns[name])\n    );\n};\n"],"mappings":"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"}

package/dist/security/policy-drift.d.ts

@@ -10,7 +10,7 @@
  * table is indistinguishable from a table with no data.
  *
  * Expected policies are parsed from `generatePostgresPoliciesDdl`, the same
- * function `db push` uses to write `drizzle/policies.sql`, so this compares
+ * function `db push` uses to write `.rebase/sql/policies.sql`, so this compares
  * against exactly what would be applied rather than a reimplementation.
  */
 import { type CollectionConfig } from "@rebasepro/types";

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,
@@ -115,6 +116,13 @@ export interface AuthContext {
      */
     claims?: Record<string, unknown>;
 }
+/**
+ * Take every privilege the user role holds on one table back — what a table
+ * gets when RLS cannot be switched on for it, so it is unreachable rather than
+ * unprotected. Quoted exactly: a mixed-case adopted table (`"User"`) folded to
+ * lower case names a table that does not exist.
+ */
+export declare const revokeUserRoleSql: (schema: string, table: string) => string;
 /**
  * Warn when the connection role shares its name with an existing schema.
  *
@@ -196,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/BranchService.d.ts

@@ -23,10 +23,31 @@ export declare class BranchingUnsupportedError extends Error {
     readonly code = "BRANCHING_UNSUPPORTED";
     constructor(message: string);
 }
+/**
+ * Where a server's branches are kept: the main database — what a branch is
+ * copied from unless told otherwise, and what may never be dropped — and the
+ * connection whose `rebase.branches` records them.
+ */
+export interface BranchHome {
+    /** The main database's name. */
+    database(): Promise<string>;
+    /**
+     * A connection on the database the registry is in. Asked for at each use:
+     * a pool to the main database is closed before it is copied.
+     */
+    registry(): Promise<DrizzleClient>;
+}
 export declare class BranchService {
     private db;
     private poolManager;
-    constructor(db: DrizzleClient, poolManager: DatabasePoolManager);
+    private readonly home;
+    /**
+     * @param db    A connection on the server the branches are made on. Branch
+     *              DDL runs here.
+     * @param home  Where branches are kept. Without one, the database the
+     *              pool manager's connection string names, and `db`'s registry.
+     */
+    constructor(db: DrizzleClient, poolManager: DatabasePoolManager, home?: BranchHome);
     /**
      * Refuse a branch mutation the connected server cannot honour.
      *
@@ -40,6 +61,13 @@ export declare class BranchService {
      * pane into a failure with a "Try again" that can never succeed.
      */
     private assertBranchingSupported;
+    /**
+     * Whether the `rebase.branches` registry exists. A database that has never
+     * had a branch made on it may not have it, and reading it there is an
+     * empty answer, not an error — nor a reason to create it. The CLI's `list`
+     * and `info` ask this rather than running the DDL that creates it.
+     */
+    hasBranchRegistry(): Promise<boolean>;
     /**
      * Ensure the `rebase.branches` metadata table exists in the default database.
      * Idempotent — safe to call on every startup.

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[];