@rebasepro/server-postgres 0.16.1-canary.ge71347e → 0.17.0

package/src/schema/collection-index.ts

@@ -0,0 +1,427 @@
+/**
+ * The one place a collection's `indexes:` block becomes `CREATE INDEX`.
+ *
+ * Like `search-column.ts` and `vector-index.ts`, this module exists so the DDL
+ * generator and the boot-time ensure render the *same* specification rather
+ * than describing the same index twice, differently.
+ *
+ * ## Why every form here is core Postgres
+ *
+ * `rebase db push` runs `atlas schema apply`, which materialises the desired
+ * state in a bare scratch database to plan against. `--exclude` does not
+ * suppress that replay, and `CREATE EXTENSION` cannot go in the file. So an
+ * index wanting `gin_trgm_ops` or `vector_cosine_ops` would parse, plan, and
+ * then fail against a database the author has never heard of. Those are
+ * refused here instead, and redirected to the feature that owns them: trigram
+ * search is `search:`, ANN is a `vector` property.
+ *
+ * Verified against atlas v1.2.3 and Postgres 18 before this was written: plain,
+ * composite with `DESC NULLS LAST`, partial, unique, covering `INCLUDE`, `GIN`
+ * and expression indexes all parse, apply, and re-plan clean. The Atlas
+ * limitation that forced the search carve-out is that it will not parse a file
+ * containing a function *definition* — a function *call* inside an index is
+ * fine. That is why this module needs no carve-out and search did.
+ *
+ * ## Why the name carries a hash
+ *
+ * `CREATE INDEX IF NOT EXISTS` is a **name** check, not a definition check. A
+ * readable name means a changed declaration keeps the old index and reports
+ * success, forever. Hashing the index's *semantics* into its name makes a
+ * redefinition a different object: the new one is built before the old one is
+ * dropped, there is never a window with no index, and drift detection reduces
+ * to a set difference over names.
+ */
+import type { CollectionConfig, CollectionIndex, IndexPredicate, Property, ResolvedRelation } from "@rebasepro/types";
+import { isPostgresCollectionConfig } from "@rebasepro/types";
+import { getTableName, resolveCollectionRelations } from "@rebasepro/common";
+import { sha1Hex, truncateToBytes } from "@rebasepro/utils";
+
+/** Resolve a property key to its column name. Injected to avoid an import cycle. */
+export type ResolveColumnName = (propName: string, prop?: Property | null) => string;
+
+export type IndexMethod = "btree" | "gin" | "brin";
+
+/** A key column, with the ordering Postgres will actually apply. */
+export interface ResolvedIndexKey {
+    column: string;
+    /** Always concrete. `btree` defaults ascending; unordered methods report `asc`. */
+    direction: "asc" | "desc";
+    /** Postgres's own default: `last` under `asc`, `first` under `desc`. */
+    nulls: "first" | "last";
+}
+
+/** A predicate resolved onto column names, ready to render and to hash. */
+export type ResolvedPredicate =
+    | { column: string; op: "=" | "!=" | "<" | "<=" | ">" | ">="; value: string | number | boolean }
+    | { column: string; op: "is null" | "is not null" }
+    | { column: string; op: "in"; value: readonly (string | number)[] }
+    | { and: readonly ResolvedPredicate[] };
+
+/** One index, fully resolved. The only shape the renderers accept. */
+export interface CollectionIndexSpec {
+    schema: string;
+    table: string;
+    method: IndexMethod;
+    unique: boolean;
+    keys: ResolvedIndexKey[];
+    include: string[];
+    predicate: ResolvedPredicate | null;
+    /** The author's one-line justification. Never enters the name. */
+    reason: string;
+    /** Derived by {@link deriveIndexName}. Frozen — see the module comment. */
+    indexName: string;
+}
+
+/**
+ * A declaration that cannot become an index.
+ *
+ * Thrown at build time, naming the collection and the array position, because
+ * the alternative is a `CREATE INDEX` that fails during a push with a Postgres
+ * error mentioning a column the author never wrote.
+ */
+export class CollectionIndexConfigError extends Error {
+    readonly collectionSlug: string;
+    readonly position: number;
+
+    constructor(collectionSlug: string, position: number, message: string) {
+        super(`${collectionSlug}.indexes[${position}]: ${message}`);
+        this.name = "CollectionIndexConfigError";
+        this.collectionSlug = collectionSlug;
+        this.position = position;
+    }
+}
+
+/** Postgres allows 32 key columns. See the doc comment on `on`. */
+export const MAX_INDEX_KEYS = 5;
+
+/**
+ * `_ix`/`_ux` plus `_` plus 7 hex — the part of the name that must always
+ * survive truncation, and therefore is never inside the truncated portion.
+ */
+const NAME_SUFFIX_BYTES = 11;
+
+/**
+ * Every Rebase-managed index name, and nothing else.
+ *
+ * The terminal `_ix_`/`_ux_` plus exactly seven lowercase hex characters is
+ * what separates this scheme from every other producer in the codebase —
+ * `_fkey`, `_gin`, `_trgm`, `_pkey`, `_key`, the vector distances, and the
+ * `idx_` prefix auth uses. `_idx` was rejected as a tail because it is already
+ * taken for real: `users_email_verification_token_idx` is byte-for-byte what a
+ * naive `<table>_<column>_idx` derives on an auth-enabled `users` collection.
+ *
+ * Load-bearing for safety, not just tidiness. An index that does NOT match this
+ * belongs to somebody else — a hand-written one, or one an introspected
+ * database arrived with — and is excluded from the Atlas diff so the push
+ * cannot drop it.
+ */
+export const isRebaseIndexName = (name: string): boolean => /_(?:ix|ux)_[0-9a-f]{7}$/.test(name);
+
+const isOrderedMethod = (method: IndexMethod): boolean => method === "btree";
+
+/**
+ * The parts of an index that decide what it *is*.
+ *
+ * A semantic projection, not the rendered statement — the same arrangement as
+ * `getPolicyNameHash`, and for the same reason. A change to how this file
+ * formats SQL (eliding a default `USING btree`, quoting differently, emitting
+ * `NULLS LAST` explicitly) must not silently rename every index in every
+ * deployed database. Hashing generator output would make every cosmetic edit a
+ * fleet-wide DROP + CREATE.
+ *
+ * `reason` is deliberately absent: rewording a comment must not rebuild an
+ * index. `nulls` is the *effective* placement, so writing Postgres's own
+ * default down is a no-op rather than a redefinition.
+ *
+ * `v` is the only escape hatch, and it is expensive on purpose: bumping it
+ * renames every index in the field.
+ */
+export const indexFingerprint = (spec: Omit<CollectionIndexSpec, "indexName">): string => sha1Hex(JSON.stringify({
+    v: 1,
+    s: spec.schema,
+    t: spec.table,
+    m: spec.method,
+    u: spec.unique,
+    k: spec.keys.map(k => [k.column, k.direction, k.nulls]),
+    i: spec.include,
+    w: spec.predicate
+})).substring(0, 7);
+
+/**
+ * `<table>_<columns>_ix_<hash>`, or `_ux_` when unique.
+ *
+ * Truncation eats the readable head and never the hash. `toPostgresIdentifier`
+ * truncates the whole string at 63 bytes, which on a hashed name would cut off
+ * the one part that makes it unique — the failure already frozen into
+ * `contracts/derived-names.txt`, where a foreign key is recorded with its
+ * `_fkey` suffix truncated away, so a second foreign key on that table would
+ * derive a byte-identical name.
+ */
+export const deriveIndexName = (spec: Omit<CollectionIndexSpec, "indexName">): string => {
+    // Built suffix-first, so the two parts that carry meaning — the `_ix`/`_ux`
+    // tag that {@link isRebaseIndexName} matches on, and the fingerprint — are
+    // never in the string being truncated. Composing the whole name and then
+    // trimming it to 63 loses both, silently: an 80-byte table name yields
+    // `xxxx…xxx_610bb9e` with the tag gone, so the index stops being
+    // recognisable as Rebase's and `db push` treats it as foreign forever.
+    const tag = spec.unique ? "ux" : "ix";
+    const suffix = `_${tag}_${indexFingerprint(spec)}`;
+    const readable = `${spec.table}_${spec.keys.map(k => k.column).join("_")}`;
+    return `${truncateToBytes(readable, 63 - NAME_SUFFIX_BYTES)}${suffix}`;
+};
+
+const quoteLiteral = (value: string | number | boolean): string => {
+    if (typeof value === "number") return String(value);
+    if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+    return `'${value.replace(/'/g, "''")}'`;
+};
+
+/** Render a resolved predicate as the body of a `WHERE` clause. */
+export const renderPredicate = (predicate: ResolvedPredicate): string => {
+    if ("and" in predicate) {
+        // Always parenthesised. Postgres would apply the same precedence
+        // without it, but the rendered SQL is read by people diffing a plan.
+        return predicate.and.map(renderPredicate).join(" AND ");
+    }
+    switch (predicate.op) {
+        case "is null":
+        case "is not null":
+            return `"${predicate.column}" ${predicate.op.toUpperCase()}`;
+        case "in":
+            return `"${predicate.column}" IN (${predicate.value.map(quoteLiteral).join(", ")})`;
+        default:
+            return `"${predicate.column}" ${predicate.op} ${quoteLiteral(predicate.value)}`;
+    }
+};
+
+/**
+ * The `CREATE INDEX` for one spec.
+ *
+ * `concurrently` is a parameter rather than a string replacement on the way
+ * out. `search-column.ts` and `vector-index.ts` both reach for
+ * `.replace("CREATE INDEX IF NOT EXISTS", …)` instead, which silently does
+ * nothing for a UNIQUE index — the rendered text is `CREATE UNIQUE INDEX …`
+ * and the pattern never matches.
+ */
+export const collectionIndexStatement = (
+    spec: CollectionIndexSpec,
+    options: { concurrently?: boolean; ifNotExists?: boolean } = {}
+): string => {
+    const unique = spec.unique ? "UNIQUE " : "";
+    const concurrently = options.concurrently ? "CONCURRENTLY " : "";
+    const ifNotExists = options.ifNotExists ? "IF NOT EXISTS " : "";
+    const using = spec.method === "btree" ? "" : ` USING ${spec.method}`;
+
+    const keys = spec.keys.map(k => {
+        if (!isOrderedMethod(spec.method)) return `"${k.column}"`;
+        const direction = k.direction === "desc" ? " DESC" : "";
+        // Emitted only when it is not what the direction already implies, so
+        // the rendered SQL matches what `pg_get_indexdef` reads back and a
+        // re-plan finds no difference.
+        const impliedNulls = k.direction === "desc" ? "first" : "last";
+        const nulls = k.nulls === impliedNulls ? "" : ` NULLS ${k.nulls.toUpperCase()}`;
+        return `"${k.column}"${direction}${nulls}`;
+    }).join(", ");
+
+    const include = spec.include.length > 0
+        ? ` INCLUDE (${spec.include.map(c => `"${c}"`).join(", ")})`
+        : "";
+    const where = spec.predicate ? ` WHERE ${renderPredicate(spec.predicate)}` : "";
+
+    return `CREATE ${unique}INDEX ${concurrently}${ifNotExists}"${spec.indexName}" ` +
+        `ON "${spec.schema}"."${spec.table}"${using} (${keys})${include}${where};`;
+};
+
+export const collectionIndexStatements = (
+    specs: readonly CollectionIndexSpec[],
+    options: { concurrently?: boolean; ifNotExists?: boolean } = {}
+): string[] => specs.map(spec => collectionIndexStatement(spec, options));
+
+const relationOf = (
+    collection: CollectionConfig,
+    propKey: string
+): ResolvedRelation | undefined => resolveCollectionRelations(collection)[propKey];
+
+/**
+ * The column a property key indexes.
+ *
+ * A `belongsTo` resolves to its `localKey` — `primaryCategory` becomes
+ * `primary_category_id` — which is the case an index is most often wanted for
+ * and the case where the property key and the column differ. Everything else
+ * goes through `resolveColumnName`.
+ *
+ * The other relation kinds have no local column at all: the foreign key lives
+ * on the target's table, or in a junction. Indexing them here is refused
+ * rather than resolved to a column that does not exist.
+ */
+export const resolveIndexableColumn = (
+    collection: CollectionConfig,
+    propKey: string,
+    resolveColumnName: ResolveColumnName,
+    fail: (message: string) => never
+): string => {
+    const relation = relationOf(collection, propKey);
+    if (relation) {
+        if (relation.kind === "belongsTo") return relation.localKey;
+        fail(
+            `"${propKey}" is a ${relation.kind} relation, which has no column on this table — ` +
+            `the foreign key lives on "${relation.targetSlug}". Declare the index there.`
+        );
+    }
+
+    const property = collection.properties?.[propKey] as Property | undefined;
+    if (!property) {
+        fail(`"${propKey}" is not a property of this collection.`);
+    }
+    return resolveColumnName(propKey, property);
+};
+
+const resolvePredicate = (
+    collection: CollectionConfig,
+    predicate: IndexPredicate,
+    resolveColumnName: ResolveColumnName,
+    fail: (message: string) => never
+): ResolvedPredicate => {
+    if ("and" in predicate) {
+        return { and: predicate.and.map(p => resolvePredicate(collection, p, resolveColumnName, fail)) };
+    }
+    const column = resolveIndexableColumn(collection, predicate.prop, resolveColumnName, fail);
+    switch (predicate.op) {
+        case "is null":
+        case "is not null":
+            return { column, op: predicate.op };
+        case "in": {
+            const seen = new Set(predicate.value);
+            if (seen.size !== predicate.value.length) {
+                fail(`the \`in\` list for "${predicate.prop}" repeats a value, which changes nothing.`);
+            }
+            return { column, op: "in", value: [...predicate.value] };
+        }
+        default:
+            return { column, op: predicate.op, value: predicate.value };
+    }
+};
+
+/** The primary key columns of a collection, for the "you already have this" refusal. */
+const primaryKeyColumns = (collection: CollectionConfig, resolveColumnName: ResolveColumnName): string[] =>
+    Object.entries(collection.properties ?? {})
+        .filter(([, prop]) => prop && typeof prop === "object" && "isId" in prop && Boolean((prop as { isId?: unknown }).isId))
+        .map(([key, prop]) => resolveColumnName(key, prop as Property));
+
+/**
+ * Every index one collection declares, resolved and named.
+ *
+ * Throws {@link CollectionIndexConfigError} rather than dropping a bad entry:
+ * an index that silently does not exist is the failure mode this whole feature
+ * is here to remove.
+ */
+export const buildCollectionIndexSpecs = (
+    collection: CollectionConfig,
+    resolveColumnName: ResolveColumnName
+): CollectionIndexSpec[] => {
+    if (!isPostgresCollectionConfig(collection)) return [];
+    const declared = collection.indexes;
+    if (!declared || declared.length === 0) return [];
+
+    const slug = collection.slug ?? getTableName(collection);
+    const schema = collection.schema ?? "public";
+    const table = getTableName(collection);
+    const pk = primaryKeyColumns(collection, resolveColumnName).sort().join(",");
+
+    const specs: CollectionIndexSpec[] = [];
+    const byName = new Map<string, number>();
+
+    declared.forEach((index: CollectionIndex, position: number) => {
+        const fail = (message: string): never => {
+            throw new CollectionIndexConfigError(slug, position, message);
+        };
+
+        if (typeof index.reason !== "string" || index.reason.trim() === "") {
+            fail("`reason` is required — see the doc comment. An index nobody can justify is one nobody can delete.");
+        }
+        if (!Array.isArray(index.on) || index.on.length === 0) {
+            fail("`on` must name at least one property.");
+        }
+        if (index.on.length > MAX_INDEX_KEYS) {
+            fail(`\`on\` has ${index.on.length} keys; the limit is ${MAX_INDEX_KEYS}. Payload columns belong in \`include\`.`);
+        }
+
+        const method: IndexMethod = index.using ?? "btree";
+        const unique = method === "btree" && Boolean((index as { unique?: boolean }).unique);
+        if (!isOrderedMethod(method)) {
+            for (const key of index.on) {
+                if (typeof key !== "string" && ("direction" in key || "nulls" in key)) {
+                    fail(`access method "${method}" does not support ASC/DESC or NULLS options.`);
+                }
+            }
+        }
+
+        const keys: ResolvedIndexKey[] = index.on.map(key => {
+            const propKey = typeof key === "string" ? key : key.prop;
+            const column = resolveIndexableColumn(collection, propKey, resolveColumnName, fail);
+            const direction = (typeof key === "string" ? undefined : (key as { direction?: "asc" | "desc" }).direction) ?? "asc";
+            const nulls = (typeof key === "string" ? undefined : (key as { nulls?: "first" | "last" }).nulls)
+                ?? (direction === "desc" ? "first" : "last");
+            return { column, direction, nulls };
+        });
+
+        const duplicateKey = keys.map(k => k.column).find((c, i, all) => all.indexOf(c) !== i);
+        if (duplicateKey) fail(`"${duplicateKey}" appears twice in \`on\`.`);
+
+        if (keys.map(k => k.column).sort().join(",") === pk && pk !== "") {
+            fail(`this is the primary key — "${table}_pkey" already indexes exactly these columns.`);
+        }
+
+        const include = ((index as { include?: readonly string[] }).include ?? [])
+            .map(propKey => resolveIndexableColumn(collection, propKey, resolveColumnName, fail));
+        const overlap = include.find(c => keys.some(k => k.column === c));
+        if (overlap) fail(`"${overlap}" is in both \`on\` and \`include\`; Postgres rejects the overlap.`);
+
+        if (unique && keys.length === 1) {
+            const propKey = typeof index.on[0] === "string" ? index.on[0] as string : (index.on[0] as { prop: string }).prop;
+            const property = collection.properties?.[propKey] as { validation?: { unique?: boolean } } | undefined;
+            if (property?.validation?.unique) {
+                fail(
+                    `"${propKey}" already declares \`validation.unique\`, which compiles to an inline UNIQUE. ` +
+                    `Two declarations of one guarantee — remove one.`
+                );
+            }
+        }
+
+        const predicate = index.where
+            ? resolvePredicate(collection, index.where, resolveColumnName, fail)
+            : null;
+
+        const withoutName = { schema, table, method, unique, keys, include, predicate, reason: index.reason };
+        const indexName = deriveIndexName(withoutName);
+
+        const clash = byName.get(indexName);
+        if (clash !== undefined) {
+            fail(`derives the same name as indexes[${clash}] — they are the same index declared twice.`);
+        }
+        byName.set(indexName, position);
+
+        specs.push({ ...withoutName, indexName });
+    });
+
+    return specs;
+};
+
+/**
+ * Every declared index across a set of collections, in a stable order.
+ *
+ * Sorted because the result reaches `schema.sql`, which `doctor` string-
+ * compares against a regenerated copy — `generatePostgresDdl` does not sort its
+ * collections, so leaving this in declaration order would make the artifact
+ * depend on the order files happened to load in.
+ */
+export const buildCollectionIndexPlan = (
+    collections: readonly CollectionConfig[],
+    resolveColumnName: ResolveColumnName
+): CollectionIndexSpec[] =>
+    collections
+        .flatMap(collection => buildCollectionIndexSpecs(collection, resolveColumnName))
+        .sort((a, b) =>
+            a.schema.localeCompare(b.schema) ||
+            a.table.localeCompare(b.table) ||
+            a.indexName.localeCompare(b.indexName));

package/src/schema/ensure-collection-tables.ts

@@ -49,6 +49,7 @@ import {
     quoteSqlLiteral
 } from "./generate-postgres-ddl-logic";
 import { buildVectorIndexPlan, vectorIndexStatement, type SkippedVectorIndex } from "./vector-index";
+import { buildCollectionIndexPlan, collectionIndexStatement } from "./collection-index";
 import {
     AUTH_USERS_COLUMNS,
     authUsersColumnDefinition,
@@ -812,6 +813,26 @@ export function planCollectionSchemaEnsure(
         vectorIndexSkipped.push(...plan.skipped);
     }
 
+    //    Declared indexes, on exactly the same terms as the ANN ones above.
+    //
+    //    Boot has to emit these, not just `db push`: the managed runtime
+    //    provisions at boot and never runs a push, so a push-only index would
+    //    simply not exist there — and nothing would say so.
+    //    `contracts/derived-names.txt` states the rule ("Both, or it is a
+    //    bug") and the gate enforces it, which is what caught this.
+    //
+    //    `concurrently` is a parameter here rather than a string replacement
+    //    on the rendered SQL. The `.replace("CREATE INDEX IF NOT EXISTS", …)`
+    //    just above silently does nothing for a UNIQUE index, whose text is
+    //    `CREATE UNIQUE INDEX …` and never matches the pattern.
+    for (const spec of buildCollectionIndexPlan(collections, resolveColumnName)) {
+        actions.push({
+            kind: "create-index",
+            target: `${spec.schema}.${spec.table}`,
+            sql: collectionIndexStatement(spec, { concurrently: true, ifNotExists: true })
+        });
+    }
+
     return {
         actions,
         statements: actions.map(a => a.sql),

package/src/schema/generate-postgres-ddl-logic.ts

@@ -20,6 +20,7 @@ import {
     vectorIndexStatements,
     type VectorIndexPlan
 } from "./vector-index";
+import { buildCollectionIndexSpecs, collectionIndexStatements } from "./collection-index";
 import { REBASE_SCHEMA } from "@rebasepro/types";
 
 // --- Helper Functions ---
@@ -734,6 +735,13 @@ export const generatePostgresDdl = async (
                 indexStatements.push(`-- No ANN index on "${skip.schema}"."${skip.table}"."${skip.column}": ${skip.reason}`);
             }
 
+            // The collection's own `indexes:` block. Last of the three index
+            // producers, and the only one the developer wrote deliberately
+            // rather than getting as a side effect of another feature.
+            indexStatements.push(...collectionIndexStatements(
+                buildCollectionIndexSpecs(collection, resolveColumnName)
+            ));
+
             // The implicit primary key, for a collection that declares none.
             const hasPk = columns.some(c => c.includes("PRIMARY KEY"));
             if (!hasPk) {
@@ -762,16 +770,20 @@ export const generatePostgresDdl = async (
         }
     }
 
-    if (fkStatements.length > 0) {
-        ddl += "-- Foreign Key Constraints\n";
-        ddl += fkStatements.join("\n") + "\n\n";
-    }
-
+    // Indexes before foreign keys. Today every FK targets a primary key created
+    // inline, so the order is safe by accident; the moment a declared
+    // `unique: true` index can back an FK target, a constraint emitted first
+    // would reference an index that does not exist yet.
     if (indexStatements.length > 0) {
         ddl += "-- Indexes\n";
         ddl += indexStatements.join("\n") + "\n\n";
     }
 
+    if (fkStatements.length > 0) {
+        ddl += "-- Foreign Key Constraints\n";
+        ddl += fkStatements.join("\n") + "\n\n";
+    }
+
     if (policyStatements.length > 0) {
         ddl += "-- Row Level Security Policies\n";
         ddl += policyStatements.join("");

package/src/schema/introspect-db-inference.ts

@@ -17,7 +17,7 @@ export function inferPropertyFromData(
     sampleValues: unknown[],
     isPk: boolean,
     /**
-     * False when generating for a project without `@rebasepro/admin-types`, where
+     * False when generating for a project without `@rebasepro/cms-types`, where
      * `BaseProperty` declares no `admin` field and the block below would not
      * compile. The type-level inferences (`propType`, `url`, `storage`) are
      * unaffected — only the form-widget hints are dropped.

package/src/schema/introspect-db-logic.ts

@@ -594,7 +594,7 @@ export interface GeneratedFile {
  *
  * There are two of them and they are not interchangeable:
  *
- * - `admin-types` — `@rebasepro/admin-types`. Its index side-effect-imports
+ * - `admin-types` — `@rebasepro/cms-types`. Its index side-effect-imports
  *   `augment.ts`, so importing it is also what *declares* the `admin` block. Only a
  *   project that depends on the package can resolve it.
  * - `common` — `@rebasepro/common`. Same key inference, no admin surface, no React
@@ -607,7 +607,7 @@ export interface GeneratedFile {
  * The last two emit **no admin block, on the collection or on any property**. That is
  * not a downgrade: `@rebasepro/types` declares no `admin` field at all, so the block
  * introspection used to emit was a type error in every headless project it was
- * written into. See `packages/admin-types/src/augment.ts`.
+ * written into. See `packages/cms-types/src/augment.ts`.
  */
 export type CollectionBuilder = "admin-types" | "common" | "annotation";
 
@@ -616,12 +616,12 @@ export type CollectionBuilder = "admin-types" | "common" | "annotation";
  *
  * Written as constants rather than inline in the import templates below because
  * `scripts/headless-guard/check-types.mjs` scans core sources for `from
- * "@rebasepro/admin-types"` and cannot tell a real import from one this module
+ * "@rebasepro/cms-types"` and cannot tell a real import from one this module
  * *writes*. It is right to be that blunt — the guard's whole value is that it
  * cannot be reasoned around — so the string simply never appears in that shape
  * here. Inlining them back into the templates re-breaks `check:types-headless`.
  */
-export const ADMIN_TYPES_PACKAGE = "@rebasepro/admin-types";
+export const ADMIN_TYPES_PACKAGE = "@rebasepro/cms-types";
 export const COMMON_PACKAGE = "@rebasepro/common";
 export const TYPES_PACKAGE = "@rebasepro/types";
 

package/src/schema/introspect-db-project.ts

@@ -49,10 +49,10 @@ function declaredDependencies(manifestPath: string): Set<string> {
  * at the moment of generation. The alternatives are all proxies for it: `rebase.json`'s
  * `apps` block says a CMS scaffold declared an admin app, and a `frontend/` directory
  * says one was scaffolded, but neither is what the compiler consults, and either can be
- * true of a project whose `config` package does not depend on `@rebasepro/admin-types`.
+ * true of a project whose `config` package does not depend on `@rebasepro/cms-types`.
  *
  * Ambiguity resolves towards the admin panel: a project that declares both packages has
- * a panel, and `@rebasepro/admin-types` is the flavour that keeps the `admin` block.
+ * a panel, and `@rebasepro/cms-types` is the flavour that keeps the `admin` block.
  */
 export function detectCollectionBuilder(outDir: string): CollectionBuilder {
     let dir = path.resolve(outDir);

package/src/schema/introspect-db.ts

@@ -110,12 +110,12 @@ async function main() {
         const checkFacts = parseCheckConstraints(metadata.checks);
 
         // Which builder the generated files may import — read from the manifests
-        // above `outDir`, because a project without `@rebasepro/admin-types` cannot
+        // above `outDir`, because a project without `@rebasepro/cms-types` cannot
         // resolve that import and has no `admin` block to write into either.
         const builder = detectCollectionBuilder(outDir);
         if (builder === "annotation") {
             outWarn(chalk.yellow(
-                "⚠ Neither @rebasepro/admin-types nor @rebasepro/common is declared above " +
+                "⚠ Neither @rebasepro/cms-types nor @rebasepro/common is declared above " +
                 `${outDir}.`
             ));
             outWarn(chalk.gray(

package/src/services/realtimeService.ts

@@ -462,6 +462,23 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             }
         }
 
+        // The shared rows go before the announcement, not after it. Every
+        // `removePresence` below publishes a departure — to local members and
+        // over the bus — while `sendPresenceState` answers a *newly arriving*
+        // subscriber from this table. Announcing first leaves a window where the
+        // table still lists someone who has left: a client hydrating inside it is
+        // handed the ghost, and the diff that would have corrected it was
+        // broadcast before that client existed, so it holds the ghost until the
+        // TTL sweep rather than for the length of one statement.
+        //
+        // One statement for every channel the client was in, rather than one per
+        // channel below — a disconnect is the common case, not a rare one. The
+        // subscription and timer cleanup above stays synchronous on purpose: it
+        // is what leaks if the database is slow, and it owes nothing to the
+        // shared table. With no bus configured this is a no-op that never awaits
+        // a query.
+        await this.presenceStoreOp(() => this.presenceStore!.removeClient(clientId), "client removal");
+
         // Remove from all broadcast channels
         for (const [channel, members] of this.channels.entries()) {
             if (members.has(clientId)) {
@@ -475,10 +492,6 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
         for (const [channel] of this.presence) {
             this.removePresence(clientId, channel, { skipStore: true });
         }
-
-        // One statement for every channel the client was in, rather than one
-        // per channel above — a disconnect is the common case, not a rare one.
-        void this.presenceStoreOp(() => this.presenceStore!.removeClient(clientId), "client removal");
     }
 
     private async handleMessage(clientId: string, message: WebSocketMessage, authContext?: SubscriptionAuthContext) {

package/src/websocket.ts

@@ -1,5 +1,5 @@
 import { RealtimeService } from "./services/realtimeService";
-import { PostgresBackendDriver } from "./PostgresBackendDriver";
+import { PostgresBackendDriver, effectiveSqlRole } from "./PostgresBackendDriver";
 import type { DataDriver, DeleteProps, FetchCollectionProps, FetchOneProps, SaveProps, TableMetadata, BranchInfo, AuthAdapter } from "@rebasepro/types";
 import { ANONYMOUS_USER_ID, isSQLAdmin, isSchemaAdmin, resolveClientListLimit, ListLimitError } from "@rebasepro/types";
 import type { User } from "@rebasepro/types";
@@ -273,7 +273,7 @@ code } }
                         verifiedUser = { uid: "service", roles: ["admin"], isAdmin: true };
                     } else {
                         // Standard JWT path
-                        const jwtPayload = extractUserFromToken(token);
+                        const jwtPayload = await extractUserFromToken(token);
                         if (jwtPayload) {
                             verifiedUser = {
                                 uid: jwtPayload.uid,
@@ -567,6 +567,16 @@ colors: true }));
                                 sql: typeof sql === "string" ? sql.substring(0, 500) : String(sql),
                                 database: options?.database,
                                 role: options?.role,
+                                // The role the statement asked for is above;
+                                // this is the one it ran as. They used to be
+                                // assumed identical, so an execution that fell
+                                // back to the owner was audited under the role
+                                // it had failed to assume. That fallback is now
+                                // an error everywhere except the documented
+                                // `DISABLE_DB_ROLE_SWITCHING` opt-out — which is
+                                // precisely the case this line still has to
+                                // report honestly.
+                                effectiveRole: effectiveSqlRole(options?.role),
                                 paramCount: Array.isArray(options?.params) ? options.params.length : 0,
                                 resultRows: Array.isArray(result) ? result.length : "unknown",
                                 uid: auditSession?.user?.uid ?? "unknown",