@ai-matrx/messaging 0.0.0 → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,995 @@
+import { MatrxTransport } from '@ai-matrx/agents/matrx';
+import { RealtimeManager } from '@ai-matrx/realtime';
+
+/**
+ * THE MESSAGING DOMAIN TYPES.
+ *
+ * Ported from `matrx-frontend/features/messaging/types.ts` with the coupling
+ * seams inverted: no imported host types, no app singletons. The DB-shaped
+ * types mirror `communication.dm_*` exactly (snake_case, nullable where the
+ * column is nullable) so a row read from PostgREST IS one of these without a
+ * mapping step that can silently drop a column.
+ *
+ * Strictness posture (C22): identity-bearing values are BRANDED, invalid states
+ * are unrepresentable (a `sending` message has a `clientMessageId`; a `failed`
+ * one carries a reason), and no surface here is `any`. The one honest `unknown`
+ * is the JSON boundary — `metadata` and `action_data` are host/DB-generated
+ * shapes this package does not own (the data 0.2.1 `Json = unknown` lesson).
+ */
+/** Nominal id types. A conversation id can never be passed where a user id goes. */
+declare const brand: unique symbol;
+type Brand<T, B extends string> = T & {
+    readonly [brand]: B;
+};
+type ConversationId = Brand<string, "ConversationId">;
+type MessageId = Brand<string, "MessageId">;
+type UserId = Brand<string, "UserId">;
+type OrganizationId = Brand<string, "OrganizationId">;
+/** The client-minted idempotency key that makes a send exactly-once end to end. */
+type ClientMessageId = Brand<string, "ClientMessageId">;
+declare const asConversationId: (value: string) => ConversationId;
+declare const asMessageId: (value: string) => MessageId;
+declare const asUserId: (value: string) => UserId;
+declare const asOrganizationId: (value: string) => OrganizationId;
+declare const asClientMessageId: (value: string) => ClientMessageId;
+type JsonValue = unknown;
+type JsonObject = Readonly<Record<string, JsonValue>>;
+type ConversationType = "direct" | "group" | "org";
+type ParticipantRole = "owner" | "admin" | "member";
+type MessageKind = "text" | "image" | "video" | "audio" | "file" | "system" | "action";
+/**
+ * The delivery ladder. `sending` and `failed` exist only client-side: they are
+ * the outbox's states, and the DB's `status` column never holds them.
+ */
+type DeliveryState = "sending" | "sent" | "delivered" | "read" | "failed";
+interface Conversation {
+    readonly id: ConversationId;
+    readonly type: ConversationType;
+    readonly groupName: string | null;
+    readonly groupImageUrl: string | null;
+    readonly createdBy: UserId | null;
+    readonly organizationId: OrganizationId;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly metadata: JsonObject;
+}
+interface Participant {
+    readonly conversationId: ConversationId;
+    readonly userId: UserId;
+    readonly role: ParticipantRole;
+    readonly joinedAt: string | null;
+    readonly lastReadAt: string | null;
+    readonly isMuted: boolean;
+    readonly isArchived: boolean;
+}
+interface UserSummary {
+    readonly userId: UserId;
+    readonly displayName: string;
+    readonly email: string | null;
+    readonly avatarUrl: string | null;
+    /** True when this participant is an AI agent rather than a person (R4). */
+    readonly isAgent: boolean;
+}
+/**
+ * A structured action carried by a message. THE SEAM other packages extend —
+ * `@ai-matrx/meet` puts a call invitation here rather than inventing a message
+ * type (D1).
+ *
+ * `version` is not decoration: a renderer that does not understand a version
+ * renders NOTHING rather than guessing, which is what lets a new sender ship
+ * before every reader has caught up.
+ */
+interface MessageAction<TKind extends string = string, TPayload = JsonObject> {
+    readonly kind: TKind;
+    readonly version: number;
+    readonly payload: TPayload;
+}
+/**
+ * A typed reference to a platform entity, rendered as a live openable card.
+ * NO DEAD ENDS: everything a message names must open, so a reference always
+ * carries enough to resolve — never a bare label.
+ */
+interface MatrxReference {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly label: string;
+    readonly href?: string | undefined;
+}
+interface Attachment {
+    /** A DURABLE file ref, never a signed URL. Signed URLs expire; identities do not. */
+    readonly fileId: string;
+    readonly fileName: string;
+    readonly mimeType: string | null;
+    readonly sizeBytes: number | null;
+    readonly width: number | null;
+    readonly height: number | null;
+}
+interface Message {
+    readonly id: MessageId;
+    readonly conversationId: ConversationId;
+    readonly senderId: UserId;
+    readonly organizationId: OrganizationId;
+    readonly content: string;
+    readonly kind: MessageKind;
+    readonly deliveryState: DeliveryState;
+    readonly replyToId: MessageId | null;
+    readonly clientMessageId: ClientMessageId | null;
+    readonly createdAt: string;
+    readonly editedAt: string | null;
+    readonly deletedAt: string | null;
+    readonly deletedForEveryone: boolean;
+    readonly action: MessageAction | null;
+    readonly attachments: readonly Attachment[];
+    readonly references: readonly MatrxReference[];
+    readonly metadata: JsonObject;
+    /** Set only while this message is in the outbox and its last send failed. */
+    readonly failureReason?: string | undefined;
+}
+interface ConversationSummary {
+    readonly conversation: Conversation;
+    readonly participants: readonly UserSummary[];
+    readonly lastMessageContent: string | null;
+    readonly lastMessageSenderId: UserId | null;
+    readonly lastMessageAt: string | null;
+    readonly unreadCount: number;
+    readonly isMuted: boolean;
+    readonly isArchived: boolean;
+    /** Resolved for display: the group name, or the other participant's name. */
+    readonly displayName: string;
+    readonly displayImageUrl: string | null;
+    /** The keyset sort value. Pagination cursors are built from this + `id`. */
+    readonly sortAt: string;
+}
+/**
+ * THE PAGINATION CURSOR. Stable ordering is terminated by a UNIQUE column
+ * (R5 scale honesty): ordering by a timestamp alone silently duplicates or
+ * skips rows whenever two rows share a millisecond, which in a large org is
+ * every page.
+ */
+interface ConversationCursor {
+    readonly beforeSortAt: string;
+    readonly beforeConversationId: ConversationId;
+}
+interface MessageCursor {
+    readonly beforeCreatedAt: string;
+    readonly beforeMessageId: MessageId;
+}
+interface Page<TItem, TCursor> {
+    readonly items: readonly TItem[];
+    readonly nextCursor: TCursor | null;
+    readonly hasMore: boolean;
+}
+/** What the host injects. Identity ONLY — every hard part is in the package. */
+interface MessagingIdentity {
+    readonly userId: UserId;
+    readonly organizationId: OrganizationId;
+}
+interface DraftMessage {
+    readonly conversationId: ConversationId;
+    readonly content: string;
+    readonly kind?: MessageKind | undefined;
+    readonly replyToId?: MessageId | undefined;
+    readonly action?: MessageAction | undefined;
+    readonly attachments?: readonly Attachment[] | undefined;
+    readonly references?: readonly MatrxReference[] | undefined;
+    readonly metadata?: JsonObject | undefined;
+}
+
+/**
+ * ACTIONABLE MESSAGES — a message that carries something you can DO.
+ *
+ * A registry, never a `switch`. Two properties come from that choice, and both
+ * are load-bearing:
+ *
+ * - **Forward compatibility.** An unknown `kind` — or a known kind at a version
+ *   this build does not understand — renders NOTHING and executes nothing. A
+ *   `switch` with a `default: throw` means the day a new sender ships, every
+ *   older reader's thread breaks. Silently rendering an unknown payload with a
+ *   generic button is worse: it offers an action nobody can honor.
+ * - **Extensibility across packages.** `@ai-matrx/meet` registers its call
+ *   invitation here rather than this package learning about meetings (D1).
+ *
+ * 🚨 **IDEMPOTENCE IS ENFORCED HERE, NOT PROMISED BY HANDLERS.** Two tabs, a
+ * double-click, and a retried tap must apply an action ONCE. The registry
+ * de-duplicates by `(kind, messageId, actorId)`: a second execution while the
+ * first is in flight AWAITS it and returns the same receipt, and a settled
+ * action returns its stored receipt without touching the server.
+ *
+ * 🚨 **THE PAYLOAD IS NOT AUTHORIZATION.** A handler must re-resolve the
+ * durable, caller-authorized request row server-side before it writes. The
+ * message's `action_data` says what was ASKED, never what is ALLOWED — trusting
+ * it turns any message into a privilege grant. Handlers declare this by
+ * construction: they receive the payload and the actor, and must go to the
+ * database themselves.
+ */
+
+type ActionOutcome = "applied" | "already" | "declined" | "unavailable";
+interface ActionReceipt {
+    readonly kind: string;
+    readonly messageId: MessageId;
+    readonly actorId: UserId;
+    readonly outcome: ActionOutcome;
+    readonly label: string;
+    readonly settledAt: string;
+    readonly detail?: string | undefined;
+}
+interface ActionContext {
+    readonly messageId: MessageId;
+    readonly actorId: UserId;
+    readonly organizationId: string;
+    /** Which of the choices the user picked, e.g. `approve` / `decline`. */
+    readonly choice: string;
+}
+interface ActionChoice {
+    readonly id: string;
+    readonly label: string;
+    readonly tone: "primary" | "neutral" | "danger";
+}
+interface ActionHandler<TPayload = JsonObject> {
+    readonly kind: string;
+    /** Versions this build understands. An unlisted version renders nothing. */
+    readonly versions: readonly number[];
+    /** What the chips say. Return `[]` to render the action as read-only. */
+    choices: (payload: TPayload) => readonly ActionChoice[];
+    /** One-line summary for the inbox preview and notifications. */
+    summarize?: (payload: TPayload) => string;
+    /**
+     * Do the thing. MUST re-resolve the authorizing row server-side; the payload
+     * is the request, not the permission. Returning `already` is how a handler
+     * reports that the server had settled it — the registry treats it as success.
+     */
+    execute: (payload: TPayload, context: ActionContext) => Promise<ActionReceipt>;
+}
+interface ActionRegistry {
+    register<TPayload = JsonObject>(handler: ActionHandler<TPayload>): void;
+    /** The handler for an action, or null when this build cannot honor it. */
+    resolve(action: MessageAction): ActionHandler | null;
+    choicesFor(action: MessageAction): readonly ActionChoice[];
+    summarize(action: MessageAction): string | null;
+    /** Idempotent execution. Concurrent callers share one in-flight result. */
+    execute(action: MessageAction, context: ActionContext): Promise<ActionReceipt>;
+    /** The stored receipt for a settled action, if there is one. */
+    receiptFor(kind: string, messageId: MessageId, actorId: UserId): ActionReceipt | null;
+    /** Record a receipt observed from another client's broadcast. */
+    observeReceipt(receipt: ActionReceipt): void;
+    known(): readonly string[];
+}
+declare function createActionRegistry(): ActionRegistry;
+
+/**
+ * EFFECTIVE-ACTOR RESOLUTION — who a message is FROM, versus who wrote the row.
+ *
+ * `sender_id` is the AUDIT PRINCIPAL: the session the write happened under. It
+ * must never change, and it must never be what the UI renders when an agent
+ * acted through a human's session. Otherwise an automated message wears a
+ * colleague's face and name — the failure this module exists to prevent (R4
+ * puts agents in conversations, which makes it the normal case, not an edge).
+ *
+ * The effective actor is declared in the message's own metadata by whoever sent
+ * it. Nothing here infers an agent from heuristics on the content.
+ */
+
+interface ActorPresentation {
+    readonly displayName: string;
+    readonly avatarUrl: string | null;
+    /** True when the message was authored by an agent, not the human principal. */
+    readonly isAgent: boolean;
+    /** Set only for an agent: the human whose session it acted under. */
+    readonly onBehalfOfName: string | null;
+    /** The audit principal. Always the row's `sender_id`. Never rewritten. */
+    readonly principalUserId: Message["senderId"];
+}
+declare function resolveActor(message: Message, sender: UserSummary | null): ActorPresentation;
+
+/**
+ * AI-NATIVE, OUT OF THE BOX (R4).
+ *
+ * Four conversation intelligences — catch me up, summarize, extract action
+ * items, draft a reply — plus agents as participants. All of it executes on the
+ * platform's agent system through `@ai-matrx/agents`; this package never talks
+ * to a model, never holds a prompt, and never carries an agent definition.
+ *
+ * 🚨 **THE USER-INPUT LAW.** `user_input` is what a HUMAN typed. Machine
+ * content — a transcript, a participant roster, a cutoff timestamp — travels as
+ * NAMED VARIABLES. This is not style: the server treats `user_input` as the
+ * turn's human utterance (it is stored as such, shown as such, and shapes the
+ * agent's framing), so smuggling a transcript through it silently corrupts
+ * every conversation it touches. Every call below sends `variables` and either
+ * a short human-shaped `user_input` or none.
+ *
+ * 🚨 **AGENT DEFINITIONS LIVE IN THE DATABASE.** The package takes agent IDs as
+ * injected identity. When an id is not configured the capability reports
+ * `unavailable` WITH the remedy — it never silently no-ops, and the UI hides
+ * the action rather than offering a dead button (no dead ends).
+ */
+
+/**
+ * Which platform agent backs each capability. Every field is a DATABASE row id
+ * supplied by the host; an omitted one disables exactly that capability.
+ */
+interface MessagingAgents {
+    readonly catchUp?: string | undefined;
+    readonly summarize?: string | undefined;
+    readonly actionItems?: string | undefined;
+    readonly draftReply?: string | undefined;
+}
+interface MessagingAiOptions {
+    transport: MatrxTransport;
+    organizationId: string;
+    agents: MessagingAgents;
+    /** Stable source slugs so server-side analytics can see where a run came from. */
+    sourceApp?: string | undefined;
+    sourceFeature?: string | undefined;
+    /** Cap on how much transcript is sent. Default 200 messages. */
+    maxTranscriptMessages?: number | undefined;
+}
+type AiCapability = keyof MessagingAgents;
+interface AiResult {
+    readonly capability: AiCapability;
+    readonly text: string;
+    readonly conversationId: string | null;
+}
+interface MessagingAi {
+    /** Which capabilities this host actually configured. Drives what the UI offers. */
+    available(): readonly AiCapability[];
+    isAvailable(capability: AiCapability): boolean;
+    catchMeUp(args: {
+        conversationId: ConversationId;
+        messages: readonly Message[];
+        participants: readonly UserSummary[];
+        since: string | null;
+        signal?: AbortSignal;
+    }): Promise<AiResult>;
+    summarize(args: {
+        conversationId: ConversationId;
+        messages: readonly Message[];
+        participants: readonly UserSummary[];
+        signal?: AbortSignal;
+    }): Promise<AiResult>;
+    extractActionItems(args: {
+        conversationId: ConversationId;
+        messages: readonly Message[];
+        participants: readonly UserSummary[];
+        signal?: AbortSignal;
+    }): Promise<AiResult>;
+    draftReply(args: {
+        conversationId: ConversationId;
+        messages: readonly Message[];
+        participants: readonly UserSummary[];
+        /** What the human asked for, if anything — this IS a human utterance. */
+        instruction?: string | undefined;
+        signal?: AbortSignal;
+    }): Promise<AiResult>;
+}
+declare function createMessagingAi(options: MessagingAiOptions): MessagingAi;
+
+/**
+ * IN-FLIGHT DEDUP + TTL CACHE — the cure for the request storm.
+ *
+ * The incident (matrx-frontend, 2026-08-21): every conversation row rendered
+ * called the profile lookup for its participants, every one of those calls hit
+ * the network independently, the transport wobbled, and the app captured
+ * **909 errors in 0.6 seconds**. The bug was never the transport — it was that
+ * N identical concurrent reads were N requests.
+ *
+ * Two guarantees, and both are load-bearing:
+ *
+ * 1. **Concurrent callers for the same key share ONE promise.** The second
+ *    caller does not start a second request; it awaits the first.
+ * 2. **A failure does not poison the cache.** The rejected promise is evicted
+ *    the moment it settles, so the next caller retries instead of inheriting a
+ *    permanent error. (The naive version caches the rejection and the surface
+ *    stays broken until reload — the reason this has a named test.)
+ *
+ * A resolved value is held for `ttlMs` and then re-read. This is a READ cache
+ * only: writes go straight through and invalidate.
+ */
+interface ReadCacheOptions {
+    /** How long a resolved value is served without a re-read. */
+    ttlMs: number;
+    /** Injected clock — the tests must not sleep. */
+    now?: () => number;
+    /** Bound on retained entries; the oldest is evicted first. */
+    maxEntries?: number;
+}
+interface ReadCache<T> {
+    /** Read through the cache. Identical concurrent keys share one call. */
+    read(key: string, load: () => Promise<T>): Promise<T>;
+    /** Drop one key (after a write that changes it). */
+    invalidate(key: string): void;
+    /** Drop everything (sign-out, org switch). */
+    clear(): void;
+    /** Diagnostics: how many resolved entries are held. */
+    size(): number;
+}
+declare function createReadCache<T>(options: ReadCacheOptions): ReadCache<T>;
+
+/**
+ * THE MESSAGING CHANNEL NAMESPACES.
+ *
+ * D5: zero hand-rolled `.channel(` in this package. Every topic is declared
+ * through `@ai-matrx/realtime`'s registry, which refuses a colliding
+ * re-declaration and hands every connection attempt a unique instance topic.
+ *
+ * TWO channels, deliberately — not four. The origin ran `messages:`, `typing:`,
+ * `presence:` and a global list channel as four independent subscriptions, and
+ * three of the four hardening items were about them fighting each other. Here:
+ *
+ * - `messaging-inbox` (per user): the conversation list's own feed.
+ * - `messaging-conversation` (per conversation): messages, presence, AND
+ *   typing on ONE channel, because they are one room. Sharing the channel is
+ *   what makes "the person typing is also present" true by construction
+ *   instead of by two subscriptions agreeing.
+ *
+ * `defineChannelNamespace` throws on a conflicting re-declaration, so these are
+ * created lazily through a `globalThis` slot: with dual ESM/CJS output the
+ * module can be evaluated twice in one process, and a second identical
+ * declaration must be a no-op rather than a crash.
+ */
+
+declare function inboxTopic(userId: UserId): string;
+declare function conversationTopic(conversationId: ConversationId): string;
+/** Broadcast event names. One place, so a sender and a receiver cannot drift. */
+declare const MESSAGING_EVENTS: {
+    /** A freshly sent message, broadcast beside the Postgres Changes row so a
+     *  receiver gets it on whichever path arrives first (both are deduped). */
+    readonly message: "mx.message";
+    /** A message edited or soft-deleted. */
+    readonly messageUpdated: "mx.message.updated";
+    /** An action receipt, so every viewer's chip settles at once. */
+    readonly actionSettled: "mx.action.settled";
+};
+
+/**
+ * THE OUTBOX — a message you typed is NEVER lost (R2, table-stakes law).
+ *
+ * This is the piece hosts always get wrong, so it is entirely in the package
+ * (C22). What "never lost" actually requires, and what each part defends:
+ *
+ * - **Durability across a reload.** The draft is persisted BEFORE the network
+ *   call, not after it succeeds. A tab closed mid-send comes back with the
+ *   message still queued. The storage port has a working default; a host that
+ *   injects nothing still gets in-memory queuing, and it SAYS so rather than
+ *   pretending to be durable.
+ * - **Exactly-once on retry.** Every entry carries a client-minted
+ *   `clientMessageId` that is generated ONCE and reused by every attempt. A
+ *   retry after a response that was actually delivered is deduped by the
+ *   database's idempotency key instead of posting the message twice.
+ * - **Order.** Entries for one conversation send strictly in order; message 2
+ *   never overtakes a retrying message 1.
+ * - **Bounded, honest failure.** Attempts back off; after `maxAttempts` the
+ *   entry stays in the queue marked `failed` WITH a reason and a retry door.
+ *   It is never silently dropped, and it never retries forever.
+ */
+
+interface OutboxEntry {
+    readonly id: string;
+    readonly clientMessageId: ClientMessageId;
+    readonly draft: DraftMessage;
+    readonly queuedAt: number;
+    readonly attempts: number;
+    readonly state: "queued" | "sending" | "failed";
+    readonly failureReason: string | null;
+}
+/**
+ * Persistence for pending sends. A default is always supplied — the package
+ * never leaves a port empty (THE ALL-INCLUSIVE LAW).
+ */
+interface OutboxStorage {
+    /** Human-readable, shown in diagnostics so "durable" is never assumed. */
+    readonly name: string;
+    readonly durable: boolean;
+    load(): readonly OutboxEntry[];
+    save(entries: readonly OutboxEntry[]): void;
+}
+declare function createMemoryOutboxStorage(): OutboxStorage;
+interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * The real default in a browser. Falls back to memory — announcing itself —
+ * when storage is unavailable (private mode, a disabled-cookies browser, SSR).
+ */
+declare function createWebOutboxStorage(args: {
+    key?: string;
+    storage?: WebStorageLike | null;
+    onFallback?: (reason: string) => void;
+}): OutboxStorage;
+interface OutboxOptions {
+    /** Actually send. Returns the persisted message. */
+    send: (draft: DraftMessage, clientMessageId: ClientMessageId) => Promise<Message>;
+    /** Called when an entry lands. The store collapses it with the optimistic row. */
+    onSent: (entry: OutboxEntry, message: Message) => void;
+    onChange: (entries: readonly OutboxEntry[]) => void;
+    onDiagnostic?: (message: string) => void;
+    storage?: OutboxStorage;
+    maxAttempts?: number;
+    /** Backoff schedule per attempt, ms. The last value repeats. */
+    backoffMs?: readonly number[];
+    timers?: {
+        setTimeout: (run: () => void, ms: number) => unknown;
+        clearTimeout: (handle: unknown) => void;
+        now: () => number;
+    };
+}
+interface Outbox {
+    entries(): readonly OutboxEntry[];
+    /** Queue a draft. Returns the id the optimistic message must carry. */
+    enqueue(draft: DraftMessage): ClientMessageId;
+    /** Retry one failed entry, on the user's explicit ask. */
+    retry(entryId: string): void;
+    /** Drop one entry — the only sanctioned way a typed message leaves the queue. */
+    discard(entryId: string): void;
+    /** Network came back / tab woke: try everything that is waiting. */
+    flush(): void;
+    pendingFor(conversationId: ConversationId): readonly OutboxEntry[];
+    dispose(): void;
+}
+declare function createOutbox(options: OutboxOptions): Outbox;
+
+/**
+ * THE STRUCTURAL SUPABASE SHAPE.
+ *
+ * D2 says messaging is Supabase-locked — there is no provider abstraction and
+ * never will be. That is a statement about the CONTRACT, not about the import
+ * graph: this package still accepts the client STRUCTURALLY and never imports
+ * `@supabase/supabase-js` at runtime.
+ *
+ * Two reasons, both learned the hard way across the fleet:
+ *
+ * 1. A host that ships two copies of `@supabase/supabase-js` (the Next.js
+ *    server/browser split is the usual way) would get two different `Session`
+ *    identities and a package that refuses the host's own client.
+ * 2. `supabase-js` is a heavy dependency with its own release train; a package
+ *    that pins one is a version-drift generator (THE LATEST LAW's failure mode
+ *    in miniature).
+ *
+ * `supabase-shape.test.ts` proves at COMPILE TIME that a real `SupabaseClient`
+ * satisfies these interfaces. If that file stops compiling, the interface here
+ * is wrong — fix it here, never with a cast at the call site, and never by
+ * asking the consumer to adapt.
+ */
+
+/** What PostgREST hands back. `error` is opaque on purpose — we normalize it. */
+interface PostgrestLikeResponse<T> {
+    data: T | null;
+    error: {
+        message: string;
+        code?: string;
+        details?: string | null;
+    } | null;
+}
+interface PostgrestFilterLike<TRow> extends PromiseLike<PostgrestLikeResponse<TRow[]>> {
+    eq(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    neq(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    in(column: string, values: readonly unknown[]): PostgrestFilterLike<TRow>;
+    is(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    lt(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    gt(column: string, value: unknown): PostgrestFilterLike<TRow>;
+    or(filters: string): PostgrestFilterLike<TRow>;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): PostgrestFilterLike<TRow>;
+    limit(count: number): PostgrestFilterLike<TRow>;
+    select(columns?: string): PostgrestFilterLike<TRow>;
+    single(): PromiseLike<PostgrestLikeResponse<TRow>>;
+    maybeSingle(): PromiseLike<PostgrestLikeResponse<TRow>>;
+}
+interface PostgrestTableLike<TRow> {
+    select(columns?: string): PostgrestFilterLike<TRow>;
+    insert(values: unknown): PostgrestFilterLike<TRow>;
+    update(values: unknown): PostgrestFilterLike<TRow>;
+    upsert(values: unknown, options?: {
+        onConflict?: string;
+    }): PostgrestFilterLike<TRow>;
+    delete(): PostgrestFilterLike<TRow>;
+}
+interface SchemaLike {
+    from<TRow = Record<string, unknown>>(table: string): PostgrestTableLike<TRow>;
+    rpc<TResult = unknown>(fn: string, args?: Record<string, unknown>): PromiseLike<PostgrestLikeResponse<TResult>>;
+}
+/**
+ * The subset of the Supabase client this package uses. `schema()` matters:
+ * every messaging table lives in the `communication` schema, never `public`
+ * (the platform's canonical DB conventions, R8).
+ */
+interface SupabaseLike extends SchemaLike {
+    schema(name: string): SchemaLike;
+}
+
+/**
+ * THE DATA CONTRACT — the ONE place a messaging table or RPC name exists.
+ *
+ * Every name below was verified against Matrx Main (`https://db.matrxserver.com`)
+ * on 2026-08-31, not guessed from a client. `matrx-dm` grew a parallel schema in
+ * its own project (`public.conversations` / `messages` / `message_reactions`);
+ * per R8 exactly ONE canonical schema survives and it is this one — the
+ * platform-conventional `communication.dm_*` tables with explicit
+ * `organization_id`, `version`, and soft-delete columns, behind auth-checked
+ * SECURITY DEFINER RPCs.
+ *
+ * Four rules hold this file together:
+ *
+ * 1. **Org is explicit on every write (R5).** Not defaulted by a trigger we
+ *    hope fires, not inherited — passed, and refused in-package when absent.
+ * 2. **Authorization is the database's job.** There is no permission branch in
+ *    this file. An RPC that says no is a `forbidden` MessagingError, never a
+ *    client-side re-decision.
+ * 3. **Direct conversations are created ATOMICALLY, by RPC.** The banned
+ *    pattern — read `find_dm_direct_conversation`, then insert — races two
+ *    tabs into two conversations for the same pair. The RPC advisory-locks the
+ *    unordered pair. Nothing here may reintroduce the read-then-insert shape.
+ * 4. **Pagination is keyset and terminated by a unique column.** Ordering by a
+ *    timestamp alone duplicates or skips rows whenever two share a millisecond
+ *    — which in a large org is every page.
+ */
+
+/** The schema. Messaging is never in `public`. */
+declare const MESSAGING_SCHEMA = "communication";
+declare const TABLES: {
+    readonly conversations: "dm_conversations";
+    readonly participants: "dm_conversation_participants";
+    readonly messages: "dm_messages";
+};
+declare const RPCS: {
+    /** Atomic direct-conversation creation. Advisory-locks the unordered pair. */
+    readonly getOrCreateDirect: "dm_get_or_create_direct_conversation";
+    /** Conversation list + participants + last message + unread, keyset paged. */
+    readonly conversationsWithDetails: "get_dm_conversations_with_details";
+    readonly unreadCount: "get_dm_unread_count";
+    readonly userInfo: "get_dm_user_info";
+    readonly isParticipant: "is_dm_participant";
+};
+/**
+ * The host's session source. A messaging read that lands between sign-in and
+ * token arrival must not become a red error — it retries ONCE after the host
+ * resolves a session, then reports `session-unavailable`.
+ */
+type SessionResolver = () => Promise<unknown>;
+interface RepositoryOptions {
+    client: SupabaseLike;
+    identity: MessagingIdentity;
+    /** Called once before a retry when a read fails with a missing session. */
+    resolveSession?: SessionResolver | undefined;
+    /** Profile-lookup cache TTL. Default 5 minutes (the frontend's proven value). */
+    userTtlMs?: number | undefined;
+    now?: (() => number) | undefined;
+}
+interface MessagingRepository {
+    readonly identity: MessagingIdentity;
+    listConversations(args?: {
+        limit?: number;
+        cursor?: ConversationCursor | null;
+    }): Promise<Page<ConversationSummary, ConversationCursor>>;
+    getConversation(id: ConversationId): Promise<Conversation>;
+    listMessages(conversationId: ConversationId, args?: {
+        limit?: number;
+        cursor?: MessageCursor | null;
+    }): Promise<Page<Message, MessageCursor>>;
+    /** Messages created strictly after `since` — the reconnect backfill read. */
+    messagesSince(conversationId: ConversationId, since: string): Promise<readonly Message[]>;
+    getOrCreateDirectConversation(otherUserId: UserId): Promise<ConversationId>;
+    createGroupConversation(args: {
+        name: string;
+        memberIds: readonly UserId[];
+    }): Promise<ConversationId>;
+    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>;
+    setConversationFlags(conversationId: ConversationId, flags: {
+        isMuted?: boolean;
+        isArchived?: boolean;
+    }): Promise<void>;
+    addMembers(conversationId: ConversationId, memberIds: readonly UserId[]): Promise<void>;
+    removeMember(conversationId: ConversationId, memberId: UserId): Promise<void>;
+    setMemberRole(conversationId: ConversationId, memberId: UserId, role: ParticipantRole): Promise<void>;
+    /** Cached + in-flight-deduped. N callers for one id make ONE request. */
+    getUser(userId: UserId): Promise<UserSummary | null>;
+    getUsers(userIds: readonly UserId[]): Promise<ReadonlyMap<UserId, UserSummary>>;
+    searchMessages(args: {
+        query: string;
+        conversationId?: ConversationId | null;
+        limit?: number;
+    }): Promise<readonly Message[]>;
+    invalidateUser(userId: UserId): void;
+}
+declare function createMessagingRepository(options: RepositoryOptions): MessagingRepository;
+
+/**
+ * THE MESSAGE STORE — where "the same message twice" is made impossible.
+ *
+ * A message can reach this store by FOUR different paths, often in any order:
+ * the optimistic bubble, the insert's own response, the broadcast, and the
+ * Postgres Changes row. Every duplicate bug in every chat product is one of
+ * those four arriving out of order. The rules here, each with a regression test:
+ *
+ * 1. **Identity is `id` OR `clientMessageId`.** The confirmed row and the
+ *    optimistic bubble are the SAME message; the client-minted key is what
+ *    proves it. Matching on `(sender, content)` — the tempting shortcut — merges
+ *    two genuinely different "ok" messages into one.
+ * 2. **Merge collapses; it never appends.** A confirmed row that finds an
+ *    optimistic twin REPLACES it in place, keeping the twin's position so the
+ *    bubble does not jump.
+ * 3. **Older never overwrites newer.** An out-of-order UPDATE carrying an older
+ *    `edited_at`/`created_at` than the held copy is DROPPED. Without this an
+ *    edit visibly reverts itself a second later.
+ * 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.
+ */
+
+interface ConversationThread {
+    readonly conversationId: ConversationId;
+    readonly messages: readonly Message[];
+    readonly hasMoreOlder: boolean;
+    /** The newest `created_at` held — the reconnect backfill's high-water mark. */
+    readonly latestAt: string | null;
+}
+interface MessagingSnapshot {
+    readonly conversations: readonly ConversationSummary[];
+    readonly hasMoreConversations: boolean;
+    /**
+     * True once the inbox has actually been READ at least once.
+     *
+     * An empty list means two completely different things — "you have no
+     * conversations" and "we have not looked yet" — and a UI that cannot tell
+     * them apart shows a confident "No conversations yet" to someone who has
+     * hundreds. That is a screen telling a lie, so the distinction is a fact the
+     * store carries rather than something each surface guesses from a timer.
+     */
+    readonly hasLoadedConversations: boolean;
+    readonly threads: ReadonlyMap<ConversationId, ConversationThread>;
+    readonly activeConversationId: ConversationId | null;
+    /** Conversations WITH unread, not total unread messages (the origin's semantics). */
+    readonly totalUnreadConversations: number;
+}
+interface MessagingStore {
+    snapshot(): MessagingSnapshot;
+    subscribe(listener: (snapshot: MessagingSnapshot) => void): () => void;
+    setConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
+    appendConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
+    upsertConversation(item: ConversationSummary): void;
+    removeConversation(id: ConversationId): void;
+    setActiveConversation(id: ConversationId | null): void;
+    setThread(id: ConversationId, messages: readonly Message[], args?: {
+        hasMoreOlder?: boolean;
+    }): 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;
+    setUnreadCount(id: ConversationId, count: number): void;
+}
+declare function createMessagingStore(): MessagingStore;
+/**
+ * The optimistic row a composer shows the instant Enter is pressed. It carries
+ * the outbox's client key, which is the whole reason the confirmed row can find
+ * and replace it rather than appearing beside it.
+ */
+declare function optimisticMessage(args: {
+    conversationId: ConversationId;
+    senderId: UserId;
+    organizationId: Message["organizationId"];
+    content: string;
+    clientMessageId: ClientMessageId;
+    kind?: Message["kind"];
+    replyToId?: MessageId | null;
+    action?: Message["action"];
+    attachments?: readonly Message["attachments"][number][];
+    references?: readonly Message["references"][number][];
+    now?: () => number;
+}): Message;
+
+/**
+ * THE MESSAGING ENGINE — the object a host mounts once and never reasons about.
+ *
+ * It owns the wiring that every chat implementation gets wrong: which channel
+ * carries what, what happens on reconnect, which of four arrival paths wins,
+ * when a read receipt is written, and what a failed send does. All of it is
+ * here so a consumer's job is `engine.send(draft)` and rendering a snapshot.
+ *
+ * THE RECONNECT RULE, inherited from `@ai-matrx/realtime` and honored here:
+ * realtime has NO REPLAY. Every channel this engine opens declares an
+ * `onBackfill` door, and those doors re-read from the database. A reconnect
+ * without a re-read leaves a permanently wrong thread that looks perfectly
+ * healthy — the single most expensive bug class in messaging.
+ */
+
+interface EngineDiagnostic {
+    readonly level: "info" | "warn" | "error";
+    readonly message: string;
+    readonly remedy?: string | undefined;
+}
+interface MessagingEngineOptions {
+    repository: MessagingRepository;
+    manager: RealtimeManager;
+    identity: MessagingIdentity;
+    outboxStorage?: OutboxStorage | undefined;
+    onDiagnostic?: ((event: EngineDiagnostic) => void) | undefined;
+    /** Fired for a message from someone else, for notification sinks. */
+    onIncoming?: ((message: Message) => void) | undefined;
+    conversationPageSize?: number | undefined;
+    messagePageSize?: number | undefined;
+}
+interface MessagingEngine {
+    readonly store: MessagingStore;
+    readonly outbox: Outbox;
+    readonly identity: MessagingIdentity;
+    /** Load page one of the inbox and start the inbox channel. */
+    start(): Promise<void>;
+    loadMoreConversations(): Promise<void>;
+    /** Open a conversation: load its thread and subscribe to its channel. */
+    openConversation(id: ConversationId): Promise<void>;
+    closeConversation(id: ConversationId): void;
+    loadOlderMessages(id: ConversationId): Promise<void>;
+    /** Queue a message. Returns immediately with the optimistic row on screen. */
+    send(draft: DraftMessage): ClientMessageId;
+    retry(entryId: string): void;
+    discard(entryId: string): void;
+    editMessage(id: MessageId, conversationId: ConversationId, content: string): Promise<void>;
+    deleteMessage(id: MessageId, conversationId: ConversationId, forEveryone: boolean): Promise<void>;
+    markRead(id: ConversationId): Promise<void>;
+    startDirectConversation(otherUserId: UserId): Promise<ConversationId>;
+    dispose(): void;
+}
+declare function createMessagingEngine(options: MessagingEngineOptions): MessagingEngine;
+/** The realtime client session id, exposed for diagnostics surfaces. */
+declare function messagingClientId(): string;
+
+/**
+ * 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" | "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 retrying after the host re-establishes a session 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
+ * "yesterday" means.
+ *
+ * Every function takes an explicit `now` so the tests do not depend on the
+ * clock, and none of them touches `Intl` with an implicit locale — a package
+ * that silently formats in the build machine's locale is a bug that only shows
+ * up for users in other timezones.
+ */
+
+declare function isSameDay(a: Date, b: Date): boolean;
+/** Compact stamp for a conversation row: `9:41 AM`, `Yesterday`, `Mar 4`. */
+declare function formatConversationTime(isoString: string | null, now?: number, locale?: string): string;
+/** The stamp under a bubble. */
+declare function formatMessageTime(isoString: string, locale?: string): string;
+/** The separator between day groups in a thread. */
+declare function formatDateSeparator(isoString: string, now?: number, locale?: string): string;
+declare function getInitials(name: string): string;
+/**
+ * A stable palette index for an avatar with no image. Deterministic on the id,
+ * so the same person is the same color on every device and every reload — a
+ * random color per render is a surprisingly loud bug.
+ */
+declare function avatarPaletteIndex(seed: string, buckets?: number): number;
+/**
+ * Group consecutive messages by the same sender within a window, the way every
+ * good chat UI does — one avatar and one name per burst.
+ */
+interface MessageGroup {
+    readonly senderId: UserId;
+    readonly messages: readonly Message[];
+    readonly dateSeparator: string | null;
+}
+declare function groupMessages(messages: readonly Message[], args?: {
+    now?: number;
+    windowMs?: number;
+    locale?: string;
+}): readonly MessageGroup[];
+/** "Ana is typing…" / "Ana and Bo are typing…" / "3 people are typing…" */
+declare function formatTypists(names: readonly string[]): string | null;
+declare function participantNames(participants: readonly UserSummary[], excluding: UserId): readonly string[];
+/** "Active now" / "Active 5m ago" — presence, said honestly. */
+declare function formatLastSeen(lastSeenMs: number | null, now?: number): string;
+
+/**
+ * THE INGRESS BOUNDARY — where a database row becomes a domain object.
+ *
+ * Everything crossing this line is validated, because the alternative is a
+ * screen that lies. A conversation row whose `participants` aggregate came back
+ * as a string instead of an array used to render an inbox entry named
+ * `undefined` with a working click target; refusing the row here turns a silent
+ * wrong screen into a loud, remediable error (nothing fails silently).
+ *
+ * The rules:
+ * - A missing REQUIRED field is a refusal, never a `?? ""` that renders blank.
+ * - A missing OPTIONAL field is a null, never an invented default.
+ * - `metadata` / `action_data` are host-and-DB-owned JSON: typed over `unknown`
+ *   and narrowed by shape, never cast (the data 0.2.1 `Json = unknown` lesson).
+ */
+
+declare function projectUserSummary(row: Record<string, unknown>): UserSummary;
+declare function projectMessageAction(value: unknown): MessageAction | null;
+declare function projectMessage(row: Record<string, unknown>, fallbackOrganizationId: OrganizationId): Message;
+declare function projectParticipantRole(value: unknown): ParticipantRole;
+declare function projectConversationSummary(row: Record<string, unknown>, viewerId: UserId, fallbackOrganizationId: OrganizationId): ConversationSummary;
+
+/**
+ * MATRX REFERENCES — a message can name a platform entity, and everything it
+ * names must OPEN. No dead ends.
+ *
+ * Two transports, both supported because both already exist in the wild:
+ *
+ * 1. **Structured**, in `metadata.references` — what this package writes.
+ * 2. **Fenced**, as a ```matrx block in the content — the platform's
+ *    reference-fence protocol, which arrives from senders outside messaging.
+ *
+ * Two failures this module exists to prevent:
+ *
+ * - **A raw fence rendered as a code block.** The reader sees JSON. `splitText`
+ *   is what lets the renderer draw a card instead.
+ * - **A fence leaking into a preview.** The inbox row and the desktop
+ *   notification are plain text; pasting the JSON there is the same defect one
+ *   layer down. `summarizeText` is the one collapse, used by both.
+ */
+
+type TextSegment = {
+    readonly type: "text";
+    readonly value: string;
+} | {
+    readonly type: "reference";
+    readonly reference: MatrxReference;
+};
+/** Every reference a message carries, from both transports, de-duplicated. */
+declare function extractReferences(content: string, structured?: readonly MatrxReference[]): readonly MatrxReference[];
+/**
+ * Split content into renderable segments. The renderer draws text for `text`
+ * and a live card for `reference`; a fence therefore CANNOT reach the screen as
+ * a code block.
+ */
+declare function splitText(content: string): readonly TextSegment[];
+/**
+ * ONE plain-text collapse, used by the inbox preview AND the notification body.
+ * A fence becomes its human label; it never reaches either as raw JSON.
+ */
+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, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationCursor, type ConversationId, type ConversationSummary, type ConversationThread, type ConversationType, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, type SchemaLike, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, avatarPaletteIndex, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, getInitials, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText };