@pmate/chat-sdk 0.12.0-next.57 → 0.12.0-next.58

package/README.md

@@ -254,3 +254,24 @@ permission change in another team does not discard this team's observations.
 Ordinary shutdown waits for accepted local reading writes, while access withdrawal
 rejects late results. Retired asynchronous reading entries reject through promises;
 refresh/subscription teardown remains safe.
+
+
+### Reading storage recovery
+
+Large reading snapshots use a persisted journal. The full plan becomes durable
+before canonical rows change; bounded transactions apply it, and the sync cursor
+commits last. A reader recovers an active plan before returning a snapshot. Failed
+staging leaves the previous snapshot authoritative; failure after activation keeps
+the old cursor until recovery completes. Pending reads retain their operation IDs.
+
+Writes use at most 128 records per transaction, including journal/lease records,
+and conservatively budget one MiB per batch. Message order is stored per row so a
+source no longer needs a growing array of every message ID. Ordinary observations
+continue to update only positions and pending operations. Locks serialize each
+owner across documents; a fenced IndexedDB lease supports contexts without Web Locks.
+
+The private reading database format is now 60. Existing stores are renamed by
+IndexedDB metadata operations, preserving keys and records. Older SDKs cannot
+write through the former namespace and need a page reload to use the new format.
+The message-body cache is separate and unchanged. The public reading state remains
+schema version 1; applications do not select storage formats or recovery steps.

package/lib/runtime/readBatchJournal.d.ts

@@ -0,0 +1,35 @@
+import { Dexie } from "dexie";
+export type ReadMutation = {
+    table: "readingThreads" | "readingMessages" | "readingPositions";
+    key: string[];
+    value?: unknown;
+};
+type Plan = {
+    profileKey: string[];
+    header: unknown;
+    versions?: unknown;
+};
+/** Cross-document serialization; the persisted journal is the crash boundary. */
+export declare function lockReadOwner<T>(factory: IDBFactory, name: string, owner: string, run: () => Promise<T>, fallback?: (run: () => Promise<T>) => Promise<T>): Promise<T>;
+/** Stage the full plan first, roll forward bounded batches, publish cursor last. */
+export declare class ReadBatchJournal {
+    private db;
+    private closed;
+    private rows;
+    private knownOwners;
+    private leases;
+    private acquiring;
+    constructor(db: Dexie, closed: () => boolean);
+    lease<T>(owner: string, run: () => Promise<T>): Promise<T>;
+    releaseLeases(): Promise<void>;
+    checkLeases(renew?: boolean): Promise<void>;
+    private check;
+    private tables;
+    recover(owner: string): Promise<void>;
+    private cleanup;
+    private apply;
+    private validatePlan;
+    private finish;
+    commit(owner: string, operations: Iterable<ReadMutation>, plan: Plan): Promise<void>;
+}
+export {};

package/lib/runtime/readBatchJournal.js

@@ -0,0 +1,210 @@
+import { Dexie } from "dexie";
+const LIMIT = 124, BYTES = 1024 * 1024, LEASE_MS = 5_000;
+const size = (value) => JSON.stringify(value).length * 3;
+const localLocks = new WeakMap();
+/** Cross-document serialization; the persisted journal is the crash boundary. */
+export async function lockReadOwner(factory, name, owner, run, fallback) {
+    const key = JSON.stringify(["pmate-reading", name, owner]);
+    if (typeof navigator !== "undefined" && navigator.locks)
+        return navigator.locks.request(key, run);
+    if (typeof window !== "undefined") {
+        if (!fallback)
+            throw new Error("READ_STORAGE_LOCK_UNAVAILABLE");
+        return fallback(run);
+    }
+    let locks = localLocks.get(factory);
+    if (!locks) {
+        locks = new Map();
+        localLocks.set(factory, locks);
+    }
+    const previous = locks.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise(resolve => { release = resolve; });
+    locks.set(key, current);
+    await previous;
+    try {
+        return await run();
+    }
+    finally {
+        release();
+        if (locks.get(key) === current)
+            locks.delete(key);
+    }
+}
+/** Stage the full plan first, roll forward bounded batches, publish cursor last. */
+export class ReadBatchJournal {
+    db;
+    closed;
+    rows;
+    knownOwners = new Set();
+    leases = new Map();
+    acquiring = new Set();
+    constructor(db, closed) {
+        this.db = db;
+        this.closed = closed;
+        this.rows = db.table("readBatches");
+    }
+    async lease(owner, run) {
+        const token = crypto.randomUUID();
+        for (;;) {
+            this.check();
+            const attempt = (async () => {
+                const acquired = await this.db.transaction("rw", this.rows, async () => {
+                    const old = (await this.rows.get([owner, "lease"]))?.lease;
+                    if (old && old.expires > Date.now())
+                        return false;
+                    await this.rows.put({ owner, key: "lease", lease: { token, expires: Date.now() + LEASE_MS } });
+                    return true;
+                });
+                if (acquired)
+                    this.leases.set(owner, token);
+                return acquired;
+            })();
+            this.acquiring.add(attempt);
+            const acquired = await attempt.finally(() => this.acquiring.delete(attempt));
+            if (acquired)
+                break;
+            await new Promise(resolve => setTimeout(resolve, 25));
+        }
+        try {
+            const result = await run();
+            this.check();
+            await this.db.transaction("r", this.rows, () => this.checkLeases());
+            return result;
+        }
+        finally {
+            this.leases.delete(owner);
+            if (!this.closed())
+                await this.db.transaction("rw", this.rows, async () => { if ((await this.rows.get([owner, "lease"]))?.lease?.token === token)
+                    await this.rows.delete([owner, "lease"]); });
+        }
+    }
+    async releaseLeases() {
+        await Promise.allSettled([...this.acquiring]);
+        for (const [owner, token] of this.leases)
+            await this.db.transaction("rw", this.rows, async () => { if ((await this.rows.get([owner, "lease"]))?.lease?.token === token)
+                await this.rows.delete([owner, "lease"]); });
+    }
+    async checkLeases(renew = false) {
+        for (const [owner, token] of this.leases) {
+            if ((await this.rows.get([owner, "lease"]))?.lease?.token !== token)
+                throw new Error("READ_STORAGE_LOCK_LOST");
+            if (renew)
+                await this.rows.put({ owner, key: "lease", lease: { token, expires: Date.now() + LEASE_MS } });
+        }
+    }
+    check() { if (this.closed())
+        throw new Error("READ_STORAGE_CLOSED"); }
+    tables() { return [this.rows, ...["readingProfiles", "readingVersions", "readingThreads", "readingMessages", "readingPositions"].map(name => this.db.table(name))]; }
+    async recover(owner) {
+        this.check();
+        const active = (await this.rows.get([owner, "active"]))?.active;
+        if (!active) {
+            if (!this.knownOwners.has(owner)) {
+                await this.cleanup(owner);
+                this.knownOwners.add(owner);
+            }
+            return;
+        }
+        const plan = (await this.rows.get([owner, `${active.id}:plan`]))?.plan;
+        if (!plan || typeof active.id !== "string" || !Number.isSafeInteger(active.next) || !Number.isSafeInteger(active.total) || active.next < 0 || active.total < 1 || active.next > active.total)
+            throw new Error("READ_STORAGE_INCOMPLETE");
+        this.validatePlan(owner, plan);
+        while (active.next < active.total) {
+            this.check();
+            await this.db.transaction("rw", this.tables(), async () => {
+                await this.checkLeases();
+                const chunk = await this.rows.get([owner, `${active.id}:${active.next}`]);
+                if (!chunk?.operations || chunk.operations.length > LIMIT || chunk.operations.some(operation => !["readingThreads", "readingMessages", "readingPositions"].includes(operation.table) || operation.key[0] !== owner || operation.value !== undefined && operation.value.owner !== owner))
+                    throw new Error("READ_STORAGE_INCOMPLETE");
+                await this.apply(chunk.operations);
+                await this.rows.put({ owner, key: "active", active: { ...active, next: active.next + 1 } });
+                await this.checkLeases(true);
+            });
+            active.next++;
+            await new Promise(resolve => setTimeout(resolve, 0));
+        }
+        this.check();
+        await this.db.transaction("rw", this.tables(), async () => { await this.checkLeases(); await this.finish(plan); await this.rows.delete([owner, "active"]); await this.checkLeases(true); });
+        await this.cleanup(owner);
+        this.knownOwners.add(owner);
+    }
+    async cleanup(owner) {
+        for (;;) {
+            this.check();
+            const keys = await this.rows.where("owner").equals(owner).limit(LIMIT).primaryKeys();
+            const removable = keys.filter(key => key[1] !== "lease");
+            if (removable.length)
+                await this.db.transaction("rw", this.rows, async () => { await this.checkLeases(); await this.rows.bulkDelete(removable); await this.checkLeases(true); });
+            const count = keys.length;
+            if (count < LIMIT)
+                return;
+            await new Promise(resolve => setTimeout(resolve, 0));
+        }
+    }
+    async apply(operations) {
+        for (const name of ["readingThreads", "readingMessages", "readingPositions"]) {
+            const selected = operations.filter(operation => operation.table === name);
+            const writes = selected.filter(operation => operation.value !== undefined).map(operation => operation.value);
+            const deletes = selected.filter(operation => operation.value === undefined).map(operation => operation.key);
+            if (writes.length)
+                await this.db.table(name).bulkPut(writes);
+            if (deletes.length)
+                await this.db.table(name).bulkDelete(deletes);
+        }
+    }
+    validatePlan(owner, plan) {
+        const header = plan.header;
+        if (!Array.isArray(plan.profileKey) || JSON.stringify(plan.profileKey) !== owner || !header || header.schemaVersion !== 1 || header.appId !== plan.profileKey[0] || header.profileId !== plan.profileKey[1])
+            throw new Error("READ_IDENTITY_MISMATCH");
+    }
+    async finish(plan) {
+        if (plan.versions !== undefined)
+            await this.db.table("readingVersions").put(plan.versions, plan.profileKey);
+        await this.db.table("readingProfiles").put(plan.header, plan.profileKey);
+    }
+    async commit(owner, operations, plan) {
+        this.check();
+        this.validatePlan(owner, plan);
+        this.knownOwners.delete(owner);
+        await this.cleanup(owner);
+        if (size(plan) > BYTES)
+            throw new Error("READ_STORAGE_RECORD_TOO_LARGE");
+        const id = crypto.randomUUID(), iterator = operations[Symbol.iterator]();
+        let next = iterator.next(), total = 0;
+        while (!next.done) {
+            const batch = [];
+            let bytes = 512;
+            while (!next.done && batch.length < LIMIT) {
+                const weight = size(next.value);
+                if (weight > BYTES - 512)
+                    throw new Error("READ_STORAGE_RECORD_TOO_LARGE");
+                if (batch.length && bytes + weight > BYTES)
+                    break;
+                bytes += weight;
+                batch.push(next.value);
+                next = iterator.next();
+            }
+            if (total === 0 && next.done) {
+                await this.db.transaction("rw", this.tables(), async () => { await this.checkLeases(); await this.apply(batch); await this.finish(plan); await this.checkLeases(true); });
+                this.knownOwners.add(owner);
+                return;
+            }
+            this.check();
+            await this.db.transaction("rw", this.rows, async () => { await this.checkLeases(); await this.rows.put({ owner, key: `${id}:${total++}`, operations: batch }); await this.checkLeases(true); });
+            await new Promise(resolve => setTimeout(resolve, 0));
+        }
+        if (!total) {
+            await this.db.transaction("rw", this.tables(), async () => { await this.checkLeases(); await this.finish(plan); await this.checkLeases(true); });
+            this.knownOwners.add(owner);
+            return;
+        }
+        await this.db.transaction("rw", this.rows, async () => {
+            await this.checkLeases();
+            await this.rows.put({ owner, key: `${id}:plan`, plan });
+            await this.rows.put({ owner, key: "active", active: { id, next: 0, total } });
+            await this.checkLeases(true);
+        });
+        await this.recover(owner);
+    }
+}

package/lib/runtime/readIndex.d.ts

@@ -110,7 +110,7 @@ export interface ReadIndexPersistence {
     /** Transform and persist atomically; UI publishes only the committed result. */
     update(appId: string, profileId: string, transform: ReadIndexTransform, observation?: ReadObservationScope): Promise<ReadIndexState>;
 }
-/** Dexie preserves the legacy database/store and outbound [appId, profileId] keys. */
+/** Preserves the database and logical keys; store renaming fences old format writers. */
 export declare class IndexedDbReadIndex implements ReadIndexPersistence {
     private storageScope?;
     private migrateLegacy;
@@ -121,10 +121,17 @@ export declare class IndexedDbReadIndex implements ReadIndexPersistence {
     private messageRows;
     private positionRows;
     private normalizedStates;
+    private orderedStates;
+    private legacyClean;
     private observationMessages;
     private versions;
     private closed;
+    private journal;
+    private factory;
+    private schemaReady;
+    private ownerTail;
     constructor(factory?: IDBFactory, name?: string, storageScope?: string | undefined, migrateLegacy?: boolean, metadataOnly?: boolean);
+    private owned;
     private transaction;
     private key;
     /** Keyset pages avoid materializing a second, unbounded array of durable rows.
@@ -133,9 +140,7 @@ export declare class IndexedDbReadIndex implements ReadIndexPersistence {
     private hydrate;
     private loadCurrent;
     private loadStored;
-    /** Message bodies are immutable for local read observations: keep them out of
-     * profile/cursor writes, and update only changed normalized rows on sync. */
-    private persist;
+    private cleanupClaimedLegacy;
     load(appId: string, profileId: string): Promise<ReadIndexState | undefined>;
     loadVersioned(appId: string, profileId: string): Promise<{
         state: ReadIndexState | undefined;
@@ -145,6 +150,10 @@ export declare class IndexedDbReadIndex implements ReadIndexPersistence {
     invalidateTeam(appId: string, profileId: string, teamId: string, version: number, knownThreadIds?: readonly string[]): Promise<ReadIndexState>;
     private observe;
     update(appId: string, profileId: string, transform: ReadIndexTransform, observation?: ReadObservationScope): Promise<ReadIndexState>;
+    private updateOwned;
+    private writeState;
+    private cleanUnreachable;
+    private changes;
     close(): Promise<void>;
 }
 export declare function sourcesInConversation(state: ReadIndexState, conversationId: string): IndexedReadThread[];

package/lib/runtime/readIndex.js

@@ -1,3 +1,5 @@
+import { prepareReadSchema } from "./readSchema.js";
+import { ReadBatchJournal, lockReadOwner } from "./readBatchJournal.js";
 import { Dexie } from "dexie";
 import { isReadingControl } from "./readingContent.js";
 import { isValidChatTeamId } from "./thread.js";
@@ -206,7 +208,7 @@ export function removeReadTeam(state, teamId, knownThreadIds = []) {
         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. */
+/** Preserves the database and logical keys; store renaming fences old format writers. */
 export class IndexedDbReadIndex {
     storageScope;
     migrateLegacy;
@@ -217,15 +219,22 @@ export class IndexedDbReadIndex {
     messageRows;
     positionRows;
     normalizedStates = new WeakSet();
+    orderedStates = new WeakSet();
+    legacyClean = new Set();
     observationMessages = new WeakMap();
     versions;
     closed = false;
+    journal;
+    factory;
+    schemaReady;
+    ownerTail = Promise.resolve();
     constructor(factory = globalThis.indexedDB, name = "pmate-social-read-index", storageScope, migrateLegacy = false, metadataOnly = false) {
         this.storageScope = storageScope;
         this.migrateLegacy = migrateLegacy;
         this.metadataOnly = metadataOnly;
         if (!factory)
             throw new Error("READ_STORAGE_UNAVAILABLE");
+        this.factory = factory;
         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: "" });
@@ -237,12 +246,39 @@ export class IndexedDbReadIndex {
         // Keep v4 indexes for already-open older SDKs, and make source discovery
         // dense for legitimate legacy rows whose optional team field is absent.
         this.database.version(5).stores({ readThreads: "[owner+id],owner,[owner+id+value.kind+value.teamId],[owner+value.conversationId+value.kind+value.teamId+id],[owner+id+value.conversationId],[owner+id+value.kind],[owner+value.conversationId+value.kind+id]" });
-        this.positionRows = this.database.table("readPositions");
-        this.threadRows = this.database.table("readThreads");
-        this.messageRows = this.database.table("readMessages");
-        this.profiles = this.database.table("profiles");
-        this.versions = this.database.table("versions");
+        this.database.version(6).stores({ profiles: "unsupportedReadingFormat", versions: "unsupportedReadingFormat", readingProfiles: "", readingVersions: "", readThreads: null, readMessages: null, readPositions: null, readingThreads: "[owner+id],owner,[owner+id+value.kind+value.teamId],[owner+value.conversationId+value.kind+value.teamId+id],[owner+id+value.conversationId],[owner+id+value.kind],[owner+value.conversationId+value.kind+id]", readingMessages: "[owner+thread+id],[owner+thread],owner", readingPositions: "[owner+id],owner", readBatches: "[owner+key],owner" });
+        this.journal = new ReadBatchJournal(this.database, () => this.closed);
+        this.positionRows = this.database.table("readingPositions");
+        this.threadRows = this.database.table("readingThreads");
+        this.messageRows = this.database.table("readingMessages");
+        this.profiles = this.database.table("readingProfiles");
+        this.versions = this.database.table("readingVersions");
         this.database.on("versionchange", () => { this.database.close({ disableAutoOpen: false }); return false; });
+        this.schemaReady = prepareReadSchema(factory, name);
+        void this.schemaReady.catch(() => { });
+    }
+    async owned(appId, profileId, run) {
+        const previous = this.ownerTail;
+        let release;
+        this.ownerTail = new Promise(resolve => { release = resolve; });
+        await previous;
+        try {
+            if (this.closed)
+                throw new Error("READ_STORAGE_CLOSED");
+            await this.schemaReady;
+            if (this.closed)
+                throw new Error("READ_STORAGE_CLOSED");
+            const owner = JSON.stringify(this.key(appId, profileId));
+            return await lockReadOwner(this.factory, this.database.name, owner, async () => { await this.journal.recover(owner); return run(); }, work => this.journal.lease(owner, work));
+        }
+        catch (error) {
+            if (this.closed)
+                throw new Error("READ_STORAGE_CLOSED");
+            throw error;
+        }
+        finally {
+            release();
+        }
     }
     async transaction(mode, execute) {
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -250,11 +286,15 @@ export class IndexedDbReadIndex {
                 throw new Error("READ_STORAGE_CLOSED");
             let started = false;
             try {
-                return await this.database.transaction(mode, [this.profiles, this.versions, this.threadRows, this.messageRows, this.positionRows], async () => {
+                return await this.database.transaction(mode, [this.profiles, this.versions, this.threadRows, this.messageRows, this.positionRows, this.database.table("readBatches")], async () => {
                     if (this.closed)
                         throw new Error("READ_STORAGE_CLOSED");
                     started = true;
-                    return execute();
+                    await this.journal.checkLeases();
+                    const result = await execute();
+                    if (mode === "rw")
+                        await this.journal.checkLeases(true);
+                    return result;
                 });
             }
             catch (error) {
@@ -292,7 +332,7 @@ export class IndexedDbReadIndex {
                 this.readPages(this.messageRows, owner, row => [row.owner, row.thread, row.id], row => {
                     if (!byThread.has(row.thread))
                         byThread.set(row.thread, new Map());
-                    byThread.get(row.thread).set(row.id, row.value);
+                    byThread.get(row.thread).set(row.id, row);
                 }),
                 this.readPages(this.positionRows, owner, row => [row.owner, row.id], row => byPosition.set(row.id, row)),
             ]);
@@ -302,14 +342,27 @@ export class IndexedDbReadIndex {
                     const position = byPosition.get(id);
                     if (!row || !position)
                         throw new Error("READ_STORAGE_INCOMPLETE");
-                    return { ...row.value, readThroughSeq: position.readThroughSeq, explicitReadMessageIds: position.explicitReadMessageIds, messages: row.messageIds.map(messageId => {
-                            const message = byThread.get(id)?.get(messageId);
+                    const stored = byThread.get(id) ?? new Map();
+                    let messages;
+                    if (row.messageCount !== undefined && !row.messageIds.length) {
+                        const ordered = [...stored.values()], ranked = ordered.every(row => Number.isSafeInteger(row.ordinal));
+                        ordered.sort((a, b) => ranked ? a.ordinal - b.ordinal : a.value.seq - b.value.seq);
+                        if (ordered.length !== row.messageCount)
+                            throw new Error("READ_STORAGE_INCOMPLETE");
+                        messages = ordered.map(row => row.value);
+                    }
+                    else
+                        messages = row.messageIds.map(messageId => {
+                            const message = stored.get(messageId);
                             if (!message)
                                 throw new Error("READ_STORAGE_INCOMPLETE");
-                            return message;
-                        }) };
+                            return message.value;
+                        });
+                    return { ...row.value, readThroughSeq: position.readThroughSeq, explicitReadMessageIds: position.explicitReadMessageIds, messages };
                 }) };
             this.normalizedStates.add(result);
+            if ((threadOrder ?? []).every(id => byId.get(id)?.messageCount !== undefined && !byId.get(id).messageIds.length && [...(byThread.get(id)?.values() ?? [])].every(row => Number.isSafeInteger(row.ordinal))))
+                this.orderedStates.add(result);
             return result;
         }
         return current;
@@ -320,140 +373,88 @@ export class IndexedDbReadIndex {
             return current;
         const metadata = readingMetadata(current);
         if (metadata !== current)
-            await this.persist(appId, profileId, current, metadata);
+            await this.writeState(appId, profileId, current, metadata);
         return metadata;
     }
     async loadStored(appId, profileId) {
-        const current = await this.profiles.get(this.key(appId, profileId));
-        if (current?.normalized)
-            return this.hydrate(current, this.key(appId, profileId));
+        const current = await this.transaction("r", async () => {
+            if (this.storageScope === undefined && (await this.profiles.get([appId, profileId, "legacy-owner-v1"]))?.legacyOwner)
+                return undefined;
+            const row = await this.profiles.get(this.key(appId, profileId));
+            if (row && (row.appId !== appId || row.profileId !== profileId || row.schemaVersion !== 1))
+                throw new Error("READ_IDENTITY_MISMATCH");
+            return row?.normalized ? this.hydrate(row, this.key(appId, profileId)) : row;
+        });
         if (current) {
-            const next = this.metadataOnly ? readingMetadata(current) : current;
-            if (this.migrateLegacy || this.metadataOnly)
-                await this.persist(appId, profileId, undefined, next, true);
-            return next;
+            await this.cleanupClaimedLegacy(appId, profileId);
+            if (!this.normalizedStates.has(current) && (this.migrateLegacy || this.metadataOnly)) {
+                const next = this.metadataOnly ? readingMetadata(current) : current;
+                await this.writeState(appId, profileId, undefined, next);
+                return next;
+            }
+            return current;
         }
         if (!this.migrateLegacy || this.storageScope === undefined)
             return undefined;
-        const markerKey = [appId, profileId, "legacy-owner-v1"];
-        const marker = await this.profiles.get(markerKey);
-        if (marker && marker.legacyOwner !== this.storageScope)
-            return undefined;
-        const legacyRow = await this.profiles.get([appId, profileId]);
-        if (!legacyRow)
+        const legacyOwner = JSON.stringify([appId, profileId]);
+        const legacy = await lockReadOwner(this.factory, this.database.name, legacyOwner, async () => {
+            await this.journal.recover(legacyOwner);
+            const allowed = await this.transaction("rw", async () => {
+                const key = [appId, profileId, "legacy-owner-v1"], marker = await this.profiles.get(key);
+                if (marker && marker.legacyOwner !== this.storageScope)
+                    return false;
+                const raw = await this.profiles.get([appId, profileId]);
+                if (!raw)
+                    return false;
+                if (raw.appId !== appId || raw.profileId !== profileId || raw.schemaVersion !== 1)
+                    throw new Error("READ_IDENTITY_MISMATCH");
+                if (!marker)
+                    await this.profiles.put({ ...createReadIndex(appId, profileId), legacyOwner: this.storageScope }, key);
+                return true;
+            });
+            if (!allowed)
+                return undefined;
+            return this.transaction("r", async () => { const row = await this.profiles.get([appId, profileId]); return row?.normalized ? this.hydrate(row, [appId, profileId]) : row; });
+        }, work => this.journal.lease(legacyOwner, work));
+        if (!legacy)
             return undefined;
-        const hydrated = await this.hydrate(legacyRow, [appId, profileId]);
-        const legacy = this.metadataOnly ? readingMetadata(hydrated) : hydrated;
         if (legacy.appId !== appId || legacy.profileId !== profileId || legacy.schemaVersion !== 1)
             throw new Error("READ_IDENTITY_MISMATCH");
-        const ownership = { ...createReadIndex(appId, profileId), legacyOwner: this.storageScope };
-        await this.profiles.put(ownership, markerKey);
-        await this.persist(appId, profileId, undefined, legacy);
-        await this.profiles.delete([appId, profileId]);
-        const oldOwner = JSON.stringify([appId, profileId]);
-        await this.threadRows.where("owner").equals(oldOwner).delete();
-        await this.messageRows.where("owner").equals(oldOwner).delete();
-        await this.positionRows.where("owner").equals(oldOwner).delete();
-        return legacy;
+        const next = this.metadataOnly ? readingMetadata(legacy) : legacy;
+        await this.writeState(appId, profileId, undefined, next);
+        await this.cleanupClaimedLegacy(appId, profileId);
+        return next;
     }
-    /** Message bodies are immutable for local read observations: keep them out of
-     * profile/cursor writes, and update only changed normalized rows on sync. */
-    async persist(appId, profileId, previous, next, replaceLegacy = false) {
-        if (previous && !this.normalizedStates.has(previous)) {
-            previous = undefined;
-            replaceLegacy = true;
-        }
-        const owner = JSON.stringify(this.key(appId, profileId));
-        const oldThreads = new Map(previous?.threads.map(thread => [thread.id, thread]) ?? []);
-        const nextIds = new Set(next.threads.map(thread => thread.id));
-        if (nextIds.size !== next.threads.length)
-            throw new Error("DUPLICATE_READ_THREAD");
-        const threadWrites = [], messageWrites = [], positionWrites = [];
-        const messageDeletes = [];
-        for (const thread of next.threads) {
-            const old = oldThreads.get(thread.id);
-            if (old === thread)
-                continue;
-            const { messages, readThroughSeq, explicitReadMessageIds, ...value } = thread;
-            const position = { owner, id: thread.id, readThroughSeq, explicitReadMessageIds };
-            if (!old || old.readThroughSeq !== readThroughSeq || JSON.stringify(old.explicitReadMessageIds) !== JSON.stringify(explicitReadMessageIds))
-                positionWrites.push(position);
-            const oldValue = old ? (({ messages: _messages, readThroughSeq: _seq, explicitReadMessageIds: _explicit, ...rest }) => rest)(old) : undefined;
-            if (!old || old.messages !== messages || JSON.stringify(oldValue) !== JSON.stringify(value)) {
-                const metadata = { owner, id: thread.id, value, messageIds: messages.map(message => message.id) };
-                const oldMetadata = old ? { owner, id: old.id, value: oldValue, messageIds: old.messages.map(message => message.id) } : undefined;
-                if (JSON.stringify(metadata) !== JSON.stringify(oldMetadata))
-                    threadWrites.push(metadata);
-            }
-            if (old?.messages === messages)
-                continue;
-            const byId = new Map(old?.messages.map(message => [message.id, message]) ?? []);
-            const ids = new Set();
-            for (const message of messages) {
-                if (ids.has(message.id))
-                    throw new Error("INVALID_READ_MESSAGE");
-                ids.add(message.id);
-                const prior = byId.get(message.id);
-                if (prior !== message && JSON.stringify(prior) !== JSON.stringify(message))
-                    messageWrites.push({ owner, thread: thread.id, id: message.id, value: message });
-            }
-            for (const id of byId.keys())
-                if (!ids.has(id))
-                    messageDeletes.push([owner, thread.id, id]);
+    async cleanupClaimedLegacy(appId, profileId) {
+        if (this.storageScope === undefined || !this.migrateLegacy)
+            return;
+        const key = JSON.stringify(this.key(appId, profileId));
+        if (this.legacyClean.has(key))
+            return;
+        const marker = await this.transaction("r", () => this.profiles.get([appId, profileId, "legacy-owner-v1"]));
+        if (marker?.legacyOwner === this.storageScope) {
+            await this.transaction("rw", () => this.profiles.delete([appId, profileId]));
+            await this.cleanUnreachable(JSON.stringify([appId, profileId]), undefined);
         }
-        for (const id of oldThreads.keys())
-            if (!nextIds.has(id)) {
-                await this.threadRows.delete([owner, id]);
-                await this.positionRows.delete([owner, id]);
-                await this.messageRows.where("[owner+thread]").equals([owner, id]).delete();
-            }
-        // A legacy document can replace the full profile after normalization. Its
-        // replacement is authoritative for the row set; discard unreachable bodies
-        // in the same transaction before installing the rebuilt normalized records.
-        if (replaceLegacy) {
-            await this.messageRows.where("owner").equals(owner).delete();
-            await this.threadRows.where("owner").equals(owner).delete();
-            await this.positionRows.where("owner").equals(owner).delete();
-        }
-        // Bound each IndexedDB bulk request. A snapshot and its cursor still commit
-        // atomically; bounding total snapshot transaction bytes is separate work.
-        for (let offset = 0; offset < positionWrites.length; offset += 128)
-            await this.positionRows.bulkPut(positionWrites.slice(offset, offset + 128));
-        for (let offset = 0; offset < threadWrites.length; offset += 128)
-            await this.threadRows.bulkPut(threadWrites.slice(offset, offset + 128));
-        for (let offset = 0; offset < messageWrites.length; offset += 128)
-            await this.messageRows.bulkPut(messageWrites.slice(offset, offset + 128));
-        for (let offset = 0; offset < messageDeletes.length; offset += 128)
-            await this.messageRows.bulkDelete(messageDeletes.slice(offset, offset + 128));
-        const header = (state) => ({ ...state, threads: [], normalized: true, threadOrder: state.threads.map(thread => thread.id) });
-        const nextHeader = header(next);
-        if (!previous || JSON.stringify(header(previous)) !== JSON.stringify(nextHeader))
-            await this.profiles.put(nextHeader, this.key(appId, profileId));
-        this.normalizedStates.add(next);
+        this.legacyClean.add(key);
     }
     async load(appId, profileId) {
-        return this.transaction(this.migrateLegacy || this.metadataOnly ? "rw" : "r", () => this.loadCurrent(appId, profileId));
+        return this.owned(appId, profileId, () => this.loadCurrent(appId, profileId));
     }
     async loadVersioned(appId, profileId) {
-        return this.transaction(this.migrateLegacy || this.metadataOnly ? "rw" : "r", async () => ({
-            state: await this.loadCurrent(appId, profileId), versions: (await this.versions.get(this.key(appId, profileId)))?.teams ?? {},
-        }));
+        return this.owned(appId, profileId, async () => ({ state: await this.loadCurrent(appId, profileId), versions: await this.transaction("r", async () => (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 ?? {});
+        return this.owned(appId, profileId, () => 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 ?? {};
+        return this.owned(appId, profileId, async () => {
+            const teams = await this.transaction("r", async () => (await this.versions.get(this.key(appId, profileId)))?.teams ?? {});
             if (readTeamVersion(teams, teamId) >= version)
-                return state;
-            const next = removeReadTeam(state, teamId, knownThreadIds);
-            await this.versions.put({ teams: { ...teams, [teamId]: version } }, this.key(appId, profileId));
-            await this.persist(appId, profileId, state, next);
-            return next;
+                return await this.loadCurrent(appId, profileId) ?? createReadIndex(appId, profileId);
+            return this.updateOwned(appId, profileId, state => removeReadTeam(state, teamId, knownThreadIds), undefined, { teams: { ...teams, [teamId]: version } });
         });
     }
     async observe(appId, profileId, transform, scope) {
@@ -545,6 +546,8 @@ export class IndexedDbReadIndex {
             if (thread.readThroughSeq !== before.readThroughSeq || JSON.stringify(thread.explicitReadMessageIds) !== JSON.stringify(before.explicitReadMessageIds))
                 writes.push({ owner, id: thread.id, readThroughSeq: thread.readThroughSeq, explicitReadMessageIds: thread.explicitReadMessageIds });
         }
+        if (writes.length > 126)
+            return undefined;
         if (writes.length)
             await this.positionRows.bulkPut(writes);
         if (JSON.stringify(header.pending) !== JSON.stringify(result.pending) || JSON.stringify(header.observedReadIntents) !== JSON.stringify(result.observedReadIntents))
@@ -564,22 +567,97 @@ export class IndexedDbReadIndex {
         return { ...base, threads, pending: result.pending, observedReadIntents: result.observedReadIntents };
     }
     async update(appId, profileId, transform, observation) {
-        return this.transaction("rw", async () => {
-            if (observation) {
-                const next = await this.observe(appId, profileId, transform, observation);
-                if (next)
-                    return next;
-            }
-            const previous = await this.loadCurrent(appId, profileId);
-            const transformed = transform(previous ?? createReadIndex(appId, profileId), (await this.versions.get(this.key(appId, profileId)))?.teams ?? {});
-            const next = this.metadataOnly ? readingMetadata(transformed) : transformed;
-            if (next.appId !== appId || next.profileId !== profileId || next.schemaVersion !== 1)
-                throw new Error("READ_IDENTITY_MISMATCH");
-            await this.persist(appId, profileId, previous, next);
+        return this.owned(appId, profileId, () => this.updateOwned(appId, profileId, transform, observation));
+    }
+    async updateOwned(appId, profileId, transform, observation, versions) {
+        if (observation) {
+            const observed = await this.transaction("rw", () => this.observe(appId, profileId, transform, observation));
+            if (observed)
+                return observed;
+        }
+        if (this.storageScope === undefined && (await this.profiles.get([appId, profileId, "legacy-owner-v1"]))?.legacyOwner)
+            throw new Error("READ_LEGACY_OWNERSHIP_CHANGED");
+        const loaded = { previous: await this.loadCurrent(appId, profileId), versions: await this.transaction("r", async () => (await this.versions.get(this.key(appId, profileId)))?.teams ?? {}) };
+        const previous = loaded.previous, transformed = transform(previous ?? createReadIndex(appId, profileId), loaded.versions);
+        const next = this.metadataOnly ? readingMetadata(transformed) : transformed;
+        if (next.appId !== appId || next.profileId !== profileId || next.schemaVersion !== 1)
+            throw new Error("READ_IDENTITY_MISMATCH");
+        if (next === previous && !versions)
             return next;
-        });
+        await this.writeState(appId, profileId, previous, next, versions);
+        return next;
+    }
+    async writeState(appId, profileId, previous, next, versions) {
+        const owner = JSON.stringify(this.key(appId, profileId)), header = { ...next, threads: [], normalized: true, threadOrder: next.threads.map(thread => thread.id) };
+        if (!previous || !this.orderedStates.has(previous))
+            await this.cleanUnreachable(owner, previous);
+        await this.journal.commit(owner, this.changes(owner, previous, next), { profileKey: this.key(appId, profileId), header, versions });
+        this.normalizedStates.add(next);
+        this.orderedStates.add(next);
+    }
+    async cleanUnreachable(owner, previous) {
+        const threads = new Map(previous?.threads.map(thread => [thread.id, new Set(thread.messages.map(message => message.id))]) ?? []);
+        for (const name of ["readingThreads", "readingPositions", "readingMessages"]) {
+            const table = this.database.table(name);
+            let after;
+            for (;;) {
+                const keys = await table.where(":id").between(after ?? [owner, Dexie.minKey], [owner, Dexie.maxKey], !after, true).limit(126).primaryKeys();
+                if (!keys.length)
+                    break;
+                const dead = keys.filter(key => !threads.has(key[1]) || name === "readingMessages" && !threads.get(key[1]).has(key[2]));
+                if (dead.length)
+                    await this.transaction("rw", () => table.bulkDelete(dead));
+                after = keys[keys.length - 1];
+                if (keys.length < 126)
+                    break;
+            }
+        }
+    }
+    *changes(owner, previous, next) {
+        const oldThreads = new Map(previous?.threads.map(thread => [thread.id, thread]) ?? []), ids = new Set(), modern = previous !== undefined && this.orderedStates.has(previous);
+        for (const thread of next.threads) {
+            if (ids.has(thread.id))
+                throw new Error("DUPLICATE_READ_THREAD");
+            ids.add(thread.id);
+            const old = oldThreads.get(thread.id);
+            if (old === thread && modern)
+                continue;
+            const { messages, readThroughSeq, explicitReadMessageIds, ...value } = thread;
+            if (!modern || !old || old.readThroughSeq !== readThroughSeq || JSON.stringify(old.explicitReadMessageIds) !== JSON.stringify(explicitReadMessageIds))
+                yield { table: "readingPositions", key: [owner, thread.id], value: { owner, id: thread.id, readThroughSeq, explicitReadMessageIds } };
+            const metadata = { owner, id: thread.id, value, messageIds: [], messageCount: messages.length };
+            const oldMetadata = old ? { owner, id: old.id, value: (({ messages: _m, readThroughSeq: _r, explicitReadMessageIds: _e, ...rest }) => rest)(old), messageIds: modern ? [] : old.messages.map(message => message.id), ...(modern ? { messageCount: old.messages.length } : {}) } : undefined;
+            if (JSON.stringify(metadata) !== JSON.stringify(oldMetadata))
+                yield { table: "readingThreads", key: [owner, thread.id], value: metadata };
+            if (old?.messages === messages && modern)
+                continue;
+            const byId = new Map(old?.messages.map(message => [message.id, message]) ?? []), ranks = new Map(old?.messages.map((message, index) => [message.id, index]) ?? []), seen = new Set();
+            for (const [ordinal, message] of messages.entries()) {
+                if (seen.has(message.id))
+                    throw new Error("INVALID_READ_MESSAGE");
+                seen.add(message.id);
+                const prior = byId.get(message.id);
+                if (!modern || ranks.get(message.id) !== ordinal || prior !== message && JSON.stringify(prior) !== JSON.stringify(message))
+                    yield { table: "readingMessages", key: [owner, thread.id, message.id], value: { owner, thread: thread.id, id: message.id, value: message, ordinal } };
+            }
+            for (const id of byId.keys())
+                if (!seen.has(id))
+                    yield { table: "readingMessages", key: [owner, thread.id, id] };
+        }
+        for (const old of oldThreads.values())
+            if (!ids.has(old.id)) {
+                yield { table: "readingThreads", key: [owner, old.id] };
+                yield { table: "readingPositions", key: [owner, old.id] };
+                for (const message of old.messages)
+                    yield { table: "readingMessages", key: [owner, old.id, message.id] };
+            }
+    }
+    async close() { this.closed = true; try {
+        await this.journal.releaseLeases();
     }
-    async close() { this.closed = true; this.database.close(); }
+    finally {
+        this.database.close();
+    } }
 }
 export function sourcesInConversation(state, conversationId) {
     return state.threads.filter(thread => (thread.conversationId ?? thread.id) === conversationId);

package/lib/runtime/readSchema.d.ts

@@ -0,0 +1,2 @@
+/** Metadata-only store renaming fences SDKs that cannot read chunked snapshots. */
+export declare function prepareReadSchema(factory: IDBFactory, name: string): Promise<void>;

package/lib/runtime/readSchema.js

@@ -0,0 +1,58 @@
+/** Metadata-only store renaming fences SDKs that cannot read chunked snapshots. */
+export async function prepareReadSchema(factory, name) {
+    const existing = await new Promise((resolve, reject) => {
+        const request = factory.open(name);
+        let fresh = false;
+        request.onupgradeneeded = event => { if (event.oldVersion === 0) {
+            fresh = true;
+            request.transaction.abort();
+        } };
+        request.onerror = event => { event.preventDefault(); if (fresh)
+            resolve(undefined);
+        else
+            reject(request.error); };
+        request.onsuccess = () => resolve(request.result);
+    });
+    if (!existing)
+        return;
+    const prepared = existing.objectStoreNames.contains("readingProfiles") && existing.objectStoreNames.contains("readingMessages");
+    const version = existing.version;
+    existing.close();
+    if (version >= 60 && prepared)
+        return;
+    await new Promise((resolve, reject) => {
+        const request = factory.open(name, Math.max(60, version + 1));
+        request.onerror = () => reject(request.error);
+        request.onupgradeneeded = () => {
+            const db = request.result, tx = request.transaction;
+            for (const [before, after] of [["profiles", "readingProfiles"], ["versions", "readingVersions"], ["readThreads", "readingThreads"], ["readMessages", "readingMessages"], ["readPositions", "readingPositions"]]) {
+                if (db.objectStoreNames.contains(before)) {
+                    if (db.objectStoreNames.contains(after)) {
+                        tx.abort();
+                        return;
+                    }
+                    tx.objectStore(before).name = after;
+                }
+            }
+            if (!db.objectStoreNames.contains("readingProfiles"))
+                db.createObjectStore("readingProfiles");
+            if (!db.objectStoreNames.contains("readingVersions"))
+                db.createObjectStore("readingVersions");
+            // Explicit-key writes from older SDKs must fail rather than recreate a cache
+            // beside a partially applied transition or silently return an empty history.
+            db.createObjectStore("profiles", { keyPath: "unsupportedReadingFormat" });
+            db.createObjectStore("versions", { keyPath: "unsupportedReadingFormat" });
+            const define = (name, keyPath, indexes) => {
+                const store = db.objectStoreNames.contains(name) ? tx.objectStore(name) : db.createObjectStore(name, { keyPath });
+                for (const [index, path] of Object.entries(indexes))
+                    if (!store.indexNames.contains(index))
+                        store.createIndex(index, path);
+            };
+            define("readingThreads", ["owner", "id"], { owner: "owner", "[owner+id+value.kind+value.teamId]": ["owner", "id", "value.kind", "value.teamId"], "[owner+value.conversationId+value.kind+value.teamId+id]": ["owner", "value.conversationId", "value.kind", "value.teamId", "id"], "[owner+id+value.conversationId]": ["owner", "id", "value.conversationId"], "[owner+id+value.kind]": ["owner", "id", "value.kind"], "[owner+value.conversationId+value.kind+id]": ["owner", "value.conversationId", "value.kind", "id"] });
+            define("readingMessages", ["owner", "thread", "id"], { owner: "owner", "[owner+thread]": ["owner", "thread"] });
+            define("readingPositions", ["owner", "id"], { owner: "owner" });
+            define("readBatches", ["owner", "key"], { owner: "owner" });
+        };
+        request.onsuccess = () => { request.result.close(); resolve(); };
+    });
+}

package/package.json

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