@pmate/chat-sdk 0.11.9 → 0.12.0-next.1

package/lib/runtime/durableSender.js

@@ -0,0 +1,184 @@
+import { Dexie } from "dexie";
+import { withChatTeam } from "./teamScope.js";
+import { messageScopeKey } from "./messageStore.js";
+/** Persists the exact wire message before sending; retries preserve its hash. */
+export class DurableChatSender {
+    client;
+    onError;
+    db;
+    outbox;
+    scope;
+    identity;
+    values = new Map();
+    snapshots = new Map();
+    listeners = new Set();
+    running = new Map();
+    closed = false;
+    offConnection;
+    ready;
+    constructor(client, scope, onError, options = {}) {
+        this.client = client;
+        this.onError = onError;
+        this.scope = messageScopeKey(scope);
+        this.identity = { ...scope };
+        this.db = new Dexie(options.name ?? "pmate-chat-outbox", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
+        this.db.version(1).stores({ outbox: "[scope+hash],scope,[scope+threadId]" });
+        this.outbox = this.db.table("outbox");
+        this.ready = this.outbox.where("scope").equals(this.scope).toArray().then(records => {
+            if (this.closed)
+                return;
+            records.filter(record => !record.confirmed).forEach(record => this.values.set(record.hash, record));
+            this.emit();
+        });
+        this.offConnection = client.watchConnection(state => {
+            if (state === "connected")
+                void this.resume().catch(onError);
+        });
+    }
+    initialize() { return this.ready; }
+    subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
+    snapshot(threadId) {
+        let snapshot = this.snapshots.get(threadId);
+        if (!snapshot) {
+            snapshot = [...this.values.values()].filter(record => threadId === undefined || record.threadId === threadId);
+            this.snapshots.set(threadId, snapshot);
+        }
+        return snapshot;
+    }
+    emit() { this.snapshots.clear(); if (!this.closed)
+        this.listeners.forEach(listener => listener()); }
+    /** Resolves after the exact wire message is durable, independently of network delivery. */
+    async enqueue(threadId, input) {
+        const message = await this.persistOutgoing(threadId, input);
+        void this.retry(message.hash).catch(error => this.onError(error));
+        return message;
+    }
+    /** Compatibility API: resolves only after transport delivery. */
+    async send(threadId, input) {
+        const message = await this.persistOutgoing(threadId, input);
+        return this.retry(message.hash);
+    }
+    async persistOutgoing(threadId, input) {
+        await this.ready;
+        if (this.closed)
+            throw new Error("CHAT_SENDER_CLOSED");
+        const message = this.client.prepareChat(input.to, withChatTeam(input.body, this.identity.teamId), input.recipients);
+        if (message.from !== this.identity.profileId)
+            throw new Error("OUTGOING_MESSAGE_IDENTITY_MISMATCH");
+        const record = { scope: this.scope, threadId, hash: message.hash, message, status: "sending" };
+        await this.outbox.put(record);
+        if (this.closed)
+            throw new Error("CHAT_SENDER_CLOSED");
+        this.values.set(record.hash, record);
+        this.emit();
+        return message;
+    }
+    retry(hash) {
+        if (this.closed)
+            return Promise.reject(new Error("CHAT_SENDER_CLOSED"));
+        const running = this.running.get(hash);
+        if (running)
+            return running;
+        const task = this.transmit(hash).finally(() => this.running.delete(hash));
+        this.running.set(hash, task);
+        return task;
+    }
+    async transmit(hash) {
+        await this.ready;
+        const record = await this.outbox.get([this.scope, hash]);
+        if (!record || this.closed)
+            throw new Error("OUTGOING_MESSAGE_UNAVAILABLE");
+        if (record.status === "sent" || record.confirmed)
+            return record.message;
+        const sending = { ...record, status: "sending" };
+        if (record.status !== "sending") {
+            const latest = await this.save(sending);
+            if (!latest || latest.confirmed || latest.status === "sent")
+                return latest?.message ?? record.message;
+        }
+        if (this.values.get(hash)?.status !== "sending") {
+            this.values.set(hash, sending);
+            this.emit();
+        }
+        try {
+            const message = await this.client.sendPrepared(record.message);
+            const sent = { ...record, message, status: "sent" };
+            const committed = await this.save(sent);
+            if (!this.closed) {
+                if (committed?.confirmed || !committed)
+                    this.values.delete(hash);
+                else
+                    this.values.set(hash, committed);
+                this.emit();
+            }
+            return message;
+        }
+        catch (error) {
+            if (!this.closed) {
+                const failed = { ...record, status: "failed" };
+                const committed = await this.save(failed);
+                if (committed?.confirmed || committed?.status === "sent") {
+                    this.values.delete(hash);
+                    this.emit();
+                    return committed.message;
+                }
+                if (committed)
+                    this.values.set(hash, committed);
+                else
+                    this.values.delete(hash);
+                this.emit();
+            }
+            throw error;
+        }
+    }
+    async save(record) {
+        return this.db.transaction("rw", this.outbox, async () => {
+            const previous = await this.outbox.get([this.scope, record.hash]);
+            if (!previous || previous.confirmed || previous.status === "sent")
+                return previous;
+            await this.outbox.put(record);
+            return record;
+        });
+    }
+    /** Confirm only after the authoritative message has been durably merged.
+     * A tombstone prevents another tab's late failure from recreating the outbox. */
+    async confirm(hashes) {
+        await this.ready;
+        await this.db.transaction("rw", this.outbox, async () => {
+            const previous = await this.outbox.bulkGet(hashes.map(hash => [this.scope, hash]));
+            const confirmed = previous.filter((record) => Boolean(record)).map(record => ({ ...record, status: "sent", confirmed: true }));
+            if (confirmed.length)
+                await this.outbox.bulkPut(confirmed);
+        });
+        let changed = false;
+        for (const hash of hashes)
+            changed = this.values.delete(hash) || changed;
+        if (changed)
+            this.emit();
+    }
+    async resume() {
+        await this.ready;
+        if (this.closed)
+            return;
+        // Only interrupted, unconfirmed sends resume automatically; failed sends require retry.
+        for (const record of this.values.values())
+            if (record.status === "sending") {
+                if (this.closed)
+                    return;
+                try {
+                    await this.retry(record.hash);
+                }
+                catch (error) {
+                    this.onError(error);
+                }
+            }
+    }
+    async close() {
+        this.closed = true;
+        this.offConnection();
+        this.listeners.clear();
+        await this.ready;
+        await Promise.allSettled([...this.running.values()]);
+        this.db.close();
+    }
+}

package/lib/runtime/index.d.ts

@@ -19,3 +19,12 @@ export * from "./teamScope.js";
 export * from "./teamMigrations.js";
 export * from "./socialReadClient.js";
 export * from "./readCounts.js";
+export * from "./coalescer.js";
+export * from "./batchedReadIndex.js";
+export * from "./readingClient.js";
+export * from "./messageStore.js";
+export * from "./messageClient.js";
+export * from "./recordCache.js";
+export * from "./durableSender.js";
+export * from "./chatSession.js";
+export * from "./messageReaders.js";

package/lib/runtime/index.js

@@ -19,3 +19,12 @@ export * from "./teamScope.js";
 export * from "./teamMigrations.js";
 export * from "./socialReadClient.js";
 export * from "./readCounts.js";
+export * from "./coalescer.js";
+export * from "./batchedReadIndex.js";
+export * from "./readingClient.js";
+export * from "./messageStore.js";
+export * from "./messageClient.js";
+export * from "./recordCache.js";
+export * from "./durableSender.js";
+export * from "./chatSession.js";
+export * from "./messageReaders.js";

package/lib/runtime/messageClient.d.ts

@@ -0,0 +1,68 @@
+import { IndexedDbMessageStore, type MessageScope, type StoredMessage } from "./messageStore.js";
+export type MessagePage<T> = {
+    messages: T[];
+    checkpoint?: string;
+    nextBefore?: string | null;
+    hasMoreChanges?: boolean;
+    resetRequired?: boolean;
+};
+export type MessageTransport<T> = {
+    /** Authoritative history. Must include control state needed to merge old rows. */
+    load: (threadId: string, signal: AbortSignal) => Promise<MessagePage<T>>;
+    changes?: (threadId: string, after: string, signal: AbortSignal) => Promise<MessagePage<T>>;
+    older?: (threadId: string, before: string, signal: AbortSignal) => Promise<MessagePage<T>>;
+};
+export type MessageSnapshot<T> = {
+    messages: readonly T[];
+    hasEarlier: boolean;
+};
+export type MessageClientOptions<T extends StoredMessage> = {
+    scope: MessageScope;
+    transport: MessageTransport<T>;
+    storage?: IndexedDbMessageStore<T>;
+    merge?: (previous: T | undefined, incoming: T) => T;
+    onError?: (error: unknown, threadId: string) => void;
+    batchSize?: number;
+    writeWindowMs?: number;
+    syncWindowMs?: number;
+};
+/** Local-first message facade; hosts never select a cache or network source. */
+export declare class MessageClient<T extends StoredMessage> {
+    private options;
+    private storage;
+    private watches;
+    private reads;
+    private syncing;
+    private writes;
+    private activeWrites;
+    private writeTasks;
+    private syncTasks;
+    private abort;
+    private channel?;
+    private closed;
+    private closing;
+    private revoked;
+    private batchSize;
+    constructor(options: MessageClientOptions<T>);
+    getSnapshot(thread: string): MessageSnapshot<T> | undefined;
+    subscribe(thread: string, listener: () => void): () => void;
+    read(thread: string, limit?: number): Promise<MessageSnapshot<T>>;
+    /** Application connection/wake events invalidate, rather than fetching directly. */
+    invalidate(thread: string): void;
+    private reload;
+    /** Events are visible only after their atomic batch commits. */
+    receive(thread: string, messages: T[]): Promise<void>;
+    private persist;
+    private flushWrites;
+    private runWrites;
+    synchronize(thread: string): Promise<void>;
+    earlier(thread: string, before: {
+        timestamp: number;
+        id: string;
+    }, limit?: number): Promise<{
+        messages: T[];
+        hasEarlier: boolean;
+    }>;
+    revoke(thread: string): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/runtime/messageClient.js

@@ -0,0 +1,225 @@
+import { WindowedTasks } from "./coalescer.js";
+import { IndexedDbMessageStore, messageScopeKey, mergeStoredMessage } from "./messageStore.js";
+/** Local-first message facade; hosts never select a cache or network source. */
+export class MessageClient {
+    options;
+    storage;
+    watches = new Map();
+    reads = new Map();
+    syncing = new Map();
+    writes = new Map();
+    activeWrites = new Set();
+    writeTasks;
+    syncTasks;
+    abort = new AbortController();
+    channel;
+    closed = false;
+    closing = false;
+    revoked = new Set();
+    batchSize;
+    constructor(options) {
+        this.options = options;
+        this.storage = options.storage ?? new IndexedDbMessageStore(options.scope, options.merge ?? mergeStoredMessage);
+        this.batchSize = options.batchSize ?? 128;
+        if (!Number.isSafeInteger(this.batchSize) || this.batchSize < 1 || this.batchSize > 1000)
+            throw new Error("INVALID_MESSAGE_BATCH_SIZE");
+        this.writeTasks = new WindowedTasks(options.writeWindowMs ?? 16, (error, thread) => options.onError?.(error, thread));
+        this.syncTasks = new WindowedTasks(options.syncWindowMs ?? 1000, (error, thread) => options.onError?.(error, thread));
+        if (typeof BroadcastChannel !== "undefined") {
+            this.channel = new BroadcastChannel(`pmate-chat:${messageScopeKey(options.scope)}`);
+            this.channel.onmessage = event => { if (typeof event.data === "string" && this.watches.has(event.data))
+                void this.reload(event.data).catch(error => options.onError?.(error, event.data)); };
+        }
+    }
+    getSnapshot(thread) { return this.watches.get(thread)?.snapshot; }
+    subscribe(thread, listener) {
+        let watch = this.watches.get(thread);
+        if (!watch) {
+            watch = { limit: 100, snapshot: { messages: [], hasEarlier: false }, listeners: new Set() };
+            this.watches.set(thread, watch);
+        }
+        watch.listeners.add(listener);
+        return () => { watch.listeners.delete(listener); };
+    }
+    read(thread, limit = 100) {
+        if (this.closed || this.closing || this.revoked.has(thread))
+            return Promise.reject(new Error("MESSAGE_CLIENT_UNAVAILABLE"));
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            return Promise.reject(new Error("INVALID_MESSAGE_LIMIT"));
+        const key = JSON.stringify([thread, limit]), running = this.reads.get(key);
+        if (running)
+            return running;
+        const task = (async () => {
+            const local = await this.storage.read(thread, limit);
+            if (!local.coverage?.complete)
+                await this.synchronize(thread);
+            if (this.closed)
+                throw new Error("MESSAGE_CLIENT_CLOSED");
+            return this.reload(thread, limit);
+        })().finally(() => { if (this.reads.get(key) === task)
+            this.reads.delete(key); });
+        this.reads.set(key, task);
+        return task;
+    }
+    /** Application connection/wake events invalidate, rather than fetching directly. */
+    invalidate(thread) {
+        if (!this.closed && !this.closing && !this.revoked.has(thread))
+            this.syncTasks.schedule(thread, () => this.synchronize(thread));
+    }
+    async reload(thread, limit = this.watches.get(thread)?.limit ?? 100) {
+        const page = await this.storage.read(thread, limit);
+        if (this.closed)
+            throw new Error("MESSAGE_CLIENT_CLOSED");
+        let watch = this.watches.get(thread);
+        const oldById = new Map(watch?.snapshot.messages.map(message => [message.id, message]));
+        const messages = page.messages.map(message => {
+            const old = oldById.get(message.id);
+            return old && JSON.stringify(old) === JSON.stringify(message) ? old : message;
+        });
+        const old = watch?.snapshot;
+        if (old && old.hasEarlier === (page.hasEarlier || Boolean(page.coverage?.nextBefore)) && old.messages.length === messages.length && old.messages.every((message, index) => message === messages[index]))
+            return old;
+        const snapshot = { messages, hasEarlier: page.hasEarlier || Boolean(page.coverage?.nextBefore) };
+        if (!watch) {
+            watch = { limit, snapshot, listeners: new Set() };
+            this.watches.set(thread, watch);
+        }
+        watch.limit = limit;
+        watch.snapshot = snapshot;
+        watch.listeners.forEach(listener => listener());
+        return snapshot;
+    }
+    /** Events are visible only after their atomic batch commits. */
+    receive(thread, messages) {
+        if (this.closed || this.closing || this.revoked.has(thread))
+            return Promise.reject(new Error("MESSAGE_CLIENT_UNAVAILABLE"));
+        const queue = this.writes.get(thread) ?? [];
+        if (messages.length > 1000 || queue.reduce((count, write) => count + write.messages.length, messages.length) > 4096)
+            return Promise.reject(new Error("MESSAGE_STORAGE_BACKPRESSURE"));
+        const promise = new Promise((resolve, reject) => queue.push({ messages, resolve, reject }));
+        this.writes.set(thread, queue);
+        this.writeTasks.schedule(thread, () => this.flushWrites(thread));
+        return promise;
+    }
+    async persist(thread, messages, checkpoint, complete, nextBefore) {
+        let changed = 0;
+        // Coverage advances only after all bounded batches have durably committed.
+        for (let offset = 0; offset < messages.length; offset += this.batchSize) {
+            if (this.closed || this.revoked.has(thread))
+                throw new Error("MESSAGE_CLIENT_UNAVAILABLE");
+            changed += await this.storage.commit(thread, messages.slice(offset, offset + this.batchSize));
+        }
+        if (complete !== undefined || checkpoint !== undefined) {
+            const old = (await this.storage.read(thread, 1)).coverage;
+            if (this.closed || this.revoked.has(thread))
+                throw new Error("MESSAGE_CLIENT_UNAVAILABLE");
+            await this.storage.commit(thread, [], { complete: complete ?? old?.complete ?? false, checkpoint: checkpoint ?? old?.checkpoint, nextBefore: nextBefore === undefined ? old?.nextBefore : nextBefore });
+        }
+        if (changed) {
+            await this.reload(thread);
+            this.channel?.postMessage(thread);
+        }
+    }
+    flushWrites(thread) {
+        const task = this.runWrites(thread).finally(() => this.activeWrites.delete(task));
+        this.activeWrites.add(task);
+        return task;
+    }
+    async runWrites(thread) {
+        const queue = this.writes.get(thread);
+        if (!queue?.length)
+            return;
+        this.writes.delete(thread);
+        try {
+            await this.persist(thread, queue.flatMap(write => write.messages));
+            queue.forEach(write => write.resolve());
+        }
+        catch (error) {
+            queue.forEach(write => write.reject(error));
+            throw error;
+        }
+    }
+    synchronize(thread) {
+        if (this.closed || this.closing || this.revoked.has(thread))
+            return Promise.reject(new Error("MESSAGE_CLIENT_UNAVAILABLE"));
+        const running = this.syncing.get(thread);
+        if (running)
+            return running;
+        const task = (async () => {
+            const coverage = (await this.storage.read(thread, 1)).coverage;
+            let after = coverage?.complete ? coverage.checkpoint : undefined;
+            let page = after && this.options.transport.changes
+                ? await this.options.transport.changes(thread, after, this.abort.signal)
+                : await this.options.transport.load(thread, this.abort.signal);
+            if (page.resetRequired) {
+                if (this.closed || this.revoked.has(thread))
+                    throw new Error("MESSAGE_CLIENT_UNAVAILABLE");
+                await this.storage.removeThread(thread);
+                after = undefined;
+                page = await this.options.transport.load(thread, this.abort.signal);
+            }
+            for (;;) {
+                if (this.closed || this.revoked.has(thread))
+                    throw new Error("MESSAGE_ACCESS_REVOKED");
+                if (page.resetRequired)
+                    throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
+                await this.persist(thread, page.messages, page.checkpoint, true, after ? undefined : page.nextBefore);
+                if (!page.hasMoreChanges)
+                    break;
+                if (!page.checkpoint || page.checkpoint === after || !this.options.transport.changes)
+                    throw new Error("MESSAGE_SYNC_NO_PROGRESS");
+                after = page.checkpoint;
+                page = await this.options.transport.changes(thread, after, this.abort.signal);
+            }
+        })().finally(() => { if (this.syncing.get(thread) === task)
+            this.syncing.delete(thread); });
+        this.syncing.set(thread, task);
+        return task;
+    }
+    async earlier(thread, before, limit = 100) {
+        if (this.closed)
+            throw new Error("MESSAGE_CLIENT_CLOSED");
+        if (this.revoked.has(thread))
+            throw new Error("MESSAGE_ACCESS_REVOKED");
+        if (!(await this.storage.read(thread, 1)).coverage?.complete)
+            await this.synchronize(thread);
+        let page = await this.storage.read(thread, limit, before);
+        while (page.messages.length < limit && page.coverage?.nextBefore && this.options.transport.older) {
+            const token = page.coverage.nextBefore;
+            const remote = await this.options.transport.older(thread, token, this.abort.signal);
+            if (this.closed || this.revoked.has(thread))
+                throw new Error("MESSAGE_CLIENT_UNAVAILABLE");
+            if (remote.resetRequired) {
+                await this.storage.removeThread(thread);
+                throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
+            }
+            if (remote.nextBefore === token)
+                throw new Error("MESSAGE_SYNC_NO_PROGRESS");
+            await this.persist(thread, remote.messages, undefined, true, remote.nextBefore ?? null);
+            page = await this.storage.read(thread, limit, before);
+        }
+        return { messages: page.messages, hasEarlier: page.hasEarlier || Boolean(page.coverage?.nextBefore) };
+    }
+    async revoke(thread) {
+        this.revoked.add(thread);
+        const queue = this.writes.get(thread);
+        this.writes.delete(thread);
+        queue?.forEach(write => write.reject(new Error("MESSAGE_ACCESS_REVOKED")));
+        await this.storage.removeThread(thread);
+        await this.reload(thread);
+        this.channel?.postMessage(thread);
+    }
+    async close() {
+        // Flush accepted event batches before closing; new requests are rejected afterwards.
+        this.closing = true;
+        this.syncTasks.close();
+        this.writeTasks.close();
+        await Promise.all([...this.writes.keys()].map(thread => this.flushWrites(thread)));
+        await Promise.all([...this.activeWrites]);
+        this.closed = true;
+        this.abort.abort();
+        this.channel?.close();
+        this.watches.clear();
+        this.storage.close();
+    }
+}

package/lib/runtime/messageReaders.d.ts

@@ -0,0 +1,39 @@
+export type MessageReadersPage = {
+    appId: string;
+    threadId: string;
+    messageId: string;
+    revision: number;
+    total: number;
+    profileIds: string[];
+    nextAfter: string | null;
+    resetRequired: boolean;
+};
+export type MessageReadersQuery = {
+    threadId: string;
+    messageId: string;
+    afterProfileId?: string;
+    revision?: number;
+    limit?: number;
+};
+export type MessageReadersOptions = {
+    appId: string;
+    profileId: string;
+    token: string;
+    hubHttpUrl: string;
+    fetch?: typeof fetch;
+};
+export declare class MessageReadersError extends Error {
+    readonly status: number;
+    readonly forbidden: boolean;
+    constructor(status: number, message: string);
+}
+/** Authenticated detail reads; concurrent identical requests share one transport call. */
+export declare class MessageReadersClient {
+    private options;
+    private pending;
+    private lifetime;
+    constructor(options: MessageReadersOptions);
+    getReaders(query: MessageReadersQuery, signal?: AbortSignal): Promise<MessageReadersPage>;
+    private request;
+    close(): void;
+}

package/lib/runtime/messageReaders.js

@@ -0,0 +1,59 @@
+export class MessageReadersError extends Error {
+    status;
+    forbidden;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.forbidden = status === 401 || status === 403;
+    }
+}
+/** Authenticated detail reads; concurrent identical requests share one transport call. */
+export class MessageReadersClient {
+    options;
+    pending = new Map();
+    lifetime = new AbortController();
+    constructor(options) { this.options = { ...options }; }
+    getReaders(query, signal) {
+        if (this.lifetime.signal.aborted)
+            return Promise.reject(new Error("MESSAGE_READERS_CLOSED"));
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        const input = { ...query, limit: query.limit ?? 50 };
+        if (!Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > 100 || (input.revision !== undefined && (!Number.isSafeInteger(input.revision) || input.revision < 0)))
+            return Promise.reject(new Error("INVALID_MESSAGE_READERS_QUERY"));
+        const key = JSON.stringify([input.threadId, input.messageId, input.afterProfileId, input.revision, input.limit]);
+        let task = this.pending.get(key);
+        if (!task) {
+            task = this.request(input).finally(() => { if (this.pending.get(key) === task)
+                this.pending.delete(key); });
+            this.pending.set(key, task);
+        }
+        if (!signal)
+            return task;
+        // Cancelling one view must not cancel another view's shared request.
+        return new Promise((resolve, reject) => {
+            const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+            signal.addEventListener("abort", abort, { once: true });
+            task.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+        });
+    }
+    async request(input) {
+        const { token, fetch: fetcher, hubHttpUrl, appId, profileId } = this.options;
+        const response = await (fetcher ?? fetch)(`${hubHttpUrl.replace(/^ws/, "http").replace(/\/+$/, "")}/api/social/reading/readers`, {
+            method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify({ ...input, appId, profileId }),
+            signal: AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(8000)]), redirect: "error", cache: "no-store",
+        });
+        if (!response.ok)
+            throw new MessageReadersError(response.status, `MESSAGE_READERS_HTTP_${response.status}`);
+        const envelope = await response.json(), data = envelope.data;
+        if (envelope.success !== true || data?.appId !== appId || data.threadId !== input.threadId || data.messageId !== input.messageId
+            || !Number.isSafeInteger(data.revision) || data.revision < 0 || !Number.isSafeInteger(data.total) || data.total < 0
+            || !Array.isArray(data.profileIds) || data.profileIds.length > input.limit || data.profileIds.length > data.total
+            || data.profileIds.some((id, i, ids) => typeof id !== "string" || !id || id.length > 512 || id === profileId || (i > 0 && id <= ids[i - 1]) || (input.afterProfileId && !data.resetRequired && id <= input.afterProfileId))
+            || typeof data.resetRequired !== "boolean" || (data.nextAfter !== null && (typeof data.nextAfter !== "string" || data.nextAfter !== data.profileIds.at(-1)))
+            || (!data.resetRequired && input.revision !== undefined && data.revision !== input.revision))
+            throw new Error("INVALID_MESSAGE_READERS_RESPONSE");
+        return data;
+    }
+    close() { this.lifetime.abort(); this.pending.clear(); }
+}

package/lib/runtime/messageStore.d.ts

@@ -0,0 +1,51 @@
+export type StoredMessage = {
+    id: string;
+    threadId: string;
+    timestamp: number;
+    revision?: number;
+    recalled?: boolean;
+};
+export type MessageScope = {
+    appId: string;
+    accountId: string;
+    profileId: string;
+    teamId: string;
+};
+export type MessageCoverage = {
+    checkpoint?: string;
+    complete: boolean;
+    nextBefore?: string | null;
+};
+type CoverageRow = MessageCoverage & {
+    scope: string;
+    thread: string;
+};
+export declare const messageScopeKey: (scope: MessageScope) => string;
+/** Normalized browser cache. Data and coverage advance together in each commit.
+ * Merge runs inside the write transaction against the latest cross-tab state. */
+export declare class IndexedDbMessageStore<T extends StoredMessage> {
+    private merge;
+    private db;
+    private rows;
+    private coverage;
+    private key;
+    constructor(scope: MessageScope, merge: (previous: T | undefined, incoming: T) => T, options?: {
+        indexedDB?: IDBFactory;
+        name?: string;
+    });
+    read(thread: string, limit?: number, before?: {
+        timestamp: number;
+        id: string;
+    }): Promise<{
+        messages: T[];
+        hasEarlier: boolean;
+        coverage: CoverageRow | undefined;
+    }>;
+    commit(thread: string, messages: T[], coverage?: MessageCoverage): Promise<number>;
+    removeThread(thread: string): Promise<void>;
+    clear(): Promise<void>;
+    close(): void;
+}
+/** Keep tombstones monotonic; applications can supply stricter domain reducers. */
+export declare function mergeStoredMessage<T extends StoredMessage>(previous: T | undefined, incoming: T): T;
+export {};