@pmate/chat-sdk 0.12.0-next.3 → 0.12.0-next.30

package/lib/runtime/conversationRead.d.ts

@@ -0,0 +1,13 @@
+import { type ReadIndexState } from "./readIndex.js";
+/** Optional observations whose index metadata may still be in flight. */
+export type ConversationReadMessage = {
+    id: string;
+    threadId: string;
+    mine?: boolean;
+    from?: string;
+    recalled?: boolean;
+    readPolicy?: "visible" | "explicit";
+    kind?: string;
+};
+/** Explicitly mark ordinary text history read; unheard audio stays unread. */
+export declare function recordConversationRead(state: ReadIndexState, conversationId: string, messages?: readonly ConversationReadMessage[], operationId?: () => `${string}-${string}-${string}-${string}-${string}`): ReadIndexState;

package/lib/runtime/conversationRead.js

@@ -0,0 +1,34 @@
+import { recordReadIntent, sourcesInConversation } from "./readIndex.js";
+/** Explicitly mark ordinary text history read; unheard audio stays unread. */
+export function recordConversationRead(state, conversationId, messages = [], operationId = () => crypto.randomUUID()) {
+    if (!conversationId)
+        throw new Error("INVALID_READING_THREAD");
+    const sources = sourcesInConversation(state, conversationId);
+    if (new Set(sources.map(source => source.teamId)).size > 1)
+        throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
+    let next = state;
+    const indexedIds = new Set();
+    for (const source of sources) {
+        const incoming = source.messages.filter(message => {
+            indexedIds.add(message.id);
+            return !message.recalled && message.from !== state.profileId && message.recipients.includes(state.profileId);
+        });
+        const latest = incoming.filter(message => message.readPolicy === "visible" && message.seq > source.readThroughSeq)
+            .reduce((last, message) => !last || message.seq > last.seq ? message : last, undefined);
+        if (latest)
+            next = recordReadIntent(next, { operationId: operationId(), threadId: source.id, messageId: latest.id, readPolicy: "visible" });
+    }
+    // Live/history messages can precede their read-index metadata. Persist their
+    // observations so leaving the page or reloading cannot resurrect the badge.
+    const observed = new Set(next.observedReadIntents?.filter(intent => intent.threadId === conversationId).map(intent => intent.messageId));
+    for (const message of messages) {
+        if (message.threadId !== conversationId || message.mine || message.from === state.profileId || message.recalled || indexedIds.has(message.id) || observed.has(message.id))
+            continue;
+        const readPolicy = message.readPolicy ?? (message.kind === "voice" ? "explicit" : "visible");
+        if (message.kind === "voice" || readPolicy === "explicit")
+            continue;
+        next = recordReadIntent(next, { operationId: operationId(), threadId: conversationId, messageId: message.id, readPolicy });
+        observed.add(message.id);
+    }
+    return next;
+}

package/lib/runtime/conversationReading.d.ts

@@ -0,0 +1,28 @@
+import { unreadInConversation, type ReadIndexState } from "./readIndex.js";
+export type ReadingCandidate = {
+    id: string;
+    threadId: string;
+    from?: string;
+    mine?: boolean;
+    recalled?: boolean;
+    unread?: boolean;
+    attentionEligible?: boolean;
+    readPolicy?: "visible" | "explicit";
+};
+export type MessageReadingState = {
+    seq?: number;
+    read: boolean;
+    readPolicy: "visible" | "explicit";
+};
+export type ConversationReadingView = {
+    messageReading: Readonly<Record<string, MessageReadingState>>;
+    unread: ReturnType<typeof unreadInConversation> | undefined;
+    badgeCount: number | undefined;
+};
+/** One projection for indexed authority and observations awaiting indexing. A
+ * directory badge is optional compatibility metadata, never proof of coverage. */
+export declare function projectConversationReading(state: ReadIndexState | undefined, conversation: {
+    id: string;
+    kind: "dm" | "group";
+    badgeCount?: number;
+}, candidates?: readonly ReadingCandidate[]): ConversationReadingView;

package/lib/runtime/conversationReading.js

@@ -0,0 +1,43 @@
+import { sourcesInConversation, unreadInConversation } from "./readIndex.js";
+/** One projection for indexed authority and observations awaiting indexing. A
+ * directory badge is optional compatibility metadata, never proof of coverage. */
+export function projectConversationReading(state, conversation, candidates = []) {
+    const sources = state ? sourcesInConversation(state, conversation.id) : [];
+    const sourceIds = new Set([conversation.id, ...sources.map(source => source.id)]);
+    const indexed = new Set(), messageReading = Object.create(null);
+    for (const source of sources)
+        for (const message of source.messages) {
+            indexed.add(message.id);
+            messageReading[message.id] = { seq: message.seq, readPolicy: message.readPolicy, read: message.recalled || message.from === state.profileId || !message.recipients.includes(state.profileId) || (message.readPolicy === "explicit" ? source.explicitReadMessageIds.includes(message.id) : message.seq <= source.readThroughSeq) };
+        }
+    const observed = new Map();
+    for (const intent of state?.observedReadIntents ?? [])
+        if (sourceIds.has(intent.threadId)) {
+            if (!observed.has(intent.messageId))
+                observed.set(intent.messageId, new Set());
+            observed.get(intent.messageId).add(intent.readPolicy);
+        }
+    const unique = new Map(candidates.filter(message => message.threadId === conversation.id).map(message => [message.id, message]));
+    let pendingMessages = 0, pendingMentions = 0, observedBadges = 0;
+    for (const message of unique.values()) {
+        const incoming = !message.mine && message.from !== state?.profileId && !message.recalled;
+        const attention = conversation.kind === "dm" || message.attentionEligible === true;
+        const policy = message.readPolicy ?? "visible";
+        const acknowledged = observed.get(message.id)?.has(policy) === true;
+        if (!indexed.has(message.id) && acknowledged)
+            messageReading[message.id] = { read: true, readPolicy: policy };
+        if (!incoming)
+            continue;
+        if (acknowledged && attention)
+            observedBadges++;
+        if (indexed.has(message.id) || acknowledged || message.unread !== true)
+            continue;
+        pendingMessages++;
+        if (message.attentionEligible === true)
+            pendingMentions++;
+    }
+    const authoritative = sources.length && state ? unreadInConversation(state, conversation.id) : undefined;
+    const unread = authoritative ? { unreadMessageCount: authoritative.unreadMessageCount + pendingMessages, unreadMentionCount: authoritative.unreadMentionCount + pendingMentions, badgeCount: authoritative.badgeCount + (conversation.kind === "group" ? pendingMentions : pendingMessages) } : undefined;
+    const pendingBadge = conversation.kind === "group" ? pendingMentions : pendingMessages;
+    return { messageReading, unread, badgeCount: unread?.badgeCount ?? (conversation.badgeCount === undefined ? undefined : Math.max(Math.max(0, conversation.badgeCount - observedBadges), pendingBadge)) };
+}

package/lib/runtime/createChat.d.ts

@@ -11,6 +11,8 @@ export type CreateChatOptions = {
     profileId: string;
     teamId: string;
     token: string;
+    /** Limit reconnect reconciliation for a dedicated conversation document. */
+    threadId?: string;
     endpoint?: string;
     clientInstanceId?: string;
     fetch?: typeof fetch;

package/lib/runtime/createChat.js

@@ -1,3 +1,4 @@
+import { isReadingControl } from "./readingContent.js";
 import { ChatSession } from "./chatSession.js";
 import { SocialReadClient } from "./socialReadClient.js";
 import { chatTeamId } from "./teamScope.js";
@@ -16,10 +17,20 @@ export function createChat(options) {
     };
     return new ChatSession({
         sharedConnection: options.connection,
+        activeThreadId: options.threadId,
         messages: { scope: { appId, accountId, profileId, teamId }, transport: { load: (thread, signal) => page(thread, signal), changes: (thread, after, signal) => page(thread, signal, { after }), older: (thread, before, signal) => page(thread, signal, { before }) }, onError },
         reading: { appId, profileId, sessionToken: token, hubHttpUrl: http, fetch: options.fetch, onError },
         connection: { appId, profileId, teamId, hubUrl: ws, clientInstanceId: options.clientInstanceId, fetchImpl: options.fetch,
             session: { token, identity: { accountId, app: appId, profileId } }, onNotification: options.onNotification, onReach: options.onReach },
+        readingCandidate: message => {
+            if (isReadingControl(message.body, appId))
+                return undefined;
+            const body = message.body;
+            if (!body || !["message", "quote"].includes(String(body.kind)) && !(body.kind === "contact" && ["friendRequest", "requestFriend"].includes(String(body.action))))
+                return undefined;
+            return { id: message.id, threadId: message.threadId, from: message.from, mine: message.from === profileId, recalled: message.recalled, unread: message.from !== profileId,
+                readPolicy: body?.contentKind === "voice" ? "explicit" : "visible", attentionEligible: Array.isArray(body.content?.mentions) && body.content.mentions.some(mention => mention?.id === profileId) };
+        },
         decode: message => decodeIncoming(message, { appId, profileId, teamId }), onError,
     });
 }
@@ -27,13 +38,15 @@ function decodeIncoming(message, scope) {
     if (message.opcode !== 1 || !message.body || typeof message.body !== "object")
         return;
     const body = message.body;
-    if (body.kind !== "message" || body.content?.appId !== scope.appId || chatTeamId(body) !== scope.teamId)
+    const invitation = body.kind === "contact" && ["friendRequest", "requestFriend"].includes(String(body.action));
+    if ((!invitation && body.kind !== "message") || (invitation ? body.payload?.appId : body.content?.appId) !== scope.appId || chatTeamId(body) !== scope.teamId)
         return;
-    if (body.threadKind !== "dm" && body.threadKind !== "group")
+    const threadKind = invitation ? "dm" : body.threadKind;
+    if (threadKind !== "dm" && threadKind !== "group")
         return;
-    if (body.threadKind === "dm" && message.from !== scope.profileId && message.to !== scope.profileId)
+    if (threadKind === "dm" && message.from !== scope.profileId && message.to !== scope.profileId)
         return;
-    const threadId = body.threadKind === "dm" ? dmThreadId(scope.appId, message.from, message.to, scope.teamId) : groupThreadId(scope.appId, message.to, scope.teamId);
-    return { appId: scope.appId, teamId: scope.teamId, threadId, threadKind: body.threadKind, messageId: message.hash, id: message.hash,
+    const threadId = threadKind === "dm" ? dmThreadId(scope.appId, message.from, message.to, scope.teamId) : groupThreadId(scope.appId, message.to, scope.teamId);
+    return { appId: scope.appId, teamId: scope.teamId, threadId, threadKind, messageId: message.hash, id: message.hash,
         timestamp: message.t, serverCreatedAt: message.t, clientCreatedAt: message.t, from: message.from, to: message.to, body: message.body, recipients: message.recipients };
 }

package/lib/runtime/durableSender.d.ts

@@ -8,13 +8,30 @@ export type OutgoingMessage = {
     message: ChatRuntimeMessage;
     status: "sending" | "failed" | "sent";
     confirmed?: boolean;
+    accessVersion?: number;
+};
+export type SenderScopeAccess = {
+    version: number;
+    allowed: boolean;
+};
+export type DurableSenderOptions = {
+    indexedDB?: IDBFactory;
+    name?: string;
+    access?: () => Promise<SenderScopeAccess>;
 };
 /** Persists the exact wire message before sending; retries preserve its hash. */
 export declare class DurableChatSender {
     private client;
     private onError;
+    private options;
     private db;
     private outbox;
+    private epochs;
+    private version;
+    private withdrawn;
+    private revoking?;
+    private channel?;
+    private accepted;
     private scope;
     private identity;
     private values;
@@ -22,12 +39,19 @@ export declare class DurableChatSender {
     private listeners;
     private running;
     private closed;
+    private closing;
+    private empty;
     private offConnection;
     private ready;
-    constructor(client: ChatClient, scope: MessageScope, onError: (error: unknown) => void, options?: {
-        indexedDB?: IDBFactory;
-        name?: string;
-    });
+    constructor(client: ChatClient, scope: MessageScope, onError: (error: unknown) => void, options?: DurableSenderOptions);
+    private readAccess;
+    private restore;
+    private checkAccess;
+    private withEpoch;
+    private deleteRows;
+    /** Stop disclosure immediately; durable invalidation is coordinated separately. */
+    withdraw(): void;
+    revoke(targetVersion?: number): Promise<void>;
     initialize(): Promise<void>;
     subscribe(listener: () => void): () => void;
     snapshot(threadId?: string): readonly OutgoingMessage[];

package/lib/runtime/durableSender.js

@@ -5,8 +5,15 @@ import { messageScopeKey } from "./messageStore.js";
 export class DurableChatSender {
     client;
     onError;
+    options;
     db;
     outbox;
+    epochs;
+    version = 0;
+    withdrawn = false;
+    revoking;
+    channel;
+    accepted = new Set();
     scope;
     identity;
     values = new Map();
@@ -14,30 +21,129 @@ export class DurableChatSender {
     listeners = new Set();
     running = new Map();
     closed = false;
+    closing = false;
+    empty = [];
     offConnection;
     ready;
     constructor(client, scope, onError, options = {}) {
         this.client = client;
         this.onError = onError;
+        this.options = options;
         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.db.version(2).stores({ scopeEpochs: "scope" });
         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.epochs = this.db.table("scopeEpochs");
+        this.db.on("versionchange", () => { this.db.close({ disableAutoOpen: false }); return false; });
+        this.ready = this.restore();
+        void this.ready.catch(() => { });
+        if (typeof BroadcastChannel !== "undefined") {
+            this.channel = new BroadcastChannel(`pmate-chat-outbox:${this.scope}:${this.db.name}`);
+            this.channel.onmessage = event => { if (Number.isSafeInteger(event.data?.version) && event.data.version > this.version)
+                this.withdraw(); };
+        }
         this.offConnection = client.watchConnection(state => {
             if (state === "connected")
                 void this.resume().catch(onError);
         });
     }
+    async readAccess() {
+        const access = await this.options.access?.();
+        if (access && (!Number.isSafeInteger(access.version) || access.version < 0 || typeof access.allowed !== "boolean"))
+            throw new Error("INVALID_OUTBOX_ACCESS");
+        return access;
+    }
+    async restore() {
+        const access = await this.readAccess();
+        const loaded = await this.db.transaction("rw", this.outbox, this.epochs, async () => {
+            const current = (await this.epochs.get(this.scope))?.version ?? 0;
+            const version = access?.version ?? current;
+            if (version < current)
+                throw new Error("OUTBOX_SCOPE_CHANGED");
+            if (version > current) {
+                await this.epochs.put({ scope: this.scope, version });
+                await this.deleteRows();
+            }
+            return { version, advanced: version > current, records: access?.allowed === false ? [] : await this.outbox.where("scope").equals(this.scope).toArray() };
+        });
+        this.version = loaded.version;
+        if (loaded.advanced)
+            this.channel?.postMessage({ version: this.version });
+        if (this.closed || this.withdrawn)
+            return;
+        const current = await this.readAccess();
+        if (current && (!current.allowed || current.version !== this.version))
+            return;
+        loaded.records.filter(record => !record.confirmed && (record.accessVersion ?? 0) === this.version).forEach(record => this.values.set(record.hash, record));
+        this.emit();
+    }
+    async checkAccess() {
+        if (this.closed)
+            throw new Error("CHAT_SENDER_CLOSED");
+        if (this.withdrawn)
+            throw new Error("OUTBOX_ACCESS_REVOKED");
+        const access = await this.readAccess();
+        if (access && access.version !== this.version) {
+            this.withdraw();
+            throw new Error("OUTBOX_SCOPE_CHANGED");
+        }
+        if (access && !access.allowed)
+            throw new Error("OUTBOX_ACCESS_REVOKED");
+    }
+    async withEpoch(mode, operation) {
+        await this.checkAccess();
+        try {
+            return await this.db.transaction(mode, this.outbox, this.epochs, async () => {
+                if (this.closed || this.withdrawn)
+                    throw new Error("OUTBOX_ACCESS_REVOKED");
+                if (((await this.epochs.get(this.scope))?.version ?? 0) !== this.version)
+                    throw new Error("OUTBOX_SCOPE_CHANGED");
+                return operation();
+            });
+        }
+        catch (error) {
+            if (String(error).includes("OUTBOX_SCOPE_CHANGED"))
+                this.withdraw();
+            throw error;
+        }
+    }
+    deleteRows() { return this.outbox.where("[scope+hash]").between([this.scope, Dexie.minKey], [this.scope, Dexie.maxKey], true, true).delete(); }
+    /** Stop disclosure immediately; durable invalidation is coordinated separately. */
+    withdraw() {
+        this.withdrawn = true;
+        this.values.clear();
+        this.emit();
+    }
+    revoke(targetVersion) {
+        if (this.closed || this.closing)
+            return Promise.reject(new Error("CHAT_SENDER_CLOSED"));
+        if (this.revoking)
+            return this.revoking;
+        this.withdraw();
+        return this.revoking = (async () => {
+            await this.ready.catch(error => { if (!String(error).includes("OUTBOX_SCOPE_CHANGED"))
+                throw error; });
+            const version = await this.db.transaction("rw", this.outbox, this.epochs, async () => {
+                const current = (await this.epochs.get(this.scope))?.version ?? 0;
+                const target = targetVersion ?? this.version + 1;
+                if (!Number.isSafeInteger(target) || target < 0)
+                    throw new Error("INVALID_OUTBOX_EPOCH");
+                if (current >= target)
+                    return current;
+                await this.epochs.put({ scope: this.scope, version: target });
+                await this.deleteRows();
+                return target;
+            });
+            this.channel?.postMessage({ version });
+        })();
+    }
     initialize() { return this.ready; }
     subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
     snapshot(threadId) {
+        if (this.closed || this.closing || this.withdrawn)
+            return this.empty;
         let snapshot = this.snapshots.get(threadId);
         if (!snapshot) {
             snapshot = [...this.values.values()].filter(record => threadId === undefined || record.threadId === threadId);
@@ -50,7 +156,8 @@ export class DurableChatSender {
     /** 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));
+        if (!this.closed && !this.closing && !this.withdrawn)
+            void this.retry(message.hash).catch(error => this.onError(error));
         return message;
     }
     /** Compatibility API: resolves only after transport delivery. */
@@ -58,23 +165,27 @@ export class DurableChatSender {
         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;
+    persistOutgoing(threadId, input) {
+        if (this.closed || this.closing || this.withdrawn)
+            return Promise.reject(new Error("OUTBOX_ACCESS_REVOKED"));
+        const pending = (async () => {
+            await this.ready;
+            await this.checkAccess();
+            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", accessVersion: this.version };
+            await this.withEpoch("rw", async () => { await this.outbox.put(record); });
+            await this.checkAccess();
+            this.values.set(record.hash, record);
+            this.emit();
+            return message;
+        })().finally(() => this.accepted.delete(pending));
+        this.accepted.add(pending);
+        return pending;
     }
     retry(hash) {
-        if (this.closed)
+        if (this.closed || this.closing || this.withdrawn)
             return Promise.reject(new Error("CHAT_SENDER_CLOSED"));
         const running = this.running.get(hash);
         if (running)
@@ -85,8 +196,8 @@ export class DurableChatSender {
     }
     async transmit(hash) {
         await this.ready;
-        const record = await this.outbox.get([this.scope, hash]);
-        if (!record || this.closed)
+        const record = await this.withEpoch("r", async () => this.outbox.get([this.scope, hash]));
+        if (!record || this.closed || this.withdrawn)
             throw new Error("OUTGOING_MESSAGE_UNAVAILABLE");
         if (record.status === "sent" || record.confirmed)
             return record.message;
@@ -96,6 +207,7 @@ export class DurableChatSender {
             if (!latest || latest.confirmed || latest.status === "sent")
                 return latest?.message ?? record.message;
         }
+        await this.checkAccess();
         if (this.values.get(hash)?.status !== "sending") {
             this.values.set(hash, sending);
             this.emit();
@@ -104,7 +216,7 @@ export class DurableChatSender {
             const message = await this.client.sendPrepared(record.message);
             const sent = { ...record, message, status: "sent" };
             const committed = await this.save(sent);
-            if (!this.closed) {
+            if (!this.closed && !this.withdrawn) {
                 if (committed?.confirmed || !committed)
                     this.values.delete(hash);
                 else
@@ -114,7 +226,7 @@ export class DurableChatSender {
             return message;
         }
         catch (error) {
-            if (!this.closed) {
+            if (!this.closed && !this.withdrawn) {
                 const failed = { ...record, status: "failed" };
                 const committed = await this.save(failed);
                 if (committed?.confirmed || committed?.status === "sent") {
@@ -132,7 +244,7 @@ export class DurableChatSender {
         }
     }
     async save(record) {
-        return this.db.transaction("rw", this.outbox, async () => {
+        return this.withEpoch("rw", async () => {
             const previous = await this.outbox.get([this.scope, record.hash]);
             if (!previous || previous.confirmed || previous.status === "sent")
                 return previous;
@@ -143,10 +255,13 @@ export class DurableChatSender {
     /** 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) {
+        hashes = [...new Set(hashes)];
+        if (!hashes.length)
+            return;
         await this.ready;
-        await this.db.transaction("rw", this.outbox, async () => {
+        await this.withEpoch("rw", 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 }));
+            const confirmed = previous.filter((record) => Boolean(record && !record.confirmed)).map(record => ({ ...record, status: "sent", confirmed: true }));
             if (confirmed.length)
                 await this.outbox.bulkPut(confirmed);
         });
@@ -158,12 +273,12 @@ export class DurableChatSender {
     }
     async resume() {
         await this.ready;
-        if (this.closed)
+        if (this.closed || this.closing || this.withdrawn)
             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)
+                if (this.closed || this.withdrawn)
                     return;
                 try {
                     await this.retry(record.hash);
@@ -174,11 +289,20 @@ export class DurableChatSender {
             }
     }
     async close() {
-        this.closed = true;
+        this.closing = true;
         this.offConnection();
         this.listeners.clear();
-        await this.ready;
-        await Promise.allSettled([...this.running.values()]);
-        this.db.close();
+        this.channel?.close();
+        this.channel = undefined;
+        try {
+            await this.ready;
+            await Promise.allSettled([...this.accepted, ...this.running.values(), ...(this.revoking ? [this.revoking] : [])]);
+        }
+        finally {
+            this.closed = true;
+            this.values.clear();
+            this.snapshots.clear();
+            this.db.close();
+        }
     }
 }

package/lib/runtime/index.d.ts

@@ -29,3 +29,6 @@ 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 } from "./messageTimeline.js";

package/lib/runtime/index.js

@@ -29,3 +29,6 @@ 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";

package/lib/runtime/messageClient.d.ts

@@ -15,6 +15,8 @@ export type MessageTransport<T> = {
 export type MessageSnapshot<T> = {
     messages: readonly T[];
     hasEarlier: boolean;
+    resetVersion: number;
+    complete: boolean;
 };
 export type MessageClientOptions<T extends StoredMessage> = {
     scope: MessageScope;
@@ -27,12 +29,15 @@ export type MessageClientOptions<T extends StoredMessage> = {
     syncWindowMs?: number;
     transactionBytes?: number;
     queueBytes?: number;
+    freshnessMs?: 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 accessListeners;
+    private allListeners;
     private reads;
     private syncing;
     private paging;
@@ -50,12 +55,32 @@ 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;
+    }>;
     getSnapshot(thread: string): MessageSnapshot<T> | undefined;
     subscribe(thread: string, listener: () => void): () => void;
-    read(thread: string, limit?: number): Promise<MessageSnapshot<T>>;
+    subscribeAll(listener: (threadId: string) => void): () => void;
+    /** Close the connection gap for saved windows with four bounded background lanes. */
+    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>;
@@ -68,11 +93,11 @@ export declare class MessageClient<T extends StoredMessage> {
     earlier(thread: string, before: {
         timestamp: number;
         id: string;
-    }, limit?: number): Promise<{
-        messages: T[];
-        hasEarlier: boolean;
-    }>;
+    }, limit?: number): 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>;
 }