@pmate/chat-sdk 0.12.0-next.4 → 0.12.0-next.40

package/lib/runtime/readIndex.js

@@ -1,5 +1,24 @@
 import { Dexie } from "dexie";
+import { isReadingControl } from "./readingContent.js";
 import { isValidChatTeamId } from "./thread.js";
+/** Retain read semantics without a second durable copy of message bodies. */
+export function readingMetadata(state) {
+    let changed = false;
+    const threads = state.threads.map(thread => {
+        let different = false;
+        const messages = thread.messages.map(message => {
+            if (message.payload === null && typeof message.readingControl === "boolean")
+                return message;
+            different = true;
+            return { ...message, payload: null, readingControl: Boolean(message.readingControl) || isReadingControl(message.payload, state.appId) };
+        });
+        if (!different)
+            return thread;
+        changed = true;
+        return { ...thread, messages };
+    });
+    return changed ? { ...state, threads } : state;
+}
 export class ReadSyncGap extends Error {
     cursor;
     constructor(cursor) {
@@ -153,31 +172,66 @@ export function coalesceReadOperations(current) {
     return [...batches.values()];
 }
 /** Counts are over the indexed message coverage, not an estimate of missing history. */
-export function unreadInThread(state, threadId) {
+export function unreadInThread(state, threadId, hidden) {
     const thread = state.threads.find(t => t.id === threadId);
     if (!thread)
         throw new Error("UNKNOWN_READ_THREAD");
     const explicit = new Set(thread.explicitReadMessageIds);
-    const messages = thread.messages.filter(message => !message.recalled && message.from !== state.profileId && message.recipients.includes(state.profileId)
+    const messages = thread.messages.filter(message => !message.recalled && !hidden?.get(message.id)?.has(message.from) && !(message.readingControl || isReadingControl(message.payload, state.appId)) && message.from !== state.profileId && message.recipients.includes(state.profileId)
         && (message.readPolicy === "explicit" ? !explicit.has(message.id) : message.seq > thread.readThroughSeq));
     const unreadMessageCount = messages.length;
     const unreadMentionCount = messages.filter(message => message.mentions.includes(state.profileId)).length;
     return { unreadMessageCount, unreadMentionCount, badgeCount: thread.kind === "group" ? unreadMentionCount : unreadMessageCount };
 }
+function readTeamVersion(versions, team) { return Object.hasOwn(versions, team) ? versions[team] : 0; }
+export function assertReadIndexVersions(expected, current = {}, teamId) {
+    const teams = new Set(teamId === undefined ? [...Object.keys(expected), ...Object.keys(current)] : [teamId]);
+    if ([...teams].some(team => readTeamVersion(expected, team) !== readTeamVersion(current, team)))
+        throw new Error("READ_SCOPE_CHANGED");
+}
+/** Remove only the withdrawn team's original sources, logical conversations and
+ * queued observations. Other teams' pending operations must survive. */
+export function removeReadTeam(state, teamId, knownThreadIds = []) {
+    const removed = new Set(knownThreadIds);
+    for (const thread of state.threads)
+        if (thread.teamId === teamId) {
+            removed.add(thread.id);
+            if (thread.conversationId)
+                removed.add(thread.conversationId);
+        }
+    return { ...state, syncCursor: "0", threads: state.threads.filter(thread => thread.teamId !== teamId && !removed.has(thread.id)),
+        pending: state.pending.filter(operation => !removed.has(operation.threadId)),
+        observedReadIntents: state.observedReadIntents?.filter(intent => !removed.has(intent.threadId)) };
+}
 /** Dexie preserves the legacy database/store and outbound [appId, profileId] keys. */
 export class IndexedDbReadIndex {
     storageScope;
+    migrateLegacy;
+    metadataOnly;
     database;
     profiles;
+    threadRows;
+    messageRows;
+    positionRows;
+    normalizedStates = new WeakSet();
+    versions;
     closed = false;
-    constructor(factory = globalThis.indexedDB, name = "pmate-social-read-index", storageScope) {
+    constructor(factory = globalThis.indexedDB, name = "pmate-social-read-index", storageScope, migrateLegacy = false, metadataOnly = false) {
         this.storageScope = storageScope;
+        this.migrateLegacy = migrateLegacy;
+        this.metadataOnly = metadataOnly;
         if (!factory)
             throw new Error("READ_STORAGE_UNAVAILABLE");
         this.database = new Dexie(name, { indexedDB: factory, IDBKeyRange: globalThis.IDBKeyRange });
         // The empty schema retains the legacy out-of-line primary key and records.
         this.database.version(1).stores({ profiles: "" });
+        this.database.version(2).stores({ profiles: "", versions: "" });
+        this.database.version(3).stores({ readThreads: "[owner+id],owner", readMessages: "[owner+thread+id],[owner+thread],owner", readPositions: "[owner+id],owner" });
+        this.positionRows = this.database.table("readPositions");
+        this.threadRows = this.database.table("readThreads");
+        this.messageRows = this.database.table("readMessages");
         this.profiles = this.database.table("profiles");
+        this.versions = this.database.table("versions");
         this.database.on("versionchange", () => { this.database.close({ disableAutoOpen: false }); return false; });
     }
     async transaction(mode, execute) {
@@ -186,7 +240,7 @@ export class IndexedDbReadIndex {
                 throw new Error("READ_STORAGE_CLOSED");
             let started = false;
             try {
-                return await this.database.transaction(mode, this.profiles, async () => {
+                return await this.database.transaction(mode, [this.profiles, this.versions, this.threadRows, this.messageRows, this.positionRows], async () => {
                     if (this.closed)
                         throw new Error("READ_STORAGE_CLOSED");
                     started = true;
@@ -205,17 +259,190 @@ export class IndexedDbReadIndex {
         throw new Error("READ_STORAGE_UNAVAILABLE");
     }
     key(appId, profileId) { return this.storageScope === undefined ? [appId, profileId] : [appId, profileId, this.storageScope]; }
+    async hydrate(current, key) {
+        if (current.normalized) {
+            const owner = JSON.stringify(key);
+            const [threads, messages, positions] = await Promise.all([
+                this.threadRows.where("owner").equals(owner).toArray(),
+                this.messageRows.where("owner").equals(owner).toArray(),
+                this.positionRows.where("owner").equals(owner).toArray(),
+            ]);
+            const byThread = new Map();
+            for (const row of messages) {
+                if (!byThread.has(row.thread))
+                    byThread.set(row.thread, new Map());
+                byThread.get(row.thread).set(row.id, row.value);
+            }
+            const byPosition = new Map(positions.map(row => [row.id, row]));
+            const byId = new Map(threads.map(row => [row.id, row]));
+            const { normalized: _normalized, threadOrder, ...state } = current;
+            const result = { ...state, threads: (threadOrder ?? []).map(id => {
+                    const row = byId.get(id);
+                    const position = byPosition.get(id);
+                    if (!row || !position)
+                        throw new Error("READ_STORAGE_INCOMPLETE");
+                    return { ...row.value, readThroughSeq: position.readThroughSeq, explicitReadMessageIds: position.explicitReadMessageIds, messages: row.messageIds.map(messageId => {
+                            const message = byThread.get(id)?.get(messageId);
+                            if (!message)
+                                throw new Error("READ_STORAGE_INCOMPLETE");
+                            return message;
+                        }) };
+                }) };
+            this.normalizedStates.add(result);
+            return result;
+        }
+        return current;
+    }
+    async loadCurrent(appId, profileId) {
+        const current = await this.loadStored(appId, profileId);
+        if (!current || !this.metadataOnly)
+            return current;
+        const metadata = readingMetadata(current);
+        if (metadata !== current)
+            await this.persist(appId, profileId, current, metadata);
+        return metadata;
+    }
+    async loadStored(appId, profileId) {
+        const current = await this.profiles.get(this.key(appId, profileId));
+        if (current?.normalized)
+            return this.hydrate(current, this.key(appId, profileId));
+        if (current) {
+            const next = this.metadataOnly ? readingMetadata(current) : current;
+            if (this.migrateLegacy || this.metadataOnly)
+                await this.persist(appId, profileId, undefined, next, true);
+            return next;
+        }
+        if (!this.migrateLegacy || this.storageScope === undefined)
+            return undefined;
+        const markerKey = [appId, profileId, "legacy-owner-v1"];
+        const marker = await this.profiles.get(markerKey);
+        if (marker && marker.legacyOwner !== this.storageScope)
+            return undefined;
+        const legacyRow = await this.profiles.get([appId, profileId]);
+        if (!legacyRow)
+            return undefined;
+        const hydrated = await this.hydrate(legacyRow, [appId, profileId]);
+        const legacy = this.metadataOnly ? readingMetadata(hydrated) : hydrated;
+        if (legacy.appId !== appId || legacy.profileId !== profileId || legacy.schemaVersion !== 1)
+            throw new Error("READ_IDENTITY_MISMATCH");
+        const ownership = { ...createReadIndex(appId, profileId), legacyOwner: this.storageScope };
+        await this.profiles.put(ownership, markerKey);
+        await this.persist(appId, profileId, undefined, legacy);
+        await this.profiles.delete([appId, profileId]);
+        const oldOwner = JSON.stringify([appId, profileId]);
+        await this.threadRows.where("owner").equals(oldOwner).delete();
+        await this.messageRows.where("owner").equals(oldOwner).delete();
+        await this.positionRows.where("owner").equals(oldOwner).delete();
+        return legacy;
+    }
+    /** Message bodies are immutable for local read observations: keep them out of
+     * profile/cursor writes, and update only changed normalized rows on sync. */
+    async persist(appId, profileId, previous, next, replaceLegacy = false) {
+        if (previous && !this.normalizedStates.has(previous)) {
+            previous = undefined;
+            replaceLegacy = true;
+        }
+        const owner = JSON.stringify(this.key(appId, profileId));
+        const oldThreads = new Map(previous?.threads.map(thread => [thread.id, thread]) ?? []);
+        const nextIds = new Set(next.threads.map(thread => thread.id));
+        if (nextIds.size !== next.threads.length)
+            throw new Error("DUPLICATE_READ_THREAD");
+        const threadWrites = [], messageWrites = [], positionWrites = [];
+        const messageDeletes = [];
+        for (const thread of next.threads) {
+            const old = oldThreads.get(thread.id);
+            if (old === thread)
+                continue;
+            const { messages, readThroughSeq, explicitReadMessageIds, ...value } = thread;
+            const position = { owner, id: thread.id, readThroughSeq, explicitReadMessageIds };
+            if (!old || old.readThroughSeq !== readThroughSeq || JSON.stringify(old.explicitReadMessageIds) !== JSON.stringify(explicitReadMessageIds))
+                positionWrites.push(position);
+            const oldValue = old ? (({ messages: _messages, readThroughSeq: _seq, explicitReadMessageIds: _explicit, ...rest }) => rest)(old) : undefined;
+            if (!old || old.messages !== messages || JSON.stringify(oldValue) !== JSON.stringify(value)) {
+                const metadata = { owner, id: thread.id, value, messageIds: messages.map(message => message.id) };
+                const oldMetadata = old ? { owner, id: old.id, value: oldValue, messageIds: old.messages.map(message => message.id) } : undefined;
+                if (JSON.stringify(metadata) !== JSON.stringify(oldMetadata))
+                    threadWrites.push(metadata);
+            }
+            if (old?.messages === messages)
+                continue;
+            const byId = new Map(old?.messages.map(message => [message.id, message]) ?? []);
+            const ids = new Set();
+            for (const message of messages) {
+                if (ids.has(message.id))
+                    throw new Error("INVALID_READ_MESSAGE");
+                ids.add(message.id);
+                const prior = byId.get(message.id);
+                if (prior !== message && JSON.stringify(prior) !== JSON.stringify(message))
+                    messageWrites.push({ owner, thread: thread.id, id: message.id, value: message });
+            }
+            for (const id of byId.keys())
+                if (!ids.has(id))
+                    messageDeletes.push([owner, thread.id, id]);
+        }
+        for (const id of oldThreads.keys())
+            if (!nextIds.has(id)) {
+                await this.threadRows.delete([owner, id]);
+                await this.positionRows.delete([owner, id]);
+                await this.messageRows.where("[owner+thread]").equals([owner, id]).delete();
+            }
+        // A legacy document can replace the full profile after normalization. Its
+        // replacement is authoritative for the row set; discard unreachable bodies
+        // in the same transaction before installing the rebuilt normalized records.
+        if (replaceLegacy) {
+            await this.messageRows.where("owner").equals(owner).delete();
+            await this.threadRows.where("owner").equals(owner).delete();
+            await this.positionRows.where("owner").equals(owner).delete();
+        }
+        // Bound each IndexedDB bulk request. A snapshot and its cursor still commit
+        // atomically; bounding total snapshot transaction bytes is separate work.
+        for (let offset = 0; offset < positionWrites.length; offset += 128)
+            await this.positionRows.bulkPut(positionWrites.slice(offset, offset + 128));
+        for (let offset = 0; offset < threadWrites.length; offset += 128)
+            await this.threadRows.bulkPut(threadWrites.slice(offset, offset + 128));
+        for (let offset = 0; offset < messageWrites.length; offset += 128)
+            await this.messageRows.bulkPut(messageWrites.slice(offset, offset + 128));
+        for (let offset = 0; offset < messageDeletes.length; offset += 128)
+            await this.messageRows.bulkDelete(messageDeletes.slice(offset, offset + 128));
+        const header = (state) => ({ ...state, threads: [], normalized: true, threadOrder: state.threads.map(thread => thread.id) });
+        const nextHeader = header(next);
+        if (!previous || JSON.stringify(header(previous)) !== JSON.stringify(nextHeader))
+            await this.profiles.put(nextHeader, this.key(appId, profileId));
+        this.normalizedStates.add(next);
+    }
     async load(appId, profileId) {
-        return this.transaction("r", () => this.profiles.get(this.key(appId, profileId)));
+        return this.transaction(this.migrateLegacy || this.metadataOnly ? "rw" : "r", () => this.loadCurrent(appId, profileId));
+    }
+    async loadVersioned(appId, profileId) {
+        return this.transaction(this.migrateLegacy || this.metadataOnly ? "rw" : "r", async () => ({
+            state: await this.loadCurrent(appId, profileId), versions: (await this.versions.get(this.key(appId, profileId)))?.teams ?? {},
+        }));
+    }
+    async loadVersions(appId, profileId) {
+        return this.transaction("r", async () => (await this.versions.get(this.key(appId, profileId)))?.teams ?? {});
+    }
+    async invalidateTeam(appId, profileId, teamId, version, knownThreadIds = []) {
+        if (!isValidChatTeamId(teamId) || !Number.isSafeInteger(version) || version < 1)
+            throw new Error("INVALID_READ_SCOPE_VERSION");
+        return this.transaction("rw", async () => {
+            const state = await this.loadCurrent(appId, profileId) ?? createReadIndex(appId, profileId);
+            const teams = (await this.versions.get(this.key(appId, profileId)))?.teams ?? {};
+            if (readTeamVersion(teams, teamId) >= version)
+                return state;
+            const next = removeReadTeam(state, teamId, knownThreadIds);
+            await this.versions.put({ teams: { ...teams, [teamId]: version } }, this.key(appId, profileId));
+            await this.persist(appId, profileId, state, next);
+            return next;
+        });
     }
     async update(appId, profileId, transform) {
         return this.transaction("rw", async () => {
-            const previous = await this.profiles.get(this.key(appId, profileId));
-            const next = transform(previous ?? createReadIndex(appId, profileId));
+            const previous = await this.loadCurrent(appId, profileId);
+            const transformed = transform(previous ?? createReadIndex(appId, profileId), (await this.versions.get(this.key(appId, profileId)))?.teams ?? {});
+            const next = this.metadataOnly ? readingMetadata(transformed) : transformed;
             if (next.appId !== appId || next.profileId !== profileId || next.schemaVersion !== 1)
                 throw new Error("READ_IDENTITY_MISMATCH");
-            if (JSON.stringify(next) !== JSON.stringify(previous))
-                await this.profiles.put(next, this.key(appId, profileId));
+            await this.persist(appId, profileId, previous, next);
             return next;
         });
     }
@@ -231,14 +458,14 @@ function readSource(state, conversationId, messageId) {
     return sources[0];
 }
 /** Aggregate logical history while each original source retains its own read cursor. */
-export function unreadInConversation(state, conversationId) {
+export function unreadInConversation(state, conversationId, hidden) {
     const sources = sourcesInConversation(state, conversationId);
     if (!sources.length)
         throw new Error("UNKNOWN_READ_CONVERSATION");
     if (new Set(sources.map(source => source.teamId)).size > 1)
         throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
     return sources.reduce((total, source) => {
-        const unread = unreadInThread(state, source.id);
+        const unread = unreadInThread(state, source.id, hidden);
         return { unreadMessageCount: total.unreadMessageCount + unread.unreadMessageCount, unreadMentionCount: total.unreadMentionCount + unread.unreadMentionCount, badgeCount: total.badgeCount + unread.badgeCount };
     }, { unreadMessageCount: 0, unreadMentionCount: 0, badgeCount: 0 });
 }

package/lib/runtime/readSync.d.ts

@@ -4,6 +4,7 @@ export type ReadSyncOptions = {
     profileId: string;
     sessionToken: string;
     hubHttpUrl: string;
+    metadataOnly?: boolean;
     persistence: ReadIndexPersistence;
     fetch?: typeof globalThis.fetch;
     onChange?: (state: ReadIndexState) => void;

package/lib/runtime/readSync.js

@@ -1,4 +1,4 @@
-import { applyReadChange, ReadSyncGap, createReadIndex, installReadSnapshot } from "./readIndex.js";
+import { readingMetadata, assertReadIndexVersions, applyReadChange, ReadSyncGap, createReadIndex, installReadSnapshot } from "./readIndex.js";
 /** Keeps local operations until an authoritative projection covers them. */
 export class ReadSyncClient {
     options;
@@ -9,8 +9,11 @@ export class ReadSyncClient {
         this.options = options;
     }
     async loadLocal() {
-        return await this.options.persistence.load(this.options.appId, this.options.profileId)
-            ?? createReadIndex(this.options.appId, this.options.profileId);
+        const { appId, profileId, persistence, metadataOnly } = this.options;
+        const state = await persistence.load(appId, profileId) ?? createReadIndex(appId, profileId);
+        if (!metadataOnly || readingMetadata(state) === state)
+            return state;
+        return persistence.update(appId, profileId, readingMetadata);
     }
     stop() { this.controller.abort(); }
     synchronize() {
@@ -46,7 +49,9 @@ export class ReadSyncClient {
     }
     async run() {
         const { appId, profileId, persistence } = this.options;
-        const current = await this.loadLocal();
+        const loaded = persistence.loadVersioned ? await persistence.loadVersioned(appId, profileId) : { state: await persistence.load(appId, profileId), versions: {} };
+        const current = loaded.state ?? createReadIndex(appId, profileId);
+        const versions = loaded.versions;
         // Ordinary reads are monotonic: only the furthest position per thread needs
         // sending. Keep every original operation in storage until the projection
         // confirms it, and never rewrite an operation ID's payload during retries.
@@ -60,6 +65,8 @@ export class ReadSyncClient {
         }
         const outgoing = current.pending.filter(operation => operation.explicitReadMessageIds.length || operation.readThroughSeq <= 0 || latest.get(operation.threadId) === operation);
         for (const operation of outgoing) {
+            if (persistence.loadVersions)
+                assertReadIndexVersions(versions, await persistence.loadVersions(appId, profileId));
             const receipt = await this.request("/api/social/reading", {
                 method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...operation, appId, profileId }),
             });
@@ -69,8 +76,10 @@ export class ReadSyncClient {
             this.readAfter = Math.max(this.readAfter, receipt.acceptedAt);
         }
         const query = new URLSearchParams({ appId, profileId });
+        if (this.options.metadataOnly)
+            query.set("metadataOnly", "true");
         if (!this.readAfter && current.syncCursor !== "0") {
-            const delta = await this.request(`/api/social/reading/changes?${new URLSearchParams({ appId, profileId, after: current.syncCursor })}`);
+            const delta = await this.request(`/api/social/reading/changes?${new URLSearchParams({ appId, profileId, after: current.syncCursor, ...(this.options.metadataOnly ? { metadataOnly: "true" } : {}) })}`);
             if (delta.appId !== appId || delta.profileId !== profileId || typeof delta.syncCursor !== "string"
                 || typeof delta.snapshotRequired !== "boolean" || !Array.isArray(delta.changes))
                 throw new Error("INVALID_READ_DELTA");
@@ -78,8 +87,9 @@ export class ReadSyncClient {
                 try {
                     if (this.controller.signal.aborted)
                         throw new Error("READ_SYNC_STOPPED");
-                    const next = await persistence.update(appId, profileId, state => {
-                        const applied = delta.changes.reduce(applyReadChange, state);
+                    const next = await persistence.update(appId, profileId, (state, currentVersions) => {
+                        assertReadIndexVersions(versions, currentVersions);
+                        const applied = delta.changes.reduce((current, change) => applyReadChange(current, this.options.metadataOnly ? { ...change, thread: readingMetadata({ appId, threads: [change.thread] }).threads[0] } : change), this.options.metadataOnly ? readingMetadata(state) : state);
                         if (applied.syncCursor !== delta.syncCursor)
                             throw new ReadSyncGap(applied.syncCursor);
                         return applied;
@@ -100,7 +110,10 @@ export class ReadSyncClient {
         if (this.controller.signal.aborted)
             throw new Error("READ_SYNC_STOPPED");
         // Merge into the latest transaction, including reads made while HTTP was pending.
-        const next = await persistence.update(appId, profileId, state => installReadSnapshot(state, snapshot));
+        const next = await persistence.update(appId, profileId, (state, currentVersions) => {
+            assertReadIndexVersions(versions, currentVersions);
+            return installReadSnapshot(state, this.options.metadataOnly ? readingMetadata(snapshot) : snapshot);
+        });
         if (!next.pending.length)
             this.readAfter = 0;
         if (!this.controller.signal.aborted)

package/lib/runtime/readingClient.d.ts

@@ -1,11 +1,15 @@
+import { type ConversationReadMessage } from "./conversationRead.js";
 import { type ReadIndexPersistence, type ReadIndexState } from "./readIndex.js";
 export type ReadingClientOptions = {
     appId: string;
     profileId: string;
     sessionToken: string;
     hubHttpUrl: string;
+    teamId?: string;
+    metadataOnly?: boolean;
     persistence?: ReadIndexPersistence;
     storageScope?: string;
+    migrateLegacy?: boolean;
     fetch?: typeof fetch;
     onError?: (error: unknown) => void;
     onRecovered?: () => void;
@@ -15,6 +19,12 @@ export type ReadingClientOptions = {
 export declare class ReadingClient {
     private options;
     private storage;
+    private backing;
+    private closing?;
+    private revoking?;
+    private versions?;
+    private prepared;
+    private accepted;
     private persistence;
     private sync;
     private tasks;
@@ -34,8 +44,17 @@ export declare class ReadingClient {
     refresh: () => void;
     synchronize(targetCursor?: string, profileId?: string): Promise<ReadIndexState>;
     update(transform: (state: ReadIndexState) => ReadIndexState): Promise<ReadIndexState>;
+    private updateScoped;
+    prepareTeam(teamId: string, version: number): Promise<void>;
+    private assertThreadTeam;
+    markRead(threadId: string, messages?: readonly ConversationReadMessage[]): Promise<ReadIndexState>;
     recordVisible(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     recordExplicit(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     private record;
+    withdraw(): void;
+    private stop;
+    /** This client is retired permanently. Drain accepted local observations
+     * before deleting one team's profile-wide projection; sibling teams survive. */
+    revokeTeam(teamId: string, version: number, knownThreadIds?: readonly string[]): Promise<void>;
     close(): Promise<void>;
 }

package/lib/runtime/readingClient.js

@@ -1,12 +1,21 @@
+import { isValidChatTeamId } from "./thread.js";
+import { isOffline, isOfflineNetworkFailure } from "./connectivity.js";
+import { recordConversationRead } from "./conversationRead.js";
 import { BatchedReadIndex } from "./batchedReadIndex.js";
 import { WindowedTasks } from "./coalescer.js";
-import { IndexedDbReadIndex, recordReadIntent } from "./readIndex.js";
+import { IndexedDbReadIndex, readingMetadata, recordReadIntent, assertReadIndexVersions } from "./readIndex.js";
 import { ReadSyncClient } from "./readSync.js";
 /** Owns durable local reads, network coalescing, retries and state notifications.
  * Hosts report actual visibility; loading or subscribing never marks messages read. */
 export class ReadingClient {
     options;
     storage;
+    backing;
+    closing;
+    revoking;
+    versions;
+    prepared = new Map();
+    accepted = new Set();
     persistence;
     sync;
     tasks;
@@ -19,7 +28,10 @@ export class ReadingClient {
     generation = 0;
     constructor(options) {
         this.options = options;
-        const storage = options.persistence ?? (this.storage = new IndexedDbReadIndex(globalThis.indexedDB, "pmate-social-read-index", options.storageScope));
+        if (options.teamId !== undefined && !isValidChatTeamId(options.teamId))
+            throw new Error("INVALID_READ_TEAM");
+        const storage = options.persistence ?? (this.storage = new IndexedDbReadIndex(globalThis.indexedDB, "pmate-social-read-index", options.storageScope, options.migrateLegacy, options.metadataOnly));
+        this.backing = storage;
         this.persistence = new BatchedReadIndex(storage);
         this.tasks = new WindowedTasks(1000, error => this.failed(error));
         this.sync = new ReadSyncClient({ ...options, persistence: this.persistence, onChange: state => this.publish(state) });
@@ -33,7 +45,7 @@ export class ReadingClient {
         this.listeners.forEach(listener => listener());
     }
     failed(error) {
-        if (this.closed)
+        if (this.closed || isOfflineNetworkFailure(error))
             return;
         this.options.onError?.(error);
         if (/HTTP_(400|401|403)/.test(String(error)) || (typeof navigator !== "undefined" && !navigator.onLine) || this.retry)
@@ -56,8 +68,9 @@ export class ReadingClient {
         this.refresh();
     }
     refresh = () => {
-        if (!this.closed)
-            this.tasks.schedule("reading", async () => { await this.synchronize(); });
+        if (!this.closed && !isOffline())
+            this.tasks.schedule("reading", async () => { if (!isOffline())
+                await this.synchronize(); });
     };
     async synchronize(targetCursor, profileId) {
         if (this.closed)
@@ -84,32 +97,122 @@ export class ReadingClient {
         }
         throw new Error("Reading projection has not reached the announced version");
     }
-    async update(transform) {
+    update(transform) {
+        // Advanced transforms may replace profile-wide state. Typed observation
+        // methods below only derive changes for their configured team.
+        return this.updateScoped(transform);
+    }
+    updateScoped(transform, teamId) {
         if (this.closed)
-            throw new Error("READING_CLIENT_CLOSED");
-        const next = await this.persistence.update(this.options.appId, this.options.profileId, transform);
-        if (!this.closed) {
-            this.publish(next);
-            if (next.pending.length || next.observedReadIntents?.length)
-                this.refresh();
-        }
-        return next;
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        // One shared metadata read per local authority generation, rather than one
+        // IndexedDB lookup for every viewport observation.
+        const versions = this.versions ??= this.persistence.loadVersions(this.options.appId, this.options.profileId);
+        const task = (async () => {
+            const expected = await versions;
+            const next = await this.persistence.update(this.options.appId, this.options.profileId, (state, currentVersions) => {
+                assertReadIndexVersions(expected, currentVersions, teamId);
+                const next = transform(state);
+                return this.options.metadataOnly ? readingMetadata(next) : next;
+            });
+            if (!this.closed) {
+                this.publish(next);
+                if (next.pending.length || next.observedReadIntents?.length)
+                    this.refresh();
+            }
+            return next;
+        })().catch(error => {
+            if (String(error).includes("READ_SCOPE_CHANGED")) {
+                if (teamId !== undefined)
+                    this.withdraw();
+                else
+                    this.versions = undefined;
+            }
+            throw error;
+        });
+        this.accepted.add(task);
+        void task.finally(() => this.accepted.delete(task)).catch(() => { });
+        return task;
+    }
+    prepareTeam(teamId, version) {
+        if (this.closed)
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        if (!isValidChatTeamId(teamId) || !Number.isSafeInteger(version) || version < 0)
+            return Promise.reject(new Error("INVALID_READ_SCOPE_VERSION"));
+        const previous = this.prepared.get(teamId);
+        if (previous && previous.version >= version)
+            return previous.task;
+        const task = (async () => {
+            if (version > 0)
+                await this.persistence.invalidateTeam(this.options.appId, this.options.profileId, teamId, version);
+            this.versions = undefined;
+        })().catch(error => { if (this.prepared.get(teamId)?.task === task)
+            this.prepared.delete(teamId); throw error; });
+        this.prepared.set(teamId, { version, task });
+        return task;
+    }
+    assertThreadTeam(state, threadId) {
+        if (this.options.teamId !== undefined && state.threads.some(thread => (thread.id === threadId || thread.conversationId === threadId) && thread.teamId !== undefined && thread.teamId !== this.options.teamId))
+            throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
+    }
+    markRead(threadId, messages = []) {
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return recordConversationRead(state, threadId, messages); }, this.options.teamId);
     }
     recordVisible(threadId, messageIds) { return this.record(threadId, messageIds, "visible"); }
     recordExplicit(threadId, messageIds) { return this.record(threadId, messageIds, "explicit"); }
     record(threadId, ids, readPolicy) {
         const messageIds = [...new Set(ids)];
-        return this.update(state => messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state));
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state); }, this.options.teamId);
     }
-    async close() {
+    withdraw() { this.stop(); }
+    stop() {
+        if (this.closed)
+            return;
         this.closed = true;
         this.generation++;
         this.offWake?.();
         this.tasks.close();
         clearTimeout(this.retry);
         this.sync.stop();
+        this.state = undefined;
+        this.listeners.forEach(listener => listener());
         this.listeners.clear();
-        await this.persistence.close();
-        await this.storage?.close();
+    }
+    /** This client is retired permanently. Drain accepted local observations
+     * before deleting one team's profile-wide projection; sibling teams survive. */
+    revokeTeam(teamId, version, knownThreadIds = []) {
+        if (this.revoking)
+            return this.revoking;
+        if (this.closing)
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        this.stop();
+        return this.revoking = (async () => {
+            try {
+                await Promise.allSettled([...this.accepted]);
+                await this.persistence.close();
+                if (!this.backing.invalidateTeam)
+                    throw new Error("READ_SCOPE_INVALIDATION_UNAVAILABLE");
+                await this.backing.invalidateTeam(this.options.appId, this.options.profileId, teamId, version, knownThreadIds);
+            }
+            finally {
+                await this.storage?.close();
+            }
+        })();
+    }
+    close() {
+        if (this.revoking)
+            return this.revoking;
+        if (this.closing)
+            return this.closing;
+        this.stop();
+        return this.closing = (async () => {
+            try {
+                await Promise.allSettled([...this.accepted]);
+                await this.persistence.close();
+            }
+            finally {
+                await this.storage?.close();
+            }
+        })();
     }
 }

package/lib/runtime/readingContent.d.ts

@@ -0,0 +1,5 @@
+/** Social control envelopes do not contribute to message unread counts. */
+export declare function isReadingControl(payload: unknown, appId: string): boolean;
+/** Mirrors the server's voice policy for ordinary and quoted wire envelopes. */
+export declare function messageRequiresPlayback(body: unknown): boolean;
+export declare function messageMentionsProfile(body: unknown, profileId: string): boolean;