@ai-matrx/messaging 0.11.8 → 0.12.0

package/dist/react.d.cts

@@ -510,6 +510,45 @@ 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" | "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.
  *
@@ -612,6 +651,95 @@ interface MessagingSupabaseClient {
 /** The internal client contract — what the repository and the manager see. */
 type MessagingSupabaseInternal = SupabaseLike & RealtimeClientLike;
 
+/**
+ * WHO IS ACTING — read from the session, never handed in (DD-241).
+ *
+ * THE CLASS THIS CLOSES, and why messaging is the WORSE half of it. Through
+ * 0.11.x this package took the acting user's id from whoever built it:
+ * `<MessagingProvider userId>` for the React path, and
+ * `createMessagingRepository({ identity: { userId } })` for the framework-free
+ * one. Both ends got their id the same way in the only host that exists —
+ * matrx-frontend's Redux `selectUserId` — and that copy is written once, when
+ * the app boots. Nothing rewrites it when the domain-wide auth cookie rotates
+ * to another account, when the person signs out in another tab, or when a
+ * refresh returns a different subject.
+ *
+ * Meet's version of this (DD-240, `@ai-matrx/meet` 0.6.0) made READS fail:
+ *
+ *   `communication.meet_pending_call_invites(p_user_id => <the stale copy>)`
+ *   → 42501 at HTTP 403, "meet: the acting user (4cf62e4e…) is not the
+ *     authenticated user"
+ *
+ * Messaging's version reaches further, because here the id is not only a read
+ * argument — it is a WRITE argument. `identity.userId` lands on the wire as
+ * `p_user1_id` (the direct-conversation pair), `sender_id` (who a message is
+ * FROM), `created_by` and `updated_by` (the audit columns), and
+ * `.eq("user_id", …)` (whose participant row is being read and updated). A
+ * stale one does not merely get refused: where RLS lets it through it writes a
+ * row attributed to somebody the tab cannot prove it is.
+ *
+ * So there is ONE source now, and it is the client's own session. The same
+ * client that mints the JWT on every PostgREST request answers "who is this?",
+ * so the id in the argument and the id in the token cannot disagree — not
+ * because they are kept in step, but because they are the same fact read once.
+ *
+ * WHAT THIS MODULE IS. A tiny observable over `client.auth`: the current acting
+ * user id, a subscription that fires when it changes, and a `resolving` state
+ * that is honest about the moment before the first `getSession()` answers.
+ *
+ *  - It is `resolving` until the first read lands. Nothing user-scoped is
+ *    issued in that window, which is what a page-load race used to spend
+ *    issuing reads and writes as a user the tab could not prove it was.
+ *  - `snapshot()` returns THE SAME REFERENCE until the acting user moves — a
+ *    `useSyncExternalStore` source that returns a fresh object per call is
+ *    "Maximum update depth exceeded", not a warning.
+ *  - It NEVER refuses anything on its own authority. It reports who the session
+ *    says you are; the database remains the only thing that decides what that
+ *    is allowed to read or write.
+ *  - A client with no `auth` at all is a real, named failure with a remedy —
+ *    never a silent fall back to "nobody".
+ *
+ * THE CLIENT BOUNDARY STAYS SHALLOW (0.2.1, `repository.ts`'s header). The
+ * public prop type is still `MessagingSupabaseClient`, which does not describe
+ * `auth` at all — so this module narrows to its own minimal `AuthLike` in ONE
+ * place, exactly as `createMessagingRepository` narrows to
+ * `MessagingSupabaseInternal`. A real `SupabaseClient` satisfying `AuthLike` is
+ * proven at compile time in `supabase-shape.test.ts`.
+ */
+
+interface SessionIdentitySnapshot {
+    /**
+     * `resolving` until the first `getSession()` answers. A user-scoped read or
+     * write issued in this window would name a guess.
+     */
+    readonly state: "resolving" | "resolved";
+    /** Who the session says is acting, or `null` for nobody. */
+    readonly userId: UserId | null;
+}
+interface SessionIdentity {
+    /**
+     * False when the client handed to us has no auth source at all — a
+     * misconfiguration, not "nobody is signed in", and the two get different
+     * sentences.
+     */
+    readonly hasAuthSource: boolean;
+    /** Stable reference until the acting user actually changes. */
+    snapshot(): SessionIdentitySnapshot;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+interface SessionIdentityOptions {
+    readonly client: MessagingSupabaseClient;
+    readonly onDiagnostic?: ((event: {
+        level: "info" | "warn" | "error";
+        message: string;
+        remedy?: string | undefined;
+    }) => void) | undefined;
+}
+/** The snapshot every server render sees: nobody is acting on a server. */
+declare const SERVER_SESSION_IDENTITY: SessionIdentitySnapshot;
+declare function createSessionIdentity(options: SessionIdentityOptions): SessionIdentity;
+
 /**
  * THE DATA CONTRACT — the ONE place a messaging table or RPC name exists.
  *
@@ -688,7 +816,23 @@ interface RepositoryOptions {
      * the provider does.
      */
     client: MessagingSupabaseClient;
-    identity: MessagingIdentity;
+    /**
+     * The active organization. Every conversation and message write carries it
+     * explicitly (R5).
+     *
+     * 🚨 THERE IS NO `userId` HERE, AND THERE WILL NOT BE ONE (DD-241). Who is
+     * acting is read from `client`'s own session — see `session-identity.ts` for
+     * the class that closed and why a handed-in id could not be made safe by
+     * convention. A caller that still passes `identity` is IGNORED and told so.
+     */
+    organizationId: string;
+    /**
+     * INTERNAL. The React provider already runs one session reader for its own
+     * render loop and hands it here so the two cannot answer differently and so
+     * one `onAuthStateChange` subscription serves both. A framework-free caller
+     * omits it and the repository builds its own from `client`.
+     */
+    sessionIdentity?: SessionIdentity | undefined;
     /** Called once before a retry when a read fails with a missing session. */
     resolveSession?: SessionResolver | undefined;
     /**
@@ -702,7 +846,14 @@ interface RepositoryOptions {
     now?: (() => number) | undefined;
 }
 interface MessagingRepository {
-    readonly identity: MessagingIdentity;
+    /** The organization every write here is stamped with. */
+    readonly organizationId: OrganizationId;
+    /**
+     * Who the session says is acting — awaited, because the first `getSession()`
+     * is a real read. Rejects with `session-unavailable` when nobody is signed
+     * in, which is the code the retry loop already knows how to heal.
+     */
+    actingUserId(): Promise<UserId>;
     listConversations(args?: {
         limit?: number;
         cursor?: ConversationCursor | null;
@@ -980,11 +1131,19 @@ declare function messagingClientId(): string;
  * package error, retrying a package call, or branching on a package quirk in
  * host code, that logic belongs in here (C22).
  *
- * 🚨 THE PROVIDER'S LIFETIME IS `client` + `userId` + `organizationId`, AND
- * NOTHING ELSE. Hosts pass fresh object literals for `agents`, `actions`, and
- * `onDiagnostic` on every render; keying the engine on those identities would
- * tear down and rebuild every channel on every parent re-render — a permanent
- * resubscribe loop that looks exactly like "realtime is broken".
+ * 🚨 THE PROVIDER'S LIFETIME IS `client` + THE SESSION'S USER + `organizationId`,
+ * AND NOTHING ELSE. Hosts pass fresh object literals for `agents`, `actions`,
+ * and `onDiagnostic` on every render; keying the engine on those identities
+ * would tear down and rebuild every channel on every parent re-render — a
+ * permanent resubscribe loop that looks exactly like "realtime is broken".
+ *
+ * 🚨 THERE IS NO `userId` PROP (DD-241, 0.12.0). Who is acting is read from the
+ * session of the `client` you pass — see `core/session-identity.ts` for the
+ * class that closed. The provider is INERT until that first read lands, an
+ * account switch rebuilds the runtime under the open tab, and a sign-out makes
+ * it inert again. A `userId` still passed at run time (a stale bundle, a
+ * JavaScript consumer) is ignored and reported through `onDiagnostic` with the
+ * remedy — never taken, and never dropped in silence.
  */
 
 /**
@@ -1080,10 +1239,14 @@ interface MessagingHost {
     readonly wrapConversationRow: ComponentType<ConversationRowWrapperProps> | null;
 }
 interface MessagingProviderProps {
-    /** Any Supabase client. `null` while the host is still resolving one. */
+    /**
+     * Any Supabase client. `null` while the host is still resolving one.
+     *
+     * 🚨 IT IS ALSO WHO YOU ARE. Messaging reads the acting user from THIS
+     * client's session, so pass the same browser client your app signs in with
+     * (DD-241). There is no `userId` prop, on purpose.
+     */
     client: MessagingSupabaseClient | null | undefined;
-    /** The signed-in user. `null` while auth is still resolving. */
-    userId: string | null | undefined;
     /** The active organization. Every write carries it (R5). */
     organizationId: string | null | undefined;
     /**
@@ -1512,45 +1675,6 @@ declare const MESSAGING_EVENTS: {
     readonly actionSettled: "mx.action.settled";
 };
 
-/**
- * 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" | "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;
-
 /**
  * Display formatting. In the package because every consumer otherwise rebuilds
  * it slightly differently and the inbox and the thread disagree about what
@@ -1681,4 +1805,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 ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, 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, type SchemaLike, SearchIcon, SendIcon, 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, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, 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 ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, 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, 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 };

package/dist/react.d.ts

@@ -510,6 +510,45 @@ 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" | "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.
  *
@@ -612,6 +651,95 @@ interface MessagingSupabaseClient {
 /** The internal client contract — what the repository and the manager see. */
 type MessagingSupabaseInternal = SupabaseLike & RealtimeClientLike;
 
+/**
+ * WHO IS ACTING — read from the session, never handed in (DD-241).
+ *
+ * THE CLASS THIS CLOSES, and why messaging is the WORSE half of it. Through
+ * 0.11.x this package took the acting user's id from whoever built it:
+ * `<MessagingProvider userId>` for the React path, and
+ * `createMessagingRepository({ identity: { userId } })` for the framework-free
+ * one. Both ends got their id the same way in the only host that exists —
+ * matrx-frontend's Redux `selectUserId` — and that copy is written once, when
+ * the app boots. Nothing rewrites it when the domain-wide auth cookie rotates
+ * to another account, when the person signs out in another tab, or when a
+ * refresh returns a different subject.
+ *
+ * Meet's version of this (DD-240, `@ai-matrx/meet` 0.6.0) made READS fail:
+ *
+ *   `communication.meet_pending_call_invites(p_user_id => <the stale copy>)`
+ *   → 42501 at HTTP 403, "meet: the acting user (4cf62e4e…) is not the
+ *     authenticated user"
+ *
+ * Messaging's version reaches further, because here the id is not only a read
+ * argument — it is a WRITE argument. `identity.userId` lands on the wire as
+ * `p_user1_id` (the direct-conversation pair), `sender_id` (who a message is
+ * FROM), `created_by` and `updated_by` (the audit columns), and
+ * `.eq("user_id", …)` (whose participant row is being read and updated). A
+ * stale one does not merely get refused: where RLS lets it through it writes a
+ * row attributed to somebody the tab cannot prove it is.
+ *
+ * So there is ONE source now, and it is the client's own session. The same
+ * client that mints the JWT on every PostgREST request answers "who is this?",
+ * so the id in the argument and the id in the token cannot disagree — not
+ * because they are kept in step, but because they are the same fact read once.
+ *
+ * WHAT THIS MODULE IS. A tiny observable over `client.auth`: the current acting
+ * user id, a subscription that fires when it changes, and a `resolving` state
+ * that is honest about the moment before the first `getSession()` answers.
+ *
+ *  - It is `resolving` until the first read lands. Nothing user-scoped is
+ *    issued in that window, which is what a page-load race used to spend
+ *    issuing reads and writes as a user the tab could not prove it was.
+ *  - `snapshot()` returns THE SAME REFERENCE until the acting user moves — a
+ *    `useSyncExternalStore` source that returns a fresh object per call is
+ *    "Maximum update depth exceeded", not a warning.
+ *  - It NEVER refuses anything on its own authority. It reports who the session
+ *    says you are; the database remains the only thing that decides what that
+ *    is allowed to read or write.
+ *  - A client with no `auth` at all is a real, named failure with a remedy —
+ *    never a silent fall back to "nobody".
+ *
+ * THE CLIENT BOUNDARY STAYS SHALLOW (0.2.1, `repository.ts`'s header). The
+ * public prop type is still `MessagingSupabaseClient`, which does not describe
+ * `auth` at all — so this module narrows to its own minimal `AuthLike` in ONE
+ * place, exactly as `createMessagingRepository` narrows to
+ * `MessagingSupabaseInternal`. A real `SupabaseClient` satisfying `AuthLike` is
+ * proven at compile time in `supabase-shape.test.ts`.
+ */
+
+interface SessionIdentitySnapshot {
+    /**
+     * `resolving` until the first `getSession()` answers. A user-scoped read or
+     * write issued in this window would name a guess.
+     */
+    readonly state: "resolving" | "resolved";
+    /** Who the session says is acting, or `null` for nobody. */
+    readonly userId: UserId | null;
+}
+interface SessionIdentity {
+    /**
+     * False when the client handed to us has no auth source at all — a
+     * misconfiguration, not "nobody is signed in", and the two get different
+     * sentences.
+     */
+    readonly hasAuthSource: boolean;
+    /** Stable reference until the acting user actually changes. */
+    snapshot(): SessionIdentitySnapshot;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+interface SessionIdentityOptions {
+    readonly client: MessagingSupabaseClient;
+    readonly onDiagnostic?: ((event: {
+        level: "info" | "warn" | "error";
+        message: string;
+        remedy?: string | undefined;
+    }) => void) | undefined;
+}
+/** The snapshot every server render sees: nobody is acting on a server. */
+declare const SERVER_SESSION_IDENTITY: SessionIdentitySnapshot;
+declare function createSessionIdentity(options: SessionIdentityOptions): SessionIdentity;
+
 /**
  * THE DATA CONTRACT — the ONE place a messaging table or RPC name exists.
  *
@@ -688,7 +816,23 @@ interface RepositoryOptions {
      * the provider does.
      */
     client: MessagingSupabaseClient;
-    identity: MessagingIdentity;
+    /**
+     * The active organization. Every conversation and message write carries it
+     * explicitly (R5).
+     *
+     * 🚨 THERE IS NO `userId` HERE, AND THERE WILL NOT BE ONE (DD-241). Who is
+     * acting is read from `client`'s own session — see `session-identity.ts` for
+     * the class that closed and why a handed-in id could not be made safe by
+     * convention. A caller that still passes `identity` is IGNORED and told so.
+     */
+    organizationId: string;
+    /**
+     * INTERNAL. The React provider already runs one session reader for its own
+     * render loop and hands it here so the two cannot answer differently and so
+     * one `onAuthStateChange` subscription serves both. A framework-free caller
+     * omits it and the repository builds its own from `client`.
+     */
+    sessionIdentity?: SessionIdentity | undefined;
     /** Called once before a retry when a read fails with a missing session. */
     resolveSession?: SessionResolver | undefined;
     /**
@@ -702,7 +846,14 @@ interface RepositoryOptions {
     now?: (() => number) | undefined;
 }
 interface MessagingRepository {
-    readonly identity: MessagingIdentity;
+    /** The organization every write here is stamped with. */
+    readonly organizationId: OrganizationId;
+    /**
+     * Who the session says is acting — awaited, because the first `getSession()`
+     * is a real read. Rejects with `session-unavailable` when nobody is signed
+     * in, which is the code the retry loop already knows how to heal.
+     */
+    actingUserId(): Promise<UserId>;
     listConversations(args?: {
         limit?: number;
         cursor?: ConversationCursor | null;
@@ -980,11 +1131,19 @@ declare function messagingClientId(): string;
  * package error, retrying a package call, or branching on a package quirk in
  * host code, that logic belongs in here (C22).
  *
- * 🚨 THE PROVIDER'S LIFETIME IS `client` + `userId` + `organizationId`, AND
- * NOTHING ELSE. Hosts pass fresh object literals for `agents`, `actions`, and
- * `onDiagnostic` on every render; keying the engine on those identities would
- * tear down and rebuild every channel on every parent re-render — a permanent
- * resubscribe loop that looks exactly like "realtime is broken".
+ * 🚨 THE PROVIDER'S LIFETIME IS `client` + THE SESSION'S USER + `organizationId`,
+ * AND NOTHING ELSE. Hosts pass fresh object literals for `agents`, `actions`,
+ * and `onDiagnostic` on every render; keying the engine on those identities
+ * would tear down and rebuild every channel on every parent re-render — a
+ * permanent resubscribe loop that looks exactly like "realtime is broken".
+ *
+ * 🚨 THERE IS NO `userId` PROP (DD-241, 0.12.0). Who is acting is read from the
+ * session of the `client` you pass — see `core/session-identity.ts` for the
+ * class that closed. The provider is INERT until that first read lands, an
+ * account switch rebuilds the runtime under the open tab, and a sign-out makes
+ * it inert again. A `userId` still passed at run time (a stale bundle, a
+ * JavaScript consumer) is ignored and reported through `onDiagnostic` with the
+ * remedy — never taken, and never dropped in silence.
  */
 
 /**
@@ -1080,10 +1239,14 @@ interface MessagingHost {
     readonly wrapConversationRow: ComponentType<ConversationRowWrapperProps> | null;
 }
 interface MessagingProviderProps {
-    /** Any Supabase client. `null` while the host is still resolving one. */
+    /**
+     * Any Supabase client. `null` while the host is still resolving one.
+     *
+     * 🚨 IT IS ALSO WHO YOU ARE. Messaging reads the acting user from THIS
+     * client's session, so pass the same browser client your app signs in with
+     * (DD-241). There is no `userId` prop, on purpose.
+     */
     client: MessagingSupabaseClient | null | undefined;
-    /** The signed-in user. `null` while auth is still resolving. */
-    userId: string | null | undefined;
     /** The active organization. Every write carries it (R5). */
     organizationId: string | null | undefined;
     /**
@@ -1512,45 +1675,6 @@ declare const MESSAGING_EVENTS: {
     readonly actionSettled: "mx.action.settled";
 };
 
-/**
- * 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" | "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;
-
 /**
  * Display formatting. In the package because every consumer otherwise rebuilds
  * it slightly differently and the inbox and the thread disagree about what
@@ -1681,4 +1805,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 ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, 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, type SchemaLike, SearchIcon, SendIcon, 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, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, 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 ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, 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, 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 };