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

package/lib/runtime/readIndex.d.ts

@@ -77,20 +77,43 @@ 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 {
+    private storageScope?;
+    private migrateLegacy;
     private database;
     private profiles;
+    private versions;
     private closed;
-    constructor(factory?: IDBFactory, name?: string);
+    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,18 +164,45 @@ 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") {
+    constructor(factory = globalThis.indexedDB, name = "pmate-social-read-index", storageScope, migrateLegacy = false) {
+        this.storageScope = storageScope;
+        this.migrateLegacy = migrateLegacy;
         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.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) {
@@ -184,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;
@@ -202,17 +229,59 @@ export class IndexedDbReadIndex {
         }
         throw new Error("READ_STORAGE_UNAVAILABLE");
     }
+    key(appId, profileId) { return this.storageScope === undefined ? [appId, profileId] : [appId, profileId, this.storageScope]; }
+    async loadCurrent(appId, profileId) {
+        const current = await this.profiles.get(this.key(appId, profileId));
+        if (current || !this.migrateLegacy || this.storageScope === undefined)
+            return current;
+        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)
+            return undefined;
+        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.profiles.delete([appId, profileId]);
+        return legacy;
+    }
     async load(appId, profileId) {
-        return this.transaction("r", () => this.profiles.get([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.profiles.get([appId, profileId]);
-            const next = transform(previous ?? createReadIndex(appId, profileId));
+            const previous = await this.loadCurrent(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))
-                await this.profiles.put(next, [appId, profileId]);
+                await this.profiles.put(next, this.key(appId, profileId));
             return next;
         });
     }

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

@@ -1,3 +1,4 @@
+import { type ConversationReadMessage } from "./conversationRead.js";
 import { type ReadIndexPersistence, type ReadIndexState } from "./readIndex.js";
 export type ReadingClientOptions = {
     appId: string;
@@ -5,6 +6,8 @@ export type ReadingClientOptions = {
     sessionToken: string;
     hubHttpUrl: string;
     persistence?: ReadIndexPersistence;
+    storageScope?: string;
+    migrateLegacy?: boolean;
     fetch?: typeof fetch;
     onError?: (error: unknown) => void;
     onRecovered?: () => void;
@@ -14,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;
@@ -33,8 +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,12 +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;
@@ -19,7 +25,8 @@ export class ReadingClient {
     generation = 0;
     constructor(options) {
         this.options = options;
-        const storage = options.persistence ?? (this.storage = new IndexedDbReadIndex());
+        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) });
@@ -84,16 +91,40 @@ 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));
     }
     recordVisible(threadId, messageIds) { return this.record(threadId, messageIds, "visible"); }
     recordExplicit(threadId, messageIds) { return this.record(threadId, messageIds, "explicit"); }
@@ -101,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/recordCache.d.ts

@@ -5,6 +5,8 @@ export type RecordCacheOptions<T> = {
     indexedDB?: IDBFactory;
     name?: string;
     onError?: (error: unknown) => void;
+    transactionBytes?: number;
+    queueBytes?: number;
 };
 /** In-memory control-event index backed by bounded asynchronous IndexedDB batches.
  * Legacy storage is read only during open; the hot path never uses localStorage. */
@@ -23,6 +25,11 @@ export declare class IndexedDbRecordCache<T> {
     private closing;
     private initialized;
     private running?;
+    private activeBytes;
+    private pendingBytes;
+    private activeRecords;
+    private transactionBytes;
+    private queueBytes;
     private channel?;
     private listeners;
     constructor(options: RecordCacheOptions<T>);
@@ -34,7 +41,9 @@ export declare class IndexedDbRecordCache<T> {
     subscribe(listener: () => void): () => void;
     private reload;
     upsert(incoming: T[]): Promise<void>;
+    private bytes;
     private write;
+    private writeBatch;
     flush(): Promise<void>;
     private runFlush;
     close(): Promise<void>;

package/lib/runtime/recordCache.js

@@ -17,17 +17,26 @@ export class IndexedDbRecordCache {
     closing = false;
     initialized = false;
     running;
+    activeBytes = 0;
+    pendingBytes = 0;
+    activeRecords = 0;
+    transactionBytes;
+    queueBytes;
     channel;
     listeners = new Set();
     constructor(options) {
         this.options = options;
+        this.transactionBytes = options.transactionBytes ?? 1_048_576;
+        this.queueBytes = options.queueBytes ?? 8_388_608;
+        if (!Number.isSafeInteger(this.transactionBytes) || this.transactionBytes < 1 || !Number.isSafeInteger(this.queueBytes) || this.queueBytes < this.transactionBytes)
+            throw new Error("INVALID_RECORD_CACHE_BYTE_LIMIT");
         this.db = new Dexie(options.name ?? "pmate-chat-records", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
         this.db.version(1).stores({ records: "[scope+id],scope", metadata: "scope" });
         this.records = this.db.table("records");
         this.metadata = this.db.table("metadata");
         this.tasks = new WindowedTasks(16, error => options.onError?.(error));
         if (typeof BroadcastChannel !== "undefined") {
-            this.channel = new BroadcastChannel(`pmate-chat-records:${options.scope}`);
+            this.channel = new BroadcastChannel(`pmate-chat-records:${options.scope}${this.db.name === "pmate-chat-records" ? "" : `:${this.db.name}`}`);
             this.channel.onmessage = () => this.tasks.schedule("reload", () => this.reload());
         }
     }
@@ -83,30 +92,70 @@ export class IndexedDbRecordCache {
         await this.ready;
         if (this.closed || this.closing)
             throw new Error("RECORD_CACHE_CLOSED");
-        if (incoming.length + this.pending.size > 4096)
+        if (incoming.length > 4096)
             throw new Error("RECORD_CACHE_BACKPRESSURE");
-        let changed = false;
+        // Plan and validate the whole operation before publishing any in-memory state.
+        const staged = new Map();
         for (const value of incoming) {
-            const key = this.options.key(value), old = this.values.get(key), next = this.options.merge(old, value);
+            const key = this.options.key(value), old = staged.get(key) ?? this.values.get(key);
+            const next = this.options.merge(old, value);
             if (JSON.stringify(old) === JSON.stringify(next))
                 continue;
+            if (this.bytes(next) > this.transactionBytes)
+                throw new Error("RECORD_CACHE_RECORD_TOO_LARGE");
+            staged.set(key, structuredClone(next));
+        }
+        let nextBytes = this.pendingBytes, nextRecords = this.pending.size;
+        for (const [key, value] of staged) {
+            const previous = this.pending.get(key);
+            nextBytes += this.bytes(value) - (previous === undefined ? 0 : this.bytes(previous));
+            if (!this.pending.has(key))
+                nextRecords++;
+        }
+        if (nextRecords + this.activeRecords > 4096 || nextBytes + this.activeBytes > this.queueBytes)
+            throw new Error("RECORD_CACHE_BACKPRESSURE");
+        let changed = false;
+        for (const [key, next] of staged) {
             this.values.set(key, next);
             this.pending.set(key, next);
             changed = true;
         }
+        this.pendingBytes = nextBytes;
         if (changed)
             this.snapshotValue = [...this.values.values()];
-        if (!changed && !this.pending.size)
+        if (!changed && !this.pending.size) {
+            await this.running;
             return;
+        }
         const committed = new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
         this.tasks.schedule("write", () => this.flush());
         return committed;
     }
+    bytes(value) { return new TextEncoder().encode(JSON.stringify({ scope: this.options.scope, id: this.options.key(value), value })).byteLength; }
     async write(values) {
+        let batch = [], bytes = 0;
+        for (const value of values) {
+            const size = this.bytes(value);
+            if (size > this.transactionBytes)
+                throw new Error("RECORD_CACHE_RECORD_TOO_LARGE");
+            if (batch.length && (batch.length === 128 || bytes + size > this.transactionBytes)) {
+                await this.writeBatch(batch);
+                batch = [];
+                bytes = 0;
+            }
+            batch.push(value);
+            bytes += size;
+        }
+        if (batch.length)
+            await this.writeBatch(batch);
+    }
+    async writeBatch(values) {
         await this.db.transaction("rw", this.records, async () => {
             const previous = await this.records.bulkGet(values.map(value => [this.options.scope, this.options.key(value)]));
             const records = values.map((value, index) => ({ scope: this.options.scope, id: this.options.key(value), value: this.options.merge(previous[index]?.value, value) }));
             const changed = records.filter((row, index) => JSON.stringify(previous[index]?.value) !== JSON.stringify(row.value));
+            if (changed.reduce((sum, row) => sum + this.bytes(row.value), 0) > this.transactionBytes)
+                throw new Error("RECORD_CACHE_MERGE_TOO_LARGE");
             if (changed.length)
                 await this.records.bulkPut(changed);
         });
@@ -126,8 +175,11 @@ export class IndexedDbRecordCache {
     async runFlush() {
         const values = [...this.pending.values()], waiters = this.waiters.splice(0);
         this.pending.clear();
+        this.pendingBytes = 0;
         if (!values.length)
             return;
+        this.activeBytes = values.reduce((sum, value) => sum + this.bytes(value), 0);
+        this.activeRecords = values.length;
         try {
             for (let offset = 0; offset < values.length; offset += 128)
                 await this.write(values.slice(offset, offset + 128));
@@ -142,9 +194,14 @@ export class IndexedDbRecordCache {
                 const key = this.options.key(value);
                 this.pending.set(key, this.options.merge(value, this.pending.get(key) ?? value));
             }
+            this.pendingBytes = [...this.pending.values()].reduce((sum, value) => sum + this.bytes(value), 0);
             waiters.forEach(waiter => waiter.reject(error));
             throw error;
         }
+        finally {
+            this.activeBytes = 0;
+            this.activeRecords = 0;
+        }
     }
     async close() {
         this.closing = true;

package/lib/runtime/responseCache.d.ts

@@ -0,0 +1,44 @@
+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;
+    private pending;
+    private tasks;
+    private running?;
+    private invalidations;
+    private closed;
+    private closing?;
+    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: {
+            value: T;
+            time: number;
+        } | 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>;
+}