# Chatpack - single-fetch guide for AI builders & coding agents

> Chatpack (npm: `@chatpack/core`) is an open-source TypeScript chat backend:
> 1:1 and group conversations, messages, permissions, read-state, and
> real-time SSE.
> **Part 1 is the integration guide** - read it before generating any code
> that uses Chatpack. Part 2 covers writing a custom storage adapter (only
> needed when the official adapters don't fit).
>
> Humans: the prose quickstart lives in the README; this file trades prose
> for completeness.

Packages (all on npm):

| Package                    | What it is                                             |
| -------------------------- | ------------------------------------------------------ |
| `@chatpack/core`           | The engine: API, HTTP handler, SSE, plugins            |
| `@chatpack/adapter-memory` | In-memory storage - demos/tests, single process only   |
| `@chatpack/adapter-drizzle`| Postgres storage via Drizzle - production              |
| `@chatpack/adapter-prisma` | Postgres storage via Prisma ORM 7 - server-only      |
| `@chatpack/adapter-mysql`  | MySQL 8 storage via Drizzle/mysql2 - server-side       |
| `@chatpack/adapter-turso`  | Turso/libSQL storage via Drizzle                      |
| `@chatpack/adapter-sqlite` | SQLite storage via Drizzle - local/single node         |
| `@chatpack/adapter-supabase` | Server-side Supabase/Postgres storage                 |
| `@chatpack/next`           | Next.js App Router mount helper (`toNextRouteHandlers`)|
| `@chatpack/client`         | Framework-agnostic REST + SSE client (+ React hooks)   |
| `@chatpack/cli`            | Setup CLI: wires an existing app, or generates a starter|
| `@chatpack/transport-redis`| Redis pub/sub transport - multi-node SSE fan-out       |
| `@chatpack/file`           | Filepack-backed message attachments (uploads, media)   |

Current releases include direct and group conversations, text messages,
permissions, read state and unread counts, SSE with reconnect gap-fill,
memory, Drizzle/Turso, and Supabase adapters, Redis event fan-out, typing/presence/receipts, reactions,
quote-replies, participant-scoped search, `afterMessageMutation`, the browser
client with React hooks and polling fallback, `@chatpack/cli init` (wires an
existing app, or generates a Next.js/Hono/Express starter),
Filepack-backed file attachments via `@chatpack/file`, invite links with join
requests, public channels (a browsable directory of public groups), mentions,
and message forwarding.

`@chatpack/adapter-prisma` supports Prisma ORM 7. Install it with
`@prisma/client`, `@prisma/adapter-pg`, and `pg`. Copy its supplied Prisma
models and migration into your application, run Prisma format/validate,
migrate deploy, and generate. Create Prisma client in server code and pass it
to `prismaAdapter(client)`. Adapter does not read credentials, own client
lifecycle, or bundle generated client. Verified provider: PostgreSQL 16 with
Prisma 7.10.0. Prisma 8, MySQL, SQLite, MongoDB, CockroachDB, SQL Server,
Accelerate, edge, and serverless-driver combinations are unverified.

True message threads, push notification providers, and reusable React UI
components have not shipped. Multi-node presence is available with
`redisPresenceStore()` and the Redis transport.

## File attachments (`@chatpack/file`)

Attachments are an optional plugin backed by
[Filepack](https://github.com/chddaniel/filepack) (npm `@filepack/*`) -
Chatpack never stores bytes, signed URLs, or object keys. A message carries
only stable references in its metadata:

```ts
{ filepack: { version: 1, attachments: [{ id, name, contentType, size }] } }
```

Server (mounts Filepack routes below the Chatpack handler, default
`/api/chat/files`, and validates every referenced file before a message
persists):

```ts
import { createFileAttachmentPlugin } from "@chatpack/file";

const chat = chatpack({
  storage, auth,
  plugins: [createFileAttachmentPlugin({
    filepack,                                  // your FilepackApi instance
    authorizeUpload: ({ actor, conversationId }) =>
      isParticipant(actor.id, conversationId), // host policy - REQUIRED
  })],
});
```

Browser: `createChatpackFileClient` from `@chatpack/file/client` wraps
`@filepack/client` for uploads, resume, and inline-vs-attachment delivery.

```ts
import { createChatpackFileClient } from "@chatpack/file/client";

const files = createChatpackFileClient({
  basePath: "/api/chat/files",
  // REQUIRED workaround for @filepack/client <= 0.1.1 in the browser: it
  // stores globalThis.fetch unbound and calls it as a method, which Chrome's
  // brand check rejects ("Illegal invocation"). The error surfaces as a
  // mislabeled CLIENT_NETWORK_ERROR with no HTTP request sent. Passing fetch
  // as an argument fixes every upload.
  controlFetch: (input, init) => fetch(input, init),
});
```

Rules:

- Every attachment reference is validated on send AND edit, before
  persistence: the file must be ready, bound to that conversation (Filepack
  route metadata `conversationId`), authorized, and matching its reference
  (`name`/`contentType`/`size`). Otherwise → `422 MESSAGE_REJECTED`.
- File reads (`GET files/files?conversationId=`, metadata, downloads) require
  the caller to be a Chatpack participant of that conversation AND the file
  to belong to it; everything else is `404 FILE_UNAVAILABLE`.
- Exact Filepack byte-transfer routes (`PUT .../content`, versioned
  `GET files/downloads/v1.*`) authenticate by Filepack's own short-lived
  capability instead of the app session - required so `<img>`/`<video>` tags
  and upload XHRs work without auth headers. All control routes stay behind
  normal Chatpack auth.
- Deleting a message never deletes its files; configure Filepack lifecycle
  cleanup separately. `DELETE` of a file through the chat mount is not
  forwarded.
- **There are no attachment-only messages.** `body` must be a non-empty
  string after trimming on both send and edit, or you get
  `400 INVALID_INPUT` - attachments live in metadata and never substitute for
  it. An image-only UI must synthesize a body (the file name, or a single
  space is not enough since it is trimmed).
- Mount `PUT` too:
  `export const { GET, POST, PATCH, DELETE, PUT } = chat.handler()`.

## Chatpack CLI

`npx @chatpack/cli init` has **two modes, chosen by whether `package.json`
exists in the target directory** - you do not select the mode with a flag.

**Existing project** (a `package.json` is present): the CLI inspects the
project and adds focused wiring - one `chatpack()` instance plus the framework
mount. Supports Next.js App Router, Hono, Express, and `web` (a plain
`Request → Response` handler for everything else). It asks before changing
files, supports `--dry-run`, never overwrites a file you own without saying so,
and never runs database migrations or guesses an auth provider's API.

```sh
npx @chatpack/cli init --framework next --adapter memory --package-manager pnpm --yes
```

**Starter** (no `package.json`): the CLI generates a whole application. Only
Git metadata, `.gitignore`, README/LICENSE and editor/CI/OS clutter may exist
beforehand; anything else is refused rather than merged into. README and LICENSE
files are preserved (a generated readme lands as `CHATPACK_SETUP.md` instead).

```sh
npx @chatpack/cli init --framework next --auth-provider better-auth --package-manager pnpm --yes
```

- `--framework next` - full chat app: application-owned UI, Neon Postgres +
  Drizzle, and one of `--auth-provider better-auth | authjs | auth0`. It covers
  the whole library rather than a demo subset - directs, groups and public
  channels, reactions, quote-replies, edits, soft deletes, mentions, forwarding,
  search, attachments, typing/presence/receipts, unread counts, roles and member
  management, invite links, join requests, mute, blocks and the moderation queue
  - across four pages: `/`, `/channels`, `/invite/[code]`, `/moderation`.
- `--framework hono` / `express` - backend-only API starters. No auth provider:
  their auth hook returns `null` on purpose, so **every request answers 401
  until you wire it to your own session**. That is fail-closed by design.
- `--framework web` is existing-project only; starters need a real runtime.
- Starters require Drizzle storage; `--adapter memory` is refused because a
  starter is meant to be production-shaped.

Starter templates are reviewed assets published inside the CLI tarball. They
pin `@chatpack/*` versions that are known to work together (core and
`adapter-drizzle` must move as a pair - core's required adapter contract grows
across minors). They use the transaction-capable Neon **WebSocket `Pool`** with
`drizzle-orm/neon-serverless`; do not swap in the Neon HTTP driver, because
Chatpack's message-ordering writes need transactions.

Three starter features stay **off until an environment variable turns them on**,
so a fresh clone runs with no extra services. All three are listed, commented
out, in the generated `.env.example`:

| Variable                                    | Unset                                                                                                      | Set                                                                                                                              |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `MODERATOR_EMAILS` / `MODERATOR_USER_IDS`   | nobody passes `moderation.canModerate`, so the queue answers `NOT_MODERATOR` (reporting and blocking still work) | those users may review reports and ban                                                                                      |
| `S3_BUCKET` (+ `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT`) | attachments are written to `.chatpack-files` on local disk                      | attachments go to any S3-compatible bucket - required on serverless, where the filesystem does not outlive one invocation |
| `REDIS_URL`                                 | in-process fan-out, correct for exactly one server process                                                  | `@chatpack/transport-redis` fan-out across nodes (presence stays single-node either way - ADR 0008)                              |

Generation stops at files and dependencies. It does **not** provision a Neon
database, write secrets, run migrations, or deploy - copy `.env.example` to
`.env.local` (`.env` for hono/express), fill it in, then run the generated
`db:generate` and `db:migrate` scripts.

Either filename works, because the starter's own `src/lib/env.ts` reads
`.env.local` then `.env` (only `.env` under `NODE_ENV=production`) before it
validates anything, and real environment variables win over both. That belongs in
the module that validates, not in the entrypoint: `next dev` loads `.env*` for the
Next starter, but the hono and express starters run under `tsx`, which - like
`node` itself - reads no env file, and ESM evaluates imports before the importing
module's own statements, so a `dotenv` call in `src/index.ts` would run after
`env.ts` had already thrown.

`db:migrate` is `drizzle-kit migrate` followed by `scripts/filepack-migrate.ts`.
Filepack's four attachment tables are **not** in the starter's
`src/db/schema.ts`: drizzle-kit loads that file through CJS,
`@filepack/adapter-drizzle` is ESM-only, and the failure mode is a printed stack
trace plus exit `0` - a `db:generate` that looks fine and emits nothing. Filepack
publishes idempotent DDL (`migrationStatements`) for hosts to apply, so that
script applies it and `db:filepack` runs it alone. Consequently the generated
`src/lib/filepack.ts` gives Filepack its own Drizzle instance over the shared
`pool`, built from the `filepackRecordsSchema` the adapter exports, because its
record store is typed against exactly that schema and the application's `db` is
not it. An adapter author copying this pattern for another ESM-only Drizzle
package should do the same - do not import it from a drizzle-kit schema file.

Whatever the mode, the generated server keeps one `chatpack()` instance, uses an
official adapter, and gets its user id from an application-owned auth resolver
returning `{ id }` or `null`. A resolver the CLI could not wire is generated as
a visible placeholder returning `null`, so it must be replaced before use.

# Part 1 - Integrating Chatpack

## First-party client

For browser applications, install `@chatpack/client`. For React, import the
wrapper from `@chatpack/client/react`; for optional realtime counterparts,
import `typingClient`, `presenceClient`, and `receiptsClient` from
`@chatpack/client/plugins`:

```ts
import { createChatClient } from "@chatpack/client/react";
import { typingClient, presenceClient, receiptsClient } from "@chatpack/client/plugins";

export const chatClient = createChatClient({
  baseURL: "http://localhost:3000",
  credentials: "include",
  userId: currentUser.id, // optional cache hint, NOT auth - see below
  plugins: [typingClient(), presenceClient(), receiptsClient()],
});

const result = await chatClient.messages.send({ conversationId, body: "hello" });
if (result.error !== null) console.error(result.error.code);

// Quote-reply, then react. Both echo the updated message into the cache.
await chatClient.messages.send({ conversationId, body: "agreed", replyToMessageId: result.data.id });
await chatClient.messages.react({ messageId: result.data.id, emoji: "👍" });
await chatClient.messages.unreact({ messageId: result.data.id, emoji: "👍" });

// Mention by id (your UI renders the @name), and forward into another thread.
await chatClient.messages.send({ conversationId, body: "@bob take a look", mentions: ["bob"] });
await chatClient.messages.forward({ messageId: result.data.id, toConversationId: otherId });
```

`messages.forward` names the destination `toConversationId` because the source
is `messageId`; it resolves with the **new** message in the target, and the cache
applies it there - the source conversation is untouched, exactly like the server.

Search every conversation visible to the signed-in participant with
`messages.search({ query, limit, cursor })`. React applications can use
`useMessageSearch({ query, limit })`, which adds `loadMore()` and `refetch()`:

```ts
const page = await chatClient.messages.search({ query: "release ready", limit: 20 });
const search = chatClient.useMessageSearch({ query: "release ready", limit: 20 });
```

Search is case-insensitive, whole-token, AND-matched, relevance-ranked, and
cursor-paginated. Core and the adapter own participant scope, matching, ranking,
tombstone exclusion, and cursor encoding. Adapters without the capability
return a structured 501 `SEARCH_UNSUPPORTED` result. An empty hook query stays
idle without a request; the imperative method still returns `INVALID_INPUT`.

Search pages are snapshots. New messages are not inserted or re-ranked. Edits
and tombstones patch loaded hits in place, and losing conversation access
removes its hits. Call `refetch()` to recompute matches and rank. The hook sends
a request whenever its query changes, so debounce text input before passing it;
the client retains at most ten normalized query entries per instance.

Client methods return `{ data, error }`; expected HTTP and network failures do
not throw. The client never owns authentication, reads cookies, manages
sessions, or places bearer tokens in the SSE URL. Native `EventSource` uses
browser cookies and handles `Last-Event-ID` reconnects. One client instance
owns one lazy stream and a small in-memory cache. The React adapter uses
`useSyncExternalStore` and has no state-library dependency.

Realtime events update the cache automatically - both the open conversation's
messages AND the conversations list, which reorders most-recently-active-first
and bumps `unreadCount` exactly like a refetch would. A conversation created
after the list loaded is fetched once and prepended. `conversations.markRead`
clears the viewer's `unreadCount` locally on success. **Do not refetch the list
on every `message.created` event** - that workaround is obsolete as of client
0.2.0.

The optional `userId` option is a cache hint only, never authentication: it
keeps the viewer's own messages from counting as unread. Omit it and the client
infers the id from the first message this client sends. Only `message.created`
reorders the list (edits and deletes do not change server-side activity
order), and redelivered events never double-count.

`messages.react` / `messages.unreact` replace one cached message's `reactions`
and touch nothing else - no reorder, no unread bump, no seq baseline change -
so a reaction event's payload can never clobber a body or `replyTo` the cache
already holds. Reactions on a message outside the loaded page are dropped
rather than spliced in.

**Polling fallback (client 0.4.0+).** Where SSE cannot work - serverless
function timeouts, buffering proxies, React Native with no `EventSource` - the
client keeps data live by refetching on an interval instead. On by default;
**never hand-roll an interval yourself.**

```ts
createChatClient({
  realtime: { mode: "auto", intervalMs: 5000 }, // "auto" (default) | "sse" | "poll"
});
```

- `auto` - open the stream; poll only if it cannot open or drops, and stop
  polling the moment it reopens. A serverless deploy works unconfigured.
- `sse` - stream only, never poll (pre-0.4 behaviour).
- `poll` - never attempt a stream; skips the failed attempt on a platform you
  know cannot hold one.
- `intervalMs` defaults to `5000`, floor `1000`.

`useRealtimeStatus()` reports **`"polling"`** (a fifth status alongside `idle` /
`connecting` / `open` / `closed`), keeping the error that caused the fallback so
a "reconnecting…" hint still works, and clearing it on recovery. Treat
`"polling"` as connected-but-degraded, not as an error.

Each tick refetches the conversations list plus the **3 most recently used**
conversations - only surfaces already loaded, at the same `limit` you last
requested. Ticks never overlap, a hidden tab does not poll, and a failed tick
leaves the last good data on screen without touching
`isPending`/`isRefetching`.

**Typing, presence and receipts do not work while polling.** They are ephemeral
and never stored (nothing to poll for), so `useTyping()` stays `null`. Design
the UI so their absence degrades quietly.

Also available: `realtime.pollNow()` for a manual "check for new messages".

**The client wraps invites, join requests, and channels.** Use
`chatClient.invites.*`, `chatClient.joinRequests.*`, and `chatClient.channels.*`
for the ten routes. `invites.accept` and `channels.join` return a
`status`-discriminated result: `"joined"` carries a conversation and
`"pending"` carries a join request. The client preserves `INVITE_NOT_FOUND`
(404), `INVITE_EXPIRED` (410), `JOIN_REQUEST_NOT_FOUND` (404), and optional
capability errors `INVITES_UNSUPPORTED` / `CHANNELS_UNSUPPORTED` (501).
Arrivals still flow through the normal `participant.added` event, so the cache
stays correct.

**The client also wraps moderation.** `chatClient.moderation.*` covers the
self-service actions (`blockUser`, `unblockUser`, `listBlockedUsers`,
`muteConversation`, `unmuteConversation`, `listMutedConversations`, `report`)
and the moderator ones (`listReports`, `getReport`, `updateReport`, `listBans`,
`banUser`, `unbanUser`). Moderator calls return `NOT_MODERATOR` (403) unless
the server's `canModerate` says otherwise, and every call returns
`MODERATION_UNSUPPORTED` (501) on an adapter without the capability.

## Hard rules (violating any of these is the #1 cause of broken integrations)

1. **Mount the ONE handler on a catch-all route. Never hand-write your own
   message/stream/API routes.** `chat.handler()` already serves every route
   in the table below - conversations, messages, read-state, typing,
   presence, AND the SSE stream - under one `basePath` (default `/api/chat`).
   Writing your own `/api/messages` or `/api/chat/stream` route breaks the
   wiring (split state, missed events) and is never needed.
2. **These are the only server-side methods** on `chat.api`:
   `getOrCreateConversation`, `createGroupConversation`, `listConversations`,
   `getConversation`, `updateConversation`, `addParticipants`,
   `removeParticipant`, `setParticipantRole`,
   `sendMessage`, `listMessages`, `editMessage`, `deleteMessage`,
   `forwardMessage` (destination is `toConversationId`, not `conversationId` -
   only the HTTP body calls it `conversationId`, because the route already
   names the source),
   `searchMessages`, `addReaction`, `removeReaction`, `markRead`, `listMessagesAfter`,
   `createInvite`, `listInvites`, `revokeInvite`, `getInvitePreview`,
   `acceptInvite`, `requestToJoin`, `listJoinRequests`, `resolveJoinRequest`,
   `listPublicConversations`, `joinConversation`.
   There is **no** `chat.api.getOrCreateDirectConversation`
   (that name is a low-level *storage adapter* method - never call the
   adapter directly). Do not invent methods; if a name is not in this list,
   it does not exist.
3. **Conversation ids are server-generated opaque strings** (e.g. `conv_1`).
   Get one from `POST /conversations` / `chat.api.getOrCreateConversation`
   with `{ otherUserId }` for a DM, or `POST /conversations/group` /
   `chat.api.createGroupConversation` for a group. **Never construct ids like
   `"alice-bob"`** - the sorted pair key is internal to Chatpack.
4. **DMs and groups are the same `Conversation` shape, told apart by `type`.**
   `type: "direct"` has exactly 2 participants, a `pairKey`, and no `name`;
   `type: "group"` has 1..256 participants, `pairKey: null`, and an optional
   `name`. **DMs are find-or-create; groups never are** - calling
   `createGroupConversation` twice with the same members makes two groups, so
   store the returned id. Group-only calls (add/remove/role/rename) on a DM
   are 409 `NOT_GROUP_CONVERSATION`.
5. **Create exactly ONE `chatpack()` instance** in one module and import it
   everywhere. Under dev-server HMR (Vite, Next dev, TanStack Start), guard
   it with `globalThis` so re-evaluation doesn't wipe in-memory state:
   ```ts
   import { chatpack, type ChatpackInstance } from "@chatpack/core";
   const g = globalThis as typeof globalThis & { __chatpack__?: ChatpackInstance };
   export const chat = (g.__chatpack__ ??= chatpack({ storage, auth }));
   ```
6. **The `auth` hook must return `{ id: string }` (non-empty) or `null`.**
   A bare string or `{ userId: ... }` is treated as unauthenticated → 401 on
   every request. The hook receives the raw WHATWG `Request` - there is no
   `request.cookies`; parse `request.headers.get("cookie")` yourself.
7. **Browser auth must be cookie-based**, because the live stream is
   `EventSource`, which cannot send custom headers. Whenever the app renders
   inside a cross-site iframe - every AI-builder preview pane (Lovable, v0,
   Bolt, Shipper, Replit, ...) works this way - the cookie must be
   `SameSite=None; Secure` - see the demo-auth recipe below. This is the
   #1 cause of 401s in embedded previews.

## 60-second wiring (framework-agnostic core)

```ts
// chat.server.ts - the whole backend setup
import { chatpack, type ChatpackInstance } from "@chatpack/core";
import { typing, presence, receipts } from "@chatpack/core/plugins";
import { memoryAdapter } from "@chatpack/adapter-memory";

function demoAuth(request: Request) {
  // Demo auth: one cookie naming the user. Swap for your auth library later.
  const cookie = request.headers.get("cookie") ?? "";
  const id = /(?:^|;\s*)demo_user=([^;]+)/.exec(cookie)?.[1] ?? null;
  return id ? { id: decodeURIComponent(id) } : null;
}

const g = globalThis as typeof globalThis & { __chatpack__?: ChatpackInstance };
export const chat = (g.__chatpack__ ??= chatpack({
  storage: memoryAdapter(),                    // demo; Postgres for production
  plugins: [typing(), presence(), receipts()], // opt-in real-time trio
  auth: demoAuth,
}));
export const chatHandler = chat.handler();     // serves everything at /api/chat
```

Then mount `chatHandler` on a catch-all route (per-framework recipes below),
and the frontend talks plain HTTP + one `EventSource`:

```ts
// 1. sign in (demo): set the cookie - iframe-proof attributes, see below
document.cookie = "demo_user=alice; Path=/; Max-Age=86400; SameSite=None; Secure; Partitioned";

// 2. open a conversation - the SERVER generates/returns the id
const { conversation } = await fetch("/api/chat/conversations", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ otherUserId: "bob" }),
}).then((r) => r.json());

// 3. send a message - the text field is `body`
await fetch(`/api/chat/conversations/${conversation.id}/messages`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ body: "hey bob!" }),
});

// 4. live updates - ONE EventSource; reconnection + gap-fill are automatic
const events = new EventSource("/api/chat/stream");
events.addEventListener("message.created", (e) => {
  const { message } = JSON.parse((e as MessageEvent).data);
  // dedupe by message.id (delivery is at-least-once), then render
});
```

Groups use the same messages/stream routes - only creation and membership
differ (the creator becomes the group's first admin). Since client 0.5.0,
`@chatpack/client` wraps all five group mutations and subscribes to
`participant.*` / `conversation.updated`, so **use the client methods; do not
hand-roll `fetch` calls for these**:

```ts
// Create a group. This is NOT find-or-create - every call makes a new group.
// You become its first admin. (conversations.create stays DM-only.)
const group = await chatClient.conversations.createGroup({
  name: "Launch",
  userIds: ["bob", "carol"],
});

// Add members (admin only; already-present ids are no-ops).
await chatClient.conversations.addParticipants({
  conversationId: group.data.id,
  userIds: ["dave"],
});

// Rename, or clear the title with name: null (admin only).
await chatClient.conversations.update({ conversationId: group.data.id, name: "Launch v2" });

// Promote or demote (admin only).
await chatClient.conversations.setParticipantRole({
  conversationId: group.data.id,
  userId: "bob",
  role: "admin",
});

// Remove a member (admin), or LEAVE by passing your own id (no admin needed).
// Removing/demoting the last admin is 409 LAST_ADMIN_REMAINING - promote a
// successor first.
await chatClient.conversations.removeParticipant({
  conversationId: group.data.id,
  userId: me,
});
```

Membership changes update the cache automatically: renames, role changes and
membership land on the conversations list and single-conversation queries;
being **added** to a group fetches and prepends it; being **removed** drops the
conversation from the cache entirely (you receive your own
`participant.removed` - it is the only signal you get). Polling clients get
the same outcomes on the next tick: snapshot changes through the list poll,
and removal via the `FORBIDDEN_READ` their next thread poll returns.
Membership events carry no `id:` line, so they are not replayed after a
reconnect - the client refetches conversations on stream reopen anyway.

Only wire the stream by hand if you are not using `@chatpack/client`:

```ts
events.addEventListener("participant.removed", (e) => {
  const { conversationId, affectedUserIds, conversation } = JSON.parse((e as MessageEvent).data);
  // You receive this even when YOU were removed - drop the conversation then.
});
```

## Demo auth that survives hosted previews and embedded iframes

This applies to ANY environment that shows the app inside a **cross-site
iframe**: AI-builder editors (Lovable's `*.lovable.app` pane inside
lovable.dev, v0's `*.vusercontent.net` inside v0.app, Bolt, Shipper, Replit,
and whatever ships next), site-builder embeds, and in-app browsers. Browsers
refuse to store or send `SameSite=Lax` cookies there, so the classic demo
cookie silently disappears and every request 401s - while the same app works
when opened as a top-level tab. Set demo cookies like this:

```ts
function signInAs(userId: string) {
  // SameSite=None + Secure  → allowed in cross-site iframes
  // Partitioned             → survives Chrome's third-party-cookie phaseout
  // localhost counts as a secure context, so this exact line works in dev too
  document.cookie =
    `demo_user=${encodeURIComponent(userId)}; Path=/; Max-Age=86400; SameSite=None; Secure; Partitioned`;
}
```

Server-side login endpoints: the same attributes on the `Set-Cookie` header
(plus `HttpOnly` for real sessions):
`Set-Cookie: session=...; Path=/; HttpOnly; Secure; SameSite=None; Partitioned`.
For production apps that never run inside an iframe, your auth library's
defaults (usually `SameSite=Lax`) are correct and more CSRF-resistant.

**Real auth (bearer tokens + SSE):** if REST calls send an `Authorization`
header (Supabase/Clerk/Firebase JWTs), keep it - write the hook to accept
either credential; the cookie is the fallback that makes `/stream` work:

```ts
auth: async (req) => {
  const bearer = req.headers.get("authorization")?.replace(/^Bearer /, "");
  if (bearer) { const u = await verifyJwt(bearer); return u ? { id: u.id } : null; }
  const session = await getSessionFromCookie(req.headers.get("cookie"));
  return session ? { id: session.userId } : null;
},
```

Do not put tokens in the `/stream` query string (they leak into logs/history).

## Mount recipes (catch-all route per framework)

**Next.js App Router** (preferred: `@chatpack/next`):

```ts
// app/api/chat/[...chatpack]/route.ts
import { toNextRouteHandlers } from "@chatpack/next";
import { chat } from "@/lib/chat.server";
export const { GET, POST, PATCH, DELETE, PUT } = toNextRouteHandlers(chat);
// (equivalent without @chatpack/next: export const { GET, POST, PATCH, DELETE, PUT } = chat.handler();)
```

**TanStack Start** (Lovable's default stack):

```ts
// src/routes/api/chat.$.ts   ← the `$` catch-all segment is required
import { createFileRoute } from "@tanstack/react-router";

async function handle({ request }: { request: Request }) {
  const { chatHandler } = await import("@/lib/chat.server");
  return chatHandler.fetch(request);
}

export const Route = createFileRoute("/api/chat/$")({
  server: { handlers: { GET: handle, POST: handle, PATCH: handle, DELETE: handle } },
});
```

**Bun / Deno / Cloudflare Workers** (handler is already Web-standard):

```ts
Bun.serve({ fetch: chatHandler.fetch });
```

**Hono / Elysia**:

```ts
app.all("/api/chat/*", (c) => chatHandler.fetch(c.req.raw));          // Hono
app.all("/api/chat/*", ({ request }) => chatHandler.fetch(request));  // Elysia
```

**Express / plain Node** (bridge Node req/res ↔ Web Request/Response -
`req.originalUrl` matters under Express mounts; streaming the body is what
makes SSE work):

```ts
app.use("/api/chat", async (req, res) => {
  const url = `http://${req.headers.host}${req.originalUrl}`;
  const chunks = [];
  for await (const c of req) chunks.push(c);
  const request = new Request(url, {
    method: req.method,
    headers: Object.entries(req.headers).flatMap(([k, v]) =>
      v === undefined ? [] : Array.isArray(v) ? v.map((x) => [k, x]) : [[k, v]],
    ),
    body: chunks.length ? new Uint8Array(Buffer.concat(chunks)) : null,
  });
  const response = await chatHandler.fetch(request);
  res.writeHead(response.status, Object.fromEntries(response.headers.entries()));
  if (response.body) {
    const reader = response.body.getReader();
    req.on("close", () => void reader.cancel().catch(() => {}));
    for (;;) {
      const { done, value } = await reader.read();
      if (done) break;
      res.write(value);
    }
  }
  res.end();
});
```

A complete plain-Node version lives in `examples/node-server` in the repo.

## HTTP routes (all served by the one handler; relative to basePath `/api/chat`)

| Method | Path                          | Request body / query                   | Response (200/201)                        |
| ------ | ----------------------------- | -------------------------------------- | ----------------------------------------- |
| POST   | `/conversations`              | `{ otherUserId, metadata? }`           | `{ conversation }` - DM, find-or-create   |
| POST   | `/conversations/group`        | `{ name?, userIds?, metadata?, visibility?, joinPolicy? }` | `{ conversation }` (201) - always new |
| GET    | `/conversations`              | `?limit=&cursor=`                      | `{ conversations, nextCursor }`           |
| GET    | `/conversations/:id`          | -                                      | `{ conversation }`                        |
| PATCH  | `/conversations/:id`          | `{ name?, visibility?, joinPolicy? }` - admin | `{ conversation }`                 |
| POST   | `/conversations/:id/participants`   | `{ userIds }` - admin            | `{ conversation }`                        |
| DELETE | `/conversations/:id/participants`   | `{ userId }` - admin, or self to leave | `{ conversation }`                  |
| PATCH  | `/conversations/:id/participants`   | `{ userId, role }` - admin       | `{ conversation }`                        |
| POST   | `/conversations/:id/invites`  | `{ expiresInSeconds?, maxUses?, requiresApproval?, metadata? }` - admin | `{ invite }` (201)  |
| GET    | `/conversations/:id/invites`  | - (admin)                              | `{ invites }`                             |
| DELETE | `/conversations/:id/invites/:code` | - (admin)                         | `{ ok: true }`                            |
| GET    | `/invites/:code`              | -                                      | `{ invite }` - preview, not the group     |
| POST   | `/invites/:code/accept`       | `{ message? }`                         | `{ status, conversation, joinRequest }`   |
| POST   | `/conversations/:id/join-requests` | `{ message? }`                    | `{ joinRequest }` (201)                   |
| GET    | `/conversations/:id/join-requests` | `?status=&limit=` - admin         | `{ joinRequests }`                        |
| PATCH  | `/conversations/:id/join-requests` | `{ userId, decision }` - admin    | `{ joinRequest, conversation }`            |
| GET    | `/channels`                   | `?limit=&cursor=`                      | `{ channels, nextCursor }` - previews      |
| POST   | `/conversations/:id/join`     | `{ message? }`                         | `{ status, conversation, joinRequest }`    |
| POST   | `/conversations/:id/messages` | `{ body, role?, replyToMessageId?, mentions?, metadata? }` | `{ message }` (201)   |
| GET    | `/conversations/:id/messages` | `?limit=&cursor=`                      | `{ messages, nextCursor }` - newest first |
| GET    | `/search/messages`            | `?q=&limit=&cursor=`                   | `{ messages, nextCursor }` - ranked       |
| POST   | `/conversations/:id/read`     | `{ messageId }`                        | `{ ok: true }`                            |
| PATCH  | `/messages/:id`               | `{ body, mentions? }`                  | `{ message }`                             |
| DELETE | `/messages/:id`               | -                                      | `{ message }` (soft-deleted)              |
| POST   | `/messages/:id/forward`       | `{ conversationId, role?, mentions?, metadata? }` | `{ message }` (201) - the copy  |
| POST   | `/messages/:id/reactions`     | `{ emoji }`                            | `{ message }` (full reaction set)         |
| DELETE | `/messages/:id/reactions`     | `{ emoji }`                            | `{ message }` (full reaction set)         |
| GET    | `/stream`                     | SSE; auto `Last-Event-ID` on reconnect | `text/event-stream`                       |

Optional moderation routes use `StorageAdapter.moderation`. Blocks and mutes
are self-service. Report queue and ban routes require
`chatpack({ moderation: { canModerate } })` authorization:

| Method | Path | Request body / query | Response |
| --- | --- | --- | --- |
| POST/DELETE | `/moderation/blocks` | `{ targetUserId }` | `{ block }` / `{ ok: true }` |
| GET | `/moderation/blocks` | `?limit=&cursor=` | `{ blocks, nextCursor }` |
| POST/DELETE | `/moderation/mutes` | `{ conversationId }` | `{ mute }` / `{ ok: true }` |
| GET | `/moderation/mutes` | `?limit=&cursor=` | `{ mutes, nextCursor }` |
| POST | `/moderation/reports` | `{ targetType, targetId, reason }` | `{ report }` |
| GET/PATCH | `/moderation/reports[/:id]` | status, targetType, or `{ status, moderatorNote? }` | report page or `{ report }` |
| GET/POST | `/moderation/bans` | filters or `{ targetUserId, reason?, expiresAt? }` | ban page or `{ ban }` |
| DELETE | `/moderation/bans/:id` | - | `{ ban }` |

Blocks stop new direct conversations and direct message mutations, but keep
existing direct history readable and do not affect shared groups. Mutes do not
change unread counts or SSE delivery. Reports support user, message, and
conversation targets. Active bans return `USER_BANNED`; adapters without the
optional capability return `MODERATION_UNSUPPORTED`.

**Ban enforcement follows your config, not your adapter.** Bans are checked on
every request and on every SSE heartbeat only when `moderation` is configured -
by default whenever `canModerate` is set, since `banUser` is the only way to
mint a ban. An app that never configures `moderation` pays no ban lookups even
on an adapter that supports them. Set `moderation: { enforceBans: true }` when
ban rows are written outside Chatpack, or `false` to keep the moderator tools
without per-request enforcement. Blocks, mutes and reports are unaffected: they
work off `StorageAdapter.moderation` alone.

Plugin routes (only when the plugin is passed to `chatpack({ plugins })`):

| Method | Path                        | Plugin       | Request body / query     | Response                                         |
| ------ | --------------------------- | ------------ | ------------------------ | ------------------------------------------------ |
| POST   | `/conversations/:id/typing` | `typing()`   | `{ isTyping?: boolean }` | `{ ok: true }`                                   |
| GET    | `/presence`                 | `presence()` | `?userIds=a,b` (max 50)  | `{ presence: { [id]: { online, lastSeenAt } } }` |

Semantics that trip up generated clients:

- Responses are **enveloped** (`{ conversation }`, `{ message }`,
  `{ messages, nextCursor }`) - unwrap them. Server-side `chat.api.*` returns
  the bare objects instead; don't share types between the two.
- Every conversation object carries `type: "direct" | "group"`,
  `pairKey: string | null` (always `null` for groups), and
  `name: string | null` (always `null` for DMs). Each participant carries
  `role: "admin" | "member"`. Both DM participants are `"admin"` - there is
  nothing to administer in a DM, and it keeps "can this user manage?" a plain
  role check on either type.
- **Every group route returns the full conversation** with its complete
  participant list - replace your cache entry, don't merge a delta. All the
  membership writes are **idempotent**: adding an existing member is a no-op
  (and never demotes an admin), removing a non-member is a silent success,
  setting the role someone already has does nothing.
- **Groups always keep at least one admin.** Removing or demoting the last one
  is 409 `LAST_ADMIN_REMAINING` - Chatpack refuses rather than silently
  promoting someone. Promote a successor first, then leave.
- A group name is trimmed, 1..200 characters; `PATCH /conversations/:id` with
  `{ "name": null }` clears it, and **omitting it while sending no other field
  is a 400** (an accidental clear is worse than an error). A group holds at most
  **256** participants (`MAX_GROUP_PARTICIPANTS`); exceeding it is 422
  `GROUP_LIMIT_EXCEEDED`.
- `POST /conversations/group` takes no required fields: a bodyless POST creates
  an empty, unnamed group with just the creator (an admin). `userIds` may
  include the creator or duplicates - both are de-duplicated.
- **Invite links** are an **optional storage capability**: the memory and
  Drizzle adapters have it, a custom adapter may not, and every invite route
  answers 501 `INVITES_UNSUPPORTED` when it is missing. Check once at startup,
  not per request.
- An invite `code` is a **capability URL**, not a credential: 32 random bytes as
  base64url (43 chars, URL-safe, sits in the path), and possession alone admits
  the holder. Bound it with `maxUses` / `expiresInSeconds` / revocation - and
  treat it like a password in logs, because it will appear in your access log.
  A group holds at most **50** invites (422 `INVITE_LIMIT_EXCEEDED`).
- `GET /invites/:code` returns an **`InvitePreview`, not a conversation**:
  `{ conversationId, name, participantCount, requiresApproval, invitedBy,
  alreadyParticipant }`. It is the only route a non-member may call, so it
  carries a participant *count* and never the member ids. Don't expect
  `participants` here.
- `POST /invites/:code/accept` returns a **discriminated union**: `status:
  "joined"` with `{ conversation, joinRequest: null }`, or `status: "pending"`
  with `{ conversation: null, joinRequest }` when the invite was minted with
  `requiresApproval: true`. Branch on `status`, not on which field is null.
- Redeeming is **idempotent and never over-charges the link**: a user who is
  already a member (or already has a pending request) gets their truthful
  result back and **burns no use** - even after the link is exhausted. A use is
  spent only when the call is actually going to admit someone, so redeeming
  into a full group is 422 `GROUP_LIMIT_EXCEEDED` with the link intact.
- Unknown code is **404** `INVITE_NOT_FOUND`; expired or used-up is **410**
  `INVITE_EXPIRED`. The 410 is the signal to ask for a new link rather than
  retry. A revoked code reads as 404 - indistinguishable from one that never
  existed.
- **Join requests**: `POST /conversations/:id/join-requests` needs no
  permission (asking is not entering) but 409s `ALREADY_PARTICIPANT` for a
  member. There is **at most one request per (conversation, user)** - re-asking
  while pending returns the same row, and a denied user asking again *replaces*
  their old row. Denial is not a block; blocking is your app's job.
- Admins resolve with `PATCH /conversations/:id/join-requests`
  `{ userId, decision: "approve" | "deny" }` - addressed by **user id**, not the
  request's own id. `GET` defaults to `?status=pending` (the moderation queue);
  pass `approved`/`denied` for history. Resolving an already-resolved request is
  404 `JOIN_REQUEST_NOT_FOUND`, so two admins cannot both apply a decision.
- Joining by link publishes the **existing** `participant.added` event, exactly
  as an admin-initiated add does - there are no new SSE event types, so a client
  written for ADR 0017 groups already handles arrivals. Creating a join request
  publishes **nothing** (the requester is not a member yet, and no member's view
  is stale); poll the queue.
- **A channel is a group with `visibility: "public"`** - there is no third
  `ConversationType`. Every conversation carries `visibility: "private" |
  "public"` (default `"private"`) and `joinPolicy: "open" | "approval"` (default
  `"approval"`). Set them at `POST /conversations/group`, or flip later with
  `PATCH /conversations/:id` - **admin only** (`canManage`, not `canInvite`), and
  409 `NOT_GROUP_CONVERSATION` on a DM. The two fields are independent: omitting
  one on a PATCH leaves it alone, it is not a reset.
- Channels are an **optional storage capability** (`channels`), separate from
  `invites`: without it, `GET /channels`, `POST /conversations/:id/join`, and any
  attempt to *set* a non-default `visibility`/`joinPolicy` answer 501
  `CHANNELS_UNSUPPORTED`. Explicitly sending the defaults still works, so
  existing clients are unaffected. An `"approval"` channel additionally needs
  `invites` (that is where the queue lives) or joining is 501
  `INVITES_UNSUPPORTED`.
- `GET /channels` returns **thin `ChannelPreview`s, not conversations**:
  `{ conversationId, name, participantCount, joinPolicy, createdAt, metadata,
  alreadyParticipant, requestPending }`, newest-active first with the same
  `?limit=&cursor=` keyset paging as `GET /conversations`. Like an invite
  preview it carries a participant *count* and **never the member ids**. Only
  public groups appear - never a DM, never a private group.
- **Public means discoverable, not readable.** Browsing the directory does not
  grant read access: `GET /conversations/:id` and the message routes still 403
  `FORBIDDEN_READ` for a non-member, and auth still runs before routing, so
  `GET /channels` 401s without a session. To read a channel you join it.
- `POST /conversations/:id/join` returns the **same discriminated union** as
  accepting an invite - `status: "joined"` with `{ conversation, joinRequest:
  null }` on an `"open"` channel, `status: "pending"` with `{ conversation:
  null, joinRequest }` on an `"approval"` one - both **200**, so branch on
  `status`. Re-asking while pending returns the same row; joining twice is 409
  `ALREADY_PARTICIPANT`; a private group is **403** `NOT_PUBLIC_CONVERSATION`
  (core knows the row exists, so it refuses rather than lying with a 404).
- A join request from the directory has `inviteCode: null` - that is how an admin
  tells "walked in off the directory" from "someone handed them a link". It
  lands in the same queue `GET /conversations/:id/join-requests` already serves.
- **An invite always overrides the channel's policy**: the policy lives on
  whatever the joiner presents. A link minted without `requiresApproval` walks
  straight into an `"approval"` channel (the admin who minted it vouched for the
  holder); a link minted with it queues even in an `"open"` one.
- Every conversation object (create, list, get) carries the **viewer's**
  `unreadCount`: messages with `seq` newer than their read-state, excluding
  the viewer's own messages. Soft-deleted messages count (they render as
  tombstones). Read the badge from here - don't count client-side.
- Message lists are **newest-first**; reverse for a chronological transcript.
  Paginate with `nextCursor` → `?cursor=`.
- Message search is case-insensitive, relevance-ranked, excludes tombstones,
  and searches only conversations where the requesting user is a participant.
  Core still applies `canRead`; dynamic access for non-participants is not
  supported by this initial implementation.
- The message text field is **`body`** (not `text`/`content`). It must be a
  **non-empty string after trimming**, on send and on edit - whitespace-only is
  400 `INVALID_INPUT`. There is no such thing as a body-less message, so an
  attachment-only or sticker-only UI has to synthesize one.
- Every message object carries `mentions: string[]` (the participants named in
  it, empty when none) and `forwardedFrom: { messageId, conversationId,
  senderId } | null`. Unlike `replyTo`, both come from stored rows: mentions
  from their own table, provenance from three columns on the message.
- Every message object carries `reactions` and reply fields:
  `reactions: [{ emoji, count, userIds }]` (grouped, `userIds` earliest-first,
  at most 2 entries per emoji in a DM, up to the participant count in a group)
  plus `replyToMessageId: string | null` and a
  read-only `replyTo: { id, senderId, excerpt, deleted } | null`. `replyTo` is
  **hydrated per request, never stored** - it cannot go stale when the parent
  is edited, and it renders even when the parent is outside the loaded page.
  `excerpt` is the parent's first 140 chars with `"…"` when truncated, and
  `""` when the parent is a tombstone. Don't look the parent up client-side.
- **Reactions:** `POST`/`DELETE /messages/:id/reactions` with `{ emoji }`, both
  **idempotent** (reacting twice = one reaction; un-reacting nothing = no-op)
  and both returning the message with its **complete** reaction set - replace
  your cache entry, don't merge a delta. The acting user comes from the auth
  hook, so a caller can only ever react as themselves. Reacting needs **write**
  permission, like editing. The emoji is in the **body** on DELETE too (keys can
  be arbitrary strings that mangle in a path segment). A reaction is not a
  message: it never bumps `unreadCount`, never reorders the conversation list,
  and never gets a `seq`.
- A reaction key is **any non-empty string, trimmed, up to 32 characters** -
  `"👍"`, `":shipit:"`, and `"custom_1234"` are all valid; `""` and 33+ chars
  are 400 `INVALID_INPUT`. Chatpack does not validate it as a Unicode emoji.
- **Replies are flat pointers, not threads.** `replyToMessageId` must name a
  message in the **same conversation** (else 404 `MESSAGE_NOT_FOUND`);
  replying to a soft-deleted message is allowed; deleting a parent leaves its
  replies intact; a reply to a reply is still one hop; and the pointer is
  immutable (`PATCH /messages/:id` only ever changes the body). v0 still has
  **no threads** - no per-message reply lists, unread counts, or pagination.
- **Mentions are ids you supply, never parsed from the text.** Send or edit with
  `mentions: ["user_1", ...]`; core never parses `body` (ADR 0022 - text is
  opaque, markdown and rendering are yours),
  so `body` and `mentions` can legitimately disagree and **your app owns keeping
  them in step** - it renders the `@name`, it tells Chatpack which ids that
  means. Every id must be a **current participant** or the whole call is 400
  `MENTION_NOT_PARTICIPANT` - a mention is never silently dropped, because an
  invisible drop makes the sender believe a notification went out. Mentioning
  yourself is allowed; at most 256 ids per message. On `PATCH /messages/:id`,
  **omitting `mentions` leaves the stored set alone** (so a mentions-unaware
  client cannot erase them) and `mentions: []` clears it. Ids already stored are
  re-accepted even if that user has since left, so fixing a typo still works;
  a *new* id must still be a participant. Treat the array as a **set** - it
  reads back sorted, not in the order you sent it. A mention is not a message:
  no `seq`, no `unreadCount`, no reordering, no SSE event of its own. Chatpack
  does **not** notify anyone or keep a mention inbox - `afterMessageMutation`
  gets `mentions` next to `recipientIds` so you can.
- **Forwarding copies the message.** `POST /messages/:id/forward` with
  `{ conversationId }` writes a **new** message in the target: your id as
  sender, the body copied verbatim, a normal `seq`, and it counts toward the
  target's unread. Nothing is a live pointer, so editing or deleting the
  original never changes the copy - and the copy carries no excerpt of the
  source, because the people reading it may have no access to that conversation.
  You need **read** on the source and **write** on the target; forwarding a
  tombstone is 409 `MESSAGE_DELETED`. `forwardedFrom` names the **immediate**
  source (one hop, like replies), and holds three ids only - never the source
  conversation's *name*. Reactions, the reply pointer, mentions, metadata, and
  `role` do **not** travel; pass fresh `mentions`/`metadata`/`role` if you want
  them, and `mentions` is validated against the **target**. `beforeMessageSend`
  runs with `action: "send"` (**not** a third `"forward"` action, so existing
  content filters keep covering it) and `forwardedFrom` set - branch on that.
- `role` is `"user" | "assistant" | "system"` (default `"user"`) - a stored
  label; core never branches on it. Anything else is a 400.
- `otherUserId` and group `userIds` are **not validated to exist by default**
  (Chatpack never owns a users table). Pass the optional
  `userExists: (userId) => boolean | Promise<boolean>` option to `chatpack()`
  and core will ask *your* identity store before creating a DM, seeding a
  group, or adding participants; a `false` answer is 404 `USER_NOT_FOUND`.
  Without the hook, ids stay fully opaque and unchecked - validate recipients
  in your app instead. The hook is never asked about the acting user (the
  `auth` hook already vouched for them), never asked twice about the same id,
  and is called in bounded batches, so seeding a 50-member group is a handful
  of round trips rather than 50.
- Timestamps are `Date` in server-side calls, ISO strings over HTTP.
- Errors: `{ "error": { "code", "message" } }` - 401 `UNAUTHENTICATED`
  (the message says *why*: bad hook return shape vs. missing cookie vs.
  unparsed cookie), 400 `INVALID_INPUT`, 403 `FORBIDDEN_*`, 403
  `NOT_CONVERSATION_ADMIN` (a group management call by a non-admin),
  403 `NOT_PUBLIC_CONVERSATION` (joining a group that is not a channel - a
  refusal, not a pretend 404),
  400 `MENTION_NOT_PARTICIPANT` (a mention named someone outside the
  conversation - 400 because the request is malformed, not denied),
  404 `*_NOT_FOUND` (including `USER_NOT_FOUND`, only possible when the app
  configured `userExists`), 409 `MESSAGE_DELETED`, 409 `NOT_GROUP_CONVERSATION`
  (a group-only call on a DM), 409 `LAST_ADMIN_REMAINING`,
  409 `ALREADY_PARTICIPANT` (asking to join a group you are in),
  410 `INVITE_EXPIRED` (the link existed and is spent - ask for a new one),
  422 `MESSAGE_REJECTED` (a `beforeMessageSend` hook refused the message),
  422 `GROUP_LIMIT_EXCEEDED`, 422 `INVITE_LIMIT_EXCEEDED`,
  501 `SEARCH_UNSUPPORTED` / `INVITES_UNSUPPORTED` / `CHANNELS_UNSUPPORTED`
  (storage has no such capability), 500 `INTERNAL_ERROR` (opaque).
- **Auth runs before routing** - an unauthenticated request to a wrong path
  still 401s. Fix auth first; then a lingering 404 `NOT_FOUND` means your
  mount path/basePath is wrong.

## Real-time over one EventSource

`GET /stream` pushes `message.created` / `message.updated` /
`message.deleted` for the authenticated user's conversations (participation
re-checked server-side per event). Reconnects gap-fill automatically from
storage via `Last-Event-ID` - durable-first, no lost messages; delivery is
at-least-once, so **dedupe by `message.id`**.

`reaction.added` / `reaction.removed` are a **third** category: durable-backed
(so not `ephemeral: true`), but their frames carry **no `id:` line**, because
`Last-Event-ID` means "the newest message `seq` I have seen" and a reaction
produces no new `seq`. Payload:
`{ type, conversationId, actorId, emoji, message }` where `message` holds the
**complete** post-change reaction set. Consequence for clients: reactions are
**not gap-filled**. A reaction applied while you were offline arrives on your
next refetch, not as a replay - so refetch the cached message pages when the
stream reopens after having been open. (`@chatpack/client` does this for you.)

`participant.added` / `participant.removed` / `conversation.updated` are a
**fourth** category with the same no-`id:` rule (a membership change allocates
no `seq`) and so are also **not gap-filled**. Payload:
`{ type, conversationId, actorId, affectedUserIds, conversation }` where
`conversation` is the complete post-change snapshot - render from it rather
than patching. `affectedUserIds` lists who was added, removed, or had their
role changed, and is empty for a rename (that change shows up in
`conversation.name`).
`participant.removed` is delivered **to the removed user too** - it is the one
signal telling their client to drop the conversation, and the only place a
Chatpack event reaches a non-participant. Refetch the conversation list when
the stream reopens.

Plugins add ephemeral events on the same stream (never stored, never
replayed): `typing.started/.stopped`, `presence.online/.offline`,
`receipt.delivered/.read`. Payload:
`{ type, ephemeral: true, conversationId?, senderId, payload, at }`.
Client conventions: throttle typing POSTs to ~1 per 3s and expire indicators
after ~5s; dedupe ticks by `payload.messageId`; durable read-state truth is
`participant.lastReadMessageId`, updated via `POST /conversations/:id/read`
(monotonic: marking an older message than the current read-state is a silent
no-op). `unreadCount` derives from this durable field, NOT from receipt
ticks - for a live badge, increment locally on `message.created` where
`senderId !== me`, reset on your own markRead.

```ts
events.onerror = () => {
  if (events.readyState === EventSource.CLOSED) {
    // Fatal (e.g. 401): browser will NOT retry - re-auth, then recreate.
  } // otherwise EventSource retries + gap-fills automatically
};
```

## Where it runs (deployment decision table)

| Environment                                                                                          | Storage                          | Real-time                                     |
| ---------------------------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------- |
| One long-lived process: `node`/`Bun.serve`, `next start`, Railway/Fly/Render, Replit Reserved VM, **AI-builder previews** (Lovable/v0 preview sandboxes behave like a dev server) | `memoryAdapter` (demo) or Drizzle | `/stream` SSE works                           |
| Several long-lived processes behind a load balancer (2+ containers/dynos, `pm2 -i`, autoscaled VMs) | Drizzle (or custom adapter) | `/stream` works **only** with `@chatpack/transport-redis` - the default transport is per-process |
| Serverless / edge / multi-instance: Vercel & AWS Lambda, Cloudflare Workers, **published AI-builder apps**, Replit Autoscale | Drizzle (or custom adapter) - `memoryAdapter` is per-isolate and loses everything | SSE is unsuitable here whatever the transport (function lifetime, not fan-out, is the blocker). Use `@chatpack/client` with `realtime: { mode: "poll" }` - or `auto`, the default, which falls back on its own. Typing/presence/receipts are unavailable; do not hand-roll an interval |

The default transport and plugin state are in-process. A demo on
`memoryAdapter` + `/stream` is correct in a preview and wrong in a serverless
deploy - say so in the app's README. For several long-lived nodes, use the
Redis transport plus `redisPresenceStore()` with `presence()`.

**Multi-node SSE (2+ long-lived processes).** Swap in the Redis transport -
one line, no other API change:

```ts
import { redisPresenceStore, redisTransport } from "@chatpack/transport-redis";
import { presence } from "@chatpack/core/plugins";
import { Redis } from "ioredis";

// Two connections: a client in subscriber mode cannot PUBLISH.
const publisher = new Redis(process.env.REDIS_URL!);
export const chat = chatpack({
  storage,
  auth,
  transport: redisTransport({
    publisher,
    subscriber: new Redis(process.env.REDIS_URL!),
  }),
  plugins: [presence({ store: redisPresenceStore({ client: publisher }) })],
});
```

Hard rules for the Redis transport:

- **Two separate Redis connections are required** (`publisher` + `subscriber`);
  passing one client twice throws at startup.
- Bring your own client - `ioredis` or `node-redis` v4+ both work; Chatpack has
  no Redis dependency. Options: `channel` (default `chatpack:events`), `nodeId`,
  `onError`.
- Import ioredis as `import { Redis } from "ioredis"` - the **named** export.
  Its default export is the same class at runtime, but ioredis is CommonJS, so
  on `"module": "nodenext"` the default is typed as the module object and
  `new Redis(url)` does not compile.
- Messages, typing, receipts, and presence go multi-node when the Redis
  transport and `redisPresenceStore()` are configured. Presence uses expiring
  per-connection leases and keeps five seconds of offline grace by default.
  Without a shared store `presence()` stays per-process, so `GET /presence`
  answers for locally-connected users only.
- A Redis outage degrades live delivery, never the send: `publish` stays
  synchronous and never throws, senders succeed, and other-node clients
  gap-fill from storage on reconnect.
- Sticky sessions are NOT needed - any node can serve any stream.
  Rationale: `docs/decisions/0012`.

## Verify the integration (before declaring success)

```sh
# 1. auth + server-generated conversation id (expect 200, id like "conv_1")
curl -si -X POST localhost:3000/api/chat/conversations \
  -H 'cookie: demo_user=alice' -H 'content-type: application/json' \
  -d '{"otherUserId":"bob"}'

# 2. send + list (expect 201, then 200 newest-first)
curl -si -X POST localhost:3000/api/chat/conversations/conv_1/messages \
  -H 'cookie: demo_user=alice' -H 'content-type: application/json' -d '{"body":"hi"}'
curl -s 'localhost:3000/api/chat/conversations/conv_1/messages?limit=10' \
  -H 'cookie: demo_user=bob'

# 3. react (expect 200 with reactions: [{"emoji":"👍","count":1,...}])
curl -si -X POST localhost:3000/api/chat/messages/MSG_ID/reactions \
  -H 'cookie: demo_user=bob' -H 'content-type: application/json' -d '{"emoji":"👍"}'

# 4. group (expect 201, type "group", alice admin + bob member, pairKey null)
curl -si -X POST localhost:3000/api/chat/conversations/group \
  -H 'cookie: demo_user=alice' -H 'content-type: application/json' \
  -d '{"name":"Launch","userIds":["bob"]}'

# 5. add a member as the admin (expect 200 with all three participants)
curl -si -X POST localhost:3000/api/chat/conversations/GROUP_ID/participants \
  -H 'cookie: demo_user=alice' -H 'content-type: application/json' \
  -d '{"userIds":["carol"]}'

# 6. publish it as an open channel, then browse and join as a stranger
#    (expect 200 with visibility "public"; then a preview with
#    participantCount and NO participants array; then status "joined")
curl -si -X PATCH localhost:3000/api/chat/conversations/GROUP_ID \
  -H 'cookie: demo_user=alice' -H 'content-type: application/json' \
  -d '{"visibility":"public","joinPolicy":"open"}'
curl -s 'localhost:3000/api/chat/channels?limit=10' -H 'cookie: demo_user=dave'
curl -si -X POST localhost:3000/api/chat/conversations/GROUP_ID/join \
  -H 'cookie: demo_user=dave'

# 7. mention a member, then forward the message into the DM
#    (expect 201 with mentions ["carol"]; then 201 whose forwardedFrom names
#    GROUP_ID and whose senderId is alice, NOT the original sender)
curl -si -X POST localhost:3000/api/chat/conversations/GROUP_ID/messages \
  -H 'cookie: demo_user=alice' -H 'content-type: application/json' \
  -d '{"body":"@carol ship it","mentions":["carol"]}'
curl -si -X POST localhost:3000/api/chat/messages/MSG_ID/forward \
  -H 'cookie: demo_user=alice' -H 'content-type: application/json' \
  -d '{"conversationId":"conv_1"}'

# 8. live stream (expect ": connected", then events as messages are sent;
#    reaction.* and participant.*/conversation.updated frames arrive with no
#    `id:` line - that is correct)
curl -sN localhost:3000/api/chat/stream -H 'cookie: demo_user=bob'
```

In the browser: after "sign in", `document.cookie` must actually contain the
demo cookie, and the Network tab must show it on `/api/chat/*` requests -
if it's missing there, revisit the cookie attributes (iframe rules above).
A 401 response body names the exact failure; read it before changing code.

## AI assistant pattern (user↔AI chat)

Chatpack has no AI features - an assistant is just a participant with a
synthetic user id:

1. Reserve an id like `"ai:assistant"` (block the prefix in your own
   auth/validation - `otherUserId` accepts any non-empty string).
2. `chat.api.getOrCreateConversation({ userId, otherUserId: "ai:assistant" })`.
3. Persist the user message with `chat.api.sendMessage` as usual.
4. Your backend calls the LLM (your keys), then
   `chat.api.sendMessage({ userId: "ai:assistant", conversationId, body: reply, role: "assistant" })`.

Token streaming is your concern; Chatpack stores whole messages (send the
final text, or edit a placeholder as chunks arrive).

## Message hooks (content rules and side-effects)

Optional `hooks` on `chatpack()` run after auth and permission checks:

```ts
chatpack({
  storage, auth,
  hooks: {
    // BEFORE persistence - block (throw) or rewrite (return { body/metadata }):
    beforeMessageSend: ({ body }) => {
      if (body.length > 2000) throw new Error("Max 2000 characters."); // → 422 MESSAGE_REJECTED
      return { body: censor(body) };  // persisted + broadcast rewritten
    },                                // return nothing → unchanged
    // AFTER persistence + broadcast - side-effects only. `action` is
    // "send" | "edit" | "delete"; filter it for push or queue work.
    afterMessageMutation: async ({
      action, message, conversation, recipientIds, mentions,
    }) => { ... },
  },
})
```

- A rejected message is never stored and never broadcast; the sender gets
  `422 MESSAGE_REJECTED` with the thrown error's message. Throw a
  `ChatpackError` to use a different code.
- `beforeMessageSend` returning `{ metadata }` applies on sends only.
- `beforeMessageSend` also gets `mentions` (the validated set) and
  `forwardedFrom` (`null` for an ordinary send). A **forward reports
  `action: "send"`**, deliberately - a third `"forward"` action would have
  silently exempted every filter already written against `"send"`. Branch on
  `forwardedFrom` when a forward needs different treatment.
- `afterMessageMutation` receives the raw persisted message, conversation,
  `recipientIds`, `mentions`, and `action` (`send`, `edit`, or `delete`).
  `mentions` sits next to `recipientIds` so a push integration can tell
  "everyone in the room" from "the people actually named" - Chatpack itself
  notifies nobody. It is reported on `delete` too (mention rows outlive a
  tombstone, like reactions). Chatpack
  still emits its internal `message.created`, `message.updated`, and
  `message.deleted` events for UI clients.
- **Notify `recipientIds`, not `otherParticipantId`.** `recipientIds` is every
  participant except the sender - exactly one in a DM, up to 255 in a group, and
  empty in a group whose creator has not invited anyone yet (the hook still
  fires).
  `otherParticipantId` is the deprecated single-valued field kept for
  compatibility: in a group it is just the *first* other participant, so a push
  integration that reads it silently drops everyone else.
- `afterMessageSend` remains as a deprecated send/edit-only compatibility hook.
- Hooks are in-process functions, not webhooks - no retries or delivery
  guarantees. Applications own device tokens and provider delivery. Keep
  heavy work in your own queue.

# Part 2 - Writing a custom storage adapter

Only needed on platforms where the official adapters don't fit (Convex,
Firebase, proprietary AI-builder clouds, or another store without a first-party
adapter).

## Decide if you even need a custom adapter

- Demos / tests / single long-lived process: `@chatpack/adapter-memory`.
- Any Postgres you can reach with a **connection string** (Neon, RDS, Railway,
  Fly, Replit, Vercel Postgres): `@chatpack/adapter-drizzle`. Do NOT write a
  custom adapter for these.
- Supabase/PostgREST through Supabase JS: use the first-party
  `@chatpack/adapter-supabase` adapter and its migration. It runs server-side
  with a privileged client; do not write a custom adapter for Supabase.
- A non-SQL store (Convex, Firestore, DynamoDB): write a custom adapter -
  continue below.
- MySQL 8 with a server-side transaction-capable `mysql2` connection or pool:
  use first-party `@chatpack/adapter-mysql`. Verified target is MySQL 8 plus
  Drizzle's `mysql2` driver. Do not infer MariaDB, PlanetScale, Aurora,
  HTTP/serverless driver, or edge-runtime support from generic MySQL tests.

## The contract

Implement the `StorageAdapter` interface exported from `@chatpack/core` and
pass it as `chatpack({ storage: yourAdapter() })`. Twenty-one required async
methods:

| Method                          | Contract                                                                  |
| ------------------------------- | ------------------------------------------------------------------------- |
| `getOrCreateDirectConversation` | Find or atomically create by `pairKey` - concurrent calls must converge   |
| `createGroupConversation`       | Always create a new group: `pairKey: null`, creator `admin`, rest `member` |
| `getConversation`               | Fetch by id (with all participants), or `null`                            |
| `listConversations`             | A user's conversations, most-recently-active first, cursor-paginated      |
| `updateConversation`            | Patch `name` (string or `null`), `visibility`, `joinPolicy`; throw if id unknown |
| `addParticipants`               | Insert-if-absent as `member`; never demote an existing participant        |
| `removeParticipant`             | Delete that membership row; absent = silent no-op. Messages stay          |
| `setParticipantRole`            | Set one participant's role; throw if they are not a participant           |
| `addMessage`                    | Persist + assign the next strictly-increasing `seq` for that conversation |
| `getMessage`                    | Fetch by id, or `null`                                                    |
| `getMessagesByIds`              | Batched fetch by id; unknown ids simply absent (quote-reply previews)     |
| `listMessages`                  | Per-conversation history, newest-first (descending `seq`), cursor-paginated |
| `listMessagesAfterSeq`          | Messages with `seq > afterSeq`, **oldest first** (SSE/polling gap-fill)   |
| `updateMessage`                 | Patch body / `editedAt` / `deletedAt` in place; throw if id unknown       |
| `updateLastRead`                | Set a participant's `lastReadMessageId`                                   |
| `countUnread`                   | Batched per-conversation unread counts for one viewer (invariant 10)      |
| `addReaction`                   | Idempotent insert; return the message's **full** reaction set (inv. 12)   |
| `removeReaction`                | Idempotent delete; return the remaining set (inv. 12)                     |
| `listReactionsByMessageIds`     | Batched reactions for a page, ascending `createdAt` (invariant 13)        |
| `setMessageMentions`            | **Replace** one message's mention set; total, idempotent, returns nothing  |
| `listMentionsByMessageIds`      | Batched mentions for a page, ascending `(createdAt, userId)` (inv. 20)     |

Exact TypeScript signatures and per-method TSDoc ship in the package's
`.d.ts` (`@chatpack/core`, `storage.ts` module).

The two mention methods are required for the same reason the group ones are: a
mention row either exists or it doesn't. An adapter that predates ADR 0023 fails
to typecheck until it implements both - deliberate, since silently discarding
mentions looks exactly like a lost notification. Forwarding adds **no** methods:
it is `addMessage` with three more nullable columns.

The five group methods are **required, not optional** (unlike `searchMessages`):
a membership row either exists or it doesn't, so the semantics are identical on
every backend and there is nothing for a platform to be unable to express. An
adapter written before groups will fail to typecheck until it implements them -
that is deliberate, because silently missing membership writes would look like
data loss.

Invite links and join requests are an **optional capability exposed as one
namespace**: `invites?: InviteStorage` on `StorageAdapter`, holding nine
methods (`createInvite`, `getInvite`, `listInvites`, `deleteInvite`,
`consumeInvite`, `createJoinRequest`, `getJoinRequest`, `listJoinRequests`,
`resolveJoinRequest`). Omit the whole namespace and core throws
`INVITES_UNSUPPORTED` (HTTP 501) on all eight invite routes; provide it and you
must provide all nine. It is one namespace rather than nine independently
optional methods precisely so a half-implemented capability cannot exist - it
would typecheck and then fail at runtime (ADR 0019 §2). Contract highlights:

- `consumeInvite` must check usability and increment `uses` in **one
  statement** - `UPDATE ... WHERE code = $1 AND (max_uses IS NULL OR uses <
  max_uses) AND (expires_at IS NULL OR expires_at > now()) RETURNING *`. Zero
  rows affected is the `null` (no-longer-usable) case. A read-then-write lets
  two simultaneous redemptions of a `maxUses: 1` link both succeed.
- `getInvite` must return expired and exhausted invites, not `null` - core
  needs them to distinguish 404 from 410.
- `deleteInvite` is scoped by `conversationId` and idempotent, so an admin of
  one group cannot revoke another group's link by guessing a code.
- `createJoinRequest` **upserts** on `(conversationId, userId)`, resetting
  `status` to `pending` and clearing `resolvedAt`/`resolvedBy` - one row per
  user per group, so a denied user re-asking replaces their row.
- Core generates the invite `code` (32 random bytes, base64url) and the adapter
  stores it verbatim as the primary key. Never generate or re-derive it:
  unguessability is a security property, not a storage detail.

Public channels (ADR 0020) follow the same shape as a **second** optional
namespace, `channels?: ChannelStorage`, holding exactly one method:

- `listPublicConversations({ limit, cursor })` → `{ conversations, nextCursor }`
  - every `type: "group"` conversation with `visibility: "public"`, ordered and
    paginated **exactly like `listConversations`** (most-recently-active first,
    same opaque cursor contract). Filter on `type` as well as `visibility`, so a
    hand-edited row can never surface a DM in a public directory. Core narrows
    each row to a `ChannelPreview` itself - return full conversations.

The `visibility` and `joinPolicy` columns, by contrast, ride the **required**
contract: every adapter stores and returns them on `Conversation`, and
`createGroupConversation`/`updateConversation` receive them always resolved by
core (never `undefined`). Two rules follow:

- **Coerce on read.** They are open text columns in SQL; narrow anything
  unrecognized to `"private"` / `"approval"` rather than passing it through. A
  stray value failing closed keeps a private group private.
- Omitting the `channels` namespace does **not** let you skip the columns. Core
  refuses to *set* a non-default value without the namespace (501
  `CHANNELS_UNSUPPORTED`), which is what stops an adapter silently dropping
  `visibility: "public"` and reporting a channel that no directory can find.
- An `"approval"` channel routes its joiners into the ADR 0019 queue, so it
  needs the `invites` namespace too. `"open"` channels need only `channels`.

`searchMessages` is an optional storage capability. Memory and Drizzle provide
it. Existing custom adapters may omit it; core then throws `SEARCH_UNSUPPORTED`
and the HTTP handler returns `501`. Adapters that provide search must return
non-tombstone participant-scoped results. First-party adapters use the core
helpers `tokenizeSearch`, `getSearchTerms`, `countSearchTokens`, and
`scoreSearchTerms`: Unicode NFKC normalization, lowercase matching, punctuation
as a separator, all unique query terms required, no stemming or prefix
matching, and occurrence-sum relevance. This makes URLs, paths, emails, phone
numbers, versions, and underscored identifiers behave the same in memory and
Postgres. Custom adapters should use these helpers to preserve the same
contract; cursors remain opaque and adapter-defined.

`moderation` is the fourth optional storage capability, independent of the other
three. Implement
`ModerationStorage` when the adapter supports blocks, mutes, reports, and bans;
the memory and Drizzle adapters are the reference implementations. Persist
four durable table families: symmetric block lookup, per-user conversation
mutes, reports with immutable message/conversation evidence JSON, and bans with
expiry and revocation fields. Make block and mute creates idempotent, reuse an
open or triaged report for the same reporter and target, and keep revoked or
expired bans in history. `createBan` must decide **in one statement** whether a
user already has an active ban and return that ban instead of inserting a
second: two moderators banning at the same moment must leave exactly one active
row, or revoking the visible ban would leave the duplicate enforcing. "Active"
means unrevoked *and* unexpired, which no unique index can express, so put the
condition in the insert itself. `revokeBan` must keep the original revoker when
called twice. Custom adapters that omit this capability remain compatible;
moderation calls then return `MODERATION_UNSUPPORTED`.

### Entities your adapter stores

- **Conversation**: `id`, `type` (`"direct" | "group"`),
  `pairKey: string | null` (set for DMs, `null` for groups),
  `name: string | null` (groups only), `visibility`
  (`"private" | "public"`, default `"private"`), `joinPolicy`
  (`"open" | "approval"`, default `"approval"`), `createdAt: Date`, `metadata`
  (JSON object), `participants` (exactly 2 for a DM, 1..256 for a group). A
  public group is a **channel** - there is no third `type`.
- **Participant**: `conversationId`, `userId`, `role`
  (`"admin" | "member"`), `joinedAt: Date`,
  `lastReadMessageId: string | null`.
- **Message**: `id`, `conversationId`, `senderId`, `body`, `role`
  (`"user" | "assistant" | "system"`), `seq: number`, `createdAt: Date`,
  `editedAt: Date | null`, `deletedAt: Date | null`,
  `replyToMessageId: string | null`, `forwardedFromMessageId`,
  `forwardedFromConversationId`, `forwardedFromSenderId` (all
  `string | null`, all three set or all three null), `metadata`.
- **Reaction**: `messageId`, `userId`, `emoji`, `createdAt: Date`. Unique on
  the `(messageId, userId, emoji)` triple. Reactions have no id and no `seq`.
- **MessageMention**: `messageId`, `userId`, `createdAt: Date`. Unique on the
  `(messageId, userId)` pair. No id and no `seq`. `userId` was a participant
  when the mention was made and is **not** re-checked, so it may name someone
  who has since left.
- **ConversationInvite** (optional capability): `code` (the primary key *and*
  the secret), `conversationId`, `createdBy`, `createdAt: Date`,
  `expiresAt: Date | null`, `maxUses: number | null`, `uses: number`,
  `requiresApproval: boolean`, `metadata`. Invites have no `seq` and are never
  swept - core caps them at 50 per group instead.
- **JoinRequest** (optional capability): `id`, `conversationId`, `userId`,
  `status` (`"pending" | "approved" | "denied"`), `message: string | null`,
  `inviteCode: string | null` (no foreign key - a request must outlive a
  revoked invite), `createdAt: Date`, `resolvedAt: Date | null`,
  `resolvedBy: string | null`, `metadata`. Unique on `(conversationId, userId)`.
- **UserBlock** (optional capability): `blockerUserId`, `blockedUserId`,
  `createdAt: Date`. Keyed on the pair; `isBlocked` must match in **either**
  direction. No id.
- **ConversationMute** (optional capability): `userId`, `conversationId`,
  `createdAt: Date`. Keyed on the pair. No id.
- **ModerationReport** (optional capability): `id`, `reporterUserId`,
  `targetType` (`"user" | "message" | "conversation"`), `targetId`, `reason`,
  `status` (`"open" | "triaged" | "resolved" | "dismissed"`),
  `moderatorNote: string | null`, `evidence` (a JSON snapshot core builds - store
  it verbatim and never refresh it), `createdAt: Date`, `updatedAt: Date`.
- **UserBan** (optional capability): `id`, `userId`, `createdByUserId`,
  `reason: string | null`, `createdAt: Date`, `expiresAt: Date | null`,
  `revokedAt: Date | null`, `revokedByUserId: string | null`. Never deleted -
  revoked and expired rows are the audit history.

Adapters store `replyToMessageId` and the three `forwardedFrom*` columns
verbatim (core already validated them) and never see the API-only decorations
`replyTo` / `reactions` / `mentions` / `forwardedFrom` - core computes those per
request from `getMessagesByIds`, `listReactionsByMessageIds`,
`listMentionsByMessageIds`, and (for `forwardedFrom`) the message's own columns.

Give `forwardedFromMessageId` **no foreign key**, for the same reason
`replyToMessageId` has none: a forward is a copy that must outlive its source,
including a source conversation the reader was never party to. Do index it
(partially, where non-null) - "what was forwarded from this" is the query an app
builds a share count on, and adding the index later means locking the table.

Users are opaque string ids. Chatpack never owns a users table - do not add
foreign keys into the app's users table and do not validate user existence in
the adapter. That last rule is unchanged by the `userExists` option: existence
checks are core's job, run against the *host's* identity store through a hook
the app supplies, before core ever calls you. Your adapter still stores
whatever ids it is handed.

## Level 1 - invariants (database-agnostic; these are the contract)

Satisfy every one of these however your platform does atomicity. Everything
else is implementation detail.

1. **One conversation per `pairKey`, even under concurrency - and that
   uniqueness must NOT apply to groups.**
   Core computes `pairKey` (sorted user ids joined with `":"`, e.g.
   `"alice:bob"`) and hands it to you. Two concurrent
   `getOrCreateDirectConversation` calls with the same `pairKey` must converge
   on a single conversation (`created: true` for at most one caller). A
   JS-side "select, then insert if missing" is NOT enough - enforce uniqueness
   in the database (unique index + insert-on-conflict, transaction, or your
   platform's equivalent). Groups store `pairKey: null` and are **never**
   find-or-create, so the constraint has to exclude nulls - in Postgres a
   *partial* unique index (`WHERE pair_key IS NOT NULL`), since a total unique
   index on a nullable column would still let unlimited nulls through but the
   intent stops being expressed. Watch the corollary: `ON CONFLICT` only
   matches a partial index when the insert **repeats the predicate**, so the DM
   insert needs `ON CONFLICT (pair_key) WHERE pair_key IS NOT NULL DO NOTHING`.
2. **`seq` is strictly increasing per conversation and assigned atomically
   with the message insert.** Never reused, never decreasing; gaps are
   allowed. Concurrent sends to the same conversation must serialize. Do NOT
   compute `MAX(seq) + 1` in application code - that races.
3. **Adapters generate ids.** `getOrCreateDirectConversation` and `addMessage`
   create the `id` themselves (any unique string; the official adapters use
   prefixed random ids like `msg_<uuid>`). Ids must be unique and stable.
4. **Adapters never enforce permissions.** Core validates participants and
   permission hooks *before* calling you. Return whatever is asked for.
   Corollary for hosted platforms: the adapter must run **server-side with
   full DB privileges** (e.g. the Supabase service-role key), and the
   Chatpack tables must NOT be readable or writable by browser/anon clients -
   otherwise users can read each other's messages around Chatpack entirely.
5. **Cursors are opaque strings that the adapter defines.** Core (and the
   HTTP layer) round-trip your `nextCursor` back into `input.cursor`
   verbatim, without inspecting it. Pick any encoding that survives a URL
   query parameter. Return `nextCursor: null` when there are no more results.
   Reference encodings: `listMessages` - the `seq` of the last message on the
   page; `listConversations` - `"<lastActivityMs>:<conversationId>"` (keyset)
   or simply the last conversation id.
6. **Ordering.** `listMessages`: newest-first (descending `seq`).
   `listMessagesAfterSeq`: oldest-first (ascending `seq`), only `seq >
   afterSeq`, capped at `limit`. `listConversations`: most-recently-active
   first (latest message activity, falling back to conversation creation
   time), with a stable tiebreak so pagination never skips or repeats.
   **`participants` must come back in a stable order across reads** - any
   order you like (the official adapters use join order, tie-broken by
   `userId`), but the *same* one every time. SQL stores give no row order
   without an explicit `ORDER BY`, and clients diff participant lists
   positionally: an unordered read makes an N-member group look like it changed
   membership on every poll.
7. **Return real `Date` instances, never ISO strings.** The interface types
   say `Date` and core does not coerce. Database drivers and HTTP clients
   (PostgREST, Convex, Firestore) often hand back strings or numbers -
   convert at the adapter boundary, both directions. JSON serialization is
   the HTTP handler's job, never yours.
8. **Soft delete is an update, not a removal.** Core calls
   `updateMessage({ body: "", deletedAt })`; the row must remain (clients
   render a tombstone) and must keep its `seq`. Never hard-delete.
   `updateMessage` patches only the fields that are defined on the input and
   throws on unknown ids; `updateLastRead` overwrites `lastReadMessageId`
   unconditionally (core has already validated the message).
9. **`metadata` is an arbitrary JSON object.** Store and return it losslessly
   (default `{}`).
10. **`countUnread` is exact and batched.** For each requested conversation,
    count messages with `seq` strictly greater than the seq of the viewer's
    `lastReadMessageId` (`null` read-state = 0, i.e. everything) AND
    `senderId !== userId` (a viewer's own messages are never unread).
    Soft-deleted messages keep their `seq` and DO count; all roles count.
    Return `{ [conversationId]: count }`; ids the viewer doesn't participate
    in may be omitted or 0 (core treats missing as 0). One call covers a
    whole page of conversations - do it in one query, not one per id.
    Note `lastReadMessageId` is a message **id**, not a seq: resolve it at
    query time (SQL: LEFT JOIN the message row + `COALESCE(read.seq, 0)`).
11. **Optional search is participant-scoped.** If implemented,
    `searchMessages` must filter by the supplied `userId`, exclude tombstones,
    rank results deterministically, and return an opaque cursor. Use the core
    search helpers for case-insensitive NFKC tokenization, punctuation
    separation, all-term matching, and occurrence-sum relevance. Core applies
    `canRead` after retrieving participant-scoped candidates. Dynamic access to
    non-participant conversations is not supported by this initial design.
12. **Reaction writes are idempotent and return the full set.** `addReaction`
    with the same `(messageId, userId, emoji)` twice must leave exactly one
    reaction - not two, not an error - so enforce uniqueness in the database
    (unique index + insert-on-conflict-do-nothing), not in JS.
    `removeReaction` for a reaction that was never there is a silent no-op.
    **Both return every reaction on the message afterwards**, so core can
    publish a complete snapshot without a second round trip. Neither may touch
    the conversation's `lastSeq` or activity timestamp - a reaction is not a
    message, so it must not reorder the conversation list or move the
    `Last-Event-ID` baseline. Only `addMessage` bumps those.
13. **`listReactionsByMessageIds` is batched and ordered.** All reactions on
    the given messages in **one** query (a page of messages, not one call per
    message), sorted ascending by `createdAt` so core's aggregated `userIds`
    come out earliest-first. Unknown ids are simply absent; an empty input
    array returns `[]` without touching the database - the same rule
    `getMessagesByIds` follows.
14. **Group creation is atomic and never find-or-create.**
    `createGroupConversation` always inserts a **new** conversation (generate
    the id, `pairKey: null`, `type: "group"`) plus one participant row per
    member, in a single transaction: a half-created group with no participants
    is unrecoverable, since nobody can read it to fix it. Core hands you a
    de-duplicated `userIds` that excludes the creator, and the creator must be
    written as `role: "admin"` while everyone else is `"member"` - do not
    reorder, and do not attempt uniqueness on membership.
15. **Membership writes are idempotent, and never clobber a role.**
    `addParticipants` inserts only ids that are absent (unique index on
    `(conversationId, userId)` + on-conflict-**do-nothing**, not
    do-update): a replayed request must not reset an admin back to `member`.
    `removeParticipant` for someone who is not a participant is a silent
    no-op, and it **never touches their messages** - history outlives
    membership. `setParticipantRole` throws when the target is not a
    participant (core has already checked, so this is a corruption signal, not
    a user error). None of these may bump `lastSeq` or the activity
    timestamp - a membership change is not a message, exactly like a reaction
    (invariant 12).
16. **Adapters never enforce group policy.** Core owns the participant cap, the
    name length, and the last-admin rule; it validates before calling you.
    Store what you are given. Adapters that re-check will drift from core and
    reject valid writes after a core upgrade.

17. **Optional invites: consumption is atomic, join requests are unique per
    pair.** If you implement the `invites` namespace, `consumeInvite` must
    check usability and increment `uses` in a **single** statement (see Level 2)
    - a read-then-write lets two redemptions of a `maxUses: 1` link both
    succeed, which is the same class of bug as a non-atomic `seq`.
    `getInvite` must still return expired and exhausted invites so core can
    tell 404 from 410. `createJoinRequest` **upserts** on
    `(conversationId, userId)`, clearing `resolvedAt`/`resolvedBy`. Store the
    `code` core hands you verbatim - never generate or re-derive it.

18. **`visibility`/`joinPolicy` round-trip, and coerce on read.** Both are
    required fields on every conversation, always supplied by core on create and
    update, and must read back as the exact value written. Narrow anything
    outside the two unions to `"private"` / `"approval"` when reading - a text
    column holds whatever a migration put there, and failing closed keeps a
    private group private. The optional `channels` namespace adds only
    `listPublicConversations`, which must return `type: "group"` **and**
    `visibility: "public"` rows in `listConversations` order.

19. **`setMessageMentions` replaces the whole set, and is total.** It is not an
    add: after the call, the message's mentions are **exactly** the `userIds`
    core handed you - insert the new, delete everything else for that message,
    in one transaction. An empty array means delete them all (`NOT IN ()` is not
    valid SQL, so drop the predicate rather than building an empty one). Rows
    that survive a replace must keep their original `createdAt` - re-stamping
    them reorders mentions that did not change. Enforce uniqueness on
    `(messageId, userId)` in the database (insert-on-conflict-do-nothing), like
    reactions, and return **nothing**: core supplied the set, so a post-write
    select is pure cost. And as with reactions, never touch `lastSeq` or the
    activity timestamp - a mention is not a message.

20. **`listMentionsByMessageIds` is batched and ordered `(createdAt, userId)`.**
    One query for a whole page, ascending by `createdAt` **with `userId` as the
    tiebreak**. The tiebreak is not decoration: a set written in one call shares
    a timestamp, so without it the row order is undefined and two adapters
    return the same mentions in different orders. Empty input returns `[]`
    without a query (invariant 13's rule again).

## Level 2 - reference realization (Postgres SQL)

The official Postgres schema. If your store speaks SQL, use it as-is; if not,
translate the shapes and satisfy the Level-1 invariants instead. Also
available programmatically: `import { migrationSql, chatpackSchema } from
"@chatpack/adapter-drizzle"` (`migrationSql` is plain idempotent DDL - no
Drizzle required to execute it).

```sql
CREATE TABLE IF NOT EXISTS "chatpack_conversations" (
  "id" text PRIMARY KEY,
  "type" text NOT NULL DEFAULT 'direct',
  "pair_key" text,                          -- NULL for groups
  "name" text,                              -- groups only
  "visibility" text NOT NULL DEFAULT 'private',
  "join_policy" text NOT NULL DEFAULT 'approval',
  "created_at" timestamptz NOT NULL,
  "metadata" jsonb NOT NULL DEFAULT '{}',
  "last_seq" integer NOT NULL DEFAULT 0,
  "last_activity_at" timestamptz NOT NULL
);
-- Upgrade path (the CREATE TABLE above no-ops on an existing table):
ALTER TABLE "chatpack_conversations"
  ADD COLUMN IF NOT EXISTS "type" text NOT NULL DEFAULT 'direct';
ALTER TABLE "chatpack_conversations"
  ADD COLUMN IF NOT EXISTS "name" text;
ALTER TABLE "chatpack_conversations"
  ALTER COLUMN "pair_key" DROP NOT NULL;
-- Channels (ADR 0020). The defaults are what make this a safe upgrade: every
-- row written before the migration reads back private and approval-gated.
ALTER TABLE "chatpack_conversations"
  ADD COLUMN IF NOT EXISTS "visibility" text NOT NULL DEFAULT 'private';
ALTER TABLE "chatpack_conversations"
  ADD COLUMN IF NOT EXISTS "join_policy" text NOT NULL DEFAULT 'approval';
-- The pair-key index becomes PARTIAL so unlimited null-keyed groups coexist
-- with one-per-pair DMs. A partial index cannot replace a total one under the
-- same name (CREATE ... IF NOT EXISTS would silently keep the old one), hence
-- the drop-and-rename.
DROP INDEX IF EXISTS "chatpack_conversations_pair_key_idx";
CREATE UNIQUE INDEX IF NOT EXISTS "chatpack_conversations_pair_key_unique_idx"
  ON "chatpack_conversations" ("pair_key") WHERE "pair_key" IS NOT NULL;
CREATE INDEX IF NOT EXISTS "chatpack_conversations_activity_idx"
  ON "chatpack_conversations" ("last_activity_at", "id");
-- The channel directory sorts by the same keyset as listConversations, so it
-- gets the same index shape - but PARTIAL, so browsing never pays to sort
-- every DM in the table.
CREATE INDEX IF NOT EXISTS "chatpack_conversations_public_idx"
  ON "chatpack_conversations" ("last_activity_at", "id") WHERE "visibility" = 'public';

CREATE TABLE IF NOT EXISTS "chatpack_conversation_participants" (
  "conversation_id" text NOT NULL REFERENCES "chatpack_conversations"("id") ON DELETE CASCADE,
  "user_id" text NOT NULL,
  "role" text NOT NULL DEFAULT 'member',
  "joined_at" timestamptz NOT NULL,
  "last_read_message_id" text
);
ALTER TABLE "chatpack_conversation_participants"
  ADD COLUMN IF NOT EXISTS "role" text NOT NULL DEFAULT 'member';
-- Both participants of a DM are admins; the column default is 'member', so
-- pre-existing rows need a backfill. Idempotent: the second run matches nothing.
UPDATE "chatpack_conversation_participants" AS p
  SET "role" = 'admin'
  WHERE "role" = 'member'
    AND EXISTS (
      SELECT 1 FROM "chatpack_conversations" AS c
      WHERE c."id" = p."conversation_id" AND c."type" = 'direct'
    );
CREATE UNIQUE INDEX IF NOT EXISTS "chatpack_participants_conv_user_idx"
  ON "chatpack_conversation_participants" ("conversation_id", "user_id");
CREATE INDEX IF NOT EXISTS "chatpack_participants_user_idx"
  ON "chatpack_conversation_participants" ("user_id");

CREATE TABLE IF NOT EXISTS "chatpack_messages" (
  "id" text PRIMARY KEY,
  "conversation_id" text NOT NULL REFERENCES "chatpack_conversations"("id") ON DELETE CASCADE,
  "sender_id" text NOT NULL,
  "body" text NOT NULL,
  "role" text NOT NULL DEFAULT 'user',
  "seq" bigint NOT NULL,
  "created_at" timestamptz NOT NULL,
  "edited_at" timestamptz,
  "deleted_at" timestamptz,
  "reply_to_message_id" text,
  -- Forward provenance (ADR 0024): three frozen ids, no foreign keys.
  "forwarded_from_message_id" text,
  "forwarded_from_conversation_id" text,
  "forwarded_from_sender_id" text,
  "metadata" jsonb NOT NULL DEFAULT '{}'
);
-- Upgrade path: the CREATE TABLE above is a no-op on an existing table, so
-- each added column needs its own idempotent statement.
ALTER TABLE "chatpack_messages"
  ADD COLUMN IF NOT EXISTS "reply_to_message_id" text;
ALTER TABLE "chatpack_messages"
  ADD COLUMN IF NOT EXISTS "forwarded_from_message_id" text;
ALTER TABLE "chatpack_messages"
  ADD COLUMN IF NOT EXISTS "forwarded_from_conversation_id" text;
ALTER TABLE "chatpack_messages"
  ADD COLUMN IF NOT EXISTS "forwarded_from_sender_id" text;
CREATE UNIQUE INDEX IF NOT EXISTS "chatpack_messages_conv_seq_idx"
  ON "chatpack_messages" ("conversation_id", "seq");
-- "What was forwarded from this message" - not a query core makes, but the one
-- an app builds a share count on. PARTIAL, because a btree indexes NULLs and
-- almost every message is not a forward.
CREATE INDEX IF NOT EXISTS "chatpack_messages_forwarded_from_idx"
  ON "chatpack_messages" ("forwarded_from_message_id")
  WHERE "forwarded_from_message_id" IS NOT NULL;

-- Search index (optional capability). Superseded an earlier trigram index.
DROP INDEX IF EXISTS "chatpack_messages_body_search_idx";
CREATE TABLE IF NOT EXISTS "chatpack_message_search_tokens" (
  "message_id" text NOT NULL REFERENCES "chatpack_messages"("id") ON DELETE CASCADE,
  "token" text NOT NULL,
  "occurrences" integer NOT NULL,
  PRIMARY KEY ("message_id", "token")
);
CREATE INDEX IF NOT EXISTS "chatpack_message_search_tokens_token_idx"
  ON "chatpack_message_search_tokens" ("token", "message_id");

CREATE TABLE IF NOT EXISTS "chatpack_message_reactions" (
  "message_id" text NOT NULL REFERENCES "chatpack_messages"("id") ON DELETE CASCADE,
  "user_id" text NOT NULL,
  "emoji" text NOT NULL,
  "created_at" timestamptz NOT NULL
);
CREATE UNIQUE INDEX IF NOT EXISTS "chatpack_reactions_msg_user_emoji_idx"
  ON "chatpack_message_reactions" ("message_id", "user_id", "emoji");
CREATE INDEX IF NOT EXISTS "chatpack_reactions_message_idx"
  ON "chatpack_message_reactions" ("message_id", "created_at");

-- Mentions (ADR 0023). Its own table rather than a text[] on the message: the
-- unique index is what makes a mention set a set, and "messages that mention
-- me" is the query every app eventually writes.
CREATE TABLE IF NOT EXISTS "chatpack_message_mentions" (
  "message_id" text NOT NULL REFERENCES "chatpack_messages"("id") ON DELETE CASCADE,
  "user_id" text NOT NULL,                  -- never a FK: you own the users table
  "created_at" timestamptz NOT NULL
);
CREATE UNIQUE INDEX IF NOT EXISTS "chatpack_mentions_msg_user_idx"
  ON "chatpack_message_mentions" ("message_id", "user_id");
CREATE INDEX IF NOT EXISTS "chatpack_mentions_message_idx"
  ON "chatpack_message_mentions" ("message_id", "created_at");
-- Core never runs this query - a mention inbox is out of scope - but adding the
-- index after the table is large means locking it, so it ships now.
CREATE INDEX IF NOT EXISTS "chatpack_mentions_user_idx"
  ON "chatpack_message_mentions" ("user_id", "created_at");

-- Optional invite capability (ADR 0019). Pure table additions: no column
-- changes and no index swaps, so this is safe to run before deploying.
CREATE TABLE IF NOT EXISTS "chatpack_conversation_invites" (
  "code" text PRIMARY KEY,                  -- the identity AND the secret
  "conversation_id" text NOT NULL REFERENCES "chatpack_conversations"("id") ON DELETE CASCADE,
  "created_by" text NOT NULL,
  "created_at" timestamptz NOT NULL,
  "expires_at" timestamptz,                 -- NULL never expires
  "max_uses" integer,                       -- NULL is unlimited
  "uses" integer NOT NULL DEFAULT 0,
  "requires_approval" boolean NOT NULL DEFAULT false,
  "metadata" jsonb NOT NULL DEFAULT '{}'
);
CREATE INDEX IF NOT EXISTS "chatpack_invites_conversation_idx"
  ON "chatpack_conversation_invites" ("conversation_id", "created_at");

CREATE TABLE IF NOT EXISTS "chatpack_join_requests" (
  "id" text PRIMARY KEY,
  "conversation_id" text NOT NULL REFERENCES "chatpack_conversations"("id") ON DELETE CASCADE,
  "user_id" text NOT NULL,
  "status" text NOT NULL DEFAULT 'pending', -- pending | approved | denied
  "message" text,
  "invite_code" text,                       -- no FK: outlives a revoked invite
  "created_at" timestamptz NOT NULL,
  "resolved_at" timestamptz,
  "resolved_by" text,
  "metadata" jsonb NOT NULL DEFAULT '{}'
);
-- The arbiter of "one request per user per group": the upsert targets this.
CREATE UNIQUE INDEX IF NOT EXISTS "chatpack_join_requests_conv_user_idx"
  ON "chatpack_join_requests" ("conversation_id", "user_id");
CREATE INDEX IF NOT EXISTS "chatpack_join_requests_status_idx"
  ON "chatpack_join_requests" ("conversation_id", "status", "created_at");

-- Optional moderation capability (ADR 0021). Four pure table additions: no
-- column changes and no index swaps, so this is safe to run before deploying.
CREATE TABLE IF NOT EXISTS "chatpack_user_blocks" (
  "blocker_user_id" text NOT NULL,
  "blocked_user_id" text NOT NULL,
  "created_at" timestamptz NOT NULL,
  PRIMARY KEY ("blocker_user_id", "blocked_user_id")
);
CREATE INDEX IF NOT EXISTS "chatpack_user_blocks_blocker_idx"
  ON "chatpack_user_blocks" ("blocker_user_id", "created_at");
CREATE TABLE IF NOT EXISTS "chatpack_conversation_mutes" (
  "user_id" text NOT NULL,
  "conversation_id" text NOT NULL
    REFERENCES "chatpack_conversations"("id") ON DELETE CASCADE,
  "created_at" timestamptz NOT NULL,
  PRIMARY KEY ("user_id", "conversation_id")
);
CREATE INDEX IF NOT EXISTS "chatpack_conversation_mutes_user_idx"
  ON "chatpack_conversation_mutes" ("user_id", "created_at");
-- "evidence" is a snapshot core builds at filing time. Store it verbatim: a
-- later edit or delete must not be able to launder the report.
CREATE TABLE IF NOT EXISTS "chatpack_moderation_reports" (
  "id" text PRIMARY KEY,
  "reporter_user_id" text NOT NULL,
  "target_type" text NOT NULL,
  "target_id" text NOT NULL,
  "reason" text NOT NULL,
  "status" text NOT NULL DEFAULT 'open',
  "moderator_note" text,
  "evidence" jsonb NOT NULL,
  "created_at" timestamptz NOT NULL,
  "updated_at" timestamptz NOT NULL
);
CREATE INDEX IF NOT EXISTS "chatpack_moderation_reports_queue_idx"
  ON "chatpack_moderation_reports" ("status", "created_at", "id");
-- Backs the "reuse an open or triaged report for the same reporter+target" rule.
CREATE INDEX IF NOT EXISTS "chatpack_moderation_reports_target_idx"
  ON "chatpack_moderation_reports"
     ("reporter_user_id", "target_type", "target_id", "status");
-- No unique index can express "one ACTIVE ban" (active = unrevoked and
-- unexpired), so createBan puts the condition in the insert instead.
CREATE TABLE IF NOT EXISTS "chatpack_user_bans" (
  "id" text PRIMARY KEY,
  "user_id" text NOT NULL,
  "created_by_user_id" text NOT NULL,
  "reason" text,
  "created_at" timestamptz NOT NULL,
  "expires_at" timestamptz,
  "revoked_at" timestamptz,
  "revoked_by_user_id" text
);
CREATE INDEX IF NOT EXISTS "chatpack_user_bans_active_idx"
  ON "chatpack_user_bans" ("user_id", "revoked_at", "expires_at");
CREATE INDEX IF NOT EXISTS "chatpack_user_bans_created_idx"
  ON "chatpack_user_bans" ("created_at", "id");
```

`reply_to_message_id` deliberately has **no foreign key**: a reply must outlive
its parent, and messages are only ever soft-deleted anyway. The three
`forwarded_from_*` columns have none for a stronger version of the same reason -
a forward is a **copy** living in a conversation that may have no overlap with
the source's participants, so a cascade from the source would delete other
people's messages.

**Existing Postgres deployments must re-run the migration before upgrading** -
every statement is `IF NOT EXISTS` / `ADD COLUMN IF NOT EXISTS`, so re-running
the whole script is safe and preserves data and seq counters.

How the reference implementation satisfies the two hard invariants
(ADR 0007 in `docs/decisions/`):

- **Atomic `seq`** - one statement, row-locked by Postgres:

  ```sql
  UPDATE chatpack_conversations
  SET last_seq = last_seq + 1, last_activity_at = $now
  WHERE id = $conversationId
  RETURNING last_seq;
  ```

  then insert the message with the returned value. The unique index on
  `(conversation_id, seq)` backstops the invariant. On Supabase/PostgREST you
  cannot express this UPDATE through the client - wrap it in a SQL function
  and call it via RPC.

- **Idempotent pair creation** - `INSERT ... ON CONFLICT (pair_key) WHERE
  pair_key IS NOT NULL DO NOTHING`, then re-select by `pair_key`; zero inserted
  rows means a concurrent call won and both converge on the same row. The
  `WHERE` clause is load-bearing, not decorative: the index is partial, and
  Postgres only matches an `ON CONFLICT` target to a partial index when the
  predicate is repeated. Omit it and **every DM insert** fails with "there is no
  unique or exclusion constraint matching the ON CONFLICT specification".

- **One active ban under concurrency** - the same "one statement" shape, but the
  predicate can't live in an index, so it lives in the insert:

  ```sql
  INSERT INTO chatpack_user_bans (...)
  SELECT $id, $userId, ...
  WHERE NOT EXISTS (
    SELECT 1 FROM chatpack_user_bans
    WHERE user_id = $userId AND revoked_at IS NULL
      AND (expires_at IS NULL OR expires_at > $now)
  );
  ```

  then re-select the active ban; zero inserted rows means a concurrent
  moderator won and both converge on the same row.

- **Group creation** takes the opposite path: a plain `INSERT` (no conflict
  target - a group is always new) for the conversation plus the participant
  rows, both inside one `db.transaction`.

- **Idempotent member adds** - same shape as reactions, keyed on the
  membership pair:

  ```sql
  INSERT INTO chatpack_conversation_participants
    (conversation_id, user_id, role, joined_at)
  VALUES ($conversationId, $userId, 'member', $now)
  ON CONFLICT (conversation_id, user_id) DO NOTHING;
  ```

  `DO NOTHING`, never `DO UPDATE`: a replayed add must not reset an existing
  admin to `member` (invariant 15). And as with reactions, note what is
  *absent* - no `UPDATE chatpack_conversations`.

- **Idempotent reacting** - same shape, one statement, then re-select the
  message's set:

  ```sql
  INSERT INTO chatpack_message_reactions (message_id, user_id, emoji, created_at)
  VALUES ($messageId, $userId, $emoji, $now)
  ON CONFLICT (message_id, user_id, emoji) DO NOTHING;
  ```

  Note what is *absent*: no `UPDATE chatpack_conversations`. Reacting must not
  advance `last_seq` or `last_activity_at` (invariant 12).

- **Atomic invite consumption** (invariant 17) - the check and the increment in
  one statement, so two simultaneous redemptions of a one-use link cannot both
  win:

  ```sql
  UPDATE chatpack_conversation_invites
  SET uses = uses + 1
  WHERE code = $code
    AND (max_uses IS NULL OR uses < max_uses)
    AND (expires_at IS NULL OR expires_at > now())
  RETURNING *;
  ```

  Zero rows returned = no longer usable (return `null`; core raises 410). Never
  `SELECT` then `UPDATE` - that is the same race as a non-atomic `seq`.

- **Upserting a join request** - one row per user per group, with the resolution
  fields explicitly cleared so a re-ask doesn't look decided:

  ```sql
  INSERT INTO chatpack_join_requests (...)
  VALUES (...)
  ON CONFLICT (conversation_id, user_id) DO UPDATE
  SET status = 'pending', message = $message, invite_code = $inviteCode,
      created_at = $now, resolved_at = NULL, resolved_by = NULL;
  ```

  `DO UPDATE` here, unlike member adds: replacing a denied row with a fresh
  pending one is exactly the intent (invariant 17).

### Non-SQL platforms (Convex, Firestore, ...)

Ignore the SQL; keep the five-collection shape (plus two more if you implement
invites) and satisfy Level 1 with your
platform's transaction primitive. Example - on Convex, each adapter method
becomes a Convex query/mutation (DB access only exists inside Convex
functions) and the `StorageAdapter` object calls them through the Convex
client; `addMessage` is a single mutation (read counter → increment → insert),
which is automatically a serializable transaction, satisfying invariant 2
with no extra machinery. Enforce invariant 1 with an index/lookup on
`pairKey` inside one mutation (skipping the check when `pairKey` is null, since
groups are never deduplicated), invariant 12 with a lookup on the
`(messageId, userId, emoji)` triple inside the reaction mutation, and
invariants 14-15 by making group creation one mutation and looking up
`(conversationId, userId)` before inserting a participant. If you implement
invites, invariant 17 needs `consumeInvite` to be one mutation that reads the
row, checks usability, and writes the incremented `uses` - which is where a
serializable-transaction platform gives you atomicity for free.

## Skeleton

```ts
import type { StorageAdapter } from "@chatpack/core";

export function myAdapter(client: MyDbClient): StorageAdapter {
  return {
    async getOrCreateDirectConversation({ pairKey, userIds, metadata }) {
      // 1. Attempt atomic create (unique on pairKey; generate the id here).
      //    type: "direct", name: null, and BOTH participants role "admin".
      // 2. On conflict, fetch the existing conversation by pairKey.
      // return { conversation, created };
    },
    async createGroupConversation({
      creatorId,
      userIds,
      name,
      metadata,
      visibility,
      joinPolicy,
    }) {
      // ALWAYS a new conversation: generate the id, type "group",
      // pairKey null. One transaction: the conversation row + the creator as
      // "admin" + each of userIds as "member" (already de-duplicated and
      // creator-free). Never find-or-create.
      // visibility/joinPolicy are always resolved by core - store them as
      // given (invariant 18).
      // return conversation;
    },
    async getConversation(conversationId) {
      // Fetch conversation + ALL participant rows, or return null. Narrow
      // visibility/joinPolicy to their unions on the way out - fail closed to
      // "private"/"approval" (invariant 18).
    },
    async listConversations({ userId, limit, cursor }) {
      // Conversations where userId is a participant, most-recently-active
      // first; keyset-paginate; you define the cursor encoding.
      // return { conversations, nextCursor }; // nextCursor: string | null
    },
    async updateConversation({ conversationId, name, visibility, joinPolicy }) {
      // Set the name (a string or null) plus both channel fields - core
      // resolves all three, so write all three. Throw if the id is unknown.
      // return updatedConversation; // with participants
    },
    async addParticipants({ conversationId, userIds }) {
      // Insert-on-conflict-DO-NOTHING per id as role "member" - a replayed
      // add must not demote an existing admin (invariant 15).
      // return updatedConversation;
    },
    async removeParticipant({ conversationId, userId }) {
      // Delete that one membership row; absent = silent no-op. Leave their
      // messages alone.
      // return updatedConversation;
    },
    async setParticipantRole({ conversationId, userId, role }) {
      // Set that participant's role; throw if they are not a participant.
      // return updatedConversation;
    },
    async addMessage({ conversationId, senderId, body, role, replyToMessageId, metadata }) {
      // Atomically bump the conversation's seq counter and insert the
      // message with that seq (single transaction / RPC / mutation).
      // Store replyToMessageId verbatim - core already validated it.
      // Same for the three forwardedFrom* fields (ADR 0024): copy them through
      // as plain nullable columns; a forward is otherwise an ordinary message.
      // return message; // with adapter-generated id and real Date fields
    },
    async getMessage(messageId) {
      // Fetch by id, or return null.
    },
    async getMessagesByIds(messageIds) {
      // One batched fetch. Unknown ids are simply absent (no nulls, no throw);
      // [] in -> [] out without hitting the database. Order is irrelevant.
      // return messages;
    },
    async listMessages({ conversationId, limit, cursor }) {
      // Descending seq; cursor = e.g. String(lastMessage.seq).
      // return { messages, nextCursor };
    },
    async listMessagesAfterSeq({ conversationId, afterSeq, limit }) {
      // Ascending seq, seq > afterSeq, up to limit. Powers gap-fill.
      // return messages;
    },
    async updateMessage({ messageId, body, editedAt, deletedAt }) {
      // Patch ONLY the defined fields; throw if messageId is unknown.
      // return updatedMessage;
    },
    async updateLastRead({ conversationId, userId, messageId }) {
      // Set that participant's lastReadMessageId.
    },
    async countUnread({ userId, conversationIds }) {
      // For each conversation: count messages with seq > the seq of this
      // user's lastReadMessageId (null -> 0) AND senderId !== userId.
      // Tombstones count. One batched query, not one per id (invariant 10).
      // return { [conversationId]: count };
    },
    // Optional capability. Omit this method when backend search is not available.
    async searchMessages({ userId, query, limit, cursor }) {
      // Search only conversations where userId participates. Exclude
      // tombstones, match case-insensitively, rank deterministically, and
      // return an opaque cursor.
      // return { messages, nextCursor };
    },
    async addReaction({ messageId, userId, emoji }) {
      // Insert-on-conflict-do-nothing on the (messageId, userId, emoji)
      // triple, then return ALL reactions on the message (invariant 12).
      // Do NOT touch the conversation's seq counter or activity timestamp.
      // return reactions;
    },
    async removeReaction({ messageId, userId, emoji }) {
      // Delete that one triple (absent = no-op), return the remaining set.
      // return reactions;
    },
    async listReactionsByMessageIds(messageIds) {
      // One batched query for a whole page, ascending createdAt so core's
      // aggregated userIds come out earliest-first. [] in -> [] out.
      // return reactions;
    },
    async setMessageMentions({ messageId, userIds }) {
      // REPLACE, not add (invariant 19): in ONE transaction, insert-on-
      // conflict-do-nothing for userIds and delete every other mention row on
      // this message. userIds: [] means delete them all. Do not re-stamp
      // createdAt on rows that survive, and do not touch the conversation's
      // seq counter or activity timestamp. Return nothing.
    },
    async listMentionsByMessageIds(messageIds) {
      // One batched query, ascending (createdAt, userId) - the userId tiebreak
      // matters because a set written in one call shares a timestamp
      // (invariant 20). [] in -> [] out.
      // return mentions;
    },
    // Optional capability (ADR 0019). Omit the WHOLE namespace or implement
    // all nine - core checks for `invites`, not for individual methods.
    invites: {
      async createInvite(input) {
        // Store input.code VERBATIM as the primary key - core generated it.
        // uses starts at 0. return invite;
      },
      async getInvite(code) {
        // Return expired/exhausted invites too, or null. Core needs both to
        // tell 404 from 410.
      },
      async listInvites(conversationId) {
        // That group's invites, newest-first, including spent ones.
      },
      async deleteInvite({ conversationId, code }) {
        // Scoped by conversationId AND idempotent: zero rows is success.
      },
      async consumeInvite(code) {
        // ONE statement: check usability and increment uses together
        // (invariant 17). Zero rows affected -> return null. return invite;
      },
      async createJoinRequest(input) {
        // UPSERT on (conversationId, userId): status "pending", and clear
        // resolvedAt/resolvedBy so a re-ask doesn't look decided.
      },
      async getJoinRequest({ conversationId, userId }) {
        // That pair's request whatever its status, or null.
      },
      async listJoinRequests({ conversationId, status, limit }) {
        // Newest-first, filtered by status when given.
      },
      async resolveJoinRequest({ conversationId, userId, status, resolvedBy, resolvedAt }) {
        // Write the decision; core already checked it exists and is pending,
        // and adds the participant itself. Throw if the row is gone.
      },
    },
    // Optional capability (ADR 0020). One method, and omitting the namespace
    // also stops core from SETTING a non-default visibility/joinPolicy - so a
    // channel can never be created that no directory can find.
    channels: {
      async listPublicConversations({ limit, cursor }) {
        // type === "group" AND visibility === "public", in listConversations
        // order with the same cursor contract. Filter on BOTH: a hand-edited
        // row must not leak a DM into a public directory. Core narrows each
        // row to a thin ChannelPreview itself.
        // return { conversations, nextCursor };
      },
    },
  };
}
```

## Pitfalls (each of these has bitten a real integration)

- Checking pair existence in JS before inserting (races; use DB uniqueness).
- `MAX(seq) + 1` computed in application code (races; use an atomic counter).
- Returning ISO strings where the contract says `Date`.
- Hard-deleting messages, or dropping `seq`/row on delete (must tombstone).
- `listMessages` returned oldest-first (must be newest-first), or
  `listMessagesAfterSeq` returned newest-first (must be oldest-first).
- Stubbing `nextCursor` as always-`null` - pagination silently breaks once
  history exceeds one page.
- Exposing `chatpack_*` tables to browser/anon database clients (bypasses
  Chatpack's permission layer; adapter must be server-only with privileged
  credentials).
- Adding a foreign key to the app's users table (Chatpack never owns users).
- Enforcing "is sender a participant?" in the adapter (core already did).
- Counting the viewer's own messages as unread in `countUnread` (they never
  are), or issuing one count query per conversation (N+1; batch the page).
- Checking "did this user already react?" in JS before inserting (races; use a
  unique index + on-conflict-do-nothing), or throwing on a duplicate react /
  a missing unreact instead of treating both as no-ops.
- Returning only the changed reaction from `addReaction`/`removeReaction`
  instead of the message's whole set - core publishes that set as a snapshot,
  so a delta silently blanks other users' reactions in every client.
- Bumping the conversation's activity timestamp or `lastSeq` on a reaction
  (reorders the conversation list and poisons `Last-Event-ID` gap-fill).
- Adding a foreign key from `reply_to_message_id` to messages (a reply must
  outlive its parent), or validating the parent in the adapter (core did).
- Returning `null` entries or throwing for unknown ids in `getMessagesByIds` /
  `listReactionsByMessageIds` (unknown ids are simply absent), or hitting the
  database at all when the input array is empty.
- Leaving the pair-key unique index **total** after adding groups, so the second
  null-keyed group collides - or making it partial but forgetting to repeat the
  predicate in `ON CONFLICT`, which breaks **every DM** with "no unique or
  exclusion constraint matching the ON CONFLICT specification" (invariant 1).
- Making `createGroupConversation` find-or-create, or inserting the conversation
  and its participants in two separate round trips (a crash between them leaves
  a group nobody can read, let alone repair).
- `ON CONFLICT ... DO UPDATE` in `addParticipants`, which demotes an admin every
  time a client retries the request.
- Throwing on a duplicate add or an absent removal instead of treating both as
  no-ops - or hard-deleting a departed member's messages (history outlives
  membership).
- Re-checking core's group policy (participant cap, name length, last-admin) in
  the adapter, or defaulting a DM's participants to `member` (both DM
  participants are `admin`).
- Bumping the conversation's activity timestamp or `lastSeq` on a membership
  change (same trap as reactions: it reorders the list and poisons gap-fill).
- `SELECT` an invite, check `uses < maxUses` in JS, then `UPDATE` - the same race
  as a non-atomic `seq`, except here it hands a one-use link to two strangers.
  `consumeInvite` must be one statement (invariant 17).
- Filtering expired invites out of `getInvite`, which turns every 410 ("that link
  expired, ask for a new one") into a 404 ("no such link").
- Implementing `getInvite`/`consumeInvite` but omitting, say, `listInvites`: core
  checks for the `invites` namespace, not for individual methods, so a partial
  namespace crashes instead of reporting 501.
- Ignoring `conversationId` in `deleteInvite`, letting one group's admin revoke
  another group's links.
- `ON CONFLICT ... DO NOTHING` in `createJoinRequest` (the opposite of
  `addParticipants`): a user denied last week must be able to ask again, so the
  upsert has to reset `status` to `pending` and clear `resolvedAt`/`resolvedBy`.
- Generating the invite code in the adapter, or hashing/normalizing the one core
  passed in - the code stored must be byte-identical to the one in the URL.
- Accepting `visibility`/`joinPolicy` on create but forgetting them in
  `updateConversation` (or vice versa), so a group can be published once and
  never unpublished - or writing only the field that changed, when core resolves
  and sends all three every time.
- Passing an unrecognized `visibility` straight through from the column instead
  of narrowing it. `"Public"`, `"publik"`, or a leftover value from a hand-run
  migration must read back as `"private"`: fail closed, or a private group
  quietly becomes browsable (invariant 18).
- `listPublicConversations` filtering on `visibility` but not on `type`, which
  puts a DM in the directory the moment one row is edited by hand.
- Ordering the directory differently from `listConversations` (or reusing the
  cursor from one in the other): both are keyset paginations over
  `(lastActivityAt, id)`, and a client that mixes them will skip or repeat rows.
- Leaving the public index **total** rather than partial - it works, but every
  directory page then sorts every DM in the table.
- Treating `setMessageMentions` as an **add**. It is a replace: leftover rows
  mean an edit that removes a mention silently keeps notifying that person
  (invariant 19). The delete-the-complement half is not optional.
- Building `NOT IN ()` for an empty `userIds` - not valid SQL. Drop the
  predicate so the empty set deletes every row for that message.
- Re-stamping `createdAt` on mentions that survive a replace, which reorders a
  set that did not change - and, with the `(createdAt, userId)` read order, makes
  the same message's `mentions` array shuffle on every unrelated edit.
- Omitting the `userId` tiebreak from `listMentionsByMessageIds`. Every row in
  one write shares a timestamp, so `ORDER BY created_at` alone leaves the order
  to the planner and two adapters disagree (invariant 20).
- Re-validating mentions in the adapter against current membership. Core
  validated once, at claim time, and deliberately grandfathers a mention of
  someone who has since left.
- A foreign key on `forwarded_from_message_id`, or a cascade from the source
  conversation. A forward is a copy in someone else's conversation; cascading
  deletes their messages when the source is cleaned up.
- Leaving `chatpack_messages_forwarded_from_idx` **total** rather than partial:
  a btree indexes NULLs, and almost every message is not a forward.

## Verify your adapter

Run these checks against your implementation before calling it done. All of
them go through the normal Chatpack API (`chat.api.*` or the HTTP routes) -
if any fails, the bug is in the adapter.

1. **Round trip.** Create a conversation (A→B), send a message, restart the
   process (or hit a fresh serverless isolate), list messages - the message
   is still there with the same `id`, `seq: 1`, and `createdAt` as a valid
   timestamp.
2. **Pair idempotency, both directions.** `getOrCreateConversation(A→B)` then
   `(B→A)` - same conversation id both times, and only one row/document
   exists.
3. **Pair idempotency, concurrent.** Fire 5+ parallel
   `getOrCreateConversation` calls for the same new pair - exactly one
   conversation exists afterwards.
4. **Seq under concurrent sends.** Fire 10 parallel `sendMessage` calls into
   one conversation - afterwards all 10 `seq` values are distinct and
   strictly increasing; no duplicates, no failures.
5. **Pagination walk.** Send 25 messages, list with `limit: 10`, follow
   `nextCursor` until `null` - you get exactly 25 unique messages,
   newest-first, no repeats, no gaps. Same walk for `listConversations`.
6. **Gap-fill.** After sending messages 1..N, `listMessagesAfterSeq` with
   `afterSeq: 3` returns 4..N oldest-first.
7. **Edit + soft delete.** Edit a message (body changes, `editedAt` set);
   delete it (body `""`, `deletedAt` set, still present in `listMessages`
   with its original `seq`); editing the deleted message now fails with
   `MESSAGE_DELETED`.
8. **Read-state.** `markRead` then re-fetch the conversation - that
   participant's `lastReadMessageId` is updated and survives a restart.
   Bonus: markRead with an OLDER message afterwards is a no-op (core
   enforces monotonicity; your adapter just stores what it's given).
9. **Unread counts.** B sends 3 messages; `getConversation` as A shows
   `unreadCount: 3`, as B shows `0` (own messages never count). A marks the
   2nd read - A now sees `1`. Delete the 3rd as B - A still sees `1`
   (tombstones count).
10. **Types at the boundary.** `createdAt instanceof Date` is `true` on
    returned conversations and messages (catches ISO-string leakage).
11. **Quote-reply round trip.** Send a parent, then a reply with
    `replyToMessageId` - the reply comes back with that pointer and a
    `replyTo` whose `excerpt` is the parent's body. Edit the parent: the
    excerpt on a **refetched** reply changes too (proves it is hydrated, not
    denormalized). Delete the parent: the reply survives with
    `replyTo.deleted: true` and an empty excerpt. A pointer at a message in
    another conversation is `MESSAGE_NOT_FOUND`.
12. **Reaction idempotency.** `addReaction` the same emoji twice as the same
    user - exactly one row exists and the returned set shows `count: 1`. Fire
    5 identical `addReaction` calls in parallel - still one row. Have the other
    participant add the same emoji - `count: 2` with both ids, earliest-first.
    `removeReaction` twice - the second is a silent no-op.
13. **Reactions do not disturb messages.** Note the conversation's list
    position and `unreadCount`, add and remove a reaction, re-list: identical
    ordering, identical unread counts, and the next message still gets the
    `seq` it would have had.
14. **Groups are not deduplicated.** `createGroupConversation` twice with the
    same members - two distinct ids, both readable, `pairKey: null` on both.
    Then `getOrCreateConversation(A→B)` still converges on one DM, proving the
    pair-key constraint survived (this is the check that catches a
    total-vs-partial index mistake).
15. **Group membership.** Create a group A(admin)+B, add C - three
    participants, C a `member`. Promote C to admin, then add C again: still
    `admin`, still one row. Remove B twice - the second is a silent no-op, B's
    messages are still in `listMessages`, and B now gets `FORBIDDEN_READ` on
    the conversation.
16. **Group unread + list.** With A, B, C in a group, B and C each send one
    message: A sees `unreadCount: 2`, B sees `1` (never their own). The group
    appears in all three users' `listConversations`, ordered by activity next
    to their DMs, and `type`/`name`/`role` survive a restart.
17. **Privilege check (hosted DBs).** With the browser/anon credentials, a
    direct read of `chatpack_messages`, `chatpack_message_reactions`,
    `chatpack_conversation_invites`, or
    `chatpack_conversation_participants` returns nothing/denied. Invite codes
    matter most here: a leaked table is a leaked set of live links.
18. **Invites, if you implemented them.** Mint a `maxUses: 1` link, then fire
    5 parallel `acceptInvite` calls as 5 different users - exactly one succeeds,
    `uses` is `1`, and the group gained exactly one member. Accept again as the
    user who got in: still `status: "joined"`, and `uses` is *still* `1`.
    Backdate `expires_at` by hand and accept - `INVITE_EXPIRED`, `uses`
    unchanged. Deny a join request, then have the same user ask again - one row,
    `status: "pending"`, `resolvedBy` back to `null`. Omit the `invites`
    namespace entirely and every invite route must be a clean 501, not a crash.
19. **Channels, if you implemented them.** Create a public `"open"` group, a
    public `"approval"` group, a private group, and a DM: `GET /channels` shows
    exactly the two public groups, newest-active first, and never a
    `participants` array. Join the open one - instant membership and a
    `participant.added` event; join the gated one - a pending request with
    `inviteCode: null`. Fire 5 parallel joins as the same user - one membership
    row. `UPDATE` the column to `'publik'` by hand: the conversation reads back
    `"private"` and drops out of the directory. Walk `?limit=1&cursor=` to the
    end - every public group exactly once. Omit the `channels` namespace and
    `GET /channels`, the join route, *and* any attempt to set a non-default
    `visibility` must all be a clean 501; explicitly sending the defaults must
    still work.
20. **Moderation, if you implemented it.** Block B as A: `isBlocked` is true in
    both directions, A and B can still read their old DM, and neither can write
    to it - but a shared group is unaffected. Block twice: one row. Report the
    same message twice as the same reporter: the same report id back, and the
    `evidence` body unchanged after the message is edited and deleted. Fire 2
    parallel `createBan` calls for one user - both return the same id, and
    `listBans({ activeOnly: false })` has exactly one row; revoke it and the user
    is unbanned. Revoke twice: `revokedByUserId` still names the first revoker.
    Backdate `expires_at` - the ban stops enforcing but stays in history. Omit
    the `moderation` namespace and every moderation route must be a clean 501,
    not a crash.
21. **Mentions replace, and survive an edit.** Send a message mentioning two
    participants - both come back, sorted, exactly two rows. Edit the body
    **without** sending `mentions`: both are still there. Edit with one of the
    two: exactly one row survives and its `created_at` is **unchanged**. Edit
    with `[]`: zero rows. Mention a non-participant: 400
    `MENTION_NOT_PARTICIPANT` and nothing was written. Remove a mentioned
    participant from the group, then re-edit the message with that same id -
    still accepted (grandfathered); a *different* departed id is rejected.
    Bonus: note the conversation's list position and `unreadCount` around all of
    this - a mention changes neither, and the next message still gets the `seq`
    it would have had.
22. **Forwarding is a copy.** Forward a message from a conversation the target's
    other participant is not in: the copy has your id as sender, the body
    verbatim, its own `seq`, and `forwardedFrom` with three ids. Now edit **and**
    delete the original - refetch the copy: byte-identical, `deletedAt: null`.
    Hard-delete the source conversation row: the copy still reads back with its
    provenance intact (proves no foreign key). Forward a tombstone: 409
    `MESSAGE_DELETED`. Forward as someone who cannot read the source:
    `FORBIDDEN_READ`; as someone who cannot write the target: `FORBIDDEN_WRITE`.
    Check that reactions, the reply pointer, mentions, metadata, and a
    non-default `role` on the source did **not** travel.

## Real-time plugins and custom adapters

`typing()`, `presence()`, `receipts()` publish **ephemeral events** on the
SSE stream - never stored, never replayed - so custom storage adapters need
**zero changes** to support them. If you implement a custom `Transport`,
note `publish`/`subscribe` carry
`TransportEvent = ChatEvent | ReactionEvent | ConversationEvent |
EphemeralEvent`. The union has **four** members, so `!isEphemeralEvent(e)` does
not mean "a message" - branch on `isMessageEvent(e)` wherever the message
snapshot matters (SSE `id:` frames, `receipts()` delivery ticks), and use
`isReactionEvent(e)` / `isConversationEvent(e)` for the other two, or a
reaction or membership change will be mistaken for a new message.
`PluginEventDeliveredContext.event` stays `ChatEvent`: plugins observe
message delivery only. Rationale: `docs/decisions/0008`,
`docs/decisions/0012`, and `docs/decisions/0017`.

For multi-node fan-out, use `@chatpack/transport-redis` rather than writing
your own (see the deployment table above). If you do write a custom
`Transport`, match its two rules: `publish` must be synchronous and must never
throw (the message is already stored - a fan-out failure must not fail the
sender), and any event crossing a process boundary must have its `Message`
date fields (`createdAt`/`editedAt`/`deletedAt`) revived into real `Date`
instances, since `JSON.stringify` turns them into strings and core does not
coerce. Rationale: `docs/decisions/0012`.

---

Full HTTP semantics: `@chatpack/core` README. ADRs (design rationale):
`docs/decisions/` in the repo. This file also ships inside every `@chatpack/*`
npm package (`node_modules/@chatpack/core/llms.txt`).

Stuck on something this file doesn't answer, or hit a wrong answer in it? Tell
the humans - Discord https://discord.gg/gY3GCTRv5Y (fastest), GitHub
Discussions https://github.com/chddaniel/chatpack/discussions, issues
https://github.com/chddaniel/chatpack/issues/new/choose. Docs
https://docs.chatpack.dev · updates https://x.com/chatpackdev.