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

package/lib/runtime/messageReaders.d.ts

@@ -1,3 +1,5 @@
+import { type ResponseCacheAccess } from "./responseCache.js";
+import { type MessageScope } from "./messageStore.js";
 export type MessageReadersPage = {
     appId: string;
     threadId: string;
@@ -21,6 +23,9 @@ export type MessageReadersOptions = {
     token: string;
     hubHttpUrl: string;
     fetch?: typeof fetch;
+    scope?: MessageScope;
+    access?: ResponseCacheAccess;
+    onError?: (error: unknown) => void;
 };
 export declare class MessageReadersError extends Error {
     readonly status: number;
@@ -32,8 +37,14 @@ export declare class MessageReadersClient {
     private options;
     private pending;
     private lifetime;
+    private cache?;
+    private revoked;
+    private generation;
     constructor(options: MessageReadersOptions);
     getReaders(query: MessageReadersQuery, signal?: AbortSignal): Promise<MessageReadersPage>;
+    private cachedRequest;
     private request;
-    close(): void;
+    withdraw(): void;
+    retireScope(version: number): Promise<void>;
+    close(): Promise<void>;
 }

package/lib/runtime/messageReaders.js

@@ -1,3 +1,6 @@
+import { isOffline } from "./connectivity.js";
+import { IndexedDbResponseCache, isResponseCacheAuthorityError, assertResponseCacheAccess } from "./responseCache.js";
+import { messageScopeKey } from "./messageStore.js";
 export class MessageReadersError extends Error {
     status;
     forbidden;
@@ -12,7 +15,17 @@ export class MessageReadersClient {
     options;
     pending = new Map();
     lifetime = new AbortController();
-    constructor(options) { this.options = { ...options }; }
+    cache;
+    revoked = false;
+    generation = 0;
+    constructor(options) {
+        this.options = { ...options };
+        if (options.scope) {
+            if (options.scope.appId !== options.appId || options.scope.profileId !== options.profileId)
+                throw new Error("MESSAGE_READERS_SCOPE_MISMATCH");
+            this.cache = new IndexedDbResponseCache(messageScopeKey(options.scope), { access: options.access });
+        }
+    }
     getReaders(query, signal) {
         if (this.lifetime.signal.aborted)
             return Promise.reject(new Error("MESSAGE_READERS_CLOSED"));
@@ -24,7 +37,7 @@ export class MessageReadersClient {
         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)
+            task = this.cachedRequest(input, key).finally(() => { if (this.pending.get(key) === task)
                 this.pending.delete(key); });
             this.pending.set(key, task);
         }
@@ -37,7 +50,54 @@ export class MessageReadersClient {
             task.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
         });
     }
+    async cachedRequest(input, key) {
+        // Keep only the standard SDK window. Arbitrary page sizes must not multiply
+        // durable cache entries. Revision is part of the key, so changed counts do
+        // not reuse a page from a previous membership/read projection.
+        const cache = input.limit === 50 ? this.cache : undefined;
+        if (!cache)
+            return this.request(input);
+        const stored = await cache.read(key).catch(error => { if (isResponseCacheAuthorityError(error))
+            throw error; this.options.onError?.(error); return undefined; });
+        if (this.lifetime.signal.aborted)
+            throw new Error("MESSAGE_READERS_CLOSED");
+        const generation = this.generation;
+        const cached = this.revoked ? undefined : stored?.cached;
+        if (cached && (Date.now() - cached.time < 5000 || (typeof navigator !== "undefined" && navigator.onLine === false)))
+            return structuredClone(cached.value);
+        let value;
+        try {
+            value = await this.request(input);
+        }
+        catch (error) {
+            if (error instanceof MessageReadersError && error.forbidden) {
+                this.revoked = true;
+                this.generation++;
+                await this.cache?.invalidate().catch(failure => this.options.onError?.(failure));
+                throw error;
+            }
+            if (cached && !this.revoked && generation === this.generation && !this.lifetime.signal.aborted && (error instanceof TypeError || (error instanceof MessageReadersError && error.status >= 500)))
+                return structuredClone(cached.value);
+            throw error;
+        }
+        if (generation !== this.generation)
+            throw new Error("MESSAGE_READERS_INVALIDATED");
+        this.revoked = false;
+        if (value.resetRequired)
+            await cache?.invalidate().catch(error => this.options.onError?.(error));
+        else if (stored)
+            await cache?.write(key, value, stored.epoch).catch(error => { if (isResponseCacheAuthorityError(error))
+                throw error; this.options.onError?.(error); });
+        if (this.lifetime.signal.aborted)
+            throw new Error("MESSAGE_READERS_CLOSED");
+        return value;
+    }
     async request(input) {
+        const scopeVersion = this.options.access ? await assertResponseCacheAccess(this.options.access) : undefined;
+        if (this.lifetime.signal.aborted)
+            throw new Error("MESSAGE_READERS_CLOSED");
+        if (isOffline())
+            throw new MessageReadersError(0, "MESSAGE_READERS_OFFLINE_UNAVAILABLE");
         const { token, fetch: fetcher, hubHttpUrl, appId, profileId } = this.options;
         const controller = new AbortController();
         const cancel = () => controller.abort(this.lifetime.signal.reason);
@@ -60,6 +120,8 @@ export class MessageReadersClient {
                 throw new Error("INVALID_MESSAGE_READERS_RESPONSE");
             if (this.lifetime.signal.aborted)
                 throw new Error("MESSAGE_READERS_CLOSED");
+            if (this.options.access)
+                await assertResponseCacheAccess(this.options.access, scopeVersion);
             return data;
         }
         finally {
@@ -67,5 +129,7 @@ export class MessageReadersClient {
             this.lifetime.signal.removeEventListener("abort", cancel);
         }
     }
-    close() { this.lifetime.abort(); this.pending.clear(); }
+    withdraw() { this.lifetime.abort(); this.pending.clear(); }
+    retireScope(version) { return this.cache?.retire(version) ?? Promise.resolve(); }
+    close() { this.lifetime.abort(); this.pending.clear(); return this.cache?.close().catch(error => this.options.onError?.(error)) ?? Promise.resolve(); }
 }

package/lib/runtime/messageStore.d.ts

@@ -15,6 +15,15 @@ export type MessageCoverage = {
     checkpoint?: string;
     complete: boolean;
     nextBefore?: string | null;
+    syncedAt?: number;
+    resetVersion?: number;
+    revoked?: boolean;
+    scopeVersion?: number;
+};
+export type MessageScopeAccess = {
+    scope: string;
+    version: number;
+    revoked: boolean;
 };
 type CoverageRow = MessageCoverage & {
     scope: string;
@@ -27,21 +36,47 @@ export declare class IndexedDbMessageStore<T extends StoredMessage> {
     private merge;
     private db;
     private rows;
+    private legacy;
     private coverage;
+    private accessRows;
     private key;
     constructor(scope: MessageScope, merge: (previous: T | undefined, incoming: T) => T, options?: {
         indexedDB?: IDBFactory;
         name?: string;
     });
+    get namespace(): string;
     read(thread: string, limit?: number, before?: {
         timestamp: number;
         id: string;
     }): Promise<{
         messages: T[];
         hasEarlier: boolean;
-        coverage: CoverageRow | undefined;
+        coverage: MessageCoverage | undefined;
+    }>;
+    /** Migration records never claim coverage or overwrite authoritative rows. */
+    importLegacy(thread: string, messages: T[]): Promise<number>;
+    /** Bounded fallback only; callers must report an incomplete window. */
+    readFallback(thread: string, limit?: number, before?: {
+        timestamp: number;
+        id: string;
+    }): Promise<{
+        messages: T[];
+        hasEarlier: boolean;
+        coverage: MessageCoverage | undefined;
     }>;
-    commit(thread: string, messages: T[], coverage?: MessageCoverage): Promise<number>;
+    commit(thread: string, messages: T[], coverage?: MessageCoverage, guard?: {
+        version: number;
+        authoritative?: boolean;
+        scopeVersion?: number;
+    }): Promise<number>;
+    windows(): Promise<CoverageRow[]>;
+    scopeAccess(): Promise<MessageScopeAccess>;
+    private scopedCoverage;
+    private clearScopeRows;
+    /** Persist the denial first; failed cleanup must never make cached rows readable. */
+    revokeScope(expectedVersion?: number): Promise<number>;
+    /** A durable epoch prevents another tab's pre-reset request from restoring rows. */
+    resetThread(thread: string, revoked?: boolean, scopeVersion?: number): Promise<number>;
     removeThread(thread: string): Promise<void>;
     clear(): Promise<void>;
     close(): void;

package/lib/runtime/messageStore.js

@@ -6,63 +6,203 @@ export class IndexedDbMessageStore {
     merge;
     db;
     rows;
+    legacy;
     coverage;
+    accessRows;
     key;
     constructor(scope, merge, options = {}) {
         this.merge = merge;
         this.key = messageScopeKey(scope);
         this.db = new Dexie(options.name ?? "pmate-chat-messages", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
         this.db.version(1).stores({ messages: "[scope+thread+id],[scope+thread+time+id],[scope+thread],scope", coverage: "[scope+thread],scope" });
+        this.db.version(2).stores({ legacyMessages: "[scope+thread+id],[scope+thread+time+id],[scope+thread],scope" });
+        this.db.version(3).stores({ scopeAccess: "scope" });
+        this.accessRows = this.db.table("scopeAccess");
+        this.legacy = this.db.table("legacyMessages");
         this.rows = this.db.table("messages");
         this.coverage = this.db.table("coverage");
         this.db.on("versionchange", () => { this.db.close({ disableAutoOpen: false }); return false; });
     }
+    get namespace() { return this.db.name; }
     async read(thread, limit = 100, before) {
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
             throw new Error("INVALID_MESSAGE_LIMIT");
-        return this.db.transaction("r", this.rows, this.coverage, async () => {
+        return this.db.transaction("r", this.rows, this.coverage, this.accessRows, async () => {
+            const access = await this.scopeAccess();
+            if (access.revoked)
+                return { messages: [], hasEarlier: false, coverage: { complete: false, revoked: true, resetVersion: 0, scopeVersion: access.version } };
             const range = this.rows.where("[scope+thread+time+id]").between([this.key, thread, Dexie.minKey, Dexie.minKey], [this.key, thread, before?.timestamp ?? Dexie.maxKey, before?.id ?? Dexie.maxKey], true, !before);
             const records = await range.reverse().limit(limit + 1).toArray();
-            return { messages: records.slice(0, limit).reverse().map(row => row.value), hasEarlier: records.length > limit, coverage: await this.coverage.get([this.key, thread]) };
+            return { messages: records.slice(0, limit).reverse().map(row => row.value), hasEarlier: records.length > limit, coverage: this.scopedCoverage(await this.coverage.get([this.key, thread]), access) };
         });
     }
-    async commit(thread, messages, coverage) {
+    /** Migration records never claim coverage or overwrite authoritative rows. */
+    async importLegacy(thread, messages) {
+        if (messages.length > 128)
+            throw new Error("MESSAGE_BATCH_TOO_LARGE");
+        let bytes = 0;
+        for (const message of messages) {
+            if (message.threadId !== thread || !message.id || !Number.isFinite(message.timestamp))
+                throw new Error("MESSAGE_SCOPE_MISMATCH");
+            bytes += new TextEncoder().encode(JSON.stringify(message)).byteLength;
+            if (bytes > 1_048_576)
+                throw new Error("MESSAGE_BATCH_TOO_LARGE");
+        }
+        return this.db.transaction("rw", this.rows, this.legacy, this.coverage, this.accessRows, async () => {
+            const access = await this.scopeAccess();
+            const coverage = await this.coverage.get([this.key, thread]);
+            if (access.revoked || coverage?.revoked)
+                throw new Error("MESSAGE_ACCESS_REVOKED");
+            if (access.version > 0)
+                throw new Error("MESSAGE_PROJECTION_CHANGED");
+            if ((coverage?.resetVersion ?? 0) > 0)
+                throw new Error("MESSAGE_PROJECTION_CHANGED");
+            const ids = [...new Set(messages.map(message => message.id))], keys = ids.map(id => [this.key, thread, id]);
+            const authoritative = await this.rows.bulkGet(keys), previous = await this.legacy.bulkGet(keys);
+            const known = new Set(authoritative.flatMap(row => row ? [row.id] : []));
+            const latest = new Map(previous.flatMap(row => row ? [[row.id, row.value]] : [])), changed = new Map();
+            for (const message of messages) {
+                if (known.has(message.id))
+                    continue;
+                const old = latest.get(message.id), value = this.merge(old, message);
+                if (value.id !== message.id || value.threadId !== thread || !Number.isFinite(value.timestamp))
+                    throw new Error("MESSAGE_SCOPE_MISMATCH");
+                latest.set(message.id, value);
+                if (JSON.stringify(old) !== JSON.stringify(value))
+                    changed.set(message.id, { scope: this.key, thread, id: value.id, time: value.timestamp, value });
+            }
+            if (changed.size)
+                await this.legacy.bulkPut([...changed.values()]);
+            return changed.size;
+        });
+    }
+    /** Bounded fallback only; callers must report an incomplete window. */
+    async readFallback(thread, limit = 100, before) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error("INVALID_MESSAGE_LIMIT");
+        return this.db.transaction("r", this.rows, this.legacy, this.coverage, this.accessRows, async () => {
+            const access = await this.scopeAccess();
+            const coverage = access.revoked ? { complete: false, revoked: true, resetVersion: 0, scopeVersion: access.version } : this.scopedCoverage(await this.coverage.get([this.key, thread]), access);
+            if (coverage?.revoked)
+                return { messages: [], hasEarlier: false, coverage };
+            const read = (table) => table.where("[scope+thread+time+id]").between([this.key, thread, Dexie.minKey, Dexie.minKey], [this.key, thread, before?.timestamp ?? Dexie.maxKey, before?.id ?? Dexie.maxKey], true, !before).reverse().limit(limit + 1).toArray();
+            const [canonical, legacy] = await Promise.all([read(this.rows), read(this.legacy)]);
+            const rows = [...new Map([...legacy, ...canonical].map(row => [row.id, row])).values()].sort((a, b) => a.time - b.time || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            return { messages: rows.slice(-limit).map(row => row.value), hasEarlier: rows.length > limit, coverage };
+        });
+    }
+    async commit(thread, messages, coverage, guard) {
         for (const message of messages)
             if (message.threadId !== thread || !message.id || !Number.isFinite(message.timestamp))
                 throw new Error("MESSAGE_SCOPE_MISMATCH");
         if (messages.length > 1000)
             throw new Error("MESSAGE_BATCH_TOO_LARGE");
-        return this.db.transaction("rw", this.rows, this.coverage, async () => {
+        return this.db.transaction("rw", this.rows, this.legacy, this.coverage, this.accessRows, async () => {
+            const access = await this.scopeAccess();
+            if ((guard?.scopeVersion ?? 0) !== access.version)
+                throw new Error("MESSAGE_SCOPE_CHANGED");
+            if (access.revoked) {
+                if (!guard?.authoritative)
+                    throw new Error("MESSAGE_ACCESS_REVOKED");
+                await this.clearScopeRows();
+                await this.accessRows.put({ ...access, revoked: false });
+            }
+            const current = await this.coverage.get([this.key, thread]);
+            if (guard && (current?.resetVersion ?? 0) !== guard.version)
+                throw new Error("MESSAGE_PROJECTION_CHANGED");
+            if (guard && current?.revoked && !guard.authoritative)
+                throw new Error("MESSAGE_ACCESS_REVOKED");
             const ids = [...new Set(messages.map(message => message.id))];
-            const previous = await this.rows.bulkGet(ids.map(id => [this.key, thread, id]));
-            const latest = new Map(previous.flatMap(row => row ? [[row.id, row.value]] : []));
+            const keys = ids.map(id => [this.key, thread, id]);
+            const previous = await this.rows.bulkGet(keys), legacy = await this.legacy.bulkGet(keys);
+            const canonicalIds = new Set(previous.flatMap(row => row ? [row.id] : []));
+            const latest = new Map([...legacy, ...previous].flatMap(row => row ? [[row.id, row.value]] : []));
             const changed = new Map();
             for (const message of messages) {
                 const old = latest.get(message.id), value = this.merge(old, message);
                 if (value.id !== message.id || value.threadId !== thread || !Number.isFinite(value.timestamp))
                     throw new Error("MESSAGE_SCOPE_MISMATCH");
                 latest.set(message.id, value);
-                if (JSON.stringify(old) !== JSON.stringify(value))
+                if (!canonicalIds.has(message.id) || JSON.stringify(old) !== JSON.stringify(value))
                     changed.set(message.id, { scope: this.key, thread, id: value.id, time: value.timestamp, value });
             }
             if (changed.size)
                 await this.rows.bulkPut([...changed.values()]);
+            const replaced = legacy.flatMap(row => row ? [[this.key, thread, row.id]] : []);
+            if (replaced.length)
+                await this.legacy.bulkDelete(replaced);
             if (coverage) {
-                const old = await this.coverage.get([this.key, thread]), next = { ...coverage, scope: this.key, thread };
+                const old = await this.coverage.get([this.key, thread]), next = { ...old, ...coverage, scope: this.key, thread };
                 if (JSON.stringify(old) !== JSON.stringify(next))
                     await this.coverage.put(next);
             }
             return changed.size;
         });
     }
+    async windows() {
+        return this.db.transaction("r", this.coverage, this.accessRows, async () => {
+            if ((await this.scopeAccess()).revoked)
+                return [];
+            return this.coverage.where("scope").equals(this.key).toArray();
+        });
+    }
+    async scopeAccess() {
+        const access = (await this.accessRows.get(this.key)) ?? { scope: this.key, version: 0, revoked: false };
+        if (!Number.isSafeInteger(access.version) || access.version < 0 || typeof access.revoked !== "boolean")
+            throw new Error("INVALID_MESSAGE_SCOPE_ACCESS");
+        return access;
+    }
+    scopedCoverage(coverage, access) {
+        return access.version ? { ...coverage, complete: coverage?.complete ?? false, scopeVersion: access.version } : coverage;
+    }
+    async clearScopeRows() {
+        await this.rows.where("[scope+thread+id]").between([this.key, Dexie.minKey, Dexie.minKey], [this.key, Dexie.maxKey, Dexie.maxKey], true, true).delete();
+        await this.legacy.where("[scope+thread+id]").between([this.key, Dexie.minKey, Dexie.minKey], [this.key, Dexie.maxKey, Dexie.maxKey], true, true).delete();
+        await this.coverage.where("[scope+thread]").between([this.key, Dexie.minKey], [this.key, Dexie.maxKey], true, true).delete();
+    }
+    /** Persist the denial first; failed cleanup must never make cached rows readable. */
+    async revokeScope(expectedVersion) {
+        const access = await this.db.transaction("rw", this.accessRows, async () => {
+            const old = await this.scopeAccess();
+            if (expectedVersion !== undefined && old.version !== expectedVersion)
+                return old;
+            const next = { scope: this.key, version: old.version + 1, revoked: true };
+            await this.accessRows.put(next);
+            return next;
+        });
+        await this.db.transaction("rw", this.rows, this.legacy, this.coverage, this.accessRows, async () => {
+            const current = await this.scopeAccess();
+            if (current.version === access.version && current.revoked)
+                await this.clearScopeRows();
+        });
+        return access.version;
+    }
+    /** A durable epoch prevents another tab's pre-reset request from restoring rows. */
+    async resetThread(thread, revoked = false, scopeVersion = 0) {
+        return this.db.transaction("rw", this.rows, this.legacy, this.coverage, this.accessRows, async () => {
+            const access = await this.scopeAccess();
+            if (access.version !== scopeVersion)
+                throw new Error("MESSAGE_SCOPE_CHANGED");
+            if (access.revoked)
+                throw new Error("MESSAGE_ACCESS_REVOKED");
+            const old = await this.coverage.get([this.key, thread]);
+            const resetVersion = (old?.resetVersion ?? 0) + 1;
+            await this.rows.where("[scope+thread]").equals([this.key, thread]).delete();
+            await this.legacy.where("[scope+thread]").equals([this.key, thread]).delete();
+            await this.coverage.put({ scope: this.key, thread, complete: false, resetVersion, revoked });
+            return resetVersion;
+        });
+    }
     async removeThread(thread) {
-        await this.db.transaction("rw", this.rows, this.coverage, async () => {
+        await this.db.transaction("rw", this.rows, this.legacy, this.coverage, this.accessRows, async () => {
             await this.rows.where("[scope+thread]").equals([this.key, thread]).delete();
+            await this.legacy.where("[scope+thread]").equals([this.key, thread]).delete();
             await this.coverage.delete([this.key, thread]);
         });
     }
     async clear() {
-        await this.db.transaction("rw", this.rows, this.coverage, async () => {
+        await this.db.transaction("rw", this.rows, this.legacy, this.coverage, this.accessRows, async () => {
+            await this.legacy.where("scope").equals(this.key).delete();
             await this.rows.where("scope").equals(this.key).delete();
             await this.coverage.where("scope").equals(this.key).delete();
         });

package/lib/runtime/messageTimeline.d.ts

@@ -0,0 +1,47 @@
+import type { StoredMessage } from "./messageStore.js";
+import type { OutgoingMessage } from "./durableSender.js";
+import type { ChatRuntimeMessage } from "./protocol.js";
+import type { MessageReadingState } from "./conversationReading.js";
+export type TimelineReactionEvent = Reaction & {
+    threadId: string;
+};
+export type TimelineReaction = {
+    emojiId: string;
+    userIds: string[];
+    mine: boolean;
+};
+export type TimelineItem<T> = {
+    id: string;
+    threadId: string;
+    timestamp: number;
+    from?: string;
+    mine: boolean;
+    status: "sending" | "sent" | "failed" | "read";
+    recalled: boolean;
+    message: T | undefined;
+    reading?: MessageReadingState;
+    reactions: readonly TimelineReaction[];
+    reactionEvents: readonly TimelineReactionEvent[];
+};
+type Reaction = {
+    id: string;
+    messageId: string;
+    from: string;
+    emojiId: string;
+    active: boolean;
+    revision: number;
+    timestamp: number;
+};
+/** Derives one display stream without copying bodies or creating another cache.
+ * Outgoing rows retain their wire identity; indexed rows take precedence. */
+export declare function projectMessageTimeline<T extends StoredMessage>(input: {
+    appId: string;
+    profileId: string;
+    threadId: string;
+    messages: readonly T[];
+    outgoing: readonly OutgoingMessage[];
+    decode: (message: ChatRuntimeMessage) => T | undefined;
+    reading: Readonly<Record<string, MessageReadingState>>;
+    previous?: readonly TimelineItem<T>[];
+}): readonly TimelineItem<T>[];
+export {};

package/lib/runtime/messageTimeline.js

@@ -0,0 +1,113 @@
+import { isReadingControl } from "./readingContent.js";
+function content(message, appId) {
+    const body = message.body;
+    return body?.kind === "message" && body.content?.appId === appId ? body : undefined;
+}
+function validReaction(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const event = value;
+    return [event.id, event.messageId, event.from, event.emojiId].every(field => typeof field === "string" && field.length > 0 && field.length <= 256) && typeof event.active === "boolean" && Number.isSafeInteger(event.revision) && event.revision >= 0 && Number.isFinite(event.timestamp);
+}
+/** Derives one display stream without copying bodies or creating another cache.
+ * Outgoing rows retain their wire identity; indexed rows take precedence. */
+export function projectMessageTimeline(input) {
+    const scoped = (message) => {
+        const value = message, body = value.body;
+        const app = body?.content?.appId ?? body?.payload?.appId;
+        return message.threadId === input.threadId && (value.appId === undefined || value.appId === input.appId) && (app === undefined || app === input.appId);
+    };
+    const records = new Map();
+    for (const pending of input.outgoing) {
+        if (pending.threadId !== input.threadId || pending.confirmed)
+            continue;
+        const message = input.decode(pending.message);
+        if (message && scoped(message))
+            records.set(message.id, { message, status: pending.status });
+    }
+    for (const message of input.messages)
+        if (scoped(message)) {
+            const legacy = message.legacyDisplay;
+            if (legacy && records.has(message.id))
+                continue;
+            const legacyStatus = legacy?.status;
+            const status = legacyStatus === "failed" || legacyStatus === "sending" || legacyStatus === "read" ? legacyStatus : "sent";
+            records.set(message.id, { message, status });
+        }
+    const recalled = new Map(), reactions = new Map();
+    const addReaction = (event) => {
+        const key = JSON.stringify([event.messageId, event.from, event.emojiId]), old = reactions.get(key);
+        if (!old || event.revision > old.revision || event.revision === old.revision && (event.timestamp > old.timestamp || event.timestamp === old.timestamp && event.id > old.id))
+            reactions.set(key, event);
+    };
+    for (const { message, status } of records.values()) {
+        if (status === "failed" && isReadingControl(message.body, input.appId))
+            continue;
+        const envelope = message, body = content(envelope, input.appId), target = body?.content?.recall?.messageId;
+        if (typeof target === "string" && target.length > 0 && target.length <= 256 && envelope.from) {
+            if (!recalled.has(target))
+                recalled.set(target, new Set());
+            recalled.get(target).add(envelope.from);
+        }
+        const reaction = body?.content?.reaction;
+        if (body?.contentKind === "text" && reaction?.version === 1 && typeof reaction.messageId === "string" && typeof reaction.emojiId === "string" && typeof reaction.active === "boolean" && typeof reaction.revision === "number" && reaction.revision >= 1 && envelope.from) {
+            const event = { id: message.id, messageId: reaction.messageId, from: envelope.from, emojiId: reaction.emojiId, active: reaction.active, revision: reaction.revision, timestamp: message.timestamp };
+            if (validReaction(event))
+                addReaction(event);
+        }
+        const events = envelope.reactionEvents ?? envelope.legacyDisplay?.reactionEvents;
+        if (Array.isArray(events))
+            for (const event of events)
+                if (validReaction(event) && event.messageId === message.id && (event.threadId === undefined || event.threadId === input.threadId))
+                    addReaction(event);
+        // Old display-only imports may have aggregates but no event IDs. Treat them
+        // as revision-zero baselines; any durable control supersedes them.
+        const baseline = envelope.legacyDisplay?.reactions;
+        if (Array.isArray(baseline))
+            for (const value of baseline) {
+                if (typeof value?.emojiId !== "string" || !Array.isArray(value.userIds))
+                    continue;
+                for (const from of value.userIds) {
+                    const event = { id: `legacy:${message.id}`, messageId: message.id, from, emojiId: value.emojiId, active: true, revision: 0, timestamp: 0 };
+                    if (validReaction(event))
+                        addReaction(event);
+                }
+            }
+    }
+    const groupedEvents = new Map();
+    for (const event of reactions.values()) {
+        const values = groupedEvents.get(event.messageId) ?? [];
+        values.push({ ...event, threadId: input.threadId });
+        groupedEvents.set(event.messageId, values);
+    }
+    for (const values of groupedEvents.values())
+        values.sort((a, b) => a.from < b.from ? -1 : a.from > b.from ? 1 : a.emojiId < b.emojiId ? -1 : a.emojiId > b.emojiId ? 1 : 0);
+    const grouped = new Map();
+    for (const event of reactions.values())
+        if (event.active) {
+            if (!grouped.has(event.messageId))
+                grouped.set(event.messageId, new Map());
+            const emojis = grouped.get(event.messageId);
+            if (!emojis.has(event.emojiId))
+                emojis.set(event.emojiId, new Set());
+            emojis.get(event.emojiId).add(event.from);
+        }
+    const previous = new Map(input.previous?.map(item => [item.id, item]) ?? []);
+    const result = [];
+    for (const { message, status } of records.values()) {
+        const envelope = message;
+        if (isReadingControl(envelope.body, input.appId))
+            continue;
+        const mine = envelope.from === input.profileId, reading = input.reading[message.id];
+        const withdrawn = Boolean(message.recalled || envelope.legacyDisplay?.recalled || envelope.from && recalled.get(message.id)?.has(envelope.from));
+        const item = { id: message.id, threadId: message.threadId, timestamp: message.timestamp, from: envelope.from, mine, status: !mine && reading ? (reading.read ? "read" : status === "read" ? "sent" : status) : status, recalled: withdrawn,
+            message: withdrawn ? undefined : message, reading, reactionEvents: withdrawn ? [] : groupedEvents.get(message.id) ?? [], reactions: withdrawn ? [] : [...(grouped.get(message.id) ?? [])].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([emojiId, users]) => { const userIds = [...users].sort(); return { emojiId, userIds, mine: userIds.includes(input.profileId) }; }) };
+        const old = previous.get(item.id);
+        const sameReading = old?.reading === item.reading || old?.reading?.seq === item.reading?.seq && old?.reading?.read === item.reading?.read && old?.reading?.readPolicy === item.reading?.readPolicy;
+        const sameReactions = old?.reactions.length === item.reactions.length && old.reactions.every((reaction, index) => { const next = item.reactions[index]; return reaction.emojiId === next.emojiId && reaction.mine === next.mine && reaction.userIds.length === next.userIds.length && reaction.userIds.every((user, i) => user === next.userIds[i]); });
+        const sameEvents = old?.reactionEvents.length === item.reactionEvents.length && old.reactionEvents.every((event, index) => { const next = item.reactionEvents[index]; return event.id === next.id && event.from === next.from && event.emojiId === next.emojiId && event.active === next.active && event.revision === next.revision && event.timestamp === next.timestamp && event.threadId === next.threadId && event.messageId === next.messageId; });
+        result.push(old && sameEvents && old.message === item.message && old.timestamp === item.timestamp && old.from === item.from && old.mine === item.mine && old.status === item.status && old.recalled === item.recalled && sameReading && sameReactions ? old : item);
+    }
+    result.sort((a, b) => a.timestamp - b.timestamp || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return input.previous?.length === result.length && result.every((item, index) => item === input.previous[index]) ? input.previous : result;
+}

package/lib/runtime/readCounts.d.ts

@@ -1,3 +1,5 @@
+import { type ResponseCacheAccess } from "./responseCache.js";
+import { type MessageScope } from "./messageStore.js";
 export type ReadCountsResult = {
     appId: string;
     threadId: string;
@@ -11,6 +13,8 @@ export type ReadCountsOptions = {
     clientInstanceId: string;
     hubHttpUrl: string;
     fetch?: typeof fetch;
+    scope?: MessageScope;
+    access?: ResponseCacheAccess;
     onChange: (value: ReadCountsResult) => void;
     onError?: (error: unknown) => void;
 };
@@ -25,13 +29,22 @@ export declare class ReadCountsClient {
     private generation;
     private retries;
     private closed;
+    private closing?;
     private revision;
     private running;
     private dirty;
     private subscribed;
     private subscriptionDenied;
     private subscriptionPending?;
+    private cache?;
+    private lastResult?;
+    private publish;
+    private revoked;
+    private accessVersion;
+    private requestedRevision;
+    private force;
     constructor(options: ReadCountsOptions);
+    private denyCache;
     private post;
     private subscription;
     private renew;
@@ -40,5 +53,6 @@ export declare class ReadCountsClient {
     reconnect(): void;
     private schedule;
     private refresh;
-    close(): void;
+    retireScope(version: number): Promise<void>;
+    close(): Promise<void>;
 }