@pmate/chat-sdk 0.12.0-next.24 → 0.12.0-next.26

package/README.md

@@ -235,3 +235,11 @@ unknown receipt counts stay unknown and an uncached reader detail page rejects
 without attempting transport. A network failure arriving after the browser went
 offline does not turn background synchronization into an operation error.
 Authorization failures still revoke the corresponding cached data.
+
+Reading entry points check the message scope even before `initialize()` finishes.
+Concurrent observations share the permission lookup and batch their local writes.
+Visibility/playback operations reject another known team's conversation; a
+permission change in another team does not discard this team's observations.
+Ordinary shutdown waits for accepted local reading writes, while access withdrawal
+rejects late results. Retired asynchronous reading entries reject through promises;
+refresh/subscription teardown remains safe.

package/lib/runtime/chatSession.d.ts

@@ -63,6 +63,10 @@ export declare class ChatSession<T extends StoredMessage> {
     private closedSummary;
     private connectionState;
     private catchUp;
+    private readingAllowed;
+    private readingListeners;
+    private acceptedReading;
+    private readingAccess?;
     private readingStarted;
     private readingStarting?;
     private withdrawn;
@@ -81,6 +85,10 @@ export declare class ChatSession<T extends StoredMessage> {
     importLegacyMessages(threadId: string, messages: T[]): Promise<void>;
     getReadingSnapshot(): import("./readIndex.js").ReadIndexState | undefined;
     subscribeReading(listener: () => void): () => void;
+    private setReadingAllowed;
+    private readingAuthority;
+    private authorizeReading;
+    private readingOperation;
     refreshReading(): void;
     synchronizeReading(cursor?: string, profileId?: string): Promise<import("./readIndex.js").ReadIndexState>;
     /** Explicit text-history acknowledgement; unheard audio stays unread. */

package/lib/runtime/chatSession.js

@@ -31,6 +31,10 @@ export class ChatSession {
     closedSummary = { threads: [], unreadMessageCount: undefined, badgeCount: undefined, connection: "closed" };
     connectionState = "closed";
     catchUp;
+    readingAllowed = false;
+    readingListeners = new Set();
+    acceptedReading = new Set();
+    readingAccess;
     readingStarted = false;
     readingStarting;
     withdrawn = false;
@@ -58,7 +62,7 @@ export class ChatSession {
                     return options.connection.onReach(event);
                 throw new Error("REACH_HANDLER_UNAVAILABLE");
             } });
-        this.reading = new ReadingClient({ ...options.reading, storageScope: JSON.stringify([scope.accountId]), migrateLegacy: true });
+        this.reading = new ReadingClient({ ...options.reading, teamId: scope.teamId, storageScope: JSON.stringify([scope.accountId]), migrateLegacy: true });
         this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, scope, access: () => this.messages.scopeAccess(), onError: options.onError, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
         this.sender = new DurableChatSender(this.connection, scope, options.onError, { access: () => this.messages.scopeAccess() });
         this.catchUp = new WindowedTasks(1000, error => { if (!this.closed)
@@ -74,7 +78,8 @@ export class ChatSession {
         this.off.push(this.messages.subscribeAccessRevoked(() => { if (!this.withdrawn && !this.closed)
             void this.revokeAccess().catch(error => options.onError(error)); }));
         this.off.push(this.messages.subscribeAll(thread => this.publish(thread)));
-        this.off.push(this.sender.subscribe(() => this.publishAll()), this.reading.subscribe(() => this.publishAll()));
+        this.off.push(this.sender.subscribe(() => this.publishAll()), this.reading.subscribe(() => { this.publishAll(); if (this.readingAllowed)
+            this.readingListeners.forEach(listener => listener()); }));
         this.off.push(this.connection.watchMessages(message => {
             try {
                 const decoded = options.decode(message);
@@ -133,6 +138,7 @@ export class ChatSession {
                 return;
             this.assertOpen();
             await this.reading.prepareTeam(this.options.messages.scope.teamId, access.version);
+            this.setReadingAllowed(true);
             await this.reading.start();
             this.assertOpen();
             this.readingStarted = true;
@@ -140,16 +146,60 @@ export class ChatSession {
     }
     /** One-time migration only: never establishes trusted history coverage. */
     importLegacyMessages(threadId, messages) { this.assertOpen(); return this.messages.importLegacy(threadId, messages); }
-    getReadingSnapshot() { return this.closed || this.withdrawn ? undefined : this.reading.getSnapshot(); }
+    getReadingSnapshot() { return this.closed || this.withdrawn || !this.readingAllowed ? undefined : this.reading.getSnapshot(); }
     subscribeReading(listener) { if (this.closed || this.withdrawn)
-        return () => { }; return this.reading.subscribe(listener); }
-    refreshReading() { this.assertOpen(); this.reading.refresh(); }
-    synchronizeReading(cursor, profileId) { this.assertOpen(); return this.reading.synchronize(cursor, profileId); }
+        return () => { }; this.readingListeners.add(listener); return () => { this.readingListeners.delete(listener); }; }
+    setReadingAllowed(allowed) {
+        if (this.readingAllowed === allowed)
+            return;
+        const previous = this.getReadingSnapshot();
+        this.readingAllowed = allowed;
+        if (previous !== this.getReadingSnapshot())
+            this.readingListeners.forEach(listener => listener());
+        this.publishAll();
+    }
+    readingAuthority() {
+        return this.readingAccess ??= this.messages.scopeAccess().then(access => { if (!access.allowed)
+            this.setReadingAllowed(false); return access; }).finally(() => { this.readingAccess = undefined; });
+    }
+    async authorizeReading() {
+        const access = await this.readingAuthority();
+        if (this.withdrawn || !access.allowed)
+            throw new Error("CHAT_ACCESS_REVOKED");
+        await this.reading.prepareTeam(this.options.messages.scope.teamId, access.version);
+        this.setReadingAllowed(true);
+    }
+    readingOperation(run, durable = true) {
+        if (this.closed || this.withdrawn)
+            return Promise.reject(new Error(this.withdrawn ? "CHAT_ACCESS_REVOKED" : "CHAT_SESSION_CLOSED"));
+        const task = (async () => {
+            await this.authorizeReading();
+            if (this.withdrawn)
+                throw new Error("CHAT_ACCESS_REVOKED");
+            if (!durable)
+                this.assertOpen();
+            const next = await run();
+            if (this.withdrawn || !(await this.readingAuthority()).allowed)
+                throw new Error("CHAT_ACCESS_REVOKED");
+            return next;
+        })();
+        if (durable) {
+            this.acceptedReading.add(task);
+            void task.finally(() => this.acceptedReading.delete(task)).catch(() => { });
+        }
+        return task;
+    }
+    refreshReading() {
+        if (this.closed || this.withdrawn)
+            return;
+        void this.authorizeReading().then(() => { if (!this.closed && !this.withdrawn)
+            this.reading.refresh(); }).catch(error => { if (!this.closed && !this.withdrawn)
+            this.options.onError(error); });
+    }
+    synchronizeReading(cursor, profileId) { return this.readingOperation(() => this.reading.synchronize(cursor, profileId), false); }
     /** Explicit text-history acknowledgement; unheard audio stays unread. */
-    markRead(threadId, messages = []) { this.assertOpen(); return this.reading.markRead(threadId, messages).then(next => { if (this.withdrawn)
-        throw new Error("CHAT_ACCESS_REVOKED"); return next; }); }
-    updateReading(transform) { this.assertOpen(); return this.reading.update(transform).then(next => { if (this.withdrawn)
-        throw new Error("CHAT_ACCESS_REVOKED"); return next; }); }
+    markRead(threadId, messages = []) { return this.readingOperation(() => this.reading.markRead(threadId, messages)); }
+    updateReading(transform) { return this.readingOperation(() => this.reading.update(transform)); }
     assertOpen() { if (this.withdrawn)
         throw new Error("CHAT_ACCESS_REVOKED"); if (this.closed)
         throw new Error("CHAT_SESSION_CLOSED"); }
@@ -278,7 +328,7 @@ export class ChatSession {
         }
         if (!threadId)
             throw new Error("INVALID_READING_THREAD");
-        return (event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids)).then(next => { this.assertOpen(); return next; });
+        return this.readingOperation(() => event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids));
     }
     /** Bridge transports can delegate social events without maintaining clients. */
     async handleReach(event) {
@@ -298,7 +348,7 @@ export class ChatSession {
             if (event.payload.profileId !== this.options.messages.scope.profileId)
                 throw new Error("Reading reach identity mismatch");
             await this.initialize();
-            await this.reading.synchronize(event.payload.syncCursor, event.payload.profileId);
+            await this.synchronizeReading(event.payload.syncCursor, event.payload.profileId);
             this.assertOpen();
         }
         return "handled";
@@ -379,7 +429,7 @@ export class ChatSession {
         let snapshot = this.snapshots.get(threadId);
         if (!snapshot) {
             const messages = this.messages.getSnapshot(threadId);
-            const state = this.reading.getSnapshot();
+            const state = this.getReadingSnapshot();
             snapshot = { messages: messages?.messages ?? [], hasEarlier: messages?.hasEarlier ?? false, resetVersion: messages?.resetVersion ?? 0, complete: messages?.complete ?? false, outgoing: this.sender.snapshot(threadId), readCounts: this.countSnapshots.get(threadId), unread: state?.threads.some(thread => (thread.conversationId ?? thread.id) === threadId) ? unreadInConversation(state, threadId) : undefined };
             this.snapshots.set(threadId, snapshot);
         }
@@ -426,7 +476,7 @@ export class ChatSession {
     }
     buildGlobal() {
         const ids = new Set(this.snapshots.keys());
-        for (const thread of this.reading.getSnapshot()?.threads ?? [])
+        for (const thread of this.getReadingSnapshot()?.threads ?? [])
             if (thread.teamId === this.options.messages.scope.teamId)
                 ids.add(thread.conversationId ?? thread.id);
         for (const outgoing of this.sender.snapshot())
@@ -435,7 +485,7 @@ export class ChatSession {
             const snapshot = this.getSnapshot(threadId);
             return { threadId, lastMessage: snapshot.messages.at(-1), unread: snapshot.unread, outgoingCount: snapshot.outgoing.length };
         });
-        const state = this.reading.getSnapshot();
+        const state = this.getReadingSnapshot();
         const known = Boolean(state && state.syncCursor !== "0" && threads.every(thread => thread.unread !== undefined));
         return { threads, unreadMessageCount: known ? threads.reduce((sum, t) => sum + (t.unread?.unreadMessageCount ?? 0), 0) : undefined, badgeCount: known ? threads.reduce((sum, t) => sum + (t.unread?.badgeCount ?? 0), 0) : undefined, connection: this.connectionState };
     }
@@ -483,6 +533,7 @@ export class ChatSession {
         this.globalSnapshot = undefined;
         this.listeners.forEach(listeners => listeners.forEach(listener => listener()));
         this.globalListeners.forEach(listener => listener());
+        this.readingListeners.forEach(listener => listener());
         if (!this.options.sharedConnection)
             this.connection.close();
         return this.revoking = Promise.resolve().then(async () => {
@@ -529,8 +580,10 @@ export class ChatSession {
             if (!this.options.sharedConnection)
                 this.connection.close();
             const senderClosing = this.sender.close();
+            const readingBarrier = Promise.allSettled([...this.acceptedReading]);
+            const readingClosing = readingBarrier.then(() => this.reading.close());
             try {
-                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), senderClosing, this.reading.close(), this.messages.close(senderClosing)]);
+                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), senderClosing, readingClosing, this.messages.close(Promise.allSettled([senderClosing, readingBarrier]))]);
                 const failed = results.find((result) => result.status === "rejected");
                 if (failed)
                     throw failed.reason;
@@ -538,6 +591,7 @@ export class ChatSession {
             finally {
                 this.listeners.clear();
                 this.globalListeners.clear();
+                this.readingListeners.clear();
                 this.snapshots.clear();
                 this.countSnapshots.clear();
                 this.historyEdges.clear();

package/lib/runtime/durableSender.js

@@ -293,6 +293,7 @@ export class DurableChatSender {
         this.offConnection();
         this.listeners.clear();
         this.channel?.close();
+        this.channel = undefined;
         try {
             await this.ready;
             await Promise.allSettled([...this.accepted, ...this.running.values(), ...(this.revoking ? [this.revoking] : [])]);

package/lib/runtime/readIndex.d.ts

@@ -79,7 +79,7 @@ export declare function unreadInThread(state: ReadIndexState, threadId: string):
 };
 export type ReadIndexVersions = Readonly<Record<string, number>>;
 export type ReadIndexTransform = (current: ReadIndexState, versions?: ReadIndexVersions) => ReadIndexState;
-export declare function assertReadIndexVersions(expected: ReadIndexVersions, current?: ReadIndexVersions): void;
+export declare function assertReadIndexVersions(expected: ReadIndexVersions, current?: ReadIndexVersions, teamId?: string): void;
 /** Remove only the withdrawn team's original sources, logical conversations and
  * queued observations. Other teams' pending operations must survive. */
 export declare function removeReadTeam(state: ReadIndexState, teamId: string, knownThreadIds?: readonly string[]): ReadIndexState;
@@ -100,12 +100,20 @@ export declare class IndexedDbReadIndex implements ReadIndexPersistence {
     private migrateLegacy;
     private database;
     private profiles;
+    private threadRows;
+    private messageRows;
+    private positionRows;
+    private normalizedStates;
     private versions;
     private closed;
     constructor(factory?: IDBFactory, name?: string, storageScope?: string | undefined, migrateLegacy?: boolean);
     private transaction;
     private key;
+    private hydrate;
     private loadCurrent;
+    /** Message bodies are immutable for local read observations: keep them out of
+     * profile/cursor writes, and update only changed normalized rows on sync. */
+    private persist;
     load(appId: string, profileId: string): Promise<ReadIndexState | undefined>;
     loadVersioned(appId: string, profileId: string): Promise<{
         state: ReadIndexState | undefined;

package/lib/runtime/readIndex.js

@@ -165,8 +165,8 @@ export function unreadInThread(state, threadId) {
     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 = {}) {
-    const teams = new Set([...Object.keys(expected), ...Object.keys(current)]);
+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");
 }
@@ -190,6 +190,10 @@ export class IndexedDbReadIndex {
     migrateLegacy;
     database;
     profiles;
+    threadRows;
+    messageRows;
+    positionRows;
+    normalizedStates = new WeakSet();
     versions;
     closed = false;
     constructor(factory = globalThis.indexedDB, name = "pmate-social-read-index", storageScope, migrateLegacy = false) {
@@ -201,6 +205,10 @@ export class IndexedDbReadIndex {
         // 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; });
@@ -211,7 +219,7 @@ export class IndexedDbReadIndex {
                 throw new Error("READ_STORAGE_CLOSED");
             let started = false;
             try {
-                return await this.database.transaction(mode, this.profiles, this.versions, 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;
@@ -230,25 +238,136 @@ 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.profiles.get(this.key(appId, profileId));
-        if (current || !this.migrateLegacy || this.storageScope === undefined)
+        if (current?.normalized)
+            return this.hydrate(current, this.key(appId, profileId));
+        if (current) {
+            if (this.migrateLegacy)
+                await this.persist(appId, profileId, undefined, current);
             return current;
+        }
+        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 legacy = await this.profiles.get([appId, profileId]);
-        if (!legacy)
+        const legacyRow = await this.profiles.get([appId, profileId]);
+        if (!legacyRow)
             return undefined;
+        const legacy = await this.hydrate(legacyRow, [appId, profileId]);
         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.profiles.put(legacy, this.key(appId, profileId));
+        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) {
+        if (previous && !this.normalizedStates.has(previous))
+            previous = undefined;
+        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();
+            }
+        // 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(this.migrateLegacy ? "rw" : "r", () => this.loadCurrent(appId, profileId));
     }
@@ -270,7 +389,7 @@ export class IndexedDbReadIndex {
                 return state;
             const next = removeReadTeam(state, teamId, knownThreadIds);
             await this.versions.put({ teams: { ...teams, [teamId]: version } }, this.key(appId, profileId));
-            await this.profiles.put(next, this.key(appId, profileId));
+            await this.persist(appId, profileId, state, next);
             return next;
         });
     }
@@ -280,8 +399,7 @@ export class IndexedDbReadIndex {
             const next = transform(previous ?? createReadIndex(appId, profileId), (await this.versions.get(this.key(appId, profileId)))?.teams ?? {});
             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;
         });
     }

package/lib/runtime/readingClient.d.ts

@@ -5,6 +5,7 @@ export type ReadingClientOptions = {
     profileId: string;
     sessionToken: string;
     hubHttpUrl: string;
+    teamId?: string;
     persistence?: ReadIndexPersistence;
     storageScope?: string;
     migrateLegacy?: boolean;
@@ -21,6 +22,7 @@ export declare class ReadingClient {
     private closing?;
     private revoking?;
     private versions?;
+    private prepared;
     private accepted;
     private persistence;
     private sync;
@@ -41,7 +43,9 @@ 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>;

package/lib/runtime/readingClient.js

@@ -1,3 +1,4 @@
+import { isValidChatTeamId } from "./thread.js";
 import { isOffline, isOfflineNetworkFailure } from "./connectivity.js";
 import { recordConversationRead } from "./conversationRead.js";
 import { BatchedReadIndex } from "./batchedReadIndex.js";
@@ -13,6 +14,7 @@ export class ReadingClient {
     closing;
     revoking;
     versions;
+    prepared = new Map();
     accepted = new Set();
     persistence;
     sync;
@@ -26,6 +28,8 @@ export class ReadingClient {
     generation = 0;
     constructor(options) {
         this.options = options;
+        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));
         this.backing = storage;
         this.persistence = new BatchedReadIndex(storage);
@@ -94,6 +98,11 @@ export class ReadingClient {
         throw new Error("Reading projection has not reached the announced version");
     }
     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)
             return Promise.reject(new Error("READING_CLIENT_CLOSED"));
         // One shared metadata read per local authority generation, rather than one
@@ -102,7 +111,7 @@ export class ReadingClient {
         const task = (async () => {
             const expected = await versions;
             const next = await this.persistence.update(this.options.appId, this.options.profileId, (state, currentVersions) => {
-                assertReadIndexVersions(expected, currentVersions);
+                assertReadIndexVersions(expected, currentVersions, teamId);
                 return transform(state);
             });
             if (!this.closed) {
@@ -111,28 +120,48 @@ export class ReadingClient {
                     this.refresh();
             }
             return next;
-        })().catch(error => { if (String(error).includes("READ_SCOPE_CHANGED"))
-            this.versions = undefined; throw error; });
+        })().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;
     }
-    async prepareTeam(teamId, version) {
+    prepareTeam(teamId, version) {
         if (this.closed)
-            throw new Error("READING_CLIENT_CLOSED");
-        if (version > 0) {
-            await this.persistence.invalidateTeam(this.options.appId, this.options.profileId, teamId, version);
+            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.update(state => recordConversationRead(state, 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);
     }
     withdraw() { this.stop(); }
     stop() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.24",
+  "version": "0.12.0-next.26",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",