@pmate/chat-sdk 0.12.0-next.6 → 0.12.0-next.61

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
 
@@ -142,7 +142,9 @@ The browser entry point is `createChat` from `@pmate/chat-sdk/runtime`:
 ```ts
 const chat = createChat({ appId, accountId, profileId, teamId, token, onError })
 await chat.start()
-const page = await chat.getMessages(threadId, { limit: 50 })
+const page = await chat.getMessages(threadId)
+// SDK owns the page size and history boundary; hosts need not construct a cursor.
+const earlier = await chat.getMessages(threadId, { earlier: true })
 // After an authoritative mutation (e.g. history assignment), await reconciliation.
 // Concurrent refreshes share transport; errors do not masquerade as fresh cache.
 const reconciled = await chat.getMessages(threadId, { refresh: true })
@@ -153,12 +155,31 @@ 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.
 await chat.close()
 ```
 
+```ts
+// When team access is withdrawn, use this instead of ordinary close(). It hides
+// snapshots immediately, retires durable caches/outbox and closes this session.
+// Other teams' reading operations remain intact. Create a new session to recover.
+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.
@@ -201,6 +222,11 @@ legacy cleanup happens after durable migration. Normal reads use memory and writ
 are merged into bounded IndexedDB transactions. Cache errors must be surfaced by
 the host, and pending operations are not reported as saved before their promise
 resolves.
+Control-event batches are bounded by both 128 records and 1 MiB per transaction;
+the queue includes in-flight writes and is limited to 4096 records / 8 MiB.
+`transactionBytes` and `queueBytes` can lower these limits. Oversized operations
+fail before changing the memory snapshot. Repeating an in-flight write waits for
+that physical write, including its failure, rather than acknowledging it early.
 
 `DurableChatSender` saves the exact message created by `ChatClient.prepareChat`
 before transmitting it. `retry(hash)` uses `sendPrepared` with the original hash
@@ -213,3 +239,72 @@ Custom primitive integrations must initialize them with the same authenticated
 scope, dispose them on identity changes, and wire their transport to an authorized
 server. Standard browser integrations should use the facade instead. The Merry migration and production validation
 are tracked in the unified message layer proposal.
+
+When the browser reports offline, scheduled message restoration and reading
+refreshes wait for the normal reconnect/wake path. Cached reads remain available;
+unknown receipt counts stay unknown and an uncached reader detail page rejects
+without attempting transport. A network failure arriving after the browser went
+offline does not turn background synchronization into an operation error.
+Authorization failures still revoke the corresponding cached data.
+
+Reading entry points check the message scope even before `initialize()` finishes.
+Concurrent observations share the permission lookup and batch their local writes.
+Visibility/playback operations reject another known team's conversation; a
+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.
+
+
+Pending voice snapshots contain `voiceAttachment` metadata, without loading audio bytes or creating Blob URLs at startup. For playback or transcription, acquire media through `await chat.getVoiceAttachment(threadId, messageId)`, use the returned `url`, and call `release()` when the consumer stops. The same method returns a remote voice reference for delivered messages. Attachment reads are charged before allocation, and close/revocation releases local URLs. A pending voice remains unread until the player actually starts; acquiring media does not mark it read.
+
+The outbox format upgrade renames the old canonical store without copying binary data in the schema transaction, then atomically separates inline payloads in bounded, resumable transactions. An already-open older application must reload; unsupported senders reject the new format. Original wire/hash, failed status and retry semantics are retained.
+
+
+Control messages use the same send API:
+
+```ts
+await chat.sendMessage(conversation, {recall: {messageId}})
+await chat.sendMessage(conversation, {reaction: {messageId, emojiId, active: true}})
+await chat.sendMessage(conversation, {invitation: {message: "Hello"}})
+await chat.sendMessage(group, {groupCreate: {title, members}})
+await chat.sendMessage(group, {groupUpdate: {expectedRevision, addMembers}})
+```
+
+These calls retain durable-acceptance semantics. Recall and reaction validate the target against the current scoped timeline or canonical local cache; the App does not supply protocol bodies or reaction versions. Reaction counters and exact wires commit in one IndexedDB transaction, including across documents. Validation ordering does not wait for each preceding commit, so a same-key burst still reaches the bounded acceptance batches. Pass `{waitFor:"delivered"}` as the third argument when an action requires server confirmation; the default still resolves after durable acceptance.
+
+
+Group metadata uses the same identity, cache and subscriptions:
+
+```ts
+const group = await chat.getGroup(conversation)
+const off = chat.subscribe(conversation.id, () => {
+  renderGroup(chat.getSnapshot(conversation.id).group)
+}, ["group"])
+await chat.createGroup(conversation, {title, members})
+await chat.updateGroup(conversation, {title: "New title"})
+off()
+```
+
+Reads restore trusted IndexedDB metadata before background revalidation. Creation and updates wait for confirmed delivery and a causal server version, including newer concurrent revisions; Apps do not poll for an exact message hash. Group events and browser recovery share a 200ms window. At most four metadata requests run concurrently, with 128 queued requests, a five-second request timeout, and at most five read-after-write attempts. Per-scope persistent metadata is capped at 64 groups / 1MiB, with 128KiB records, 32-record write batches, conditional cross-document writes and bounded pruning. Cached metadata does not bypass scope withdrawal or server membership checks. Binary media remains on demand.

package/lib/runtime/batchedReadIndex.d.ts

@@ -1,6 +1,8 @@
-import { type ReadIndexPersistence, type ReadIndexState } from "./readIndex.js";
+import { type ReadIndexPersistence, type ReadIndexState, type ReadIndexTransform, type ReadObservationScope } from "./readIndex.js";
 type Change = {
-    transform: (state: ReadIndexState) => ReadIndexState;
+    weight: number;
+    observation?: ReadObservationScope;
+    transform: ReadIndexTransform;
     resolve: (state: ReadIndexState) => void;
     reject: (error: unknown) => void;
 };
@@ -13,9 +15,20 @@ export declare class BatchedReadIndex implements ReadIndexPersistence {
     private queueLimit;
     private queues;
     private closed;
+    private sourceCounts;
     constructor(storage: ReadIndexPersistence, windowMs?: number, batchSize?: number, queueLimit?: number);
     load(appId: string, profileId: string): Promise<ReadIndexState | undefined>;
-    update(appId: string, profileId: string, transform: Change["transform"]): Promise<ReadIndexState>;
+    loadVersioned(appId: string, profileId: string): Promise<{
+        state: ReadIndexState | undefined;
+        versions: import("./readIndex.js").ReadIndexVersions;
+    } | {
+        state: ReadIndexState | undefined;
+        versions: {};
+    }>;
+    loadVersions(appId: string, profileId: string): Promise<{}>;
+    invalidateTeam(appId: string, profileId: string, teamId: string, version: number, knownThreadIds?: readonly string[]): Promise<ReadIndexState>;
+    private weight;
+    update(appId: string, profileId: string, transform: Change["transform"], observation?: ReadObservationScope): Promise<ReadIndexState>;
     private drain;
     flush(appId: string, profileId: string): Promise<void>;
     close(): Promise<void>;

package/lib/runtime/batchedReadIndex.js

@@ -8,6 +8,7 @@ export class BatchedReadIndex {
     queueLimit;
     queues = new Map();
     closed = false;
+    sourceCounts = new WeakMap();
     constructor(storage, windowMs = 16, batchSize = 128, queueLimit = 4096) {
         this.storage = storage;
         this.windowMs = windowMs;
@@ -22,7 +23,42 @@ export class BatchedReadIndex {
             throw new Error("READ_STORAGE_CLOSED");
         return this.storage.load(appId, profileId);
     }
-    update(appId, profileId, transform) {
+    async loadVersioned(appId, profileId) {
+        await this.flush(appId, profileId);
+        if (this.closed)
+            throw new Error("READ_STORAGE_CLOSED");
+        return this.storage.loadVersioned ? this.storage.loadVersioned(appId, profileId) : { state: await this.storage.load(appId, profileId), versions: {} };
+    }
+    async loadVersions(appId, profileId) {
+        if (this.closed)
+            throw new Error("READ_STORAGE_CLOSED");
+        return this.storage.loadVersions ? this.storage.loadVersions(appId, profileId) : {};
+    }
+    async invalidateTeam(appId, profileId, teamId, version, knownThreadIds) {
+        if (this.closed)
+            throw new Error("READ_STORAGE_CLOSED");
+        if (!this.storage.invalidateTeam)
+            throw new Error("READ_SCOPE_INVALIDATION_UNAVAILABLE");
+        // Do not flush a blocked old HTTP transform first. The durable epoch is the
+        // barrier; any queued transform sees it inside its eventual transaction.
+        return this.storage.invalidateTeam(appId, profileId, teamId, version, knownThreadIds);
+    }
+    weight(observation) {
+        if (!observation)
+            return 1;
+        let counts = this.sourceCounts.get(observation.base);
+        if (!counts) {
+            counts = new Map();
+            for (const thread of observation.base.threads) {
+                counts.set(thread.id, (counts.get(thread.id) ?? 0) + 1);
+                if (thread.conversationId && thread.conversationId !== thread.id)
+                    counts.set(thread.conversationId, (counts.get(thread.conversationId) ?? 0) + 1);
+            }
+            this.sourceCounts.set(observation.base, counts);
+        }
+        return observation.targets.reduce((sum, target) => sum + (counts.get(target.threadId) ?? 1), 0);
+    }
+    update(appId, profileId, transform, observation) {
         if (this.closed)
             return Promise.reject(new Error("READ_STORAGE_CLOSED"));
         const key = JSON.stringify([appId, profileId]);
@@ -33,7 +69,7 @@ export class BatchedReadIndex {
         }
         if (queue.pending.length >= this.queueLimit)
             return Promise.reject(new Error("READ_STORAGE_BACKPRESSURE"));
-        const promise = new Promise((resolve, reject) => queue.pending.push({ transform, resolve, reject }));
+        const promise = new Promise((resolve, reject) => queue.pending.push({ transform, observation, weight: this.weight(observation), resolve, reject }));
         if (!queue.running && queue.timer === undefined)
             queue.timer = setTimeout(() => { queue.timer = undefined; void this.drain(key, queue); }, this.windowMs);
         return promise;
@@ -43,12 +79,22 @@ export class BatchedReadIndex {
             return queue.running;
         clearTimeout(queue.timer);
         queue.timer = undefined;
-        const batch = queue.pending.splice(0, this.batchSize);
+        const batch = [];
+        let weight = 0;
+        while (queue.pending.length && batch.length < this.batchSize) {
+            const nextWeight = queue.pending[0].weight;
+            if (batch.length && weight + nextWeight > 128)
+                break;
+            weight += nextWeight;
+            batch.push(queue.pending.shift());
+        }
         if (!batch.length)
             return;
         const run = (async () => {
             try {
-                const next = await this.storage.update(queue.appId, queue.profileId, state => batch.reduce((current, change) => change.transform(current), state));
+                const first = batch[0].observation;
+                const observation = first && batch.every(change => change.observation?.base === first.base) ? { base: first.base, targets: batch.flatMap(change => change.observation.targets) } : undefined;
+                const next = await this.storage.update(queue.appId, queue.profileId, (state, versions) => batch.reduce((current, change) => change.transform(current, versions), state), observation);
                 batch.forEach(change => change.resolve(next));
             }
             catch (error) {

package/lib/runtime/cachedMessage.d.ts

@@ -0,0 +1,12 @@
+import type { ChatReaderSocialMessage } from "./readerClient.js";
+import type { ChatRuntimeMessage } from "./protocol.js";
+export type CachedChatMessage = ChatReaderSocialMessage & {
+    id: string;
+    timestamp: number;
+    readPolicy?: "visible" | "explicit";
+};
+export declare function decodeCachedChatMessage(message: ChatRuntimeMessage, scope: {
+    appId: string;
+    profileId: string;
+    teamId: string;
+}): CachedChatMessage | undefined;

package/lib/runtime/cachedMessage.js

@@ -0,0 +1,18 @@
+import { chatTeamId } from "./teamScope.js";
+import { dmThreadId, groupThreadId } from "./thread.js";
+export function decodeCachedChatMessage(message, scope) {
+    if (message.opcode !== 1 || !message.body || typeof message.body !== "object")
+        return;
+    const body = message.body;
+    const invitation = body.kind === "contact" && ["friendRequest", "requestFriend"].includes(String(body.action));
+    if ((!invitation && body.kind !== "message") || (invitation ? body.payload?.appId : body.content?.appId) !== scope.appId || chatTeamId(body) !== scope.teamId)
+        return;
+    const threadKind = invitation ? "dm" : body.threadKind;
+    if (threadKind !== "dm" && threadKind !== "group")
+        return;
+    if (threadKind === "dm" && message.from !== scope.profileId && message.to !== scope.profileId)
+        return;
+    const threadId = threadKind === "dm" ? dmThreadId(scope.appId, message.from, message.to, scope.teamId) : groupThreadId(scope.appId, message.to, scope.teamId);
+    return { appId: scope.appId, teamId: scope.teamId, threadId, threadKind, messageId: message.hash, id: message.hash,
+        timestamp: message.t, serverCreatedAt: message.t, clientCreatedAt: message.t, from: message.from, to: message.to, body: message.body, recipients: message.recipients };
+}

package/lib/runtime/chatClient.d.ts

@@ -62,6 +62,7 @@ export declare class ChatClient {
         profileId: string | undefined;
         accountId: string | undefined;
         teamId: string | undefined;
+        clientInstanceId: string;
     };
     watchConnection(handler: (state: ChatConnectionState) => void): () => void;
     private setConnection;

package/lib/runtime/chatClient.js

@@ -123,7 +123,7 @@ export class ChatClient {
     /** Non-secret identity used to validate a shared browser transport. */
     identityScope() {
         const identity = this.session?.identity ?? this.session?.session?.identity;
-        return { appId: this.options.appId, profileId: this.profileIdValue ?? this.options.profileId, accountId: identity?.accountId, teamId: this.options.teamId };
+        return { appId: this.options.appId, profileId: this.profileIdValue ?? this.options.profileId, accountId: identity?.accountId, teamId: this.options.teamId, clientInstanceId: this.instanceId };
     }
     watchConnection(handler) {
         this.connectionHandlers.add(handler);

package/lib/runtime/chatSession.d.ts

@@ -1,36 +1,55 @@
+import { type ChatGroup } from "./groupClient.js";
+import type { SocialGroup } from "./socialReadClient.js";
+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";
+import { type ReadCountsResult } from "./readCounts.js";
+import type { OnlineReachEvent } from "./reach.js";
 import { type MessageReadersQuery } from "./messageReaders.js";
 import { type MessageClientOptions, type MessageSnapshot } from "./messageClient.js";
-import { DurableChatSender } from "./durableSender.js";
-import { type ReadingClientOptions } from "./readingClient.js";
+import { DurableChatSender, type SendMessageInput, type DurableSenderOptions, type VoiceAttachmentLease } from "./durableSender.js";
+import { ReadingClient, type ReadingClientOptions } from "./readingClient.js";
 import { ChatClient, type ChatClientOptions, type ChatConnectionState } from "./chatClient.js";
 import { unreadInConversation } from "./readIndex.js";
 import type { StoredMessage } from "./messageStore.js";
-import type { ChatBody, ChatRuntimeMessage } from "./protocol.js";
+import type { ChatRuntimeMessage } from "./protocol.js";
 export type ChatSessionOptions<T extends StoredMessage> = {
     messages: MessageClientOptions<T>;
     connection: ChatClientOptions;
     sharedConnection?: ChatClient;
+    activeThreadId?: string;
+    uploadVoice?: DurableSenderOptions["uploadVoice"];
+    reconcileOutgoing?: DurableSenderOptions["reconcile"];
+    loadGroup?: (groupId: string, signal: AbortSignal) => Promise<SocialGroup>;
     reading: ReadingClientOptions;
     decode: (message: ChatRuntimeMessage) => T | undefined;
+    readingCandidate?: (message: T) => ReadingCandidate | undefined;
     onError: (error: unknown) => void;
 };
 export type ChatThreadSnapshot<T> = {
     messages: readonly T[];
+    timeline: readonly TimelineItem<T>[];
     outgoing: ReturnType<DurableChatSender["snapshot"]>;
     hasEarlier: boolean;
     resetVersion: number;
     complete: boolean;
-    unread: ReturnType<typeof unreadInConversation>;
+    group?: ChatGroup;
+    readCounts?: ReadCountsResult;
+    unread: ReturnType<typeof unreadInConversation> | undefined;
+    messageReading: Readonly<Record<string, MessageReadingState>>;
 };
 export type ChatSummarySnapshot<T> = {
     threads: readonly {
         threadId: string;
         lastMessage?: T;
+        lastItem?: TimelineItem<T>;
+        group?: ChatGroup;
         unread: ChatThreadSnapshot<T>["unread"];
         outgoingCount: number;
     }[];
-    unreadMessageCount: number;
-    badgeCount: number;
+    unreadMessageCount: number | undefined;
+    badgeCount: number | undefined;
     connection: ChatConnectionState;
 };
 /** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
@@ -40,20 +59,63 @@ export declare class ChatSession<T extends StoredMessage> {
     private connection;
     private reading;
     private readers;
+    private groups?;
+    private counts?;
+    private countsReceiver?;
+    private countsThread?;
+    private countSnapshots;
+    private countClosings;
+    private countTasks;
+    private controlTails;
+    private acceptedControls;
+    private controlCount;
+    private controlBytes;
     private sender;
     private listeners;
     private snapshots;
+    private timelineDecoded;
+    private decodeTimeline;
+    private historyEdges;
+    private earlierReads;
     private off;
     private globalListeners;
     private globalSnapshot?;
+    private closedThread;
+    private closedSummary;
     private connectionState;
     private catchUp;
+    private readingAllowed;
+    private readingListeners;
+    private acceptedReading;
+    private readingAccess?;
     private readingStarted;
+    private readingStarting?;
+    private withdrawn;
+    private revoking?;
     private closed;
     private starting?;
+    private initializing?;
     private closing?;
     constructor(options: ChatSessionOptions<T>);
+    private scheduleCatchUp;
     start(): Promise<void>;
+    /** Initializes local state and background reading sync without opening a
+     * second transport when the host already owns calls/presence. */
+    initialize(): Promise<void>;
+    private startReading;
+    /** One-time migration only: never establishes trusted history coverage. */
+    importLegacyMessages(threadId: string, messages: T[]): Promise<void>;
+    getReadingSnapshot(): import("./readIndex.js").ReadIndexState | undefined;
+    subscribeReading(listener: () => void): () => void;
+    private setReadingAllowed;
+    private readingAuthority;
+    private authorizeReading;
+    private readingOperation;
+    refreshReading(): void;
+    synchronizeReading(cursor?: string, profileId?: string): Promise<import("./readIndex.js").ReadIndexState>;
+    /** Explicit text-history acknowledgement; unheard audio stays unread. */
+    markRead(threadId: string, messages?: readonly ConversationReadMessage[]): Promise<import("./readIndex.js").ReadIndexState>;
+    updateReading(transform: Parameters<ReadingClient["update"]>[0]): Promise<import("./readIndex.js").ReadIndexState>;
     private assertOpen;
     getMessages(threadId: string, options?: {
         limit?: number;
@@ -61,25 +123,60 @@ export declare class ChatSession<T extends StoredMessage> {
             timestamp: number;
             id: string;
         };
+        earlier?: boolean;
         all?: boolean;
         refresh?: boolean;
     }): Promise<MessageSnapshot<T>>;
+    private confirmMessages;
+    private rememberHistoryEdge;
+    private readEarlier;
     private readAll;
-    sendMessage(threadId: string, input: {
-        to: string;
-        body: ChatBody;
-        recipients?: string[];
+    /** Reads trusted local group metadata immediately; SDK refreshes it in the background. */
+    getGroup(thread: ChatConversation, options?: {
+        refresh?: boolean;
+    }): Promise<ChatGroup>;
+    createGroup(thread: ChatConversation, content: {
+        title: string;
+        members: readonly string[];
+    }): Promise<ChatGroup>;
+    updateGroup(thread: ChatConversation, changes: {
+        expectedRevision?: string;
+        addMembers?: readonly string[];
+        removeMembers?: readonly string[];
+        title?: string;
+        avatar?: string;
+    }): Promise<ChatGroup>;
+    sendMessage(thread: ChatConversation, input: OutgoingContent, options?: {
+        waitFor?: "accepted" | "delivered";
+    }): Promise<ChatRuntimeMessage>;
+    sendMessage(threadId: string, input: SendMessageInput, options?: {
+        waitFor?: "accepted" | "delivered";
     }): Promise<ChatRuntimeMessage>;
+    private sendControl;
     getReaders(threadId: string, messageId: string, page?: Omit<MessageReadersQuery, "threadId" | "messageId">, signal?: AbortSignal): Promise<import("./messageReaders.js").MessageReadersPage>;
+    /** Resolve voice media uniformly; pending local bytes are loaded only on demand. */
+    getVoiceAttachment(threadId: string, messageId: string): Promise<VoiceAttachmentLease>;
     retryMessage(messageId: string): Promise<ChatRuntimeMessage>;
-    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<import("./readIndex.js").ReadIndexState>;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): ReturnType<ReadingClient["recordVisible"]>;
+    observeMessages(threadId: string | undefined, ids: string[], event: "receipts", clientInstanceId?: string): Promise<void>;
+    /** Bridge transports can delegate social events without maintaining clients. */
+    handleReach(event: OnlineReachEvent): Promise<"handled" | undefined>;
+    private wakeCounts;
+    private publishCountSnapshot;
+    private publishCounts;
+    private watchCounts;
     getSnapshot(): ChatSummarySnapshot<T>;
     getSnapshot(threadId: string): ChatThreadSnapshot<T>;
+    private buildThreadSnapshot;
     subscribe(listener: () => void): () => void;
-    subscribe(threadId: string, listener: () => void): () => void;
+    subscribe(threadId: string, listener: () => void, fields?: readonly (keyof ChatThreadSnapshot<T>)[]): () => void;
     private publishAll;
     private buildGlobal;
     private publishGlobal;
     private publish;
+    /** Permanently retire this identity/team session. UI withdrawal is immediate;
+     * completion means all durable stores have crossed the same authority epoch. */
+    revokeAccess(): Promise<void>;
     close(): Promise<void>;
+    private dispose;
 }