@pmate/chat-sdk 0.12.0-next.20 → 0.12.0-next.21

package/lib/runtime/messageStore.js

@@ -8,6 +8,7 @@ export class IndexedDbMessageStore {
     rows;
     legacy;
     coverage;
+    accessRows;
     key;
     constructor(scope, merge, options = {}) {
         this.merge = merge;
@@ -15,6 +16,8 @@ export class IndexedDbMessageStore {
         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");
@@ -24,10 +27,13 @@ export class IndexedDbMessageStore {
     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) };
         });
     }
     /** Migration records never claim coverage or overwrite authoritative rows. */
@@ -42,10 +48,13 @@ export class IndexedDbMessageStore {
             if (bytes > 1_048_576)
                 throw new Error("MESSAGE_BATCH_TOO_LARGE");
         }
-        return this.db.transaction("rw", this.rows, this.legacy, this.coverage, async () => {
+        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 (coverage?.revoked)
+            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]);
@@ -71,8 +80,9 @@ export class IndexedDbMessageStore {
     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, async () => {
-            const coverage = await this.coverage.get([this.key, thread]);
+        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();
@@ -87,7 +97,16 @@ export class IndexedDbMessageStore {
                 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.legacy, 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");
@@ -109,8 +128,9 @@ export class IndexedDbMessageStore {
             }
             if (changed.size)
                 await this.rows.bulkPut([...changed.values()]);
-            if (ids.length)
-                await this.legacy.bulkDelete(ids.map(id => [this.key, thread, id]));
+            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 = { ...old, ...coverage, scope: this.key, thread };
                 if (JSON.stringify(old) !== JSON.stringify(next))
@@ -120,11 +140,51 @@ export class IndexedDbMessageStore {
         });
     }
     async windows() {
-        return this.coverage.where("scope").equals(this.key).toArray();
+        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) {
-        return this.db.transaction("rw", this.rows, this.legacy, this.coverage, async () => {
+    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();
@@ -134,14 +194,14 @@ export class IndexedDbMessageStore {
         });
     }
     async removeThread(thread) {
-        await this.db.transaction("rw", this.rows, this.legacy, 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.legacy, 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/readCounts.d.ts

@@ -1,3 +1,4 @@
+import { type ResponseCacheAccess } from "./responseCache.js";
 import { type MessageScope } from "./messageStore.js";
 export type ReadCountsResult = {
     appId: string;
@@ -13,6 +14,7 @@ export type ReadCountsOptions = {
     hubHttpUrl: string;
     fetch?: typeof fetch;
     scope?: MessageScope;
+    access?: ResponseCacheAccess;
     onChange: (value: ReadCountsResult) => void;
     onError?: (error: unknown) => void;
 };
@@ -51,5 +53,6 @@ export declare class ReadCountsClient {
     reconnect(): void;
     private schedule;
     private refresh;
+    retireScope(version: number): Promise<void>;
     close(): Promise<void>;
 }

package/lib/runtime/readCounts.js

@@ -1,4 +1,4 @@
-import { IndexedDbResponseCache } from "./responseCache.js";
+import { IndexedDbResponseCache, isResponseCacheAuthorityError, assertResponseCacheAccess } from "./responseCache.js";
 import { messageScopeKey } from "./messageStore.js";
 let subscriptionSequence = 0;
 function nextSubscriptionSequence() { subscriptionSequence = Math.max(Date.now() * 1000, subscriptionSequence + 1); return subscriptionSequence; }
@@ -37,7 +37,7 @@ export class ReadCountsClient {
         if (options.scope) {
             if (options.scope.appId !== options.appId || options.scope.profileId !== options.profileId)
                 throw new Error("READ_COUNTS_SCOPE_MISMATCH");
-            this.cache = new IndexedDbResponseCache(messageScopeKey(options.scope));
+            this.cache = new IndexedDbResponseCache(messageScopeKey(options.scope), { access: options.access });
         }
     }
     denyCache() {
@@ -47,12 +47,15 @@ export class ReadCountsClient {
         void this.cache?.invalidate().catch(error => this.options.onError?.(error));
     }
     async post(path, body, signal) {
+        const scopeVersion = this.options.access ? await assertResponseCacheAccess(this.options.access) : undefined;
         const response = await (this.options.fetch ?? fetch)(`${this.options.hubHttpUrl.replace(/\/$/, "")}${path}`, { method: "POST", headers: { authorization: `Bearer ${this.options.token}`, "content-type": "application/json" }, body: JSON.stringify(body), signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(8000)]) : AbortSignal.timeout(8000), redirect: "error" });
         if (!response.ok)
             throw new Error(`READ_COUNTS_HTTP_${response.status}`);
         const envelope = await response.json();
         if (envelope.success !== true)
             throw new Error("INVALID_READ_COUNTS_RESPONSE");
+        if (this.options.access)
+            await assertResponseCacheAccess(this.options.access, scopeVersion);
         return envelope.data;
     }
     subscription(threadId, release) {
@@ -89,6 +92,12 @@ export class ReadCountsClient {
                 clearInterval(this.heartbeat);
                 this.heartbeat = undefined;
             }
+            if (isResponseCacheAuthorityError(error)) {
+                this.lastResult = undefined;
+                this.subscriptionDenied = true;
+                clearInterval(this.heartbeat);
+                this.heartbeat = undefined;
+            }
             this.options.onError?.(error);
         }).finally(() => { if (this.subscriptionPending === pending)
             this.subscriptionPending = undefined; });
@@ -176,7 +185,8 @@ export class ReadCountsClient {
         this.force = false;
         const key = JSON.stringify(["counts", threadId, [...ids].sort()]);
         try {
-            const stored = this.cache ? await this.cache.read(key).catch(error => { this.options.onError?.(error); return undefined; }) : undefined;
+            const stored = this.cache ? await this.cache.read(key).catch(error => { if (isResponseCacheAuthorityError(error))
+                throw error; this.options.onError?.(error); return undefined; }) : undefined;
             if (generation !== this.generation || this.closed || accessVersion !== this.accessVersion)
                 return;
             const cached = this.revoked || (stored?.cached && stored.cached.value.revision < this.revision) ? undefined : stored?.cached;
@@ -197,7 +207,7 @@ export class ReadCountsClient {
             this.retries = 0;
             this.revoked = false;
             if (stored)
-                await this.cache?.write(key, value, stored.epoch).catch(error => { if (String(error).includes("RESPONSE_CACHE_INVALIDATED"))
+                await this.cache?.write(key, value, stored.epoch).catch(error => { if (isResponseCacheAuthorityError(error))
                     throw error; this.options.onError?.(error); });
             if (generation !== this.generation || this.closed || accessVersion !== this.accessVersion)
                 return;
@@ -210,8 +220,15 @@ export class ReadCountsClient {
             if (!controller.signal.aborted && generation === this.generation && !this.closed) {
                 if (/READ_COUNTS_HTTP_(401|403)/.test(String(error)))
                     this.denyCache();
+                if (isResponseCacheAuthorityError(error)) {
+                    this.lastResult = undefined;
+                    this.subscriptionDenied = true;
+                    this.dirty = false;
+                    clearInterval(this.heartbeat);
+                    this.heartbeat = undefined;
+                }
                 this.options.onError?.(error);
-                if (!/READ_COUNTS_HTTP_4\d\d|INVALID_READ_COUNTS/.test(String(error)) && this.retries < 3) {
+                if (!isResponseCacheAuthorityError(error) && !/READ_COUNTS_HTTP_4\d\d|INVALID_READ_COUNTS/.test(String(error)) && this.retries < 3) {
                     retryDelay = 1000 * 2 ** this.retries++;
                     this.dirty = true;
                 }
@@ -225,6 +242,7 @@ export class ReadCountsClient {
             }
         }
     }
+    retireScope(version) { return this.cache?.retire(version) ?? Promise.resolve(); }
     close() {
         if (this.closing)
             return this.closing;

package/lib/runtime/readIndex.d.ts

@@ -77,10 +77,22 @@ export declare function unreadInThread(state: ReadIndexState, threadId: string):
     unreadMentionCount: number;
     badgeCount: number;
 };
+export type ReadIndexVersions = Readonly<Record<string, number>>;
+export type ReadIndexTransform = (current: ReadIndexState, versions?: ReadIndexVersions) => ReadIndexState;
+export declare function assertReadIndexVersions(expected: ReadIndexVersions, current?: ReadIndexVersions): 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;
 export interface ReadIndexPersistence {
     load(appId: string, profileId: string): Promise<ReadIndexState | undefined>;
+    loadVersioned?(appId: string, profileId: string): Promise<{
+        state: ReadIndexState | undefined;
+        versions: ReadIndexVersions;
+    }>;
+    loadVersions?(appId: string, profileId: string): Promise<ReadIndexVersions>;
+    invalidateTeam?(appId: string, profileId: string, teamId: string, version: number, knownThreadIds?: readonly string[]): Promise<ReadIndexState>;
     /** Transform and persist atomically; UI publishes only the committed result. */
-    update(appId: string, profileId: string, transform: (current: ReadIndexState) => ReadIndexState): Promise<ReadIndexState>;
+    update(appId: string, profileId: string, transform: ReadIndexTransform): Promise<ReadIndexState>;
 }
 /** Dexie preserves the legacy database/store and outbound [appId, profileId] keys. */
 export declare class IndexedDbReadIndex implements ReadIndexPersistence {
@@ -88,13 +100,20 @@ export declare class IndexedDbReadIndex implements ReadIndexPersistence {
     private migrateLegacy;
     private database;
     private profiles;
+    private versions;
     private closed;
     constructor(factory?: IDBFactory, name?: string, storageScope?: string | undefined, migrateLegacy?: boolean);
     private transaction;
     private key;
     private loadCurrent;
     load(appId: string, profileId: string): Promise<ReadIndexState | undefined>;
-    update(appId: string, profileId: string, transform: (current: ReadIndexState) => ReadIndexState): Promise<ReadIndexState>;
+    loadVersioned(appId: string, profileId: string): Promise<{
+        state: ReadIndexState | undefined;
+        versions: Record<string, number>;
+    }>;
+    loadVersions(appId: string, profileId: string): Promise<ReadIndexVersions>;
+    invalidateTeam(appId: string, profileId: string, teamId: string, version: number, knownThreadIds?: readonly string[]): Promise<ReadIndexState>;
+    update(appId: string, profileId: string, transform: ReadIndexTransform): Promise<ReadIndexState>;
     close(): Promise<void>;
 }
 export declare function sourcesInConversation(state: ReadIndexState, conversationId: string): IndexedReadThread[];

package/lib/runtime/readIndex.js

@@ -164,12 +164,33 @@ export function unreadInThread(state, threadId) {
     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 = {}) {
+    const teams = new Set([...Object.keys(expected), ...Object.keys(current)]);
+    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;
     database;
     profiles;
+    versions;
     closed = false;
     constructor(factory = globalThis.indexedDB, name = "pmate-social-read-index", storageScope, migrateLegacy = false) {
         this.storageScope = storageScope;
@@ -179,7 +200,9 @@ export class IndexedDbReadIndex {
         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.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) {
@@ -188,7 +211,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, async () => {
                     if (this.closed)
                         throw new Error("READ_STORAGE_CLOSED");
                     started = true;
@@ -229,10 +252,32 @@ export class IndexedDbReadIndex {
     async load(appId, profileId) {
         return this.transaction(this.migrateLegacy ? "rw" : "r", () => this.loadCurrent(appId, profileId));
     }
+    async loadVersioned(appId, profileId) {
+        return this.transaction(this.migrateLegacy ? "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.profiles.put(next, this.key(appId, profileId));
+            return next;
+        });
+    }
     async update(appId, profileId, transform) {
         return this.transaction("rw", async () => {
             const previous = await this.loadCurrent(appId, profileId);
-            const next = transform(previous ?? createReadIndex(appId, profileId));
+            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))

package/lib/runtime/readSync.js

@@ -1,4 +1,4 @@
-import { applyReadChange, ReadSyncGap, createReadIndex, installReadSnapshot } from "./readIndex.js";
+import { assertReadIndexVersions, applyReadChange, ReadSyncGap, createReadIndex, installReadSnapshot } from "./readIndex.js";
 /** Keeps local operations until an authoritative projection covers them. */
 export class ReadSyncClient {
     options;
@@ -46,7 +46,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 +62,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 }),
             });
@@ -78,7 +82,8 @@ export class ReadSyncClient {
                 try {
                     if (this.controller.signal.aborted)
                         throw new Error("READ_SYNC_STOPPED");
-                    const next = await persistence.update(appId, profileId, state => {
+                    const next = await persistence.update(appId, profileId, (state, currentVersions) => {
+                        assertReadIndexVersions(versions, currentVersions);
                         const applied = delta.changes.reduce(applyReadChange, state);
                         if (applied.syncCursor !== delta.syncCursor)
                             throw new ReadSyncGap(applied.syncCursor);
@@ -100,7 +105,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, snapshot);
+        });
         if (!next.pending.length)
             this.readAfter = 0;
         if (!this.controller.signal.aborted)

package/lib/runtime/readingClient.d.ts

@@ -17,6 +17,11 @@ export type ReadingClientOptions = {
 export declare class ReadingClient {
     private options;
     private storage;
+    private backing;
+    private closing?;
+    private revoking?;
+    private versions?;
+    private accepted;
     private persistence;
     private sync;
     private tasks;
@@ -36,9 +41,15 @@ export declare class ReadingClient {
     refresh: () => void;
     synchronize(targetCursor?: string, profileId?: string): Promise<ReadIndexState>;
     update(transform: (state: ReadIndexState) => ReadIndexState): Promise<ReadIndexState>;
+    prepareTeam(teamId: string, version: number): Promise<void>;
     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,13 +1,18 @@
 import { recordConversationRead } from "./conversationRead.js";
 import { BatchedReadIndex } from "./batchedReadIndex.js";
 import { WindowedTasks } from "./coalescer.js";
-import { IndexedDbReadIndex, recordReadIntent } from "./readIndex.js";
+import { IndexedDbReadIndex, 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;
+    accepted = new Set();
     persistence;
     sync;
     tasks;
@@ -21,6 +26,7 @@ export class ReadingClient {
     constructor(options) {
         this.options = options;
         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);
         this.tasks = new WindowedTasks(1000, error => this.failed(error));
         this.sync = new ReadSyncClient({ ...options, persistence: this.persistence, onChange: state => this.publish(state) });
@@ -85,16 +91,37 @@ export class ReadingClient {
         }
         throw new Error("Reading projection has not reached the announced version");
     }
-    async update(transform) {
+    update(transform) {
+        if (this.closed)
+            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);
+                return transform(state);
+            });
+            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"))
+            this.versions = undefined; throw error; });
+        this.accepted.add(task);
+        void task.finally(() => this.accepted.delete(task)).catch(() => { });
+        return task;
+    }
+    async prepareTeam(teamId, version) {
         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();
+        if (version > 0) {
+            await this.persistence.invalidateTeam(this.options.appId, this.options.profileId, teamId, version);
+            this.versions = undefined;
         }
-        return next;
     }
     markRead(threadId, messages = []) {
         return this.update(state => recordConversationRead(state, threadId, messages));
@@ -105,15 +132,55 @@ export class ReadingClient {
         const messageIds = [...new Set(ids)];
         return this.update(state => messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state));
     }
-    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/responseCache.d.ts

@@ -1,7 +1,14 @@
+export type ResponseCacheAccess = () => Promise<{
+    version: number;
+    allowed: boolean;
+}>;
+export declare function isResponseCacheAuthorityError(error: unknown): boolean;
+export declare function assertResponseCacheAccess(access?: ResponseCacheAccess, expectedVersion?: number): Promise<number | undefined>;
 /** Small response windows, isolated by identity. Epochs fence late writes after
  * access withdrawal. No localStorage or synchronous writes on the read path. */
 export declare class IndexedDbResponseCache<T> {
     private scope;
+    private options;
     private db;
     private rows;
     private epochs;
@@ -14,7 +21,12 @@ export declare class IndexedDbResponseCache<T> {
     constructor(scope: string, options?: {
         indexedDB?: IDBFactory;
         name?: string;
+        access?: ResponseCacheAccess;
     });
+    /** Resolve shared message-scope authority before opening our transaction.
+     * A newer authority version retires response windows exactly once; delayed
+     * callers can never roll the authority backwards or delete recovered data. */
+    private synchronizeAccess;
     read(key: string): Promise<{
         epoch: number;
         cached: {
@@ -23,6 +35,9 @@ export declare class IndexedDbResponseCache<T> {
         } | undefined;
     }>;
     write(key: string, value: T, epoch: number): Promise<void>;
+    /** Idempotent shared-scope retirement: an old cleanup cannot erase windows
+     * created after the same authority version was already recovered. */
+    retire(version: number): Promise<void>;
     invalidate(): Promise<void>;
     flush(): Promise<void>;
     close(): Promise<void>;