@ai-matrx/messaging 0.15.14 → 0.15.16

package/dist/react.d.cts

@@ -449,6 +449,49 @@ interface MessagingAi {
 declare function unreadCutoff(messages: readonly Message[], unreadCount: number): string | null;
 declare function createMessagingAi(options: MessagingAiOptions): MessagingAi;
 
+/**
+ * ONE error classification for the whole package (C22).
+ *
+ * The banned alternative is the host catching a PostgREST error and deciding
+ * for itself whether it was an auth blip, a permission denial, or a real bug —
+ * which is how the same three-branch `if` ends up copy-pasted into every
+ * consumer and drifts. Everything this package throws is a `MessagingError`
+ * with a stable `code`, and the two that hosts genuinely treat differently
+ * (`session-unavailable`, `forbidden`) say so in the type.
+ *
+ * The incident behind `session-unavailable`: a DM reader mounted before the
+ * access token existed, every RPC came back `42501`, and the app captured 909
+ * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
+ * warns and retries; it is never a red error.
+ */
+type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "write-not-applied" | "misconfigured"
+/** A NEW conversation needs an organization to land in and none is selected. */
+ | "organization-required" | "unknown";
+declare class MessagingError extends Error {
+    readonly code: MessagingErrorCode;
+    /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
+    readonly remedy: string;
+    readonly cause?: unknown;
+    constructor(code: MessagingErrorCode, message: string, remedy: string, cause?: unknown);
+    /** True when re-running the same call is the fix. */
+    get isRetryable(): boolean;
+}
+interface PostgrestErrorLike {
+    message: string;
+    code?: string | undefined;
+    details?: string | null | undefined;
+}
+/**
+ * THE ONE PLACE a raw PostgREST/transport error becomes a typed one. Called at
+ * every boundary in `repository.ts`; nothing else in the package inspects a raw
+ * error, and no consumer should ever have to.
+ */
+declare function normalizeMessagingError(error: PostgrestErrorLike | Error | unknown, operation: string): MessagingError;
+/** A response whose SHAPE is wrong — the ingress boundary, not the wire. */
+declare function invalidResponse(operation: string, detail: string): MessagingError;
+/** A mutation that PostgREST accepted syntactically but applied to no row. */
+declare function writeNotApplied(operation: string, detail: string): MessagingError;
+
 /**
  * THE OUTBOX — a message you typed is NEVER lost (R2, table-stakes law).
  *
@@ -537,47 +580,6 @@ interface Outbox {
 }
 declare function createOutbox(options: OutboxOptions): Outbox;
 
-/**
- * ONE error classification for the whole package (C22).
- *
- * The banned alternative is the host catching a PostgREST error and deciding
- * for itself whether it was an auth blip, a permission denial, or a real bug —
- * which is how the same three-branch `if` ends up copy-pasted into every
- * consumer and drifts. Everything this package throws is a `MessagingError`
- * with a stable `code`, and the two that hosts genuinely treat differently
- * (`session-unavailable`, `forbidden`) say so in the type.
- *
- * The incident behind `session-unavailable`: a DM reader mounted before the
- * access token existed, every RPC came back `42501`, and the app captured 909
- * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
- * warns and retries; it is never a red error.
- */
-type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured"
-/** A NEW conversation needs an organization to land in and none is selected. */
- | "organization-required" | "unknown";
-declare class MessagingError extends Error {
-    readonly code: MessagingErrorCode;
-    /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
-    readonly remedy: string;
-    readonly cause?: unknown;
-    constructor(code: MessagingErrorCode, message: string, remedy: string, cause?: unknown);
-    /** True when re-running the same call is the fix. */
-    get isRetryable(): boolean;
-}
-interface PostgrestErrorLike {
-    message: string;
-    code?: string | undefined;
-    details?: string | null | undefined;
-}
-/**
- * THE ONE PLACE a raw PostgREST/transport error becomes a typed one. Called at
- * every boundary in `repository.ts`; nothing else in the package inspects a raw
- * error, and no consumer should ever have to.
- */
-declare function normalizeMessagingError(error: PostgrestErrorLike | Error | unknown, operation: string): MessagingError;
-/** A response whose SHAPE is wrong — the ingress boundary, not the wire. */
-declare function invalidResponse(operation: string, detail: string): MessagingError;
-
 /**
  * THE STRUCTURAL SUPABASE SHAPE.
  *
@@ -609,6 +611,7 @@ interface PostgrestLikeResponse<T> {
         code?: string;
         details?: string | null;
     } | null;
+    count?: number | null;
 }
 interface PostgrestFilterLike<TRow> extends PromiseLike<PostgrestLikeResponse<TRow[]>> {
     eq(column: string, value: unknown): PostgrestFilterLike<TRow>;
@@ -622,12 +625,17 @@ interface PostgrestFilterLike<TRow> extends PromiseLike<PostgrestLikeResponse<TR
         ascending?: boolean;
     }): PostgrestFilterLike<TRow>;
     limit(count: number): PostgrestFilterLike<TRow>;
-    select(columns?: string): PostgrestFilterLike<TRow>;
+    range(from: number, to: number): PostgrestFilterLike<TRow>;
+    select(columns?: string, options?: {
+        count?: "exact";
+    }): PostgrestFilterLike<TRow>;
     single(): PromiseLike<PostgrestLikeResponse<TRow>>;
     maybeSingle(): PromiseLike<PostgrestLikeResponse<TRow>>;
 }
 interface PostgrestTableLike<TRow> {
-    select(columns?: string): PostgrestFilterLike<TRow>;
+    select(columns?: string, options?: {
+        count?: "exact";
+    }): PostgrestFilterLike<TRow>;
     insert(values: unknown): PostgrestFilterLike<TRow>;
     update(values: unknown): PostgrestFilterLike<TRow>;
     upsert(values: unknown, options?: {
@@ -920,6 +928,11 @@ interface MessagingRepository {
         exact: boolean;
     }>;
     getConversation(id: ConversationId): Promise<Conversation>;
+    /**
+     * One conversation's complete inbox/header row, independent of inbox paging.
+     * Deep links use this door when their conversation is not in the loaded page.
+     */
+    getConversationSummary(id: ConversationId): Promise<ConversationSummary>;
     listMessages(conversationId: ConversationId, args?: {
         limit?: number;
         cursor?: MessageCursor | null;
@@ -934,7 +947,8 @@ interface MessagingRepository {
     insertMessage(draft: DraftMessage, clientMessageId: ClientMessageId): Promise<Message>;
     editMessage(id: MessageId, content: string): Promise<Message>;
     deleteMessage(id: MessageId, forEveryone: boolean): Promise<void>;
-    markRead(conversationId: ConversationId, at?: string): Promise<void>;
+    /** Persists the cutoff, then returns the server's remaining unread count. */
+    markRead(conversationId: ConversationId, at: string): Promise<number>;
     setConversationFlags(conversationId: ConversationId, flags: {
         isMuted?: boolean;
         isArchived?: boolean;
@@ -975,10 +989,10 @@ declare function createMessagingRepository(options: RepositoryOptions): Messagin
  * 4. **Order is `created_at` then `id`.** The unique tiebreaker is not
  *    decoration: two messages in the same millisecond otherwise swap places on
  *    every re-render.
- * 5. **The active conversation's unread count is forced to zero.** A stale
- *    server count must never re-badge a conversation the user is reading — a
- *    safety net the origin needed in three separate places, so it lives in one
- *    place here.
+ * 5. **Navigation is not a read receipt.** Active-conversation state never
+ *    clears unread counts. Only a confirmed participant write may do that, and
+ *    overlapping confirmations apply monotonically so one baseline is never
+ *    subtracted twice.
  */
 
 /**
@@ -1008,6 +1022,12 @@ interface ConversationThread {
 }
 interface MessagingSnapshot {
     readonly conversations: readonly ConversationSummary[];
+    /**
+     * Summaries known by id, including a directly opened conversation outside
+     * the current filtered inbox page. Header lookup uses this map; inbox
+     * rendering continues to use `conversations` exactly as returned by its page.
+     */
+    readonly conversationSummaries: ReadonlyMap<ConversationId, ConversationSummary>;
     readonly hasMoreConversations: boolean;
     /**
      * True once the inbox has actually been READ at least once.
@@ -1066,6 +1086,7 @@ interface MessagingStore {
     } | null): void;
     appendConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
     upsertConversation(item: ConversationSummary): void;
+    setConversationSummary(item: ConversationSummary): void;
     removeConversation(id: ConversationId): void;
     setActiveConversation(id: ConversationId | null): void;
     /** Record (or clear, with `null`) why a conversation could not be read. */
@@ -1073,12 +1094,19 @@ interface MessagingStore {
     setThread(id: ConversationId, messages: readonly Message[], args?: {
         hasMoreOlder?: boolean;
     }): void;
+    clearThread(id: ConversationId): void;
     prependOlder(id: ConversationId, messages: readonly Message[], hasMoreOlder: boolean): void;
     /** The one door every incoming message uses. Returns what actually happened. */
     ingest(message: Message): "added" | "merged" | "dropped-stale" | "dropped-duplicate";
     ingestMany(messages: readonly Message[]): void;
     removeMessage(conversationId: ConversationId, messageId: MessageId): void;
-    markConversationRead(id: ConversationId): void;
+    captureConversationRead(id: ConversationId, at: string): ConversationReadCutoff;
+    /**
+     * Apply a confirmed read through the exact cutoff persisted by the repository.
+     * `unreadCount` is the portion visible when that write began; arrivals after
+     * `at` remain unread when the confirmation comes back.
+     */
+    markConversationRead(id: ConversationId, cutoff: ConversationReadCutoff, canonicalUnreadCount?: number): void;
     /**
      * Move a conversation's preview + sort position to reflect a message, with NO
      * refetch. Sending a message must not cost a conversation-list RPC — at a
@@ -1090,6 +1118,12 @@ interface MessagingStore {
     }): void;
     setUnreadCount(id: ConversationId, count: number): void;
 }
+interface ConversationReadCutoff {
+    readonly at: string;
+    readonly unreadCount: number;
+    /** Per-conversation unread-state revision observed when this read began. */
+    readonly revision: number;
+}
 declare function createMessagingStore(): MessagingStore;
 /**
  * The optimistic row a composer shows the instant Enter is pressed. It carries
@@ -1129,6 +1163,12 @@ interface EngineDiagnostic {
     readonly level: "info" | "warn" | "error";
     readonly message: string;
     readonly remedy?: string | undefined;
+    /** Stable machine-readable metadata for host diagnostic adapters. */
+    readonly code?: MessagingErrorCode | undefined;
+    readonly operation?: string | undefined;
+    readonly isRetryable?: boolean | undefined;
+    readonly error?: MessagingError | undefined;
+    readonly conversationId?: ConversationId | undefined;
 }
 interface MessagingEngineOptions {
     repository: MessagingRepository;
@@ -1877,4 +1917,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerAttachment, type ComposerInputRenderProps, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerAttachment, type ComposerInputRenderProps, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadCutoff, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists, writeNotApplied };

package/dist/react.d.ts

@@ -449,6 +449,49 @@ interface MessagingAi {
 declare function unreadCutoff(messages: readonly Message[], unreadCount: number): string | null;
 declare function createMessagingAi(options: MessagingAiOptions): MessagingAi;
 
+/**
+ * ONE error classification for the whole package (C22).
+ *
+ * The banned alternative is the host catching a PostgREST error and deciding
+ * for itself whether it was an auth blip, a permission denial, or a real bug —
+ * which is how the same three-branch `if` ends up copy-pasted into every
+ * consumer and drifts. Everything this package throws is a `MessagingError`
+ * with a stable `code`, and the two that hosts genuinely treat differently
+ * (`session-unavailable`, `forbidden`) say so in the type.
+ *
+ * The incident behind `session-unavailable`: a DM reader mounted before the
+ * access token existed, every RPC came back `42501`, and the app captured 909
+ * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
+ * warns and retries; it is never a red error.
+ */
+type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "write-not-applied" | "misconfigured"
+/** A NEW conversation needs an organization to land in and none is selected. */
+ | "organization-required" | "unknown";
+declare class MessagingError extends Error {
+    readonly code: MessagingErrorCode;
+    /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
+    readonly remedy: string;
+    readonly cause?: unknown;
+    constructor(code: MessagingErrorCode, message: string, remedy: string, cause?: unknown);
+    /** True when re-running the same call is the fix. */
+    get isRetryable(): boolean;
+}
+interface PostgrestErrorLike {
+    message: string;
+    code?: string | undefined;
+    details?: string | null | undefined;
+}
+/**
+ * THE ONE PLACE a raw PostgREST/transport error becomes a typed one. Called at
+ * every boundary in `repository.ts`; nothing else in the package inspects a raw
+ * error, and no consumer should ever have to.
+ */
+declare function normalizeMessagingError(error: PostgrestErrorLike | Error | unknown, operation: string): MessagingError;
+/** A response whose SHAPE is wrong — the ingress boundary, not the wire. */
+declare function invalidResponse(operation: string, detail: string): MessagingError;
+/** A mutation that PostgREST accepted syntactically but applied to no row. */
+declare function writeNotApplied(operation: string, detail: string): MessagingError;
+
 /**
  * THE OUTBOX — a message you typed is NEVER lost (R2, table-stakes law).
  *
@@ -537,47 +580,6 @@ interface Outbox {
 }
 declare function createOutbox(options: OutboxOptions): Outbox;
 
-/**
- * ONE error classification for the whole package (C22).
- *
- * The banned alternative is the host catching a PostgREST error and deciding
- * for itself whether it was an auth blip, a permission denial, or a real bug —
- * which is how the same three-branch `if` ends up copy-pasted into every
- * consumer and drifts. Everything this package throws is a `MessagingError`
- * with a stable `code`, and the two that hosts genuinely treat differently
- * (`session-unavailable`, `forbidden`) say so in the type.
- *
- * The incident behind `session-unavailable`: a DM reader mounted before the
- * access token existed, every RPC came back `42501`, and the app captured 909
- * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
- * warns and retries; it is never a red error.
- */
-type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured"
-/** A NEW conversation needs an organization to land in and none is selected. */
- | "organization-required" | "unknown";
-declare class MessagingError extends Error {
-    readonly code: MessagingErrorCode;
-    /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
-    readonly remedy: string;
-    readonly cause?: unknown;
-    constructor(code: MessagingErrorCode, message: string, remedy: string, cause?: unknown);
-    /** True when re-running the same call is the fix. */
-    get isRetryable(): boolean;
-}
-interface PostgrestErrorLike {
-    message: string;
-    code?: string | undefined;
-    details?: string | null | undefined;
-}
-/**
- * THE ONE PLACE a raw PostgREST/transport error becomes a typed one. Called at
- * every boundary in `repository.ts`; nothing else in the package inspects a raw
- * error, and no consumer should ever have to.
- */
-declare function normalizeMessagingError(error: PostgrestErrorLike | Error | unknown, operation: string): MessagingError;
-/** A response whose SHAPE is wrong — the ingress boundary, not the wire. */
-declare function invalidResponse(operation: string, detail: string): MessagingError;
-
 /**
  * THE STRUCTURAL SUPABASE SHAPE.
  *
@@ -609,6 +611,7 @@ interface PostgrestLikeResponse<T> {
         code?: string;
         details?: string | null;
     } | null;
+    count?: number | null;
 }
 interface PostgrestFilterLike<TRow> extends PromiseLike<PostgrestLikeResponse<TRow[]>> {
     eq(column: string, value: unknown): PostgrestFilterLike<TRow>;
@@ -622,12 +625,17 @@ interface PostgrestFilterLike<TRow> extends PromiseLike<PostgrestLikeResponse<TR
         ascending?: boolean;
     }): PostgrestFilterLike<TRow>;
     limit(count: number): PostgrestFilterLike<TRow>;
-    select(columns?: string): PostgrestFilterLike<TRow>;
+    range(from: number, to: number): PostgrestFilterLike<TRow>;
+    select(columns?: string, options?: {
+        count?: "exact";
+    }): PostgrestFilterLike<TRow>;
     single(): PromiseLike<PostgrestLikeResponse<TRow>>;
     maybeSingle(): PromiseLike<PostgrestLikeResponse<TRow>>;
 }
 interface PostgrestTableLike<TRow> {
-    select(columns?: string): PostgrestFilterLike<TRow>;
+    select(columns?: string, options?: {
+        count?: "exact";
+    }): PostgrestFilterLike<TRow>;
     insert(values: unknown): PostgrestFilterLike<TRow>;
     update(values: unknown): PostgrestFilterLike<TRow>;
     upsert(values: unknown, options?: {
@@ -920,6 +928,11 @@ interface MessagingRepository {
         exact: boolean;
     }>;
     getConversation(id: ConversationId): Promise<Conversation>;
+    /**
+     * One conversation's complete inbox/header row, independent of inbox paging.
+     * Deep links use this door when their conversation is not in the loaded page.
+     */
+    getConversationSummary(id: ConversationId): Promise<ConversationSummary>;
     listMessages(conversationId: ConversationId, args?: {
         limit?: number;
         cursor?: MessageCursor | null;
@@ -934,7 +947,8 @@ interface MessagingRepository {
     insertMessage(draft: DraftMessage, clientMessageId: ClientMessageId): Promise<Message>;
     editMessage(id: MessageId, content: string): Promise<Message>;
     deleteMessage(id: MessageId, forEveryone: boolean): Promise<void>;
-    markRead(conversationId: ConversationId, at?: string): Promise<void>;
+    /** Persists the cutoff, then returns the server's remaining unread count. */
+    markRead(conversationId: ConversationId, at: string): Promise<number>;
     setConversationFlags(conversationId: ConversationId, flags: {
         isMuted?: boolean;
         isArchived?: boolean;
@@ -975,10 +989,10 @@ declare function createMessagingRepository(options: RepositoryOptions): Messagin
  * 4. **Order is `created_at` then `id`.** The unique tiebreaker is not
  *    decoration: two messages in the same millisecond otherwise swap places on
  *    every re-render.
- * 5. **The active conversation's unread count is forced to zero.** A stale
- *    server count must never re-badge a conversation the user is reading — a
- *    safety net the origin needed in three separate places, so it lives in one
- *    place here.
+ * 5. **Navigation is not a read receipt.** Active-conversation state never
+ *    clears unread counts. Only a confirmed participant write may do that, and
+ *    overlapping confirmations apply monotonically so one baseline is never
+ *    subtracted twice.
  */
 
 /**
@@ -1008,6 +1022,12 @@ interface ConversationThread {
 }
 interface MessagingSnapshot {
     readonly conversations: readonly ConversationSummary[];
+    /**
+     * Summaries known by id, including a directly opened conversation outside
+     * the current filtered inbox page. Header lookup uses this map; inbox
+     * rendering continues to use `conversations` exactly as returned by its page.
+     */
+    readonly conversationSummaries: ReadonlyMap<ConversationId, ConversationSummary>;
     readonly hasMoreConversations: boolean;
     /**
      * True once the inbox has actually been READ at least once.
@@ -1066,6 +1086,7 @@ interface MessagingStore {
     } | null): void;
     appendConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
     upsertConversation(item: ConversationSummary): void;
+    setConversationSummary(item: ConversationSummary): void;
     removeConversation(id: ConversationId): void;
     setActiveConversation(id: ConversationId | null): void;
     /** Record (or clear, with `null`) why a conversation could not be read. */
@@ -1073,12 +1094,19 @@ interface MessagingStore {
     setThread(id: ConversationId, messages: readonly Message[], args?: {
         hasMoreOlder?: boolean;
     }): void;
+    clearThread(id: ConversationId): void;
     prependOlder(id: ConversationId, messages: readonly Message[], hasMoreOlder: boolean): void;
     /** The one door every incoming message uses. Returns what actually happened. */
     ingest(message: Message): "added" | "merged" | "dropped-stale" | "dropped-duplicate";
     ingestMany(messages: readonly Message[]): void;
     removeMessage(conversationId: ConversationId, messageId: MessageId): void;
-    markConversationRead(id: ConversationId): void;
+    captureConversationRead(id: ConversationId, at: string): ConversationReadCutoff;
+    /**
+     * Apply a confirmed read through the exact cutoff persisted by the repository.
+     * `unreadCount` is the portion visible when that write began; arrivals after
+     * `at` remain unread when the confirmation comes back.
+     */
+    markConversationRead(id: ConversationId, cutoff: ConversationReadCutoff, canonicalUnreadCount?: number): void;
     /**
      * Move a conversation's preview + sort position to reflect a message, with NO
      * refetch. Sending a message must not cost a conversation-list RPC — at a
@@ -1090,6 +1118,12 @@ interface MessagingStore {
     }): void;
     setUnreadCount(id: ConversationId, count: number): void;
 }
+interface ConversationReadCutoff {
+    readonly at: string;
+    readonly unreadCount: number;
+    /** Per-conversation unread-state revision observed when this read began. */
+    readonly revision: number;
+}
 declare function createMessagingStore(): MessagingStore;
 /**
  * The optimistic row a composer shows the instant Enter is pressed. It carries
@@ -1129,6 +1163,12 @@ interface EngineDiagnostic {
     readonly level: "info" | "warn" | "error";
     readonly message: string;
     readonly remedy?: string | undefined;
+    /** Stable machine-readable metadata for host diagnostic adapters. */
+    readonly code?: MessagingErrorCode | undefined;
+    readonly operation?: string | undefined;
+    readonly isRetryable?: boolean | undefined;
+    readonly error?: MessagingError | undefined;
+    readonly conversationId?: ConversationId | undefined;
 }
 interface MessagingEngineOptions {
     repository: MessagingRepository;
@@ -1877,4 +1917,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerAttachment, type ComposerInputRenderProps, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerAttachment, type ComposerInputRenderProps, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadCutoff, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists, writeNotApplied };