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

package/README.md

@@ -39,7 +39,7 @@ A dropped socket (including a network change or a suspended laptop) previously r
 
 `client.watchConnection(handler)` immediately reports the current state and returns an unsubscribe function. States are `connecting`, `reconnecting`, `authenticating`, `connected`, `authentication_required`, and `closed`. Only `connected` means the Hub acknowledged authentication. A rejected authentication stops retries; supply a fresh login session using a new client. `close()` cancels retries, heartbeat timers and browser wake listeners.
 
-Messages sent without an acknowledgement are rejected on disconnect and are **not replayed**: delivery is uncertain, so automatic retries could duplicate them. Callers should preserve drafts, display a reconnecting state, and refresh message history after recovery. No durable offline outbox is provided. An initial `connect()` wait times out after 30 seconds, but recovery continues until explicitly closed; retain the client and observe its connection state.
+The low-level `ChatClient.sendChat` rejects unacknowledged sends on disconnect and does not provide a durable outbox. Browser applications should use `createChat().sendMessage` below, which persists the exact wire in IndexedDB and owns delivery state and retries. An initial `connect()` wait times out after 30 seconds, but recovery continues until explicitly closed; retain the client and observe its connection state.
 
 ## Versioned Markdown and chart content
 
@@ -155,7 +155,10 @@ const offSummary = chat.subscribe(() => renderSummary(chat.getSnapshot()))
 await chat.observeMessages(threadId, visibleIds, "visible")
 // Report only the actual audio `playing` event.
 await chat.observeMessages(threadId, [voiceId], "played")
-await chat.sendMessage(threadId, { to, body, recipients })
+const conversation = { id: threadId, kind: "dm" as const, targetId: peerId, teamId }
+await chat.sendMessage(conversation, { text: "Hello" })
+await chat.sendMessage(conversation, { image: { url: uploadedUrl, name: "photo.png" } })
+await chat.sendMessage(conversation, { voice: { blob: recording, durationMs: 1200 } })
 const readers = await chat.getReaders(threadId, messageId)
 off(); offSummary()
 // Ordinary navigation/shutdown preserves offline data.
@@ -169,6 +172,14 @@ await chat.close()
 await chat.revokeAccess()
 ```
 
+Conversation descriptors identify the target and optional group `memberIds`; the SDK
+checks the descriptor against its identity and team before acceptance. It builds
+text, image, quote and voice envelopes and expands group `@all`/`@所有人` to concrete
+members. Content callers do not provide `appId`, protocol `body` or `recipients`.
+The existing `sendMessage(threadId, { to, body, recipients })` form remains available
+for protocol integrations. Blob voice uploads stay in the durable sender; offline
+uploads wait for retry instead of starting HTTP.
+
 The facade owns all clients below. Message reads transparently restore IndexedDB
 windows and fetch missing ranges through the authenticated Hub. Its normalized
 messages retain the protocol body; product rendering remains with the host.
@@ -243,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/chatSession.d.ts

@@ -1,3 +1,4 @@
+import { type ChatConversation, type OutgoingContent } from "./outgoingContent.js";
 import { type TimelineItem } from "./messageTimeline.js";
 import { type ReadingCandidate, type MessageReadingState } from "./conversationReading.js";
 import type { ConversationReadMessage } from "./conversationRead.js";
@@ -120,6 +121,7 @@ export declare class ChatSession<T extends StoredMessage> {
     private rememberHistoryEdge;
     private readEarlier;
     private readAll;
+    sendMessage(thread: ChatConversation, input: OutgoingContent): Promise<ChatRuntimeMessage>;
     sendMessage(threadId: string, input: SendMessageInput): Promise<ChatRuntimeMessage>;
     getReaders(threadId: string, messageId: string, page?: Omit<MessageReadersQuery, "threadId" | "messageId">, signal?: AbortSignal): Promise<import("./messageReaders.js").MessageReadersPage>;
     retryMessage(messageId: string): Promise<ChatRuntimeMessage>;

package/lib/runtime/chatSession.js

@@ -1,3 +1,4 @@
+import { outgoingContent } from "./outgoingContent.js";
 import { projectMessageTimeline } from "./messageTimeline.js";
 import { projectConversationReading } from "./conversationReading.js";
 import { ReadCountsClient } from "./readCounts.js";
@@ -359,9 +360,11 @@ export class ChatSession {
         }
         throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
     }
-    sendMessage(threadId, input) {
+    sendMessage(thread, input) {
         this.assertOpen();
-        return this.sender.enqueue(threadId, input).then(next => { if (this.withdrawn)
+        const threadId = typeof thread === "string" ? thread : thread.id;
+        const wire = typeof thread === "string" ? input : outgoingContent(this.options.messages.scope, thread, input);
+        return this.sender.enqueue(threadId, wire).then(next => { if (this.withdrawn)
             throw new Error("CHAT_ACCESS_REVOKED"); return next; });
     }
     async getReaders(threadId, messageId, page = {}, signal) {

package/lib/runtime/index.d.ts

@@ -33,3 +33,4 @@ export * from "./conversationRead.js";
 export { projectConversationReading, type ReadingCandidate, type MessageReadingState, type ConversationReadingView } from "./conversationReading.js";
 export { projectMessageTimeline, type TimelineItem, type TimelineReaction, type TimelineReactionEvent } from "./messageTimeline.js";
 export * from "./messageLaunch.js";
+export * from "./outgoingContent.js";

package/lib/runtime/index.js

@@ -33,3 +33,4 @@ export * from "./conversationRead.js";
 export { projectConversationReading } from "./conversationReading.js";
 export { projectMessageTimeline } from "./messageTimeline.js";
 export * from "./messageLaunch.js";
+export * from "./outgoingContent.js";

package/lib/runtime/outgoingContent.d.ts

@@ -0,0 +1,47 @@
+import type { ChatMention } from "../mentions/model.js";
+import type { MessageScope } from "./messageStore.js";
+import type { SendMessageInput } from "./durableSender.js";
+export type ChatConversation = {
+    id: string;
+    kind: "dm" | "group";
+    targetId: string;
+    teamId?: string;
+    memberIds?: readonly string[];
+};
+export type MessageQuote = {
+    messageId?: string;
+    senderName: string;
+    content: string;
+};
+export type OutgoingContent = {
+    text: string;
+    mentions?: ChatMention[];
+    quote?: MessageQuote;
+    image?: never;
+    voice?: never;
+} | {
+    image: {
+        url: string;
+        name?: string;
+    };
+    text?: never;
+    voice?: never;
+} | {
+    voice: ({
+        blob: Blob;
+        url?: never;
+    } | {
+        url: string;
+        blob?: never;
+    }) & {
+        durationMs: number;
+        transcript?: string;
+    };
+    text?: never;
+    image?: never;
+};
+export declare const ALL_MENTION_ID = "__pmate_mention_all__";
+/** Expand group mentions into concrete members understood by all protocol readers. */
+export declare function expandGroupMentions(text: string, mentions: ChatMention[] | undefined, memberIds: readonly string[], senderId: string): ChatMention[];
+/** Build the existing wire protocol inside the owner, before durable acceptance. */
+export declare function outgoingContent(scope: MessageScope, thread: ChatConversation, input: OutgoingContent): SendMessageInput;

package/lib/runtime/outgoingContent.js

@@ -0,0 +1,58 @@
+import { dmThreadId, groupThreadId } from "./thread.js";
+export const ALL_MENTION_ID = "__pmate_mention_all__";
+/** Expand group mentions into concrete members understood by all protocol readers. */
+export function expandGroupMentions(text, mentions, memberIds, senderId) {
+    const validMembers = [...new Set(memberIds)], members = validMembers.filter(id => id !== senderId), entries = [...(mentions ?? [])];
+    const pattern = /(?:^|[\s([{，。！？、：；])(@(?:all|所有人))(?=$|[\s,.;:!?，。！？、：；)\]}])/gu;
+    for (const match of text.matchAll(pattern)) {
+        const start = match.index + match[0].length - match[1].length;
+        if (!entries.some(entry => entry.start === start && entry.end === start + match[1].length))
+            entries.push({ id: ALL_MENTION_ID, name: match[1].slice(1), start, end: start + match[1].length });
+    }
+    const seen = new Set();
+    return entries.flatMap(entry => {
+        if (text.slice(entry.start, entry.end) !== `@${entry.name}`)
+            return [];
+        if (entry.id === ALL_MENTION_ID)
+            return ["all", "所有人"].includes(entry.name) ? members.map(id => ({ ...entry, id })) : [];
+        return validMembers.includes(entry.id) ? [entry] : [];
+    }).filter(entry => { const key = `${entry.id}:${entry.start}:${entry.end}`; if (seen.has(key))
+        return false; seen.add(key); return true; });
+}
+/** Build the existing wire protocol inside the owner, before durable acceptance. */
+export function outgoingContent(scope, thread, input) {
+    if (!thread || !["dm", "group"].includes(thread.kind) || typeof thread.targetId !== "string" || !thread.targetId || thread.teamId !== undefined && thread.teamId !== scope.teamId)
+        throw new Error("INVALID_MESSAGE_CONVERSATION");
+    const expected = thread.kind === "group" ? groupThreadId(scope.appId, thread.targetId, scope.teamId) : dmThreadId(scope.appId, scope.profileId, thread.targetId, scope.teamId);
+    if (thread.id !== expected)
+        throw new Error("MESSAGE_CONVERSATION_MISMATCH");
+    const recipients = thread.kind === "group" ? [...new Set(thread.memberIds)] : undefined;
+    if (recipients && (!recipients.length || recipients.some(id => typeof id !== "string" || !id)))
+        throw new Error("MESSAGE_GROUP_MEMBERS_UNAVAILABLE");
+    const base = { appId: scope.appId, ...(scope.teamId === undefined ? {} : { teamId: scope.teamId }), ...(thread.kind === "group" ? { groupId: thread.targetId } : {}) };
+    if (!input || typeof input !== "object" || ["text", "image", "voice"].filter(key => Object.hasOwn(input, key)).length !== 1)
+        throw new Error("INVALID_MESSAGE_CONTENT");
+    let content, contentKind = "text", voiceBlob;
+    if ("text" in input) {
+        if (typeof input.text !== "string")
+            throw new Error("INVALID_MESSAGE_TEXT");
+        const mentions = thread.kind === "group" ? expandGroupMentions(input.text, input.mentions, recipients, scope.profileId) : input.mentions;
+        content = { ...base, text: input.text, ...(input.quote ? { quote: input.quote } : {}), ...(mentions?.length ? { mentions } : {}) };
+    }
+    else if ("image" in input && input.image) {
+        if (typeof input.image.url !== "string" || !input.image.url)
+            throw new Error("INVALID_MESSAGE_IMAGE");
+        contentKind = "image";
+        content = { ...base, url: input.image.url, ...(input.image.name === undefined ? {} : { name: input.image.name }) };
+    }
+    else if ("voice" in input && input.voice) {
+        const voice = input.voice;
+        if (!Number.isFinite(voice.durationMs) || voice.durationMs <= 0 || !("blob" in voice ? voice.blob instanceof Blob : typeof voice.url === "string" && voice.url.length > 0))
+            throw new Error("INVALID_MESSAGE_VOICE");
+        voiceBlob = voice.blob;
+        content = { ...base, text: "[语音]", voice: { url: voiceBlob ? "" : voice.url, durationMs: voice.durationMs, ...(voice.transcript ? { transcript: voice.transcript } : {}) } };
+    }
+    else
+        throw new Error("INVALID_MESSAGE_CONTENT");
+    return { to: thread.targetId, body: { kind: "message", threadKind: thread.kind, contentKind, content }, ...(recipients ? { recipients } : {}), ...(voiceBlob ? { voiceBlob } : {}) };
+}

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/lib/runtime/voiceUpload.js

@@ -1,6 +1,11 @@
+import { isOffline } from "./connectivity.js";
 /** The SDK owns upload I/O; hosts configure only their service endpoint. */
 export function voiceUploader(profileId, endpoint = "https://upload-fc.pmate.chat", fetcher = globalThis.fetch) {
     return async (blob, signal) => {
+        if (signal.aborted)
+            throw new DOMException("Upload aborted", "AbortError");
+        if (isOffline())
+            throw new Error("VOICE_UPLOAD_OFFLINE");
         const bytes = new Uint8Array(await blob.arrayBuffer());
         if (signal.aborted)
             throw new DOMException("Upload aborted", "AbortError");
@@ -9,6 +14,8 @@ export function voiceUploader(profileId, endpoint = "https://upload-fc.pmate.cha
             binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
         const extension = blob.type.includes("mp4") ? "m4a" : blob.type.includes("mpeg") ? "mp3" : "webm";
         const type = extension === "m4a" ? "audio/mp4" : extension === "mp3" ? "audio/mpeg" : "audio/webm";
+        if (isOffline())
+            throw new Error("VOICE_UPLOAD_OFFLINE");
         const response = await fetcher(`${endpoint.replace(/\/+$/, "")}/file`, { method: "POST", signal, headers: { "Content-Type": "application/json", "x-file-content-type": type }, body: JSON.stringify({ user: profileId, base64: btoa(binary), filename: `voice-${Date.now()}.${extension}` }) });
         if (!response.ok)
             throw new Error("VOICE_UPLOAD_FAILED");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.56",
+  "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",