@rebasepro/server-postgres 0.14.0 → 0.14.1

package/src/services/FetchService.ts

@@ -1,8 +1,8 @@
-import { and, asc, count, desc, eq, getTableColumns, getTableName, gt, lt, or, SQL, TableRelationalConfig, TablesRelationalConfig } from "drizzle-orm";
+import { and, asc, count, desc, eq, getTableColumns, getTableName, gt, isNotNull, isNull, lt, or, sql, SQL, TableRelationalConfig, TablesRelationalConfig } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
-import { CollectionConfig, FilterValues, ResolvedRelation, LogicalCondition, isManyToMany } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, OrderByTuple, ResolvedRelation, LogicalCondition, isManyToMany } from "@rebasepro/types";
 import type { VectorSearchParams } from "@rebasepro/types";
-import { resolveCollectionRelations, findRelation, fieldKeyForColumn, createRelationRef, createRelationRefWithData } from "@rebasepro/common";
+import { resolveCollectionRelations, findRelation, fieldKeyForColumn, createRelationRef, createRelationRefWithData, normalizeDriverOrderBy } from "@rebasepro/common";
 import { generateForeignKeyName, toWireKey } from "@rebasepro/utils";
 import { DrizzleConditionBuilder, getUnknownFilterFieldsMode, type FilterCompilationOptions } from "../utils/drizzle-conditions";
 import {
@@ -30,6 +30,9 @@ import { reachedDatabase } from "../utils/pg-error-utils";
 /** Type-safe accessor for Drizzle's relational query API via dynamic table name */
 type DbQueryAccessor = Record<string, RelationalQueryBuilder<any, any>> | undefined;
 
+/** One sort key, with the column or expression it was resolved to. */
+type ResolvedOrderKey = { field: string; direction: "asc" | "desc"; target: AnyPgColumn | SQL };
+
 /**
  * Service for handling all row read operations.
  * Handles fetching, searching, counting, and filtering rows.
@@ -145,6 +148,48 @@ export class FetchService {
         return this.resolveOrderByField(table, orderBy, collection);
     }
 
+    /**
+     * Resolve every sort key to the expression it orders by, in order of
+     * significance.
+     *
+     * A key that resolves to nothing is dropped rather than skipping the rest:
+     * `resolveOrderByField` only *returns* undefined under the lenient
+     * unknown-field mode, where dropping is the configured answer, and dropping
+     * one key of several still honours the ones that did resolve.
+     */
+    private resolveOrderKeys(
+        table: PgTable<any>,
+        keys: OrderByTuple[],
+        collection?: CollectionConfig,
+        searchString?: string
+    ): ResolvedOrderKey[] {
+        const resolved: ResolvedOrderKey[] = [];
+        for (const [field, direction] of keys) {
+            const target = this.resolveOrderTarget(table, field, collection, searchString);
+            if (target) resolved.push({ field,
+direction,
+target });
+        }
+        return resolved;
+    }
+
+    /**
+     * The full `ORDER BY`: the caller's keys, then the id.
+     *
+     * 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.
+     */
+    private buildOrderExpressions(keys: ResolvedOrderKey[], idField: AnyPgColumn): SQL[] {
+        const expressions = keys.map(({ direction, target }) => direction === "asc" ? asc(target) : desc(target));
+        expressions.push(desc(idField));
+        return expressions as SQL[];
+    }
+
     private resolveOrderByField(
         table: PgTable<any>,
         orderBy: string,
@@ -442,7 +487,7 @@ export class FetchService {
         idInfo: { fieldName: string; type: "string" | "number" },
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             offset?: number;
@@ -506,18 +551,11 @@ export class FetchService {
         }
 
         // OrderBy
-        const orderExpressions: unknown[] = [];
-        if (options.orderBy) {
-            const collection = getCollectionByPath(collectionPath, this.registry);
-            const orderByField = this.resolveOrderTarget(table, options.orderBy, collection, options.searchString);
-            if (orderByField) {
-                orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
-            }
-        }
-        orderExpressions.push(desc(idField));
-        if (orderExpressions.length > 0) {
-            queryOpts.orderBy = orderExpressions;
-        }
+        const orderKeys = normalizeDriverOrderBy(options.orderBy, options.order);
+        const resolvedOrder = orderKeys
+            ? this.resolveOrderKeys(table, orderKeys, getCollectionByPath(collectionPath, this.registry), options.searchString)
+            : [];
+        queryOpts.orderBy = this.buildOrderExpressions(resolvedOrder, idField);
 
         // Limit
         const limitValue = options.searchString ? (options.limit || 50) : options.limit;
@@ -531,25 +569,31 @@ export 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.
      */
     private buildCursorConditions(
         table: PgTable<any>,
         idField: AnyPgColumn,
         idInfo: { fieldName: string; type: "string" | "number" },
-        options: { orderBy?: string; order?: "desc" | "asc"; startAfter?: Record<string, unknown> },
+        options: { orderBy?: string | OrderByTuple[]; order?: "desc" | "asc"; startAfter?: Record<string, unknown> },
         collectionPath?: string
     ): SQL[] {
         if (!options.startAfter) return [];
         const cursor = options.startAfter;
+        const keys = normalizeDriverOrderBy(options.orderBy, options.order);
 
-        if (options.orderBy) {
+        if (keys) {
             // Relevance is computed per query, not stored, so there is no value
             // on the cursor row to compare a later page against — and two
             // requests with different search strings would produce scores that
             // are not on the same scale at all. Refusing is the only honest
             // answer: a dropped cursor condition silently repeats and skips
             // rows, which is precisely what paging exists to prevent.
-            if (options.orderBy === FetchService.SCORE_FIELD) {
+            if (keys.some(([field]) => field === FetchService.SCORE_FIELD)) {
                 throw ApiError.badRequest(
                     "Cursor pagination (`startAfter`) cannot be combined with `orderBy: \"_score\"`. " +
                     "Relevance is computed per query rather than stored, so it cannot key a cursor. " +
@@ -559,23 +603,25 @@ export class FetchService {
                 );
             }
             const collection = collectionPath ? getCollectionByPath(collectionPath, this.registry) : undefined;
-            const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
-            if (orderByField) {
-                const startAfterOrderValue = (cursor.values as Record<string, unknown> | undefined)?.[options.orderBy] ?? cursor[options.orderBy];
-                const startAfterId = cursor.id ?? cursor[idInfo.fieldName];
-
-                if (startAfterOrderValue !== undefined && startAfterId !== undefined) {
-                    if (options.order === "asc") {
-                        return [or(
-                            gt(orderByField, startAfterOrderValue),
-                            and(eq(orderByField, startAfterOrderValue), gt(idField, startAfterId))
-                        )!];
-                    } else {
-                        return [or(
-                            lt(orderByField, startAfterOrderValue),
-                            and(eq(orderByField, startAfterOrderValue), lt(idField, startAfterId))
-                        )!];
-                    }
+            const resolved = this.resolveOrderKeys(table, keys, collection);
+            const startAfterId = cursor.id ?? cursor[idInfo.fieldName];
+
+            if (resolved.length > 0 && startAfterId !== undefined) {
+                const cursorValues = cursor.values as Record<string, unknown> | undefined;
+                // `in`, not `??`: a cursor row whose sort value is genuinely
+                // NULL is a row this has to be able to page past, and `??`
+                // read it as "the cursor did not carry this key" and dropped
+                // the whole condition.
+                const values = resolved.map(({ field }) => (cursorValues && field in cursorValues)
+                    ? cursorValues[field]
+                    : cursor[field]);
+                // Every key needs a value from the cursor row. A missing one
+                // cannot be guessed, and a comparison built from the keys that
+                // happen to be present is not the same comparison — so this
+                // falls through to no cursor condition, which is what a single
+                // missing sort value has always done here.
+                if (values.every((value) => value !== undefined)) {
+                    return [this.buildKeysetComparison(resolved, values, idField, startAfterId)];
                 }
             }
         } else {
@@ -590,6 +636,54 @@ export class FetchService {
         return [];
     }
 
+    /**
+     * "Sorts strictly after the cursor row", over `keys` and then the id.
+     *
+     * 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
+     * direction, and `roles ASC, created_at DESC` is exactly the case this
+     * exists to serve.
+     *
+     * NULLs are compared by the rule Postgres sorts them under (last ascending,
+     * first descending) rather than by `>`/`<`, which answer *unknown* against
+     * NULL and therefore match nothing. Ordering by a nullable column and paging
+     * used to drop every row whose sort value was NULL from page two onward.
+     */
+    private buildKeysetComparison(
+        keys: ResolvedOrderKey[],
+        values: unknown[],
+        idField: AnyPgColumn,
+        cursorId: unknown,
+        index = 0
+    ): SQL {
+        // Past the last key, the id settles it. It is ordered `DESC`, so "after"
+        // the cursor row means a smaller id.
+        if (index >= keys.length) return lt(idField, cursorId);
+
+        const { direction } = keys[index];
+        // A column, not an expression: the one target that is an expression is
+        // `_score`, and a cursor over relevance is refused before this is
+        // reached. Drizzle's comparison helpers are typed per operand kind, so
+        // the union has to be resolved here rather than at the call site.
+        const target = keys[index].target as AnyPgColumn;
+        const value = values[index];
+        const rest = this.buildKeysetComparison(keys, values, idField, cursorId, index + 1);
+
+        if (value === null) {
+            // The cursor row sorts among the NULLs.
+            return direction === "asc"
+                // NULLS LAST: nothing non-null is left, so only later NULLs.
+                ? and(isNull(target), rest)!
+                // NULLS FIRST: every non-null row is still ahead, plus later NULLs.
+                : or(isNotNull(target), and(isNull(target), rest))!;
+        }
+
+        return direction === "asc"
+            // NULLS LAST, so the NULLs are still ahead of a non-null cursor row.
+            ? or(gt(target, value), isNull(target), and(eq(target, value), rest))!
+            : or(lt(target, value), and(eq(target, value), rest))!;
+    }
+
     /**
      * Compile "rows reachable from this parent" into a `WHERE` condition on the
      * target table, so a nested listing can run as an ordinary collection query.
@@ -779,7 +873,7 @@ idColumn };
         collectionPath: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             offset?: number;
@@ -909,18 +1003,19 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             if (finalCondition) query = query.where(finalCondition);
         }
 
-        const orderExpressions = [];
         // Vector search overrides ORDER BY with distance (ascending = closest first)
-        if (vectorMeta) {
-            orderExpressions.push(asc(vectorMeta.orderBy));
-        } else if (options.orderBy) {
-            const orderByField = this.resolveOrderTarget(table, options.orderBy, collection, options.searchString);
-            if (orderByField) {
-                orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
-            }
-        }
-        orderExpressions.push(desc(idField));
-        if (orderExpressions.length > 0) query = query.orderBy(...orderExpressions);
+        const orderExpressions = vectorMeta
+            ? [asc(vectorMeta.orderBy), desc(idField)]
+            : this.buildOrderExpressions(
+                this.resolveOrderKeys(
+                    table,
+                    normalizeDriverOrderBy(options.orderBy, options.order) ?? [],
+                    collection,
+                    options.searchString
+                ),
+                idField
+            );
+        query = query.orderBy(...orderExpressions);
 
         if (options.startAfter) {
             const cursorConditions = this.buildCursorConditions(table, idField, idInfo, options, collectionPath);
@@ -1098,7 +1193,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
              * logical group was pushed every row in the table.
              */
             logical?: LogicalCondition;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             offset?: number;
@@ -1137,7 +1232,7 @@ relatedTo: hop });
              * that RLS allowed.
              */
             logical?: LogicalCondition;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             databaseId?: string;
@@ -1161,6 +1256,14 @@ relatedTo: hop });
             logical?: LogicalCondition;
             searchString?: string;
             databaseId?: string;
+            /**
+             * Only the `threshold` half of a vector search narrows a count: the
+             * distance ordering and the `_distance` column change which rows
+             * come back first, not how many there are. Omitting it here left
+             * `meta.total` counting rows the threshold had excluded, so a
+             * request that was served three rows was told there were nine.
+             */
+            vectorSearch?: VectorSearchParams;
         } = {}
     ): Promise<number> {
         // Same narrowing as the listing — and, unlike the count it replaces,
@@ -1197,6 +1300,23 @@ relatedTo: hop });
             if (logicalCondition) allConditions.push(logicalCondition);
         }
 
+        // A `threshold` genuinely narrows the row set on the fetch path, and
+        // this count did not apply it — so a similarity-filtered listing
+        // reported the size of the *unfiltered* set, and `hasMore` stayed true
+        // over pages that were already empty. Only the threshold narrows it:
+        // the ORDER BY and the `_distance` projection change which rows come
+        // first and what rides along with them, not how many there are.
+        if (options.vectorSearch) {
+            // Built for any vector search rather than only a thresholded one,
+            // because this is also where an unknown or non-vector
+            // `vector_search` property is refused with a 400. Without a
+            // threshold it contributes no filter, so the count is unchanged and
+            // what is gained is that `/count` refuses the request the listing
+            // refuses instead of answering it with a number.
+            const vectorMeta = DrizzleConditionBuilder.buildVectorSearchConditions(table, options.vectorSearch);
+            if (vectorMeta.filter) allConditions.push(vectorMeta.filter);
+        }
+
         if (allConditions.length > 0) {
             const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(allConditions);
             if (finalCondition) query = query.where(finalCondition);
@@ -1206,6 +1326,131 @@ relatedTo: hop });
         return Number(result[0]?.count || 0);
     }
 
+    /**
+     * `count`/`sum`/`avg`/`min`/`max`, optionally grouped.
+     *
+     * The gap this fills is narrow and constant: every dashboard wants "revenue
+     * by status" and "orders per day", and without it the options were a custom
+     * function holding hand-written SQL, or fetching every row and reducing in
+     * JavaScript — which is wrong at any size that matters, and silently wrong
+     * under a `limit`.
+     *
+     * It runs through the same request-scoped handle as every other read, so
+     * **RLS applies to the rows being aggregated**. That is the property worth
+     * protecting here: an aggregate is an effective way to read data you cannot
+     * select, and `count(*)` over a table whose policies would return nothing
+     * has to be zero.
+     */
+    async aggregate<M extends Record<string, unknown>>(
+        collectionPath: string,
+        options: {
+            aggregates: { fn: "count" | "sum" | "avg" | "min" | "max"; field?: string; alias: string }[];
+            groupBy?: string[];
+            filter?: FilterValues<Extract<keyof M, string>>;
+            logical?: LogicalCondition;
+            searchString?: string;
+            limit?: number;
+        }
+    ): Promise<Record<string, unknown>[]> {
+        const collection = getCollectionByPath(collectionPath, this.registry);
+        const table = getTableForCollection(collection, this.registry);
+        const columns = getTableColumns(table);
+
+        const columnFor = (field: string, forWhat: string): AnyPgColumn => {
+            const column = columns[field as keyof typeof columns] as AnyPgColumn | undefined;
+            if (!column) {
+                throw ApiError.badRequest(
+                    `Unknown field '${field}' in ${forWhat}. Valid fields: ${Object.keys(columns).sort().join(", ")}`,
+                    "UNKNOWN_AGGREGATE_FIELD"
+                );
+            }
+            return column;
+        };
+
+        const selection: Record<string, SQL> = {};
+
+        for (const aggregate of options.aggregates) {
+            if (aggregate.fn === "count" && !aggregate.field) {
+                selection[aggregate.alias] = sql`count(*)`;
+                continue;
+            }
+            const column = columnFor(aggregate.field as string, `${aggregate.fn}()`);
+            switch (aggregate.fn) {
+                case "count": selection[aggregate.alias] = sql`count(${column})`; break;
+                // Cast through numeric so what comes back is a string this
+                // method parses, rather than a float whose precision depends on
+                // the column type — `avg` over an integer column is otherwise
+                // one shape here and another there.
+                case "sum": selection[aggregate.alias] = sql`sum(${column})::numeric`; break;
+                case "avg": selection[aggregate.alias] = sql`avg(${column})::numeric`; break;
+                case "min": selection[aggregate.alias] = sql`min(${column})`; break;
+                case "max": selection[aggregate.alias] = sql`max(${column})`; break;
+            }
+        }
+
+        const groupColumns = (options.groupBy ?? []).map(field => ({
+            field,
+            column: columnFor(field, "groupBy")
+        }));
+        for (const group of groupColumns) {
+            selection[group.field] = sql`${group.column}`;
+        }
+
+        let query = this.db.select(selection).from(table).$dynamic();
+
+        const conditions: SQL[] = [];
+        if (options.searchString) {
+            const searchConditions = DrizzleConditionBuilder.buildSearchConditions(
+                options.searchString, collection.properties, table, collection
+            );
+            // No searchable field means no row matches — the same impossible
+            // WHERE the listing uses, rather than an unfiltered aggregate.
+            if (searchConditions.length === 0) return [];
+            conditions.push(DrizzleConditionBuilder.combineConditionsWithOr(searchConditions) as SQL);
+        }
+        if (options.filter) {
+            conditions.push(...this.buildFilterConditions(options.filter, table, collectionPath));
+        }
+        if (options.logical) {
+            const logicalCondition = DrizzleConditionBuilder.buildLogicalConditions(
+                options.logical, table, collectionPath, this.filterContext(collectionPath, table)
+            );
+            if (logicalCondition) conditions.push(logicalCondition);
+        }
+        if (conditions.length > 0) {
+            const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(conditions);
+            if (finalCondition) query = query.where(finalCondition);
+        }
+
+        if (groupColumns.length > 0) {
+            query = query.groupBy(...groupColumns.map(g => g.column));
+            // Bounded for the same reason a listing is: grouping by a
+            // high-cardinality column is a whole table's worth of rows in one
+            // response.
+            if (options.limit) query = query.limit(options.limit);
+        }
+
+        const rows = await query as Record<string, unknown>[];
+
+        // `count`, `sum` and `avg` arrive as strings: Postgres returns bigint
+        // and numeric that way because they do not fit a JS number in general.
+        // They do fit for every aggregate anyone puts on a dashboard, and a
+        // caller handed `"12"` where they expected `12` has to find that out
+        // for themselves. Parsed once, here.
+        const numericAliases = new Set(
+            options.aggregates.filter(a => a.fn === "count" || a.fn === "sum" || a.fn === "avg").map(a => a.alias)
+        );
+        return rows.map(row => {
+            const out: Record<string, unknown> = { ...row };
+            for (const alias of numericAliases) {
+                if (out[alias] === null || out[alias] === undefined) continue;
+                const parsed = Number(out[alias]);
+                if (!Number.isNaN(parsed)) out[alias] = parsed;
+            }
+            return out;
+        });
+    }
+
     /**
      * Check if a field value is unique
      */
@@ -1269,7 +1514,7 @@ relatedTo: hop });
             filter?: FilterValues<Extract<keyof M, string>>;
             /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
             logical?: LogicalCondition;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             offset?: number;
@@ -1546,7 +1791,7 @@ relatedTo: hop }, include
              * described different sets of rows.
              */
             logical?: LogicalCondition;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             offset?: number;
@@ -1627,17 +1872,19 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
             if (finalCondition) query = query.where(finalCondition);
         }
 
-        const orderExpressions = [];
-        if (vectorMeta) {
-            orderExpressions.push(asc(vectorMeta.orderBy));
-        } else if (options.orderBy) {
-            const orderByField = this.resolveOrderTarget(table, options.orderBy, collection, options.searchString);
-            if (orderByField) {
-                orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
-            }
-        }
-        orderExpressions.push(desc(idField));
-        if (orderExpressions.length > 0) query = query.orderBy(...orderExpressions);
+        // Vector search overrides ORDER BY with distance (ascending = closest first)
+        const orderExpressions = vectorMeta
+            ? [asc(vectorMeta.orderBy), desc(idField)]
+            : this.buildOrderExpressions(
+                this.resolveOrderKeys(
+                    table,
+                    normalizeDriverOrderBy(options.orderBy, options.order) ?? [],
+                    collection,
+                    options.searchString
+                ),
+                idField
+            );
+        query = query.orderBy(...orderExpressions);
 
         const limitValue = options.vectorSearch
             ? (options.limit || 10)

package/src/services/RelationService.ts

@@ -1,7 +1,7 @@
 import { and, eq, inArray, notInArray, or, sql, SQL, getTableName as drizzleTableName } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import { DrizzleClient } from "../interfaces";
-import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, OrderByTuple, ResolvedRelation, ResolvedManyToMany, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations, findRelation, fieldKeyForColumn } from "@rebasepro/common";
 import { hasForeignKeyOnTarget, isManyToMany, type ResolvedVia } from "@rebasepro/types";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
@@ -306,7 +306,7 @@ export class RelationService {
         relationKey: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             startAfter?: Record<string, unknown>;
@@ -335,7 +335,7 @@ export class RelationService {
         relation: ResolvedRelation,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
-            orderBy?: string;
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             startAfter?: Record<string, unknown>;

package/src/services/channel-history.ts

@@ -35,6 +35,7 @@ import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { ChannelHistoryEntry, ChannelRetentionRule } from "@rebasepro/types";
 import { logger } from "@rebasepro/server";
 import { revokeInternalTableSql } from "@rebasepro/common";
+import { drizzleDdlBootstrapper } from "../schema/drizzle-ddl";
 
 /** How many messages a replay returns when the caller does not say. */
 const DEFAULT_REPLAY_LIMIT = 200;
@@ -167,12 +168,19 @@ export class ChannelHistoryStore {
     async ensureTables(): Promise<void> {
         if (!this.enabled || this.tablesReady) return;
 
-        await this.db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+        // Contained, retrying steps rather than one straight sequence — see the
+        // note on `ChannelPresenceStore.ensureTables`. The failure mode here is
+        // the same and the stakes are the same: the two `REVOKE`s at the end are
+        // what keep retained broadcasts off the end-user role, and a lost create
+        // race used to skip them.
+        const ddl = drizzleDdlBootstrapper(this.db, "channel-history");
+
+        await ddl.ensureObject("rebase schema", "CREATE SCHEMA IF NOT EXISTS rebase");
 
         // The primary key is exactly the replay query's access path
         // (`channel = $1 AND seq > $2 ORDER BY seq`), so it needs no further
         // index of its own.
-        await this.db.execute(sql`
+        await ddl.ensureObject("channel_messages table", `
             CREATE TABLE IF NOT EXISTS rebase.channel_messages (
                 channel TEXT NOT NULL,
                 seq BIGINT NOT NULL,
@@ -185,14 +193,14 @@ export class ChannelHistoryStore {
         `);
 
         // Only for the TTL arm of pruning; the limit arm rides the primary key.
-        await this.db.execute(sql`
+        await ddl.ensureObject("channel_messages created_at index", `
             CREATE INDEX IF NOT EXISTS idx_channel_messages_created
             ON rebase.channel_messages (created_at)
         `);
 
         // Never pruned — see the note at the top of this file. One row per
         // channel that has ever retained a message.
-        await this.db.execute(sql`
+        await ddl.ensureObject("channel_cursors table", `
             CREATE TABLE IF NOT EXISTS rebase.channel_cursors (
                 channel TEXT PRIMARY KEY,
                 last_seq BIGINT NOT NULL
@@ -209,8 +217,32 @@ export class ChannelHistoryStore {
         // `docs/channel-authorization.md`. The driver's schema-wide
         // grant reaches these (created here, after it ran), so take the
         // privilege back.
-        await this.db.execute(sql.raw(revokeInternalTableSql("rebase", "channel_messages")));
-        await this.db.execute(sql.raw(revokeInternalTableSql("rebase", "channel_cursors")));
+        //
+        // Driven off a probe of what exists rather than off who won each create.
+        const [messagesReady, cursorsReady] = await Promise.all([
+            ddl.isReadable("rebase.channel_messages"),
+            ddl.isReadable("rebase.channel_cursors")
+        ]);
+        if (messagesReady) {
+            await ddl.step("channel_messages revoke", () =>
+                this.db.execute(sql.raw(revokeInternalTableSql("rebase", "channel_messages")))
+            );
+        }
+        if (cursorsReady) {
+            await ddl.step("channel_cursors revoke", () =>
+                this.db.execute(sql.raw(revokeInternalTableSql("rebase", "channel_cursors")))
+            );
+        }
+
+        if (!messagesReady || !cursorsReady) {
+            // Left un-ready on purpose so the next call retries. Announcing
+            // "ready" here is what would turn a half-created schema into replays
+            // that answer empty forever.
+            logger.warn(
+                "[ChannelHistory] Retained-channel tables are not both present; history is not ready yet."
+            );
+            return;
+        }
 
         this.tablesReady = true;
         logger.info(`✅ [ChannelHistory] Retained channels ready (${this.rules.length} rule(s)).`);