@pmate/chat-sdk 0.12.0-next.8 → 0.12.0-next.81

package/lib/runtime/groupClient.d.ts

@@ -0,0 +1,91 @@
+import { type ResponseCacheAccess } from "./responseCache.js";
+import { type MessageScope } from "./messageStore.js";
+import { type ChatConversation } from "./outgoingContent.js";
+import type { SocialGroup } from "./socialReadClient.js";
+export type ActiveChatGroup = {
+    groupId: string;
+    teamId: string;
+    ownerId: string;
+    title: string;
+    avatar?: string;
+    memberIds: readonly string[];
+    revision: string;
+    versionNumber: number;
+    status: "active";
+};
+export type DissolvedChatGroup = {
+    groupId: string;
+    teamId: string;
+    ownerId: string;
+    revision: string;
+    versionNumber: number;
+    status: "dissolved";
+    dissolvedBy?: string;
+    dissolvedAt?: number;
+};
+export type ChatGroup = ActiveChatGroup | DissolvedChatGroup;
+export type GroupSnapshot = {
+    data?: ChatGroup;
+    loading: boolean;
+    error?: unknown;
+};
+export type GroupClientOptions = {
+    scope: MessageScope;
+    access: ResponseCacheAccess;
+    load: (groupId: string, signal: AbortSignal) => Promise<SocialGroup>;
+    onError: (error: unknown) => void;
+    onDenied?: (error: unknown, threadId: string, signal?: AbortSignal) => Promise<boolean | void> | boolean | void;
+    indexedDB?: IDBFactory;
+    name?: string;
+};
+/** SDK-owned roster cache. Read sources, concurrency and reconciliation stay private. */
+export declare class GroupClient {
+    private options;
+    private cache;
+    private entries;
+    private pins;
+    private listeners;
+    private localQueue;
+    private localScheduled;
+    private localRunning;
+    private tasks;
+    private authority?;
+    private version?;
+    private clock;
+    private active;
+    private queue;
+    private controllers;
+    private channel?;
+    private denied;
+    private withdrawn;
+    private closed;
+    private closing?;
+    constructor(options: GroupClientOptions);
+    private assertOpen;
+    private checkAuthority;
+    private entry;
+    snapshot(threadId: string): GroupSnapshot;
+    subscribe(listener: (threadId: string) => void): () => void;
+    pin(threadId: string): () => void;
+    private publish;
+    private normalize;
+    private cached;
+    private local;
+    private flushLocal;
+    private reload;
+    get(thread: ChatConversation, options?: {
+        refresh?: boolean;
+    }): Promise<ChatGroup>;
+    private schedule;
+    private denyGroup;
+    revoke(threadId: string): Promise<void>;
+    wake(): void;
+    hint(thread: ChatConversation, versionNumber?: number): void;
+    private slot;
+    private drain;
+    private request;
+    after(thread: ChatConversation, minimumVersion: number): Promise<ChatGroup>;
+    withdraw(): void;
+    retire(version: number): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/runtime/groupClient.js

@@ -0,0 +1,380 @@
+import { scopedGroupDenial } from "./groupDenial.js";
+import { IndexedDbResponseCache } from "./responseCache.js";
+import { WindowedTasks } from "./coalescer.js";
+import { isOffline } from "./connectivity.js";
+import { messageScopeKey } from "./messageStore.js";
+import { validateConversation, validMessageIdentifier } from "./outgoingContent.js";
+const empty = Object.freeze({ loading: false });
+const token = (value) => value.status === "access-denied" ? `denied:${value.revision}` : `${value.versionNumber}:${value.revision}`;
+/** SDK-owned roster cache. Read sources, concurrency and reconciliation stay private. */
+export class GroupClient {
+    options;
+    cache;
+    entries = new Map();
+    pins = new Map();
+    listeners = new Set();
+    localQueue = [];
+    localScheduled = false;
+    localRunning = new Set();
+    tasks;
+    authority;
+    version;
+    clock = 0;
+    active = 0;
+    queue = [];
+    controllers = new Set();
+    channel;
+    denied = new Set();
+    withdrawn = false;
+    closed = false;
+    closing;
+    constructor(options) {
+        this.options = options;
+        const scope = JSON.stringify(["groups", messageScopeKey(options.scope)]);
+        this.options = { ...options, scope: { ...options.scope } };
+        this.cache = new IndexedDbResponseCache(scope, { indexedDB: options.indexedDB, name: options.name, access: () => this.checkAuthority(), entries: 64, batchRecords: 32, recordBytes: 131072, revision: token });
+        this.tasks = new WindowedTasks(200, error => { if (!this.closed)
+            options.onError(error); });
+        if (typeof BroadcastChannel !== "undefined") {
+            this.channel = new BroadcastChannel(`pmate-chat-groups:${scope}:${options.name ?? "default"}`);
+            this.channel.onmessage = event => {
+                if (event.data?.authority !== this.version || typeof event.data?.threadId !== "string")
+                    return;
+                const entry = this.entries.get(event.data.threadId);
+                if (entry)
+                    void this.reload(entry).catch(error => { if (!this.closed)
+                        options.onError(error); });
+            };
+        }
+    }
+    assertOpen() { if (this.closed)
+        throw new Error("GROUP_CLIENT_CLOSED"); if (this.withdrawn)
+        throw new Error("GROUP_ACCESS_REVOKED"); }
+    checkAuthority() {
+        if (this.withdrawn)
+            throw new Error("GROUP_ACCESS_REVOKED");
+        if (this.authority)
+            return this.authority;
+        return this.authority = this.options.access().then(access => {
+            if (this.withdrawn)
+                throw new Error("GROUP_ACCESS_REVOKED");
+            if (!access.allowed) {
+                this.withdraw();
+                throw new Error("GROUP_ACCESS_REVOKED");
+            }
+            if (this.version !== undefined && this.version !== access.version) {
+                this.withdraw();
+                throw new Error("GROUP_SCOPE_CHANGED");
+            }
+            this.version = access.version;
+            return access;
+        }).finally(() => { this.authority = undefined; });
+    }
+    entry(thread) {
+        this.assertOpen();
+        validateConversation(this.options.scope, thread);
+        if (thread.kind !== "group")
+            throw new Error("INVALID_GROUP_CONVERSATION");
+        let entry = this.entries.get(thread.id);
+        if (!entry) {
+            if (this.entries.size >= 256) {
+                const old = [...this.entries.values()].filter(value => !value.local && !value.request && !this.pins.has(value.thread.id)).sort((a, b) => a.used - b.used)[0];
+                if (!old)
+                    throw new Error("GROUP_CACHE_BACKPRESSURE");
+                this.entries.delete(old.thread.id);
+            }
+            entry = { thread: { id: thread.id, kind: "group", targetId: thread.targetId, teamId: thread.teamId }, snapshot: empty, epoch: 0, token: null, loaded: false, checked: false, generation: 0, wanted: 0, attempts: 0, used: 0 };
+            this.entries.set(thread.id, entry);
+        }
+        entry.used = ++this.clock;
+        return entry;
+    }
+    snapshot(threadId) { return this.closed || this.withdrawn ? empty : this.entries.get(threadId)?.snapshot ?? empty; }
+    subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
+    pin(threadId) { this.pins.set(threadId, (this.pins.get(threadId) ?? 0) + 1); return () => { const count = (this.pins.get(threadId) ?? 1) - 1; if (count)
+        this.pins.set(threadId, count);
+    else
+        this.pins.delete(threadId); }; }
+    publish(entry, next) {
+        if (this.closed)
+            return;
+        const previous = entry.snapshot;
+        if (previous.data && next.data && JSON.stringify(previous.data) === JSON.stringify(next.data))
+            next = { ...next, data: previous.data };
+        if (previous.data === next.data && previous.loading === next.loading && previous.error === next.error)
+            return;
+        entry.snapshot = Object.freeze(next);
+        this.listeners.forEach(listener => listener(entry.thread.id));
+    }
+    normalize(value, entry) {
+        const scope = this.options.scope;
+        if (!value || value.appId !== scope.appId || value.groupId !== entry.thread.targetId || value.teamId !== scope.teamId || !validMessageIdentifier(value.ownerId) || !validMessageIdentifier(value.revision) || !Number.isSafeInteger(value.versionNumber) || value.versionNumber < 1)
+            throw new Error("INVALID_GROUP_METADATA");
+        if (value.status === "dissolved") {
+            if (value.dissolvedBy !== undefined && !validMessageIdentifier(value.dissolvedBy) || value.dissolvedAt !== undefined && (!Number.isSafeInteger(value.dissolvedAt) || value.dissolvedAt < 0))
+                throw new Error("INVALID_GROUP_METADATA");
+            return Object.freeze({ groupId: value.groupId, teamId: scope.teamId, ownerId: value.ownerId, revision: value.revision, versionNumber: value.versionNumber, status: "dissolved", ...(value.dissolvedBy ? { dissolvedBy: value.dissolvedBy } : {}), ...(value.dissolvedAt === undefined ? {} : { dissolvedAt: value.dissolvedAt }) });
+        }
+        if (value.status !== undefined && value.status !== "active" || !Array.isArray(value.members) || !value.members.length || value.members.length > 256 || !value.members.every(validMessageIdentifier) || !value.members.includes(value.ownerId) || !value.members.includes(scope.profileId) || typeof value.title !== "string" || value.avatar !== undefined && value.avatar !== null && typeof value.avatar !== "string")
+            throw new Error("INVALID_GROUP_METADATA");
+        return Object.freeze({ groupId: value.groupId, teamId: scope.teamId, ownerId: value.ownerId, title: value.title, ...(value.avatar ? { avatar: value.avatar } : {}), memberIds: Object.freeze([...new Set(value.members)].sort()), revision: value.revision, versionNumber: value.versionNumber, status: "active" });
+    }
+    cached(value, entry) {
+        return this.normalize(value.status === "dissolved" ? { appId: this.options.scope.appId, ...value } : { appId: this.options.scope.appId, ...value, members: value.memberIds }, entry);
+    }
+    local(entry) {
+        if (entry.loaded)
+            return Promise.resolve();
+        if (entry.local)
+            return entry.local;
+        this.publish(entry, { ...entry.snapshot, loading: !entry.snapshot.data });
+        entry.local = new Promise((resolve, reject) => this.localQueue.push({ entry, resolve, reject })).finally(() => { entry.local = undefined; });
+        if (!this.localScheduled) {
+            this.localScheduled = true;
+            queueMicrotask(() => { this.localScheduled = false; void this.flushLocal(); });
+        }
+        return entry.local;
+    }
+    flushLocal() {
+        const task = (async () => {
+            while (this.localQueue.length) {
+                const batch = this.localQueue.splice(0, 128);
+                try {
+                    this.assertOpen();
+                    await this.checkAuthority();
+                    const rows = await this.cache.readMany(batch.map(item => item.entry.thread.id));
+                    await this.checkAuthority();
+                    this.assertOpen();
+                    for (const item of batch) {
+                        try {
+                            const row = rows.get(item.entry.thread.id), entry = item.entry;
+                            const denied = row.cached?.value.status === "access-denied";
+                            let data = row.cached && !denied ? this.cached(row.cached.value, entry) : undefined;
+                            if (denied)
+                                this.denied.add(entry.thread.id);
+                            const old = entry.snapshot.data;
+                            if (old && data && old.versionNumber > data.versionNumber)
+                                data = old;
+                            if (old && data && old.versionNumber === data.versionNumber && JSON.stringify(old) !== JSON.stringify(data))
+                                throw new Error("GROUP_REVISION_CONFLICT");
+                            entry.epoch = row.epoch;
+                            entry.token = row.cached ? token(row.cached.value) : null;
+                            entry.loaded = true;
+                            this.publish(entry, { data: denied ? undefined : data ?? old, loading: false, ...(denied ? { error: scopedGroupDenial(Object.assign(new Error("GROUP_ACCESS_DENIED"), { status: 403, threadId: entry.thread.id })) } : {}) });
+                            item.resolve();
+                        }
+                        catch (error) {
+                            this.publish(item.entry, { ...item.entry.snapshot, loading: false, error });
+                            item.reject(error);
+                        }
+                    }
+                }
+                catch (error) {
+                    for (const item of batch) {
+                        this.publish(item.entry, { loading: false, error });
+                        item.reject(error);
+                    }
+                }
+            }
+        })().finally(() => this.localRunning.delete(task));
+        this.localRunning.add(task);
+        return task;
+    }
+    async reload(entry) { entry.loaded = false; await this.local(entry); }
+    async get(thread, options = {}) {
+        const entry = this.entry(thread);
+        await this.local(entry);
+        await this.checkAuthority();
+        this.assertOpen();
+        if (options.refresh)
+            this.denied.delete(thread.id);
+        else if (this.denied.has(thread.id))
+            throw entry.snapshot.error ?? scopedGroupDenial(Object.assign(new Error("GROUP_ACCESS_DENIED"), { status: 403, threadId: thread.id }));
+        if (entry.snapshot.data && !options.refresh) {
+            if (!entry.checked && !isOffline())
+                this.schedule(entry);
+            return entry.snapshot.data;
+        }
+        if (isOffline())
+            throw entry.snapshot.error ?? new Error("GROUP_METADATA_OFFLINE");
+        return this.request(entry);
+    }
+    schedule(entry) { if (!this.closed && !this.withdrawn && !this.denied.has(entry.thread.id) && !isOffline())
+        this.tasks.schedule(entry.thread.id, async () => { await this.get(entry.thread, { refresh: true }); }); }
+    async denyGroup(entry, error) {
+        const value = { status: "access-denied", revision: crypto.randomUUID() };
+        this.denied.add(entry.thread.id);
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const row = await this.cache.read(entry.thread.id);
+            try {
+                await this.cache.write(entry.thread.id, value, row.epoch, row.cached ? token(row.cached.value) : null);
+                entry.epoch = row.epoch;
+                entry.token = token(value);
+                entry.checked = true;
+                this.publish(entry, { loading: false, error });
+                this.channel?.postMessage({ threadId: entry.thread.id, authority: this.version });
+                return;
+            }
+            catch (failure) {
+                if (attempt === 2 || !String(failure).includes("RESPONSE_CACHE_CHANGED"))
+                    throw failure;
+            }
+        }
+    }
+    async revoke(threadId) {
+        this.denied.add(threadId);
+        const entry = this.entries.get(threadId);
+        if (entry)
+            await this.denyGroup(entry, scopedGroupDenial(Object.assign(new Error("GROUP_ACCESS_DENIED"), { status: 403, threadId })));
+        else
+            await this.cache.remove(threadId);
+    }
+    wake() { for (const entry of this.entries.values())
+        this.schedule(entry); }
+    hint(thread, versionNumber) {
+        const entry = this.entries.get(thread.id);
+        if (!entry || this.closed || this.withdrawn || versionNumber !== undefined && versionNumber <= (entry.snapshot.data?.versionNumber ?? 0))
+            return;
+        entry.generation++;
+        entry.attempts = 0;
+        entry.wanted = Math.max(entry.wanted, versionNumber ?? 0);
+        this.schedule(entry);
+    }
+    slot(run) {
+        if (this.queue.length >= 128)
+            return Promise.reject(new Error("GROUP_NETWORK_BACKPRESSURE"));
+        return new Promise((resolve, reject) => { this.queue.push({ run, resolve, reject }); this.drain(); });
+    }
+    drain() {
+        while (!this.closed && this.active < 4 && this.queue.length) {
+            const work = this.queue.shift();
+            this.active++;
+            void work.run().then(work.resolve, work.reject).finally(() => { this.active--; this.drain(); });
+        }
+    }
+    request(entry) {
+        if (entry.request)
+            return entry.request;
+        const task = this.slot(async () => {
+            this.assertOpen();
+            await this.checkAuthority();
+            const base = entry.token, generation = entry.generation, controller = new AbortController();
+            this.controllers.add(controller);
+            const timer = setTimeout(() => controller.abort(), 5000);
+            this.publish(entry, { ...entry.snapshot, loading: !entry.snapshot.data, error: undefined });
+            try {
+                const value = this.normalize(await this.options.load(entry.thread.targetId, controller.signal), entry);
+                await this.checkAuthority();
+                this.assertOpen();
+                if (this.denied.has(entry.thread.id))
+                    throw Object.assign(new Error("GROUP_ACCESS_REVOKED"), { status: 403, threadId: entry.thread.id });
+                if (entry.snapshot.data && value.versionNumber <= entry.snapshot.data.versionNumber)
+                    await this.reload(entry);
+                const old = entry.snapshot.data;
+                if (old && value.versionNumber < old.versionNumber) {
+                    this.publish(entry, { data: old, loading: false });
+                    return old;
+                }
+                if (old && value.versionNumber === old.versionNumber) {
+                    if (value.revision !== old.revision || JSON.stringify(value) !== JSON.stringify(old))
+                        throw new Error("GROUP_REVISION_CONFLICT");
+                    entry.checked = true;
+                    this.publish(entry, { data: old, loading: false });
+                    return old;
+                }
+                try {
+                    await this.cache.write(entry.thread.id, value, entry.epoch, base);
+                }
+                catch (error) {
+                    if (!String(error).includes("RESPONSE_CACHE_CHANGED"))
+                        throw error;
+                    await this.reload(entry);
+                    this.schedule(entry);
+                    if (entry.snapshot.data)
+                        return entry.snapshot.data;
+                    throw error;
+                }
+                await this.checkAuthority();
+                this.assertOpen();
+                entry.token = token(value);
+                entry.checked = true;
+                this.publish(entry, { data: value, loading: false });
+                this.channel?.postMessage({ threadId: entry.thread.id, authority: this.version });
+                return value;
+            }
+            catch (error) {
+                if (!this.closed) {
+                    const denied = [401, 403].includes(error?.status ?? 0);
+                    this.publish(entry, { data: denied ? undefined : entry.snapshot.data, loading: false, error });
+                    if (denied && await this.options.onDenied?.(error, entry.thread.id, controller.signal) === true) {
+                        Object.assign(error, { threadId: entry.thread.id });
+                        scopedGroupDenial(error);
+                        try {
+                            await this.denyGroup(entry, error);
+                        }
+                        catch (failure) {
+                            await this.options.onDenied?.(failure, entry.thread.id, controller.signal);
+                            throw failure;
+                        }
+                    }
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+                this.controllers.delete(controller);
+                if (!this.closed && (generation !== entry.generation || entry.wanted > (entry.snapshot.data?.versionNumber ?? 0)) && entry.attempts++ < 4)
+                    this.schedule(entry);
+            }
+        }).finally(() => { if (entry.request === task)
+            entry.request = undefined; });
+        entry.request = task;
+        return task;
+    }
+    async after(thread, minimumVersion) {
+        if (!Number.isSafeInteger(minimumVersion) || minimumVersion < 1)
+            throw new Error("INVALID_GROUP_VERSION");
+        const entry = this.entry(thread);
+        for (const delay of [0, 200, 400, 800, 1600]) {
+            if (entry.snapshot.data && entry.snapshot.data.versionNumber >= minimumVersion)
+                return entry.snapshot.data;
+            if (delay)
+                await new Promise(resolve => setTimeout(resolve, delay));
+            this.assertOpen();
+            try {
+                const value = await this.get(thread, { refresh: true });
+                if (value.versionNumber >= minimumVersion)
+                    return value;
+            }
+            catch (error) {
+                if (this.closed || this.withdrawn || isOffline() || ![503].includes(error?.status ?? 0))
+                    throw error;
+            }
+        }
+        throw new Error("GROUP_SYNC_PENDING");
+    }
+    withdraw() { this.withdrawn = true; this.tasks.close(); this.controllers.forEach(controller => controller.abort()); for (const entry of this.entries.values())
+        this.publish(entry, { loading: false, error: new Error("GROUP_ACCESS_REVOKED") }); }
+    retire(version) { this.withdraw(); return this.cache.retire(version); }
+    close() {
+        if (this.closing)
+            return this.closing;
+        this.closed = true;
+        this.tasks.close();
+        this.channel?.close();
+        this.controllers.forEach(controller => controller.abort());
+        this.listeners.clear();
+        const error = new Error("GROUP_CLIENT_CLOSED");
+        this.queue.splice(0).forEach(work => work.reject(error));
+        this.localQueue.splice(0).forEach(work => work.reject(error));
+        return this.closing = (async () => { try {
+            await Promise.allSettled([...this.entries.values()].flatMap(entry => entry.request ? [entry.request] : []));
+            await Promise.allSettled([...this.localRunning]);
+            await this.cache.close();
+        }
+        finally {
+            this.entries.clear();
+            this.pins.clear();
+        } })();
+    }
+}

package/lib/runtime/groupDenial.d.ts

@@ -0,0 +1,2 @@
+export declare function scopedGroupDenial<T extends object>(error: T): T;
+export declare function isScopedGroupDenial(error: unknown): boolean;

package/lib/runtime/groupDenial.js

@@ -0,0 +1,4 @@
+// Only SDK-verified failures may opt out of whole-session retirement.
+const scoped = new WeakSet();
+export function scopedGroupDenial(error) { scoped.add(error); return error; }
+export function isScopedGroupDenial(error) { return error !== null && typeof error === "object" && scoped.has(error); }

package/lib/runtime/index.d.ts

@@ -29,3 +29,10 @@ export * from "./durableSender.js";
 export * from "./chatSession.js";
 export * from "./messageReaders.js";
 export * from "./createChat.js";
+export * from "./conversationRead.js";
+export { projectConversationReading, type ReadingCandidate, type MessageReadingState, type ConversationReadingView } from "./conversationReading.js";
+export { projectMessageTimeline, type TimelineItem, type TimelineReaction, type TimelineReactionEvent } from "./messageTimeline.js";
+export * from "./messageLaunch.js";
+export * from "./outgoingContent.js";
+export type { ChatGroup } from "./groupClient.js";
+export type { ConversationTarget } from "./conversationDirectory.js";

package/lib/runtime/index.js

@@ -29,3 +29,8 @@ export * from "./durableSender.js";
 export * from "./chatSession.js";
 export * from "./messageReaders.js";
 export * from "./createChat.js";
+export * from "./conversationRead.js";
+export { projectConversationReading } from "./conversationReading.js";
+export { projectMessageTimeline } from "./messageTimeline.js";
+export * from "./messageLaunch.js";
+export * from "./outgoingContent.js";

package/lib/runtime/indexedDbRecovery.d.ts

@@ -0,0 +1,4 @@
+import type { Dexie } from "dexie";
+/** WebKit can invalidate an IDB connection while the application is suspended.
+ * Only replay a whole rejected transaction; never replay individual requests or clear data. */
+export declare function recoverableTransactions(db: Dexie, isClosed: () => boolean): Dexie["transaction"];

package/lib/runtime/indexedDbRecovery.js

@@ -0,0 +1,27 @@
+/** WebKit can invalidate an IDB connection while the application is suspended.
+ * Only replay a whole rejected transaction; never replay individual requests or clear data. */
+export function recoverableTransactions(db, isClosed) {
+    const transaction = (...args) => db.transaction.apply(db, args);
+    let recovery;
+    return (async (...args) => {
+        try {
+            return await transaction(...args);
+        }
+        catch (error) {
+            const failure = error;
+            if (isClosed() || !(failure.name === "UnknownError" || failure.inner?.name === "UnknownError") || !/without an in-progress transaction/i.test(failure.message ?? ""))
+                throw error;
+            if (!recovery) {
+                db.close({ disableAutoOpen: false });
+                const opening = db.open();
+                recovery = opening;
+                void opening.finally(() => { if (recovery === opening)
+                    recovery = undefined; }).catch(() => { });
+            }
+            await recovery;
+            if (isClosed())
+                throw error;
+            return transaction(...args);
+        }
+    });
+}

package/lib/runtime/messageClient.d.ts

@@ -7,6 +7,8 @@ export type MessagePage<T> = {
     resetRequired?: boolean;
 };
 export type MessageTransport<T> = {
+    /** Optional team-scoped authorization for fresh instances recovering a revoked cache. */
+    authorizeScope?: (signal: AbortSignal) => Promise<void>;
     /** 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>>;
@@ -36,9 +38,12 @@ export declare class MessageClient<T extends StoredMessage> {
     private options;
     private storage;
     private watches;
+    private windowEdges;
+    private accessListeners;
     private allListeners;
     private reads;
     private syncing;
+    private completedSyncs;
     private paging;
     private writes;
     private activeWrites;
@@ -54,15 +59,37 @@ export declare class MessageClient<T extends StoredMessage> {
     private queueBytes;
     private pendingBytes;
     private pendingRecords;
+    private legacyImports;
+    private revokingScope?;
+    private scopeReady?;
+    private scopeVersion;
+    private scopeAllowed;
+    private scopeDenied;
+    private enqueuing;
+    private ensureScope;
     constructor(options: MessageClientOptions<T>);
+    /** Shared guard for sibling caches; it never authorizes a denied old instance. */
+    subscribeAccessRevoked(listener: () => void): () => void;
+    scopeAccess(): Promise<{
+        version: number;
+        allowed: boolean;
+    }>;
+    private authorizingScope?;
+    /** Recovery belongs to the SDK; withdrawn instances never regain authority. */
+    authorizeScope(): Promise<void>;
     getSnapshot(thread: string): MessageSnapshot<T> | undefined;
+    /** Exact authoritative row only; migration-only rows never prove delivery. */
+    cachedMessage(thread: string, id: string): Promise<T>;
     subscribe(thread: string, listener: () => void): () => void;
     subscribeAll(listener: (threadId: string) => void): () => void;
     /** Close the connection gap for saved windows with four bounded background lanes. */
-    restore(since: number): Promise<void>;
+    restore(since: number, threadId?: string): Promise<void>;
     read(thread: string, limit?: number, refresh?: boolean): Promise<MessageSnapshot<T>>;
     /** Application connection/wake events invalidate, rather than fetching directly. */
     invalidate(thread: string): void;
+    private fallback;
+    /** Migration batches remain separate from authoritative message coverage. */
+    importLegacy(thread: string, messages: T[]): Promise<void>;
     private reload;
     /** Events are visible only after their atomic batch commits. */
     receive(thread: string, messages: T[]): Promise<void>;
@@ -71,18 +98,18 @@ export declare class MessageClient<T extends StoredMessage> {
     private release;
     private flushWrites;
     private runWrites;
+    private assertNetworkAvailable;
     synchronize(thread: string): Promise<void>;
+    /** Keep an explicitly requested history range in the shared subscribed view. */
+    expandWindow(thread: string, page: MessageSnapshot<T>): Promise<void>;
     earlier(thread: string, before: {
         timestamp: number;
         id: string;
-    }, limit?: number): Promise<{
-        messages: T[];
-        hasEarlier: boolean;
-        resetVersion: number;
-        complete: boolean;
-    }>;
+    }, limit?: number, expand?: boolean): Promise<MessageSnapshot<T>>;
     private fillWindow;
     private denyView;
+    private denyScope;
+    revokeScope(): Promise<number>;
     revoke(thread: string): Promise<void>;
-    close(): Promise<void>;
+    close(beforeDispose?: Promise<unknown>): Promise<void>;
 }