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

package/lib/runtime/messageReaders.js

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

package/lib/runtime/messageStore.d.ts

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

package/lib/runtime/messageStore.js

@@ -6,6 +6,7 @@ export class IndexedDbMessageStore {
     merge;
     db;
     rows;
+    legacy;
     coverage;
     key;
     constructor(scope, merge, options = {}) {
@@ -13,10 +14,13 @@ export class IndexedDbMessageStore {
         this.key = messageScopeKey(scope);
         this.db = new Dexie(options.name ?? "pmate-chat-messages", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
         this.db.version(1).stores({ messages: "[scope+thread+id],[scope+thread+time+id],[scope+thread],scope", coverage: "[scope+thread],scope" });
+        this.db.version(2).stores({ legacyMessages: "[scope+thread+id],[scope+thread+time+id],[scope+thread],scope" });
+        this.legacy = this.db.table("legacyMessages");
         this.rows = this.db.table("messages");
         this.coverage = this.db.table("coverage");
         this.db.on("versionchange", () => { this.db.close({ disableAutoOpen: false }); return false; });
     }
+    get namespace() { return this.db.name; }
     async read(thread, limit = 100, before) {
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
             throw new Error("INVALID_MESSAGE_LIMIT");
@@ -26,43 +30,119 @@ export class IndexedDbMessageStore {
             return { messages: records.slice(0, limit).reverse().map(row => row.value), hasEarlier: records.length > limit, coverage: await this.coverage.get([this.key, thread]) };
         });
     }
-    async commit(thread, messages, coverage) {
+    /** Migration records never claim coverage or overwrite authoritative rows. */
+    async importLegacy(thread, messages) {
+        if (messages.length > 128)
+            throw new Error("MESSAGE_BATCH_TOO_LARGE");
+        let bytes = 0;
+        for (const message of messages) {
+            if (message.threadId !== thread || !message.id || !Number.isFinite(message.timestamp))
+                throw new Error("MESSAGE_SCOPE_MISMATCH");
+            bytes += new TextEncoder().encode(JSON.stringify(message)).byteLength;
+            if (bytes > 1_048_576)
+                throw new Error("MESSAGE_BATCH_TOO_LARGE");
+        }
+        return this.db.transaction("rw", this.rows, this.legacy, this.coverage, async () => {
+            const coverage = await this.coverage.get([this.key, thread]);
+            if (coverage?.revoked)
+                throw new Error("MESSAGE_ACCESS_REVOKED");
+            if ((coverage?.resetVersion ?? 0) > 0)
+                throw new Error("MESSAGE_PROJECTION_CHANGED");
+            const ids = [...new Set(messages.map(message => message.id))], keys = ids.map(id => [this.key, thread, id]);
+            const authoritative = await this.rows.bulkGet(keys), previous = await this.legacy.bulkGet(keys);
+            const known = new Set(authoritative.flatMap(row => row ? [row.id] : []));
+            const latest = new Map(previous.flatMap(row => row ? [[row.id, row.value]] : [])), changed = new Map();
+            for (const message of messages) {
+                if (known.has(message.id))
+                    continue;
+                const old = latest.get(message.id), value = this.merge(old, message);
+                if (value.id !== message.id || value.threadId !== thread || !Number.isFinite(value.timestamp))
+                    throw new Error("MESSAGE_SCOPE_MISMATCH");
+                latest.set(message.id, value);
+                if (JSON.stringify(old) !== JSON.stringify(value))
+                    changed.set(message.id, { scope: this.key, thread, id: value.id, time: value.timestamp, value });
+            }
+            if (changed.size)
+                await this.legacy.bulkPut([...changed.values()]);
+            return changed.size;
+        });
+    }
+    /** Bounded fallback only; callers must report an incomplete window. */
+    async readFallback(thread, limit = 100, before) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error("INVALID_MESSAGE_LIMIT");
+        return this.db.transaction("r", this.rows, this.legacy, this.coverage, async () => {
+            const coverage = await this.coverage.get([this.key, thread]);
+            if (coverage?.revoked)
+                return { messages: [], hasEarlier: false, coverage };
+            const read = (table) => table.where("[scope+thread+time+id]").between([this.key, thread, Dexie.minKey, Dexie.minKey], [this.key, thread, before?.timestamp ?? Dexie.maxKey, before?.id ?? Dexie.maxKey], true, !before).reverse().limit(limit + 1).toArray();
+            const [canonical, legacy] = await Promise.all([read(this.rows), read(this.legacy)]);
+            const rows = [...new Map([...legacy, ...canonical].map(row => [row.id, row])).values()].sort((a, b) => a.time - b.time || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            return { messages: rows.slice(-limit).map(row => row.value), hasEarlier: rows.length > limit, coverage };
+        });
+    }
+    async commit(thread, messages, coverage, guard) {
         for (const message of messages)
             if (message.threadId !== thread || !message.id || !Number.isFinite(message.timestamp))
                 throw new Error("MESSAGE_SCOPE_MISMATCH");
         if (messages.length > 1000)
             throw new Error("MESSAGE_BATCH_TOO_LARGE");
-        return this.db.transaction("rw", this.rows, this.coverage, async () => {
+        return this.db.transaction("rw", this.rows, this.legacy, this.coverage, async () => {
+            const current = await this.coverage.get([this.key, thread]);
+            if (guard && (current?.resetVersion ?? 0) !== guard.version)
+                throw new Error("MESSAGE_PROJECTION_CHANGED");
+            if (guard && current?.revoked && !guard.authoritative)
+                throw new Error("MESSAGE_ACCESS_REVOKED");
             const ids = [...new Set(messages.map(message => message.id))];
-            const previous = await this.rows.bulkGet(ids.map(id => [this.key, thread, id]));
-            const latest = new Map(previous.flatMap(row => row ? [[row.id, row.value]] : []));
+            const keys = ids.map(id => [this.key, thread, id]);
+            const previous = await this.rows.bulkGet(keys), legacy = await this.legacy.bulkGet(keys);
+            const canonicalIds = new Set(previous.flatMap(row => row ? [row.id] : []));
+            const latest = new Map([...legacy, ...previous].flatMap(row => row ? [[row.id, row.value]] : []));
             const changed = new Map();
             for (const message of messages) {
                 const old = latest.get(message.id), value = this.merge(old, message);
                 if (value.id !== message.id || value.threadId !== thread || !Number.isFinite(value.timestamp))
                     throw new Error("MESSAGE_SCOPE_MISMATCH");
                 latest.set(message.id, value);
-                if (JSON.stringify(old) !== JSON.stringify(value))
+                if (!canonicalIds.has(message.id) || JSON.stringify(old) !== JSON.stringify(value))
                     changed.set(message.id, { scope: this.key, thread, id: value.id, time: value.timestamp, value });
             }
             if (changed.size)
                 await this.rows.bulkPut([...changed.values()]);
+            if (ids.length)
+                await this.legacy.bulkDelete(ids.map(id => [this.key, thread, id]));
             if (coverage) {
-                const old = await this.coverage.get([this.key, thread]), next = { ...coverage, scope: this.key, thread };
+                const old = await this.coverage.get([this.key, thread]), next = { ...old, ...coverage, scope: this.key, thread };
                 if (JSON.stringify(old) !== JSON.stringify(next))
                     await this.coverage.put(next);
             }
             return changed.size;
         });
     }
+    async windows() {
+        return this.coverage.where("scope").equals(this.key).toArray();
+    }
+    /** 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 () => {
+            const old = await this.coverage.get([this.key, thread]);
+            const resetVersion = (old?.resetVersion ?? 0) + 1;
+            await this.rows.where("[scope+thread]").equals([this.key, thread]).delete();
+            await this.legacy.where("[scope+thread]").equals([this.key, thread]).delete();
+            await this.coverage.put({ scope: this.key, thread, complete: false, resetVersion, revoked });
+            return resetVersion;
+        });
+    }
     async removeThread(thread) {
-        await this.db.transaction("rw", this.rows, this.coverage, async () => {
+        await this.db.transaction("rw", this.rows, this.legacy, this.coverage, async () => {
             await this.rows.where("[scope+thread]").equals([this.key, thread]).delete();
+            await this.legacy.where("[scope+thread]").equals([this.key, thread]).delete();
             await this.coverage.delete([this.key, thread]);
         });
     }
     async clear() {
-        await this.db.transaction("rw", this.rows, this.coverage, async () => {
+        await this.db.transaction("rw", this.rows, this.legacy, this.coverage, 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 MessageScope } from "./messageStore.js";
 export type ReadCountsResult = {
     appId: string;
     threadId: string;
@@ -11,6 +12,7 @@ export type ReadCountsOptions = {
     clientInstanceId: string;
     hubHttpUrl: string;
     fetch?: typeof fetch;
+    scope?: MessageScope;
     onChange: (value: ReadCountsResult) => void;
     onError?: (error: unknown) => void;
 };
@@ -25,13 +27,22 @@ export declare class ReadCountsClient {
     private generation;
     private retries;
     private closed;
+    private closing?;
     private revision;
     private running;
     private dirty;
     private subscribed;
     private subscriptionDenied;
     private subscriptionPending?;
+    private cache?;
+    private lastResult?;
+    private publish;
+    private revoked;
+    private accessVersion;
+    private requestedRevision;
+    private force;
     constructor(options: ReadCountsOptions);
+    private denyCache;
     private post;
     private subscription;
     private renew;
@@ -40,5 +51,5 @@ export declare class ReadCountsClient {
     reconnect(): void;
     private schedule;
     private refresh;
-    close(): void;
+    close(): Promise<void>;
 }

package/lib/runtime/readCounts.js

@@ -1,3 +1,5 @@
+import { IndexedDbResponseCache } from "./responseCache.js";
+import { messageScopeKey } from "./messageStore.js";
 let subscriptionSequence = 0;
 function nextSubscriptionSequence() { subscriptionSequence = Math.max(Date.now() * 1000, subscriptionSequence + 1); return subscriptionSequence; }
 /** One active conversation; fixed event window, bounded batches, no count polling. */
@@ -11,14 +13,38 @@ export class ReadCountsClient {
     generation = 0;
     retries = 0;
     closed = false;
+    closing;
     revision = -1;
     running = false;
     dirty = false;
     subscribed = false;
     subscriptionDenied = false;
     subscriptionPending;
+    cache;
+    lastResult;
+    publish(value) {
+        if (JSON.stringify(value) === JSON.stringify(this.lastResult))
+            return;
+        this.lastResult = value;
+        this.options.onChange(value);
+    }
+    revoked = false;
+    accessVersion = 0;
+    requestedRevision = -1;
+    force = false;
     constructor(options) {
         this.options = options;
+        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));
+        }
+    }
+    denyCache() {
+        this.revoked = true;
+        this.accessVersion++;
+        this.lastResult = undefined;
+        void this.cache?.invalidate().catch(error => this.options.onError?.(error));
     }
     async post(path, body, signal) {
         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" });
@@ -33,7 +59,7 @@ export class ReadCountsClient {
         return this.post("/api/social/reading/subscription", { appId: this.options.appId, profileId: this.options.profileId, threadId, clientInstanceId: this.options.clientInstanceId, sequence: nextSubscriptionSequence(), release });
     }
     renew() {
-        if (!this.thread || this.closed || this.subscriptionDenied)
+        if (!this.thread || this.closed || this.subscriptionDenied || (typeof navigator !== "undefined" && navigator.onLine === false))
             return;
         const threadId = this.thread, generation = this.generation;
         if (this.subscriptionPending?.generation === generation)
@@ -48,14 +74,18 @@ export class ReadCountsClient {
                 this.heartbeat = setInterval(() => { if (!this.closed && this.thread === threadId)
                     this.renew(); }, 20_000);
             // Recover changes that occurred before a receiver/subscription became ready.
-            if (recovered && this.revision >= 0)
+            if (recovered) {
+                // A fresh cache predates the new lease and cannot cover its delivery gap.
+                this.force = true;
                 this.schedule(0);
+            }
         }).catch(error => {
             if (this.closed || generation !== this.generation)
                 return;
             this.subscribed = false;
             if (/READ_COUNTS_HTTP_(401|403)/.test(String(error))) {
                 this.subscriptionDenied = true;
+                this.denyCache();
                 clearInterval(this.heartbeat);
                 this.heartbeat = undefined;
             }
@@ -83,9 +113,12 @@ export class ReadCountsClient {
         clearTimeout(this.timer);
         clearInterval(this.heartbeat);
         this.timer = undefined;
+        this.lastResult = undefined;
         this.thread = threadId;
         this.ids = ids;
         this.revision = -1;
+        this.requestedRevision = -1;
+        this.force = false;
         this.dirty = false;
         this.retries = 0;
         this.subscribed = false;
@@ -104,11 +137,13 @@ export class ReadCountsClient {
             throw new Error("INVALID_READ_COUNTS_EVENT");
         if (threadId !== this.thread || revision <= this.revision || this.closed)
             return;
+        this.requestedRevision = Math.max(this.requestedRevision, revision);
         this.schedule(3000);
     }
     reconnect() {
         if (!this.thread || this.closed)
             return;
+        this.force = true;
         this.subscribed = false;
         this.subscriptionDenied = false;
         this.renew();
@@ -137,20 +172,44 @@ export class ReadCountsClient {
         let retryDelay;
         const controller = new AbortController();
         this.controller = controller;
+        const accessVersion = this.accessVersion, force = this.force;
+        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;
+            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;
+            if (cached) {
+                this.revision = cached.value.revision;
+                this.publish(cached.value);
+                const offline = typeof navigator !== "undefined" && navigator.onLine === false;
+                if (offline || (!force && this.requestedRevision <= this.revision && Date.now() - cached.time < 5000))
+                    return;
+            }
             const value = await this.post("/api/social/reading/counts", { appId: this.options.appId, profileId: this.options.profileId, threadId, messageIds: ids }, controller.signal);
-            if (generation !== this.generation || this.closed)
+            if (generation !== this.generation || this.closed || accessVersion !== this.accessVersion)
                 return;
             if (value?.appId !== this.options.appId || value.threadId !== threadId || !Number.isSafeInteger(value.revision) || value.revision < 0 || !value.counts || typeof value.counts !== "object" || ids.some(id => !Number.isSafeInteger(value.counts[id]) || value.counts[id] < 0) || Object.keys(value.counts).some(id => !ids.includes(id)))
                 throw new Error("INVALID_READ_COUNTS_RESULT");
+            if (value.revision < this.revision)
+                return;
             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"))
+                    throw error; this.options.onError?.(error); });
+            if (generation !== this.generation || this.closed || accessVersion !== this.accessVersion)
+                return;
             this.revision = value.revision;
-            this.options.onChange(value);
+            this.publish(value);
             if (!this.subscribed)
                 this.renew();
         }
         catch (error) {
             if (!controller.signal.aborted && generation === this.generation && !this.closed) {
+                if (/READ_COUNTS_HTTP_(401|403)/.test(String(error)))
+                    this.denyCache();
                 this.options.onError?.(error);
                 if (!/READ_COUNTS_HTTP_4\d\d|INVALID_READ_COUNTS/.test(String(error)) && this.retries < 3) {
                     retryDelay = 1000 * 2 ** this.retries++;
@@ -167,8 +226,8 @@ export class ReadCountsClient {
         }
     }
     close() {
-        if (this.closed)
-            return;
+        if (this.closing)
+            return this.closing;
         const old = this.thread;
         this.closed = true;
         this.generation++;
@@ -178,5 +237,6 @@ export class ReadCountsClient {
         if (old)
             void this.subscription(old, true).catch(() => { });
         this.thread = undefined;
+        return this.closing = this.cache?.close().catch(error => this.options.onError?.(error)) ?? Promise.resolve();
     }
 }

package/lib/runtime/readIndex.d.ts

@@ -84,11 +84,15 @@ export interface ReadIndexPersistence {
 }
 /** 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 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>;
     close(): Promise<void>;

package/lib/runtime/readIndex.js

@@ -166,10 +166,14 @@ export function unreadInThread(state, threadId) {
 }
 /** Dexie preserves the legacy database/store and outbound [appId, profileId] keys. */
 export class IndexedDbReadIndex {
+    storageScope;
+    migrateLegacy;
     database;
     profiles;
     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 });
@@ -202,17 +206,37 @@ 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 update(appId, profileId, transform) {
         return this.transaction("rw", async () => {
-            const previous = await this.profiles.get([appId, profileId]);
+            const previous = await this.loadCurrent(appId, profileId);
             const next = transform(previous ?? createReadIndex(appId, profileId));
             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/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;
@@ -33,6 +36,7 @@ export declare class ReadingClient {
     refresh: () => void;
     synchronize(targetCursor?: string, profileId?: string): Promise<ReadIndexState>;
     update(transform: (state: ReadIndexState) => ReadIndexState): Promise<ReadIndexState>;
+    markRead(threadId: string, messages?: readonly ConversationReadMessage[]): Promise<ReadIndexState>;
     recordVisible(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     recordExplicit(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     private record;

package/lib/runtime/readingClient.js

@@ -1,3 +1,4 @@
+import { recordConversationRead } from "./conversationRead.js";
 import { BatchedReadIndex } from "./batchedReadIndex.js";
 import { WindowedTasks } from "./coalescer.js";
 import { IndexedDbReadIndex, recordReadIntent } from "./readIndex.js";
@@ -19,7 +20,7 @@ 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.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) });
@@ -95,6 +96,9 @@ export class ReadingClient {
         }
         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"); }
     record(threadId, ids, readPolicy) {

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>;