@ai-matrx/messaging 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog — `@ai-matrx/messaging`
+
+## 0.1.0 — 2026-08-31
+
+First release. Enterprise, AI-native in-app messaging for Matrx clients, built to the ratified
+work order at `common-docs/systems/communications/messaging/HANDOFF.md`, on top of
+`@ai-matrx/realtime` (D5: zero hand-rolled `.channel(` in this package).
+
+### Added
+
+- **Core (`@ai-matrx/messaging`)** — framework-free; the only runtime dependencies are
+  `@ai-matrx/realtime` and `@ai-matrx/agents`.
+  - `createMessagingRepository` — THE data contract, and the only file in the package holding a
+    table or RPC name. Atomic direct-conversation creation through
+    `dm_get_or_create_direct_conversation` (read-then-insert is structurally absent), keyset
+    pagination terminated by a unique column, explicit `organization_id` on every write, a single
+    session retry that never touches a permission denial, and an in-flight-deduped profile cache.
+  - `createMessagingStore` — the one door every incoming message uses. Collapses the optimistic
+    bubble onto its confirmed row by client key, drops out-of-order updates, orders by
+    `(created_at, id)`, and forces the active conversation's unread count to zero.
+  - `createOutbox` — a message you typed is never lost: persisted before the send, one
+    idempotency key across every attempt, strict order, durable across a reload, and a bounded
+    failure that keeps the message with a reason and a retry door.
+  - `createMessagingEngine` — channel wiring with a backfill door on every recovery path,
+    optimistic send, read receipts, and conversation lifecycle.
+  - `createActionRegistry` — actionable messages with idempotence enforced by the registry, and
+    forward compatibility on unknown kinds and versions. The seam `@ai-matrx/meet` extends.
+  - `createMessagingAi` — catch me up, summarize, extract action items, draft a reply, executed
+    through the platform's agent system. Machine content travels as named variables, never
+    `user_input`.
+  - Matrx references (`splitText`, `summarizeText`, `extractReferences`, `composeFence`),
+    effective-actor resolution, the ingress-boundary projection layer, the typed error
+    classification, formatting/grouping helpers, and the two channel namespaces.
+- **React (`@ai-matrx/messaging/react`)** — the complete product, not a kernel:
+  `MessagingProvider`, `MessagingInbox`, `ConversationList`, `ConversationView`, `Composer`,
+  `MessageBubble`, `MessageActionChips`, the parts (`Avatar`, `ReferenceCard`, `DeliveryTick`,
+  skeletons, empty states), fifteen inlined SVG icons (C19 — no icon-library dependency), and the
+  hooks for hosts that compose their own page layout.
+- **Styling** — `@ai-matrx/messaging/styles.css` (structural: layout, motion, `100dvh`, safe-area
+  insets, 44px touch targets, a 16px composer minimum so iOS Safari does not zoom on focus) and
+  `@ai-matrx/messaging/tokens.css` (a complete default palette, light and dark, host-overridable).
+  Hardcoded colors in the structural sheet fail the release gate.
+- 113 tests, each named for the failure it prevents, plus a packed-tarball canary that exercises
+  ESM + CJS, both entries, the `"use client"` banner per chunk, the `globalThis` slots across
+  module graphs, the stylesheets' presence and export-map resolution, and the stability of the
+  table/RPC names.
+
+### Deliberately not in this release
+
+Recorded in `FEATURE.md` § Deliberate omissions and in the work order, not quietly dropped:
+reactions, per-message read receipts, edit history and pinning (all need a DB change — the
+canonical schema has no columns for them); attachment UPLOAD (reads and durable-ref rendering
+ship; the upload path belongs on `@ai-matrx/data/files`); a separate thread surface; moderation
+affordances; and a `/native` entry (C25 — built at the first real Expo consumer, inside this
+package).
+
+### Consumer action
+
+None required — this is a first release with no existing consumers.
+
+Adopting it in a repo that has its own messaging feature (matrx-frontend is the intended first
+consumer):
+
+- Wrap the messaging route in `<MessagingProvider client={supabase} userId={…}
+  organizationId={…}>` and render `<MessagingInbox />`. Import `tokens.css` then `styles.css`.
+- **Delete, do not wrap** (C9): the host's own realtime subscription and channel bookkeeping, its
+  message dedup and echo suppression, its optimistic-send reconciliation, its typing and presence
+  timers, its conversation-list cache and in-flight dedup, and its `find-then-insert`
+  direct-conversation path. A second copy beside the package is the named failure.
+- Re-register the host's actionable-message kinds as `ActionHandler`s on the provider. Each
+  handler must re-resolve its authorizing row server-side; the payload is the request, never the
+  permission.
+- Wire `onOpenReference` to the app's router, or reference cards render inert-but-labeled.
+- Pass `transport` + `agents` to light up the AI actions; without them they do not render.
+- `resolveSession` enables the single retry on a missing session — pass it, or a read during
+  sign-in reports `session-unavailable` instead of recovering.
+- This package supersedes host code that talks to `communication.dm_*` directly. Anything still
+  reading those tables outside the package should be moved onto it or deleted.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,288 @@
-# @ai-matrx/messaging
+# `@ai-matrx/messaging`
 
-Reserved for the AI Matrx real-time direct and group messaging package. This `0.0.0` release reserves the canonical package name; it does not contain an implementation yet.
+Enterprise, AI-native in-app messaging for every Matrx client: direct, group, and org-scoped
+conversations, with agents as first-class participants — delivered as a drop-in package with the
+polish of iMessage and the power of Slack.
+
+One provider, one component, under an hour to full production messaging including the AI.
+
+```bash
+pnpm add @ai-matrx/messaging
+```
+
+Built on [`@ai-matrx/realtime`](../realtime/README.md). There is **zero hand-rolled `.channel(`
+code in this package**, and there must be none in yours.
+
+---
+
+## Why this package exists
+
+Messaging is the feature everyone assumes is easy and nobody ships correctly twice. The hard
+parts are not the bubbles; they are the eight ways a message can be lost, duplicated, reverted,
+or attributed to the wrong person. Every one of those has a name in this README and a regression
+test beside it.
+
+We are deliberately **inflexible**. There is no provider abstraction, no transport adapter, no
+"bring your own store". The package does exactly what we want it to do, and that is the product.
+
+---
+
+## The doctrine
+
+### 1. A message can arrive FOUR ways. It renders once.
+
+The optimistic bubble, the insert's own response, the broadcast, and the Postgres Changes row —
+in any order. Identity is `id` **or** `clientMessageId`, and the confirmed row *collapses onto*
+the optimistic one in place.
+
+The tempting shortcut — matching on `(sender, content)` — silently merges two genuinely different
+"ok" messages into one. The client-minted idempotency key exists so identity never has to be
+guessed. It is minted once per queued message and reused by **every** send attempt, which is also
+what makes a retry safe when the previous attempt actually reached the database.
+
+### 2. Older never overwrites newer.
+
+An out-of-order UPDATE carrying an older `edited_at` than the copy already held is **dropped**.
+Without this, an edit visibly reverts itself a second later and then re-applies.
+
+The one exception is deliberate: a persisted row always supersedes an optimistic one, even when
+the optimistic timestamp reads later. That timestamp is a guess from the sending device's clock,
+and a skewed clock must not strand a bubble as permanently "sending".
+
+### 3. Reconnect means RE-READ. Realtime has no replay.
+
+Every channel this package opens declares an `onBackfill` door, and those doors re-read from the
+database — the conversation channel from its own high-water mark, so it fetches what it missed
+rather than everything. A reconnect without a re-read leaves a permanently wrong thread that
+looks perfectly healthy. That is the most expensive bug in messaging, and it is structurally
+impossible here.
+
+### 4. A message you typed is NEVER lost.
+
+The outbox persists the draft **before** the network call, not after it succeeds. Guarantees:
+
+- **Durable across a reload.** A tab closed mid-send comes back with the message still queued.
+  The default storage is `localStorage`; when it is unavailable the package falls back to memory
+  and **says so** rather than pretending to be durable.
+- **In order.** Message 2 never overtakes a retrying message 1.
+- **Bounded and honest.** Attempts back off; after the last one the entry stays in the queue,
+  marked `failed`, **with a reason** and a retry door. Never silently dropped, never retrying
+  forever.
+- **Visible.** A queued message renders as an optimistic bubble immediately. An invisible queue
+  is a lost message from the user's side.
+
+### 5. Direct conversations are created ATOMICALLY, in the database.
+
+Via `dm_get_or_create_direct_conversation`, which advisory-locks the unordered user pair. The
+banned pattern is read-then-insert: two tabs, a double-click, or two batched system
+notifications race it into two "direct" conversations for one pair, forever.
+
+### 6. Authorization is the database's. Org is explicit.
+
+RLS plus auth-checked SECURITY DEFINER RPCs. There is not one permission branch in this package —
+an RPC that says no becomes a `forbidden` error, never a client-side re-decision. And every
+conversation and message write carries an explicit `organization_id`; the package refuses the
+write rather than letting an unscoped row reach the database.
+
+### 7. A missing session is a lifecycle moment, not an error.
+
+A read that lands between sign-in and token arrival retries **once** after the host resolves a
+session, then reports `session-unavailable` as a *warning*. A permission denial is never retried —
+retrying one is how a request storm is built. (The incident: a reader mounted before the access
+token existed and the app captured **909 errors in 0.6 seconds**.) Profile and list reads also
+share one in-flight promise per key, so N concurrent readers make one request — and a failure is
+never cached, or one wobble leaves the surface broken until reload.
+
+### 8. Pagination is keyset, terminated by a unique column.
+
+`(created_at, id)`, never `created_at` alone — which duplicates or skips rows whenever two share a
+millisecond, i.e. every page in a large org. The package also asks for one row more than the page
+so `hasMore` is a fact rather than a guess from "we got a full page".
+
+### 9. An agent never wears a colleague's face.
+
+`sender_id` is the audit principal and never changes. When an agent acted through a human's
+session, the *rendered* author is the agent — and it names the human it acted for. An unnamed
+agent is labeled "Agent"; falling back to the human's name and avatar would put an automated
+message under a real person's byline.
+
+### 10. Everything a message names must OPEN.
+
+Matrx references arrive two ways — structured in `metadata.references`, or as a ` ```matrx `
+fence in the content. Both become live cards. A fence **never** reaches the reader as a code
+block of JSON, and never reaches an inbox preview or a desktop notification as raw JSON either;
+one collapse function serves both. A reference with no resolvable identity is dropped rather than
+drawn as a card that cannot open.
+
+### 11. An action this build cannot honor renders NOTHING.
+
+Actionable messages go through a registry, not a `switch`. An unknown `kind` — or a known kind at
+an unknown `version` — renders no chips and executes nothing, which is what lets a new sender ship
+before every reader has caught up. Idempotence is enforced *by the registry*: concurrent
+executions of `(kind, messageId, actorId)` share one call, 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 row before it writes.
+
+### 12. Nothing structured rides `user_input`.
+
+`user_input` is what a human typed. Transcripts, rosters, and cutoffs travel as named
+**variables**. The server stores and frames `user_input` as the turn's human utterance, so
+smuggling a transcript through it silently corrupts every conversation it touches. The one
+`user_input` this package ever sends is the instruction a person typed into "draft a reply".
+
+---
+
+## Using it
+
+### The one-hour integration
+
+```tsx
+import { MessagingProvider, MessagingInbox } from "@ai-matrx/messaging/react";
+import "@ai-matrx/messaging/tokens.css"; // defaults — override with your brand
+import "@ai-matrx/messaging/styles.css"; // structural, required
+
+export default function MessagesPage() {
+  return (
+    <MessagingProvider
+      client={supabase}
+      userId={user.id}
+      organizationId={org.id}
+    >
+      <MessagingInbox />
+    </MessagingProvider>
+  );
+}
+```
+
+That is realtime, presence, typing, optimistic send, the offline outbox, references, actionable
+messages, keyset pagination, and the whole polished UI. There is nothing else to wire.
+
+### Adding the AI
+
+```tsx
+<MessagingProvider
+  client={supabase}
+  userId={user.id}
+  organizationId={org.id}
+  transport={matrxTransport}          // from @ai-matrx/agents/matrx
+  agents={{
+    catchUp: "…", summarize: "…", actionItems: "…", draftReply: "…",
+  }}
+>
+```
+
+Agent definitions live in the **database**, never in this package — the id is the only part a
+host injects. A capability with no agent id **does not render at all**; it is never a dead button
+that fails when pressed.
+
+### Making references open
+
+```tsx
+<MessagingProvider … onOpenReference={(ref) => router.push(`/${ref.entityType}/${ref.entityId}`)}>
+```
+
+Omit it and reference cards render as labeled, non-interactive cards with a title explaining why —
+honest, never a button that does nothing.
+
+### Registering an actionable message kind
+
+```tsx
+<MessagingProvider … actions={[{
+  kind: "access_request",
+  versions: [1],
+  choices: () => [
+    { id: "approve", label: "Approve", tone: "primary" },
+    { id: "decline", label: "Decline", tone: "danger" },
+  ],
+  execute: async (payload, ctx) => {
+    // Re-resolve the authorized request row here. The payload is the REQUEST,
+    // never the permission.
+    const outcome = await decideAccessRequest(payload.requestId, ctx.choice);
+    return { kind: "access_request", messageId: ctx.messageId, actorId: ctx.actorId,
+             outcome: outcome.alreadyAnswered ? "already" : "applied",
+             label: outcome.alreadyAnswered ? "Already answered" : "Approved",
+             settledAt: new Date().toISOString() };
+  },
+}]}>
+```
+
+This is the seam `@ai-matrx/meet` uses: a call invitation is just a message with a structured
+payload.
+
+### Theming
+
+Structural CSS ships in the package; the token **contract** is enforced; token **values** are
+yours. Import `tokens.css` for a complete working default, then override the names you care
+about:
+
+```css
+:root {
+  --mx-msg-accent: #7c3aed;
+  --mx-msg-bubble-mine-bg: var(--mx-msg-accent);
+}
+```
+
+Hardcoded colors inside package components are banned, and the tarball gate fails the build if a
+hex value appears in `styles.css`. Dark values are defined for both `prefers-color-scheme` and an
+explicit `[data-theme="dark"]`, so a host toggle wins in either direction.
+
+### Composing your own layout
+
+`<MessagingInbox />` is the product. If you want the list in a sidebar and the thread on a route:
+
+```tsx
+<ConversationList onSelect={(id) => router.push(`/messages/${id}`)} />
+<ConversationView conversationId={id} />
+```
+
+Hooks — `useConversations`, `useConversation`, `useComposer`, `useTypists`, `useOnlineUserIds`,
+`useMessagingAi`, `useMessageAction` — are exported for hosts that compose their own pages. They
+are **not** an invitation to rebuild the product out of parts.
+
+### Outside React
+
+The default entry is framework-free — safe from Redux middleware, a service module, a worker, or
+a node test:
+
+```ts
+import { createMessagingEngine, createMessagingRepository } from "@ai-matrx/messaging";
+```
+
+---
+
+## The database contract
+
+One canonical schema, in Matrx Main, under the platform's DB conventions:
+
+| | |
+|---|---|
+| Schema | `communication` (never `public`) |
+| Tables | `dm_conversations`, `dm_conversation_participants`, `dm_messages` |
+| RPCs | `dm_get_or_create_direct_conversation`, `get_dm_conversations_with_details`, `get_dm_user_info`, `get_dm_unread_count`, `is_dm_participant` |
+
+Every name lives in exactly one file — `src/core/repository.ts` — and the packed-tarball canary
+asserts them, so a silent rename fails the build instead of the app.
+
+`matrx-dm` grew a parallel schema in its own project (`public.conversations` / `messages` /
+`message_reactions`). Per the work order's R8 exactly one canonical schema survives, and it is
+this one — the one with explicit org, versioning, soft deletes, and auth-checked RPCs.
+
+---
+
+## Entry points
+
+| Entry | Contents | `"use client"` |
+|---|---|---|
+| `@ai-matrx/messaging` | Framework-free core: repository, store, outbox, engine, action registry, references, AI, formatting | **No** — a stamped pure module becomes a client reference inside an RSC |
+| `@ai-matrx/messaging/react` | Provider, hooks, and the complete product UI. Re-exports the core, so a React app needs one specifier | Yes |
+| `@ai-matrx/messaging/styles.css` | Structural CSS. Required | — |
+| `@ai-matrx/messaging/tokens.css` | Default token values. Import, then override | — |
+
+There is deliberately **no `/native` entry**. Per C25, platform bindings are built at the first
+real consumer and always inside the package; a React Native UI that no Expo app exercises is
+untested theory that rots. The core is already platform-agnostic (it is proven under a `node`
+test environment with no DOM shim), so `/native` is a UI layer away when the mobile app adopts it.
+
+## License
+
+MIT.