@rebasepro/server-postgres 0.22.0 → 0.24.0

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

@@ -115,6 +115,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.
  *

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.
      *

package/dist/services/FetchService.d.ts

@@ -141,6 +141,11 @@ export declare class FetchService {
      * rows in arbitrary order, and paging over that repeats and skips rows.
      */
     static readonly SCORE_FIELD = "_score";
+    /**
+     * The distance a vector search attaches to every row it serves, and to no
+     * other. Like `_score` it is computed per query and stored nowhere.
+     */
+    static readonly DISTANCE_FIELD = "_distance";
     private resolveOrderTarget;
     /**
      * The aggregate a sort key names, as an expression, or `undefined` if the
@@ -181,15 +186,17 @@ export declare class FetchService {
      */
     private static nullsLast;
     /**
-     * The full `ORDER BY`: the caller's keys, then the id.
+     * The full `ORDER BY`: the caller's keys, then the primary key.
      *
-     * The id is always last and always descending. It is not decoration — it is
-     * what makes the ordering *total*, and a cursor over a non-total order
-     * repeats and skips rows among the ties. Every keyset comparison built by
-     * {@link buildCursorConditions} ends on the same `id DESC`, and the two have
-     * to agree: they did not, and an ascending sort paged with `id >` against an
-     * `ORDER BY … , id DESC`, so rows sharing a sort value were dropped from
-     * every page after the first.
+     * The key is always last and always descending, every column of it. It is
+     * not decoration — it is what makes the ordering *total*, and a cursor over
+     * a non-total order repeats and skips rows among the ties. Every keyset
+     * comparison built by {@link buildCursorConditions} ends on the same key
+     * `DESC`, and the two have to agree: they did not, and an ascending sort
+     * paged with `id >` against an `ORDER BY … , id DESC`, so rows sharing a
+     * sort value were dropped from every page after the first. Nor is the
+     * first column of a composite key enough: it ties every row that shares
+     * it, which is exactly the rows a cursor then skipped.
      *
      * Where the NULLs go is written out rather than inherited. Postgres already
      * defaults to `NULLS LAST` ascending and `NULLS FIRST` descending, so this
@@ -202,22 +209,6 @@ export declare class FetchService {
      */
     private buildOrderExpressions;
     private resolveOrderByField;
-    /**
-     * Build the `with` config for Drizzle's relational query API.
-     * Converts collection relations to a Drizzle-compatible `with` object.
-     *
-     * When `include` is provided, only those relations are loaded.
-     * When `include` is absent, ALL relations are loaded (the admin path).
-     *
-     * Automatically detects many-to-many junction tables and nests
-     * the target relation so actual row data is returned.
-     */
-    private buildWithConfig;
-    /**
-     * Get the Drizzle relation name on the junction table that points to the actual target row.
-     * For example, for posts_tags junction, this returns "tag_id" (the relation pointing to tags).
-     */
-    private getJunctionTargetRelationName;
     /**
      * The relations one level of an include tree names, resolved.
      *
@@ -303,22 +294,73 @@ export declare class FetchService {
      */
     cursorFor(collectionPath: string, row: Record<string, unknown>, orderBy?: OrderByTuple[]): string | undefined;
     /**
-     * Post-fetch joinPath relations for a single flat row.
-     * joinPath relations cannot be expressed via Drizzle's `with` config,
-     * so they must be loaded separately after the primary query.
+     * Every relation of one row, as the refs the admin renders, attached in
+     * place.
+     *
+     * Loaded by the batched loaders an `include` takes, so a target reached from
+     * this row is read as the caller may see it: its `beforeQuery` scope and its
+     * soft delete applied, its unreadable fields stripped. Populated through
+     * drizzle's relational `with`, the single get knew neither, and a
+     * tenant-scoped user fetching an owner was handed another tenant's docs —
+     * and the trashed ones — under a relation `?include=` answered correctly.
+     *
+     * A to-many relation that reaches nothing is `[]`; a to-one is left off. A
+     * relation that fails for a reason other than the database is logged and
+     * left off, as on the include path, rather than failing the whole row.
      */
-    private resolveJoinPathRelations;
+    private loadRelationRefs;
     /**
      * 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. */
+    private static keyColumns;
+    /**
+     * The cursor row's key, one value per key column — or `undefined` for a
+     * cursor that names no row.
+     *
+     * A cursor carries the row's address, which for a composite key is every
+     * part joined (see {@link cursorFor}). One that carries fewer parts than
+     * the key has columns — the first column's value alone, say — cannot say
+     * which row it stopped at, and is refused rather than read as a guess.
+     */
+    private static cursorKey;
+    /**
+     * "Sorts after the cursor row" on the key alone: the key descending, as the
+     * `ORDER BY` ends.
+     *
+     * Every column runs the same direction, so for a composite key the
+     * row-value comparison is exactly the lexicographic order the `ORDER BY`
+     * produces.
+     */
+    private static keyAfter;
+    /**
+     * The cursor row's value for a timestamp key, to the microsecond.
+     *
+     * A cursor is built from the row as served, and a timestamp is served to
+     * the millisecond while Postgres stores it to the microsecond. Seeking past
+     * the served value compares the column against something up to 999µs short
+     * of the cursor row's own, so every row in that sliver lands on the wrong
+     * side of it: paging `createdAt desc` over rows written in one transaction
+     * stopped after the first page, and ascending repeated the cursor row
+     * forever.
+     *
+     * So the exact value is read back from the cursor row by its key — but only
+     * while that row still holds the millisecond the cursor carries. A row
+     * deleted or re-stamped since the page was served falls back to the stored
+     * value, which is where the listing was when the cursor was issued.
+     *
+     * Any other key, and a NULL, is returned as it came.
+     */
+    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
@@ -426,6 +468,8 @@ export declare class FetchService {
         fields?: string[];
         /** `SELECT DISTINCT` over the projection. */
         distinct?: boolean;
+        /** See `FetchCollectionProps.withDeleted`. */
+        withDeleted?: WithDeleted;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Search rows by text
@@ -493,9 +537,35 @@ export declare class FetchService {
         logical?: LogicalCondition;
         searchString?: string;
         limit?: number;
+        /** Groups to skip. Applied only to a grouped aggregate, like `limit`. */
+        offset?: number;
+        /**
+         * Sort for the groups: by a `groupBy` field or an aggregate's alias.
+         * Applied only to a grouped aggregate; see {@link aggregateOrdering}.
+         */
+        orderBy?: OrderByTuple[];
         /** See `FetchCollectionProps.withDeleted`. */
         withDeleted?: WithDeleted;
     }): Promise<Record<string, unknown>[]>;
+    /**
+     * The `ORDER BY` of a grouped aggregate: the caller's keys, then every
+     * group key they did not name.
+     *
+     * A grouped aggregate is paged like a listing — `limit` bounds it, so more
+     * groups than one page holds are reached with `offset` — and a page is only
+     * a page over a total order. With no `ORDER BY` at all, Postgres returns the
+     * groups in whatever order its plan produces them, so "the next fifty" was
+     * not a thing that existed. The group keys identify a group, so ending on
+     * them makes the order total and puts every page boundary in the same place
+     * on every request.
+     *
+     * A key may name a `groupBy` field or an aggregate by its alias
+     * (`count`, `sum_total`), sorted on the aggregate's own expression — a
+     * drizzle selection is not aliased in the SQL, so there is no output name
+     * to refer to. Anything else is a 400: Postgres would refuse it too, but as
+     * a `GROUP BY` error from inside the statement.
+     */
+    private aggregateOrdering;
     /**
      * Check if a field value is unique.
      *

package/dist/services/PersistService.d.ts

@@ -1,9 +1,37 @@
+import { Properties } from "@rebasepro/types";
 import { RelationService } from "./RelationService.js";
-import type { ReadCallContextProvider } from "./read-scope.js";
+import { type ReadCallContextProvider } from "./read-scope.js";
 import { RelationWriteService } from "./RelationWriteService.js";
 import { FetchService } from "./FetchService.js";
 import { DrizzleClient } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
+/**
+ * The top-level properties whose value is stamped once, when the row is
+ * created: `on_create` dates and `user_on_create` identities.
+ *
+ * What they hold is a fact about the row's creation, so a write to a row that
+ * already exists has nothing to say about them — an update, and the
+ * conflict-update of an upsert that met a stored row. Top level only: a stamp
+ * nested inside a `map` is part of that map's value, not a column a write can
+ * leave out.
+ */
+export declare function createStampKeys(properties: Properties | undefined): string[];
+/** How {@link PersistService.save} writes a row that may already be stored. */
+export interface PersistSaveOptions {
+    /** INSERT ... ON CONFLICT DO UPDATE. See `SaveProps.upsert`. */
+    upsert?: boolean;
+    /** The conflict target, instead of the primary key. See `SaveProps.onConflict`. */
+    onConflict?: readonly string[];
+    /**
+     * Keys of `values` that belong to the INSERT alone: what the create
+     * pipeline filled in rather than what the caller wrote — a declared
+     * `defaultValue`, a tenant stamp. When an upsert's INSERT meets a stored
+     * row, those columns keep the value they have. The create-time stamps
+     * (`on_create`, `user_on_create`) are left out of the conflict-update
+     * without being named here.
+     */
+    insertOnlyKeys?: readonly string[];
+}
 /**
  * Service for handling all row write operations.
  * Handles saving, deleting, and updating rows.
@@ -82,6 +110,10 @@ export declare class PersistService {
      * the row already exists — which is what a re-runnable import needs. The
      * conflict is matched on the primary key unless `options.onConflict` names
      * other columns; see {@link SaveProps.onConflict} for why that matters.
+     * When the INSERT meets a stored row, the conflict-update sets what the
+     * caller wrote and nothing the create alone decides — see
+     * {@link PersistSaveOptions.insertOnlyKeys} — and only on a row the caller's
+     * `beforeQuery` scope reaches.
      *
      * `values` may carry field operations (`{ views: { $inc: 1 } }`). They are
      * split out here rather than at the REST boundary because every request
@@ -89,10 +121,14 @@ export declare class PersistService {
      * one method, and a rule applied at one door is a rule the other doors do
      * not have. What they compile to is `field-op-sql.ts`.
      */
-    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
-        upsert?: boolean;
-        onConflict?: readonly string[];
-    }): Promise<Record<string, unknown>>;
+    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: PersistSaveOptions): Promise<Record<string, unknown>>;
+    /**
+     * The caller's `beforeQuery` scope over this table, as one condition: what
+     * a stored row must satisfy for a write that meets it to change it. The
+     * same scope the update gate and the single get apply; `undefined` when the
+     * collection declares no hook.
+     */
+    private writeScope;
     /**
      * Get the RelationService instance for external use
      */

package/dist/services/RelationService.d.ts

@@ -16,6 +16,24 @@ 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;
+};
 /**
  * Service for handling all relation-related operations.
  * Handles fetching, updating, and managing row relations.
@@ -75,6 +93,17 @@ export declare class RelationService {
      * dynamic relation builder all apply it or none of them do.
      */
     private narrowTargetRead;
+    /**
+     * The target rows a caller may see through `relation`: the target's
+     * `beforeQuery` scope and its soft delete, as one condition on the target
+     * table, or `undefined` when neither applies.
+     *
+     * What every loader here narrows a read by, exposed for the membership
+     * writes. A write that diffs a new link set against "what is linked now"
+     * has to diff against what the caller could have read — otherwise saving
+     * back the list they were shown unlinks every row they were not.
+     */
+    visibleTargetCondition(parentCollection: CollectionConfig, relation: ResolvedRelation, parentId?: string | number): Promise<SQL | undefined>;
     /**
      * One target row, as the {@link RelatedRow} everything here returns.
      *

package/dist/services/RelationWriteService.d.ts

@@ -64,6 +64,12 @@ export declare class RelationWriteService {
      * lost update the membership diff exists to avoid.
      */
     updateRelationPivot(tx: DrizzleClient, hop: NestedPathHop, targetId: string | number, pivot: Record<string, unknown>): Promise<void>;
+    /**
+     * The target rows of `relation` this caller can see, for a junction diff —
+     * or `undefined` when that is all of them. See
+     * {@link RelationService.visibleTargetCondition}.
+     */
+    private visibleTargets;
     /** A collection's id, parsed to the type its primary key column holds. */
     private parsedId;
     /** The same, for the membership list a to-many write names. */

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

@@ -1,3 +1,4 @@
+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.
@@ -7,12 +8,13 @@ export interface CdcChangeEvent {
     table: string;
     op: "INSERT" | "UPDATE" | "DELETE";
     /**
-     * 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;
 }
 /**
@@ -31,7 +33,12 @@ export declare function parseCdcPayload(payload: string): CdcChangeEvent | null;
  */
 export declare class CdcListener {
     private readonly listener;
-    constructor(connectionString: string, onEvent: (event: CdcChangeEvent) => void | Promise<void>);
+    /**
+     * @param onReconnect Called when the connection is listening again after a
+     *        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);
     /**
      * Connect and begin listening. Idempotent.
      *
@@ -44,4 +51,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

@@ -27,23 +27,49 @@ export declare const CDC_TRIGGER_FUNCTION = "rebase.rebase_cdc_notify";
 export declare const CDC_TRIGGER_NAME = "rebase_cdc_trigger";
 /**
  * SQL that (re)creates the generic CDC trigger function. Safe to run repeatedly:
- * `CREATE OR REPLACE` updates in place without dropping dependent triggers.
+ * `CREATE OR REPLACE` updates in place without dropping dependent triggers —
+ * which is also how a database instrumented by an older version gets this body
+ * on its next boot, for every table at once, re-attached or not.
  *
- * 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.
+ * The function emits `{ schema, table, op, row }`, and `row` is an **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.
  */
 export declare function buildCdcFunctionSql(): string;
 /**
  * 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.
+ *
+ * `identityColumns` are what the payload names the changed row by — see
+ * {@link buildCdcFunctionSql}. Passed as trigger arguments, so one shared
+ * function serves every table without a catalogue read per row. Empty means
+ * "the primary key".
  */
-export declare function buildCdcTriggerSql(schema: string, table: string): string;
+export declare function buildCdcTriggerSql(schema: string, table: string, identityColumns?: readonly string[]): 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. */
@@ -53,6 +79,18 @@ export interface ProvisionResult {
         reason: string;
     }>;
 }
+/**
+ * Replace an already-installed trigger function with the current body, 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. Returns whether a function was there to replace.
+ */
+export declare function refreshInstalledCdcFunction(run: RawSqlRunner): Promise<boolean>;
 /**
  * Idempotently install the CDC trigger function and per-table triggers.
  *