@rebasepro/server-postgres 0.9.1-canary.ff338b5 → 0.10.1-canary.18115ba

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

@@ -21,4 +21,4 @@
  * `DROP SCHEMA "rebase" CASCADE` on the next diff. The `auth` schema is safe
  * because the generated schema.sql declares it.
  */
-export declare const AUTH_BOOTSTRAP_SQL = "-- Auth schema + RLS helper functions (required by the policies below)\nCREATE SCHEMA IF NOT EXISTS auth;\n\nCREATE OR REPLACE FUNCTION auth.uid() RETURNS text AS $$\n    SELECT NULLIF(current_setting('app.user_id', true), '');\n$$ LANGUAGE sql STABLE;\n\nCREATE OR REPLACE FUNCTION auth.jwt() RETURNS jsonb AS $$\n    SELECT COALESCE(\n        NULLIF(current_setting('app.jwt', true), ''),\n        '{}'\n    )::jsonb;\n$$ LANGUAGE sql STABLE;\n\nCREATE OR REPLACE FUNCTION auth.roles() RETURNS text AS $$\n    SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');\n$$ LANGUAGE sql STABLE;\n";
+export declare const AUTH_BOOTSTRAP_SQL = "-- Auth schema + RLS helper functions (required by the policies below)\nCREATE SCHEMA IF NOT EXISTS auth;\n\n-- Falls back to the pre-rename `app.user_id` so a database that has taken the\n-- new schema but is still served by an older backend keeps resolving the\n-- principal. Drop the COALESCE once no such deployment remains.\nCREATE OR REPLACE FUNCTION auth.uid() RETURNS text AS $$\n    SELECT COALESCE(\n        NULLIF(current_setting('app.uid', true), ''),\n        NULLIF(current_setting('app.user_id', true), '')\n    );\n$$ LANGUAGE sql STABLE;\n\nCREATE OR REPLACE FUNCTION auth.jwt() RETURNS jsonb AS $$\n    SELECT COALESCE(\n        NULLIF(current_setting('app.jwt', true), ''),\n        '{}'\n    )::jsonb;\n$$ LANGUAGE sql STABLE;\n\nCREATE OR REPLACE FUNCTION auth.roles() RETURNS text AS $$\n    SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');\n$$ LANGUAGE sql STABLE;\n";

package/dist/schema/auth-schema.d.ts

@@ -232,6 +232,23 @@ export declare function createAuthSchema(usersSchemaName?: string): {
             }, {}, {
                 $type: Record<string, unknown>;
             }>;
+            tokensValidAfter: import("drizzle-orm/pg-core").PgColumn<{
+                name: "tokens_valid_after";
+                tableName: "users";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             createdAt: import("drizzle-orm/pg-core").PgColumn<{
                 name: "created_at";
                 tableName: "users";
@@ -290,8 +307,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "refresh_tokens";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -307,6 +324,23 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            sessionId: import("drizzle-orm/pg-core").PgColumn<{
+                name: "session_id";
+                tableName: "refresh_tokens";
+                dataType: "string";
+                columnType: "PgUUID";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             tokenHash: import("drizzle-orm/pg-core").PgColumn<{
                 name: "token_hash";
                 tableName: "refresh_tokens";
@@ -343,6 +377,57 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            revoked: import("drizzle-orm/pg-core").PgColumn<{
+                name: "revoked";
+                tableName: "refresh_tokens";
+                dataType: "boolean";
+                columnType: "PgBoolean";
+                data: boolean;
+                driverParam: boolean;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            rotatedAt: import("drizzle-orm/pg-core").PgColumn<{
+                name: "rotated_at";
+                tableName: "refresh_tokens";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            sessionStartedAt: import("drizzle-orm/pg-core").PgColumn<{
+                name: "session_started_at";
+                tableName: "refresh_tokens";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             userAgent: import("drizzle-orm/pg-core").PgColumn<{
                 name: "user_agent";
                 tableName: "refresh_tokens";
@@ -422,8 +507,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "password_reset_tokens";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -593,8 +678,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "user_identities";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -723,8 +808,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "mfa_factors";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -983,8 +1068,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "recovery_codes";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -1077,8 +1162,8 @@ export declare function createAuthSchema(usersSchemaName?: string): {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            userId: import("drizzle-orm/pg-core").PgColumn<{
-                name: "user_id";
+            uid: import("drizzle-orm/pg-core").PgColumn<{
+                name: "uid";
                 tableName: "magic_link_tokens";
                 dataType: "string";
                 columnType: "PgUUID";
@@ -1398,6 +1483,23 @@ export declare const users: import("drizzle-orm/pg-core").PgTableWithColumns<{
         }, {}, {
             $type: Record<string, unknown>;
         }>;
+        tokensValidAfter: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tokens_valid_after";
+            tableName: "users";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         createdAt: import("drizzle-orm/pg-core").PgColumn<{
             name: "created_at";
             tableName: "users";
@@ -1456,8 +1558,8 @@ export declare const refreshTokens: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "refresh_tokens";
             dataType: "string";
             columnType: "PgUUID";
@@ -1473,6 +1575,23 @@ export declare const refreshTokens: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        sessionId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "session_id";
+            tableName: "refresh_tokens";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         tokenHash: import("drizzle-orm/pg-core").PgColumn<{
             name: "token_hash";
             tableName: "refresh_tokens";
@@ -1509,6 +1628,57 @@ export declare const refreshTokens: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        revoked: import("drizzle-orm/pg-core").PgColumn<{
+            name: "revoked";
+            tableName: "refresh_tokens";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        rotatedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "rotated_at";
+            tableName: "refresh_tokens";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sessionStartedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "session_started_at";
+            tableName: "refresh_tokens";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         userAgent: import("drizzle-orm/pg-core").PgColumn<{
             name: "user_agent";
             tableName: "refresh_tokens";
@@ -1588,8 +1758,8 @@ export declare const passwordResetTokens: import("drizzle-orm/pg-core").PgTableW
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "password_reset_tokens";
             dataType: "string";
             columnType: "PgUUID";
@@ -1759,8 +1929,8 @@ export declare const userIdentities: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "user_identities";
             dataType: "string";
             columnType: "PgUUID";
@@ -1889,8 +2059,8 @@ export declare const mfaFactors: import("drizzle-orm/pg-core").PgTableWithColumn
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "mfa_factors";
             dataType: "string";
             columnType: "PgUUID";
@@ -2149,8 +2319,8 @@ export declare const recoveryCodes: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "recovery_codes";
             dataType: "string";
             columnType: "PgUUID";
@@ -2243,8 +2413,8 @@ export declare const magicLinkTokens: import("drizzle-orm/pg-core").PgTableWithC
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        userId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "user_id";
+        uid: import("drizzle-orm/pg-core").PgColumn<{
+            name: "uid";
             tableName: "magic_link_tokens";
             dataType: "string";
             columnType: "PgUUID";

package/dist/schema/introspect-db-logic.d.ts

@@ -32,11 +32,6 @@ export interface TableMeta {
     fks: ForeignKeyRow[];
 }
 export declare function singularize(word: string): string;
-/**
- * Convert a snake_case name to a human-readable Title Case label.
- * e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
- */
-export declare function humanize(snakeName: string): string;
 /**
  * Convert a snake_case table name to a camelCase + "Collection" variable name.
  * e.g. "company_token" -> "companyTokenCollection"

package/dist/schema/introspect-db-naming.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Naming helpers shared by the introspection modules. These live apart from
+ * `introspect-db-logic.ts` because the inference pass needs them too, and
+ * importing them from there would close a cycle back through this module.
+ */
+/**
+ * Convert a snake_case name to a human-readable Title Case label.
+ * e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
+ */
+export declare function humanize(snakeName: string): string;

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

@@ -26,6 +26,14 @@ export interface PolicyRef {
     hasUsing: boolean;
     /** Whether a WITH CHECK clause is present at all (not what it says). */
     hasWithCheck: boolean;
+    /**
+     * The live clause text, when read from `pg_policies`. Present only for live
+     * policies (the expected side is parsed from DDL and does not carry it).
+     * Used solely for the insecure-tautology scan, not for divergence — Postgres
+     * rewrites this text, so it is not safe to diff against expected.
+     */
+    qual?: string | null;
+    withCheck?: string | null;
 }
 export interface PolicyDrift {
     /** Described by the collections, absent from the database. */
@@ -38,6 +46,22 @@ export interface PolicyDrift {
         actual: PolicyRef;
         differences: string[];
     }[];
+    /**
+     * A live policy whose expression is the known-permissive tautology
+     * `auth.uid() IS NOT NULL` — true for anonymous visitors too, because the
+     * user path coerces a blank id to the `'anonymous'` sentinel. This is what
+     * `policy.authenticated()` used to compile to, so a database pushed before
+     * that fix carries it, and neither the name, roles, command nor clause
+     * *presence* differs from the corrected policy — the only thing that changed
+     * is the expression text, which this checker otherwise (correctly) ignores.
+     * So it is the one drift that hides from every other check here.
+     *
+     * @see reason  a sentence naming the clause and what to do.
+     */
+    insecure: {
+        policy: PolicyRef;
+        reason: string;
+    }[];
 }
 export interface Queryable {
     query<R>(text: string, values?: unknown[]): Promise<{

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

@@ -51,7 +51,7 @@ export interface ConnectionPosture {
     privileged: boolean;
 }
 export interface AuthContext {
-    userId: string;
+    uid: string;
     /** Raw roles as carried on the user (strings or `{ id }` objects). */
     roles: unknown[];
 }
@@ -93,7 +93,7 @@ export declare function ensureAppRole(run: RawSqlRunner, schemas: string[]): Pro
  * SECURITY: this function is only ever called on the **user** path (the server
  * context uses the base/owner driver and never calls it). The default policies
  * treat `auth.uid() IS NULL` as the trusted server context, and `auth.uid()`
- * is `NULLIF(current_setting('app.user_id'), '')` — so an EMPTY user id would
+ * is `NULLIF(current_setting('app.uid'), '')` — so an EMPTY user id would
  * be read as NULL and silently escalate a user request to server privileges.
  * Coerce empty/blank ids to `ANONYMOUS_USER_ID` here, at the single chokepoint,
  * rather than trusting every caller (e.g. realtime subscription auth) to do it.

package/dist/services/channel-history.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Ordered, replayable per-channel message history.
+ *
+ * Broadcast on its own is fire-and-forget to whoever is connected at the
+ * instant it is sent: fine for presence and for "someone saved" notifications,
+ * not enough for op-based collaborative editing, where a client that blinks
+ * out for two seconds has to resync a whole document rather than catch up on
+ * the four operations it missed. This adds the missing half — every retained
+ * broadcast gets a per-channel sequence number, and a client can ask for
+ * everything after the last one it saw.
+ *
+ * Three decisions worth stating, because each rules out a simpler-looking one:
+ *
+ *  - **Retention is server-side and opt-in.** A channel is created by whoever
+ *    names it, so a client-supplied history depth would let any visitor commit
+ *    the backend to unbounded storage. And presence channels — the common case
+ *    — must not pay for this: with no rules configured nothing is written, no
+ *    table is created, and `broadcast` runs exactly the code it ran before.
+ *
+ *  - **Sequence numbers come from the database, not from a counter in this
+ *    process.** They have to survive a restart and be shared across instances;
+ *    an in-memory counter would restart at 1 after a deploy and hand a
+ *    reconnecting client a replay from the wrong era, silently.
+ *
+ *  - **The cursor row outlives the messages it numbered.** Pruning is what
+ *    makes retention affordable, but pruning the cursor along with the messages
+ *    would restart the sequence and make `sinceSeq` mean something different
+ *    before and after — the worst kind of bug, because replay would still
+ *    return rows and they would look plausible. Cursors are tiny and are kept
+ *    forever; see {@link prune}, which touches only `channel_messages`.
+ */
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ChannelHistoryEntry, ChannelRetentionRule } from "@rebasepro/types";
+/**
+ * Parse a retention TTL into milliseconds.
+ *
+ * Accepts a raw millisecond count or a short duration string (`"30s"`, `"15m"`,
+ * `"24h"`, `"7d"`). Returns undefined for anything unparseable, which the
+ * caller treats as "no TTL" — a misspelt duration must not silently become an
+ * aggressive one.
+ */
+export declare function parseTtlMs(ttl: number | string | undefined): number | undefined;
+/**
+ * Whether `channel` is covered by `rule`.
+ *
+ * Exact match, or a trailing `*` acting as a prefix. Not a general glob: this
+ * decides what reaches disk, and a pattern language whose reach is not obvious
+ * at a glance is the wrong tool for that job.
+ */
+export declare function channelMatchesRule(channel: string, rule: ChannelRetentionRule): boolean;
+/** A rule with its TTL already resolved to milliseconds. */
+export interface ResolvedRetention {
+    limit?: number;
+    ttlMs?: number;
+}
+/**
+ * Persistence and replay for retained channels.
+ *
+ * Inert unless constructed with at least one rule: {@link enabled} is false,
+ * {@link ensureTables} does nothing, and {@link retentionFor} answers undefined
+ * for every channel, so the realtime service never reaches the SQL below.
+ */
+export declare class ChannelHistoryStore {
+    private db;
+    private rules;
+    /** Resolved rule per channel name, so the match runs once per channel. */
+    private resolved;
+    /** Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}. */
+    private lastPruned;
+    private tablesReady;
+    constructor(db: NodePgDatabase<Record<string, unknown>>, rules?: ChannelRetentionRule[]);
+    /** Whether any channel retains anything at all. */
+    get enabled(): boolean;
+    /**
+     * The retention that applies to `channel`, or undefined when none does.
+     *
+     * First matching rule wins, so callers order them most-specific first.
+     */
+    retentionFor(channel: string): ResolvedRetention | undefined;
+    /**
+     * Create the history tables. Idempotent, and a no-op when no rule is set —
+     * a deployment that never retains anything gets no schema for it.
+     */
+    ensureTables(): Promise<void>;
+    /**
+     * Append a broadcast and return the sequence number it was given.
+     *
+     * The sequence is allocated by the same statement that stores the message,
+     * so a crash between the two is not a possibility. `ON CONFLICT DO UPDATE`
+     * takes a row lock on the channel's cursor, which is what makes concurrent
+     * broadcasts to one channel line up in a single order — and what keeps
+     * different channels from contending with each other at all.
+     */
+    append(channel: string, event: string, payload: unknown, senderId?: string): Promise<{
+        seq: number;
+        at: string;
+    }>;
+    /**
+     * Everything retained for `channel` after `sinceSeq`, oldest first.
+     *
+     * `latestSeq` is reported whether or not the messages were capped, so a
+     * client that is further behind than one page can tell.
+     */
+    replay(channel: string, sinceSeq?: number, limit?: number): Promise<{
+        messages: ChannelHistoryEntry[];
+        latestSeq: number;
+    }>;
+    /**
+     * Enforce a channel's retention bounds.
+     *
+     * Throttled per channel, so a burst of operations prunes once rather than
+     * once per message — the cost then tracks elapsed time instead of write
+     * volume, which is what makes retention affordable on a hot channel.
+     */
+    prune(channel: string, retention: ResolvedRetention): Promise<number>;
+    /** Forget throttle and match caches. Called on shutdown. */
+    clear(): void;
+}

package/dist/services/realtimeService.d.ts

@@ -4,12 +4,13 @@ import { DataDriver, WebSocketMessage } from "@rebasepro/types";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import type { ChannelRetentionRule } from "@rebasepro/types";
 /**
  * Auth context stored per-subscription so real-time refetches respect RLS.
  * Mirrors the session variables set by PostgresBackendDriver.withAuth().
  */
 export interface SubscriptionAuthContext {
-    userId: string;
+    uid: string;
     roles: string[];
 }
 /**
@@ -24,6 +25,26 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private clients;
     private channels;
     private presence;
+    /**
+     * Ordered, replayable history for channels that opt into it.
+     *
+     * Undefined until {@link configureChannelHistory} is called, and inert even
+     * then unless retention rules were supplied — so presence and ephemeral
+     * notification channels never touch it. See `channel-history.ts`.
+     */
+    private channelHistory?;
+    /**
+     * One promise chain per retained channel, so that assigning a sequence
+     * number and fanning the message out happen in the same order for every
+     * message on that channel.
+     *
+     * Without it, two concurrent broadcasts can be numbered 4 and 5 by the
+     * database and still reach subscribers as 5 then 4 — live order and replay
+     * order would disagree, which is exactly the divergence sequence numbers
+     * are supposed to rule out. Keyed by channel, so unrelated channels never
+     * wait on each other.
+     */
+    private channelSendQueues;
     private presenceInterval?;
     private static readonly PRESENCE_TIMEOUT_MS;
     private dataService;
@@ -197,8 +218,54 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     joinChannel(clientId: string, channel: string): void;
     /** Leave a broadcast channel */
     leaveChannel(clientId: string, channel: string): void;
-    /** Broadcast a message to all clients in a channel except sender */
+    /**
+     * Broadcast a message to all clients in a channel except the sender.
+     *
+     * On a channel with no retention rule this is what it always was: a
+     * synchronous fan-out to whoever is connected, with no sequence number, no
+     * SQL and no await — the body below runs to completion before returning.
+     *
+     * On a retained channel the message is durably numbered first and only then
+     * delivered, through a per-channel queue so that delivery order matches
+     * sequence order. That ordering is the whole point: a client that catches up
+     * with `sinceSeq` has to arrive at the same state as one that never
+     * disconnected.
+     */
     broadcastToChannel(clientId: string, channel: string, event: string, payload: unknown): void;
+    /**
+     * Number a broadcast, store it, then deliver it.
+     *
+     * A message that cannot be stored is **not** delivered. Delivering it would
+     * put it in front of live subscribers while leaving it absent from every
+     * future replay — the two views of the channel would disagree permanently,
+     * and no later message could repair the gap. Failing loudly to the sender
+     * instead lets it retry, which for an operation stream is the only outcome
+     * that keeps clients convergent.
+     */
+    private persistAndFanOut;
+    /** Deliver a broadcast frame to every member of a channel but the sender. */
+    private fanOutBroadcast;
+    /**
+     * Install retention rules and create the tables they need.
+     *
+     * Safe to call with no rules (and safe not to call at all): the store stays
+     * inert, no schema is created, and broadcast keeps its original
+     * fire-and-forget path.
+     */
+    configureChannelHistory(rules: ChannelRetentionRule[] | undefined): Promise<void>;
+    /** Whether any channel is configured to retain messages. */
+    isChannelHistoryEnabled(): boolean;
+    /**
+     * Answer a client's catch-up request.
+     *
+     * A channel with no retention rule is answered with `retained: false`
+     * rather than an empty list, so the client can tell "you missed nothing"
+     * apart from "this channel never keeps anything" — the second means its
+     * reconnect strategy has to be a full resync, and silence would leave it
+     * guessing.
+     */
+    private handleChannelHistoryRequest;
+    private sendChannelHistory;
     /** Track presence in a channel */
     trackPresence(clientId: string, channel: string, state: Record<string, unknown>): void;
     /** Remove presence from a channel */