nodmix 2026.5.25

package/docs/concepts/message-lifecycle-refactor.md

@@ -0,0 +1,1128 @@
+---
+summary: "Design plan for the unified durable message receive, send, preview, edit, and streaming lifecycle"
+read_when:
+  - Refactoring channel send or receive behavior
+  - Changing channel turn, reply dispatch, outbound queue, preview streaming, or plugin SDK message APIs
+  - Designing a new channel plugin that needs durable sends, receipts, previews, edits, or retries
+title: "Message lifecycle refactor"
+---
+
+This page is the target design for replacing scattered channel turn, reply
+dispatch, preview streaming, and outbound delivery helpers with one durable
+message lifecycle.
+
+The short version:
+
+- The core primitives should be **receive** and **send**, not **reply**.
+- A reply is only a relation on an outbound message.
+- A turn is an inbound-processing convenience, not the owner of delivery.
+- Sending must be context based: `begin`, render, preview or stream, final send,
+  commit, fail.
+- Receiving must be context based too: normalize, dedupe, route, record,
+  dispatch, platform ack, fail.
+- The public plugin SDK should collapse to one small channel-message surface.
+
+## Problems
+
+The current channel stack grew from several valid local needs:
+
+- Simple inbound adapters use `runtime.channel.turn.run`.
+- Rich adapters use `runtime.channel.turn.runPrepared`.
+- Legacy helpers use `dispatchInboundReplyWithBase`,
+  `recordInboundSessionAndDispatchReply`, reply payload helpers, reply chunking,
+  reply references, and outbound runtime helpers.
+- Preview streaming lives in channel-specific dispatchers.
+- Final delivery durability is being added around existing reply payload paths.
+
+That shape fixes local bugs, but it leaves Nodmix with too many public
+concepts and too many places where delivery semantics can drift.
+
+The reliability issue that exposed this is:
+
+```text
+Telegram polling update acked
+  -> assistant final text exists
+  -> process restarts before sendMessage succeeds
+  -> final response is lost
+```
+
+The target invariant is broader than Telegram: once core decides a visible
+outbound message should exist, the intent must be durable before the platform
+send is attempted, and the platform receipt must be committed after success.
+That gives Nodmix at-least-once recovery. Exactly-once behavior exists only
+for adapters that can prove native idempotency or reconcile an
+unknown-after-send attempt against platform state before replay.
+
+That is the end state for this refactor, not a description of every current
+path. During migration, existing outbound helpers can still fall through to a
+direct send when best-effort queue writes fail. The refactor is complete only
+when durable final sends fail closed or explicitly opt out with a documented
+non-durable policy.
+
+## Goals
+
+- One core lifecycle for all channel message receive and send paths.
+- Durable final sends by default in the new message lifecycle after an adapter
+  declares replay-safe behavior.
+- Shared preview, edit, stream, finalization, retry, recovery, and receipt
+  semantics.
+- A small plugin SDK surface that third-party plugins can learn and maintain.
+- Compatibility for existing `channel.turn` callers during migration.
+- Clear extension points for new channel capabilities.
+- No platform-specific branches in core.
+- No token-delta channel messages. Channel streaming remains message preview,
+  edit, append, or completed block delivery.
+- Structured Nodmix-origin metadata for operational/system output so visible
+  gateway failures do not re-enter shared bot-enabled rooms as fresh prompts.
+
+## Non goals
+
+- Do not remove `runtime.channel.turn.*` in the first phase.
+- Do not force every channel into the same native transport behavior.
+- Do not teach core Telegram topics, Slack native streams, Matrix redactions,
+  Feishu cards, QQ voice, or Teams activities.
+- Do not publish all internal migration helpers as stable SDK API.
+- Do not make retries replay completed non-idempotent platform operations.
+
+## Reference model
+
+Vercel Chat has a good public mental model:
+
+- `Chat`
+- `Thread`
+- `Channel`
+- `Message`
+- adapter methods such as `postMessage`, `editMessage`, `deleteMessage`,
+  `stream`, `startTyping`, and history fetches
+- a state adapter for dedupe, locks, queues, and persistence
+
+Nodmix should borrow the vocabulary, not copy the surface.
+
+What Nodmix needs beyond that model:
+
+- Durable outbound send intents before direct transport calls.
+- Explicit send contexts with begin, commit, and fail.
+- Receive contexts that know platform ack policy.
+- Receipts that survive restart and can drive edits, deletes, recovery, and
+  duplicate suppression.
+- A smaller public SDK. Bundled plugins can use internal runtime helpers, but
+  third-party plugins should see one coherent message API.
+- Agent-specific behavior: sessions, transcripts, block streaming, tool
+  progress, approvals, media directives, silent replies, and group mention
+  history.
+
+`thread.post()` style promises are not enough for Nodmix. They hide the
+transaction boundary that decides whether a send is recoverable.
+
+## Core model
+
+The new domain should live under an internal core namespace such as
+`src/channels/message/*`.
+
+It has four concepts:
+
+```typescript
+core.messages.receive(...)
+core.messages.send(...)
+core.messages.live(...)
+core.messages.state(...)
+```
+
+`receive` owns inbound lifecycle.
+
+`send` owns outbound lifecycle.
+
+`live` owns preview, edit, progress, and stream state.
+
+`state` owns durable intent storage, receipts, idempotency, recovery, locks, and
+dedupe.
+
+## Message terms
+
+### Message
+
+A normalized message is platform-neutral:
+
+```typescript
+type ChannelMessage = {
+  id: string;
+  channel: string;
+  accountId?: string;
+  direction: "inbound" | "outbound";
+  target: MessageTarget;
+  sender?: MessageActor;
+  body?: MessageBody;
+  attachments?: MessageAttachment[];
+  relation?: MessageRelation;
+  origin?: MessageOrigin;
+  timestamp?: number;
+  raw?: unknown;
+};
+```
+
+### Target
+
+The target describes where the message lives:
+
+```typescript
+type MessageTarget = {
+  kind: "direct" | "group" | "channel" | "thread";
+  id: string;
+  label?: string;
+  spaceId?: string;
+  parentId?: string;
+  threadId?: string;
+  nativeChannelId?: string;
+};
+```
+
+### Relation
+
+Reply is a relation, not an API root:
+
+```typescript
+type MessageRelation =
+  | {
+      kind: "reply";
+      inboundMessageId?: string;
+      replyToId?: string;
+      threadId?: string;
+      quote?: MessageQuote;
+    }
+  | {
+      kind: "followup";
+      sessionKey?: string;
+      previousMessageId?: string;
+    }
+  | {
+      kind: "broadcast";
+      reason?: string;
+    }
+  | {
+      kind: "system";
+      reason:
+        | "approval"
+        | "task"
+        | "hook"
+        | "cron"
+        | "subagent"
+        | "message_tool"
+        | "cli"
+        | "control_ui"
+        | "automation"
+        | "error";
+    };
+```
+
+This lets the same send path handle normal replies, cron notifications, approval
+prompts, task completions, message-tool sends, CLI or Control UI sends, subagent
+results, and automation sends.
+
+### Origin
+
+Origin describes who produced a message and how Nodmix should treat echoes of
+that message. It is separate from relation: a message can be a reply to a user
+and still be Nodmix-originated operational output.
+
+```typescript
+type MessageOrigin =
+  | {
+      source: "nodmix";
+      schemaVersion: 1;
+      kind: "gateway_failure";
+      code: "agent_failed_before_reply" | "missing_api_key" | "model_login_expired";
+      echoPolicy: "drop_bot_room_echo";
+    }
+  | {
+      source: "user" | "external_bot" | "platform" | "unknown";
+    };
+```
+
+Core owns the meaning of Nodmix-originated output. Channels own how that
+origin is encoded into their transport.
+
+The first required use is gateway failure output. Humans should still see
+messages such as "Agent failed before reply" or "Missing API key", but tagged
+Nodmix operational output must not be accepted as bot-authored input in shared
+rooms when `allowBots` is enabled.
+
+### Receipt
+
+Receipts are first-class:
+
+```typescript
+type MessageReceipt = {
+  primaryPlatformMessageId?: string;
+  platformMessageIds: string[];
+  parts: MessageReceiptPart[];
+  threadId?: string;
+  replyToId?: string;
+  editToken?: string;
+  deleteToken?: string;
+  url?: string;
+  sentAt: number;
+  raw?: unknown;
+};
+
+type MessageReceiptPart = {
+  platformMessageId: string;
+  kind: "text" | "media" | "voice" | "card" | "preview" | "unknown";
+  index: number;
+  threadId?: string;
+  replyToId?: string;
+  editToken?: string;
+  deleteToken?: string;
+  url?: string;
+  raw?: unknown;
+};
+```
+
+Receipts are the bridge from durable intent to future edit, delete, preview
+finalization, duplicate suppression, and recovery.
+
+A receipt can describe one platform message or a multi-part delivery. Chunked
+text, media plus text, voice plus text, and card fallbacks must preserve all
+platform ids while still exposing a primary id for threading and later edits.
+
+## Receive context
+
+Receiving should not be a bare helper call. The core needs a context that knows
+dedupe, routing, session recording, and platform ack policy.
+
+```typescript
+type MessageReceiveContext = {
+  id: string;
+  channel: string;
+  accountId?: string;
+  input: ChannelMessage;
+  ack: ReceiveAckController;
+  route: MessageRouteController;
+  session: MessageSessionController;
+  log: MessageLifecycleLogger;
+
+  dedupe(): Promise<ReceiveDedupeResult>;
+  resolve(): Promise<ResolvedInboundMessage>;
+  record(resolved: ResolvedInboundMessage): Promise<RecordResult>;
+  dispatch(recorded: RecordResult): Promise<DispatchResult>;
+  commit(result: DispatchResult): Promise<void>;
+  fail(error: unknown): Promise<void>;
+};
+```
+
+Receive flow:
+
+```text
+platform event
+  -> begin receive context
+  -> normalize
+  -> classify
+  -> dedupe and self-echo gate
+  -> route and authorize
+  -> record inbound session metadata
+  -> dispatch agent run
+  -> durable outbound sends happen through send context
+  -> commit receive
+  -> ack platform when policy allows
+```
+
+Ack is not one thing. The receive contract must keep these signals separate:
+
+- **Transport ack:** tells the platform webhook or socket that Nodmix accepted
+  the event envelope. Some platforms require this before dispatch.
+- **Polling offset ack:** advances a cursor so the same event is not fetched
+  again. This must not advance past work that cannot be recovered.
+- **Inbound record ack:** confirms Nodmix persisted enough inbound metadata to
+  dedupe and route a redelivery.
+- **User-visible receipt:** optional read/status/typing behavior; never a
+  durability boundary.
+
+`ReceiveAckPolicy` controls transport or polling acknowledgement only. It must
+not be reused for read receipts or status reactions.
+
+Before bot authorization, receive must apply the shared Nodmix echo policy
+when the channel can decode message origin metadata:
+
+```typescript
+function shouldDropNodmixEcho(params: {
+  origin?: MessageOrigin;
+  isBotAuthor: boolean;
+  isRoomish: boolean;
+}): boolean {
+  return (
+    params.isBotAuthor &&
+    params.isRoomish &&
+    params.origin?.source === "nodmix" &&
+    params.origin.kind === "gateway_failure" &&
+    params.origin.echoPolicy === "drop_bot_room_echo"
+  );
+}
+```
+
+This drop is tag-based, not text-based. A bot-authored room message with the
+same visible gateway-failure text but without Nodmix origin metadata still
+goes through normal `allowBots` authorization.
+
+Ack policy is explicit:
+
+```typescript
+type ReceiveAckPolicy =
+  | { kind: "immediate"; reason: "webhook-timeout" | "platform-contract" }
+  | { kind: "after-record" }
+  | { kind: "after-durable-send" }
+  | { kind: "manual" };
+```
+
+Telegram polling now uses the receive-context ack policy for its persisted
+restart watermark. The tracker still observes grammY updates as they enter the
+middleware chain, but Nodmix persists only the safe completed update id after
+successful dispatch, leaving failed or lower pending updates replayable after a
+restart. Telegram's upstream `getUpdates` fetch offset is still controlled by
+the polling library, so the remaining deeper cut is a fully durable polling
+source if we need platform-level redelivery beyond Nodmix's restart
+watermark. Webhook platforms may need immediate HTTP ack, but they still need
+inbound dedupe and durable outbound send intents because webhooks can redeliver.
+
+## Send context
+
+Sending is also context based:
+
+```typescript
+type MessageSendContext = {
+  id: string;
+  channel: string;
+  accountId?: string;
+  message: ChannelMessage;
+  intent: DurableSendIntent;
+  attempt: number;
+  signal: AbortSignal;
+  previousReceipt?: MessageReceipt;
+  preview?: LiveMessageState;
+  log: MessageLifecycleLogger;
+
+  render(): Promise<RenderedMessageBatch>;
+  previewUpdate(rendered: RenderedMessageBatch): Promise<LiveMessageState>;
+  send(rendered: RenderedMessageBatch): Promise<MessageReceipt>;
+  edit(receipt: MessageReceipt, rendered: RenderedMessageBatch): Promise<MessageReceipt>;
+  delete(receipt: MessageReceipt): Promise<void>;
+  commit(receipt: MessageReceipt): Promise<void>;
+  fail(error: unknown): Promise<void>;
+};
+```
+
+Preferred orchestration:
+
+```typescript
+await core.messages.withSendContext(message, async (ctx) => {
+  const rendered = await ctx.render();
+
+  if (ctx.preview?.canFinalizeInPlace) {
+    return await ctx.edit(ctx.preview.receipt, rendered);
+  }
+
+  return await ctx.send(rendered);
+});
+```
+
+The helper expands to:
+
+```text
+begin durable intent
+  -> render
+  -> optional preview/edit/stream work
+  -> mark sending
+  -> final platform send or final edit
+  -> mark committing with raw receipt
+  -> commit receipt
+  -> ack durable intent
+  -> fail durable intent on classified failure
+```
+
+The intent must exist before transport I/O. A restart after begin but before
+commit is recoverable.
+
+The dangerous boundary is after platform success and before receipt commit. If a
+process dies there, Nodmix cannot know whether the platform message exists
+unless the adapter provides native idempotency or a receipt reconciliation path.
+Those attempts must resume in `unknown_after_send`, not blindly replay. Channels
+without reconciliation may choose at-least-once replay only if duplicate visible
+messages are an acceptable, documented tradeoff for that channel and relation.
+The current SDK reconciliation bridge requires the adapter to declare
+`reconcileUnknownSend`, then asks `durableFinal.reconcileUnknownSend` to
+classify an unknown entry as `sent`, `not_sent`, or `unresolved`; only `not_sent`
+permits replay, and unresolved entries stay terminal or retry only the
+reconciliation check.
+
+Durability policy must be explicit:
+
+```typescript
+type MessageDurabilityPolicy = "required" | "best_effort" | "disabled";
+```
+
+`required` means core must fail closed when it cannot write the durable intent.
+`best_effort` can fall through when persistence is unavailable. `disabled` keeps
+the old direct send behavior. During migration, legacy wrappers and public
+compatibility helpers default to `disabled`; they must not infer `required` from
+the fact that a channel has a generic outbound adapter.
+
+Send contexts also own channel-local post-send effects. A migration is not safe
+if durable delivery bypasses local behavior that was previously attached to the
+channel's direct send path. Examples include self-echo suppression caches,
+thread participation markers, native edit anchors, model-signature rendering,
+and platform-specific duplicate guards. Those effects must either move into the
+send adapter, the render adapter, or a named send-context hook before that
+channel can enable durable generic final delivery.
+
+Send helpers must return receipts all the way back to their caller. Durable
+wrappers cannot swallow message ids or replace a channel delivery result with
+`undefined`; buffered dispatchers use those ids for thread anchors, later edits,
+preview finalization, and duplicate suppression.
+
+Fallback sends operate on batches, not single payloads. Silent-reply rewrites,
+media fallback, card fallback, and chunk projection can all produce more than
+one deliverable message, so a send context must either deliver the whole
+projected batch or explicitly document why only one payload is valid.
+
+```typescript
+type RenderedMessageBatch = {
+  units: RenderedMessageUnit[];
+  atomicity: "all_or_retry_remaining" | "best_effort_parts";
+  idempotencyKey: string;
+};
+
+type RenderedMessageUnit = {
+  index: number;
+  kind: "text" | "media" | "voice" | "card" | "preview" | "unknown";
+  payload: unknown;
+  required: boolean;
+};
+```
+
+When such a fallback is durable, the whole projected batch must be represented by
+one durable send intent or another atomic batch plan. Recording each payload
+one-by-one is not enough: a crash between payloads can leave a partial visible
+fallback with no durable record for the remaining payloads. Recovery must know
+which units already have receipts and either replay only missing units or mark
+the batch `unknown_after_send` until the adapter reconciles it.
+
+## Live context
+
+Preview, edit, progress, and stream behavior should be one opt-in lifecycle.
+
+```typescript
+type MessageLiveAdapter = {
+  begin?(ctx: MessageSendContext): Promise<LiveMessageState>;
+  update?(
+    ctx: MessageSendContext,
+    state: LiveMessageState,
+    update: LiveMessageUpdate,
+  ): Promise<LiveMessageState>;
+  finalize?(
+    ctx: MessageSendContext,
+    state: LiveMessageState,
+    final: RenderedMessageBatch,
+  ): Promise<MessageReceipt>;
+  cancel?(
+    ctx: MessageSendContext,
+    state: LiveMessageState,
+    reason: LiveCancelReason,
+  ): Promise<void>;
+};
+```
+
+Live state is durable enough to recover or suppress duplicates:
+
+```typescript
+type LiveMessageState = {
+  mode: "partial" | "block" | "progress" | "native";
+  receipt?: MessageReceipt;
+  visibleSince?: number;
+  canFinalizeInPlace: boolean;
+  lastRenderedHash?: string;
+  staleAfterMs?: number;
+};
+```
+
+This should cover current behavior:
+
+- Telegram send plus edit preview, with fresh final after stale preview age.
+- Discord send plus edit preview, cancel on media/error/explicit reply.
+- Slack native stream or draft preview depending on thread shape.
+- Mattermost draft post finalization.
+- Matrix draft event finalization or redaction on mismatch.
+- Teams native progress stream.
+- QQ Bot stream or accumulated fallback.
+
+## Adapter surface
+
+The public SDK target should be one subpath:
+
+```typescript
+import { defineChannelMessageAdapter } from "nodmix/plugin-sdk/channel-message";
+```
+
+Target shape:
+
+```typescript
+type ChannelMessageAdapter = {
+  receive?: MessageReceiveAdapter;
+  send: MessageSendAdapter;
+  live?: MessageLiveAdapter;
+  origin?: MessageOriginAdapter;
+  render?: MessageRenderAdapter;
+  capabilities: MessageCapabilities;
+};
+```
+
+Send adapter:
+
+```typescript
+type MessageSendAdapter = {
+  send(ctx: MessageSendContext, rendered: RenderedMessageBatch): Promise<MessageReceipt>;
+  edit?(
+    ctx: MessageSendContext,
+    receipt: MessageReceipt,
+    rendered: RenderedMessageBatch,
+  ): Promise<MessageReceipt>;
+  delete?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
+  classifyError?(ctx: MessageSendContext, error: unknown): DeliveryFailureKind;
+  reconcileUnknownSend?(ctx: MessageSendContext): Promise<MessageReceipt | null>;
+  afterSendSuccess?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
+  afterCommit?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
+};
+```
+
+Receive adapter:
+
+```typescript
+type MessageReceiveAdapter<TRaw = unknown> = {
+  normalize(raw: TRaw, ctx: MessageNormalizeContext): Promise<ChannelMessage>;
+  classify?(message: ChannelMessage): Promise<MessageEventClass>;
+  preflight?(message: ChannelMessage, event: MessageEventClass): Promise<MessagePreflightResult>;
+  ackPolicy?(message: ChannelMessage, event: MessageEventClass): ReceiveAckPolicy;
+};
+```
+
+Before preflight authorization, core must run the shared Nodmix echo predicate
+whenever `origin.decode` returns Nodmix-origin metadata. The receive adapter
+supplies platform facts such as bot author and room shape; core owns the drop
+decision and ordering so channels do not reimplement text filters.
+
+Origin adapter:
+
+```typescript
+type MessageOriginAdapter<TRaw = unknown, TNative = unknown> = {
+  encode?(origin: MessageOrigin): TNative | undefined;
+  decode?(raw: TRaw): MessageOrigin | undefined;
+};
+```
+
+Core sets `MessageOrigin`. Channels only translate it to and from native
+transport metadata. Slack maps this to `chat.postMessage({ metadata })` and
+inbound `message.metadata`; Matrix can map it to extra event content; channels
+without native metadata can use a receipt/outbound registry when that is the
+best available approximation.
+
+Capabilities:
+
+```typescript
+type MessageCapabilities = {
+  text: { maxLength?: number; chunking?: boolean };
+  attachments?: {
+    upload: boolean;
+    remoteUrl: boolean;
+    voice?: boolean;
+  };
+  threads?: {
+    reply: boolean;
+    topic?: boolean;
+    nativeThread?: boolean;
+  };
+  live?: {
+    edit: boolean;
+    delete: boolean;
+    nativeStream?: boolean;
+    progress?: boolean;
+  };
+  delivery?: {
+    idempotencyKey?: boolean;
+    retryAfter?: boolean;
+    receiptRequired?: boolean;
+  };
+};
+```
+
+## Public SDK reduction
+
+The new public surface should absorb or deprecate these conceptual areas:
+
+- `reply-runtime`
+- `reply-dispatch-runtime`
+- `reply-reference`
+- `reply-chunking`
+- `reply-payload`
+- `inbound-reply-dispatch`
+- `channel-reply-pipeline`
+- most public uses of `outbound-runtime`
+- ad hoc draft stream lifecycle helpers
+
+Compatibility subpaths can remain as wrappers, but new third-party plugins
+should not need them.
+
+Bundled plugins may keep internal helper imports through reserved runtime
+subpaths while migrating. Public docs should steer plugin authors to
+`plugin-sdk/channel-message` once it exists.
+
+## Relationship to channel turn
+
+`runtime.channel.turn.*` should stay during migration.
+
+It should become a compatibility adapter:
+
+```text
+channel.turn.run
+  -> messages.receive context
+  -> session dispatch
+  -> messages.send context for visible output
+```
+
+`channel.turn.runPrepared` should also remain initially:
+
+```text
+channel-owned dispatcher
+  -> messages.receive record/finalize bridge
+  -> messages.live for preview/progress
+  -> messages.send for final delivery
+```
+
+After all bundled plugins and known third-party compatibility paths are bridged,
+`channel.turn` can be deprecated. It should not be removed until there is a
+published SDK migration path and contract tests proving old plugins still work
+or fail with a clear version error.
+
+## Compatibility guardrails
+
+During migration, generic durable delivery is opt-in for any channel whose
+existing delivery callback has side effects beyond "send this payload".
+
+Legacy entry points are non-durable by default:
+
+- `channel.turn.run` and `dispatchAssembledChannelTurn` use the channel's
+  delivery callback unless that channel explicitly supplies an audited durable
+  policy/options object.
+- `channel.turn.runPrepared` stays channel-owned until the prepared dispatcher
+  explicitly calls the send context.
+- Public compatibility helpers such as `recordInboundSessionAndDispatchReply`,
+  `dispatchInboundReplyWithBase`, and direct-DM helpers never inject generic
+  durable delivery before the caller-provided `deliver` or `reply` callback.
+
+For migration bridge types, `durable: undefined` means "not durable". The
+durable path is enabled only by an explicit policy/options value. `durable:
+false` can remain as a compatibility spelling, but implementation should not
+require every unmigrated channel to add it.
+
+Current bridge code must keep the durability decision explicit:
+
+- Durable final delivery returns a discriminated status. `handled_visible` and
+  `handled_no_send` are terminal; `unsupported` and `not_applicable` may fall
+  back to channel-owned delivery; `failed` propagates the send failure.
+- Generic durable final delivery is gated by adapter capabilities such as
+  silent delivery, reply target preservation, native quote preservation, and
+  message-sending hooks. Missing parity should choose channel-owned delivery,
+  not a generic send that changes user-visible behavior.
+- Queue-backed durable sends expose a delivery intent reference. Existing
+  `pendingFinalDelivery*` session fields can carry the intent id during the
+  transition; the end state is a `MessageSendIntent` store instead of frozen
+  reply text plus ad hoc context fields.
+
+Do not enable the generic durable path for a channel until all of these are
+true:
+
+- The generic send adapter executes the same rendering and transport behavior as
+  the old direct path.
+- Local post-send side effects are preserved through the send context.
+- The adapter returns receipts or delivery results with all platform message
+  ids.
+- Prepared dispatcher paths either call the new send context or stay documented
+  as outside the durable guarantee.
+- Fallback delivery handles every projected payload, not only the first one.
+- Durable fallback delivery records the whole projected payload array as one
+  replayable intent or batch plan.
+
+Concrete migration hazards to preserve:
+
+- iMessage monitor delivery records sent messages in an echo cache after a
+  successful send. Durable final sends must still populate that cache, otherwise
+  Nodmix can re-ingest its own final replies as inbound user messages.
+- Tlon appends an optional model signature and records participated threads
+  after group replies. Generic durable delivery must not bypass those effects;
+  either move them into Tlon render/send/finalize adapters or keep Tlon on the
+  channel-owned path.
+- Discord and other prepared dispatchers already own direct delivery and preview
+  behavior. They are not covered by an assembled-turn durable guarantee until
+  their prepared dispatchers explicitly route finals through the send context.
+- Telegram silent fallback delivery must deliver the full projected payload
+  array. A single-payload shortcut can drop additional fallback payloads after
+  projection.
+- LINE, Zalo, Nostr, and other existing assembled/helper paths may
+  have reply-token handling, media proxying, sent-message caches, loading/status
+  cleanup, or callback-only targets. They stay on channel-owned delivery until
+  those semantics are represented by the send adapter and verified by tests.
+- Direct-DM helpers can have a reply callback that is the only correct transport
+  target. Generic outbound must not guess from `OriginatingTo` or `To` and skip
+  that callback.
+- Nodmix gateway failure output must stay visible to humans, but tagged
+  bot-authored room echoes must be dropped before `allowBots` authorization.
+  Channels must not implement this with visible-text prefix filters except as a
+  short emergency stopgap; the durable contract is structured origin metadata.
+
+## Internal storage
+
+The durable queue should store message send intents, not reply payloads.
+
+```typescript
+type DurableSendIntent = {
+  id: string;
+  idempotencyKey: string;
+  channel: string;
+  accountId?: string;
+  message: ChannelMessage;
+  batch?: RenderedMessageBatch;
+  liveState?: LiveMessageState;
+  status:
+    | "pending"
+    | "sending"
+    | "committing"
+    | "unknown_after_send"
+    | "sent"
+    | "failed"
+    | "cancelled";
+  attempt: number;
+  nextAttemptAt?: number;
+  receipt?: MessageReceipt;
+  partialReceipt?: MessageReceipt;
+  failure?: DeliveryFailure;
+  createdAt: number;
+  updatedAt: number;
+};
+```
+
+Recovery loop:
+
+```text
+load pending or sending intents
+  -> acquire idempotency lock
+  -> skip if receipt already committed
+  -> reconstruct send context
+  -> render if needed
+  -> reconcile unknown_after_send if needed
+  -> call adapter send/edit/finalize
+  -> commit receipt, mark unknown_after_send, or schedule retry
+```
+
+The queue should keep enough identity to replay through the same account,
+thread, target, formatting policy, and media rules after restart.
+
+## Failure classes
+
+Channel adapters classify transport failures into closed categories:
+
+```typescript
+type DeliveryFailureKind =
+  | "transient"
+  | "rate_limit"
+  | "auth"
+  | "permission"
+  | "not_found"
+  | "invalid_payload"
+  | "conflict"
+  | "cancelled"
+  | "unknown";
+```
+
+Core policy:
+
+- Retry `transient` and `rate_limit`.
+- Do not retry `invalid_payload` unless a render fallback exists.
+- Do not retry `auth` or `permission` until configuration changes.
+- For `not_found`, let live finalization fall back from edit to fresh send when
+  the channel declares that safe.
+- For `conflict`, use receipt/idempotency rules to decide whether the message
+  already exists.
+- Any error after the adapter may have completed platform I/O but before receipt
+  commit becomes `unknown_after_send` unless the adapter can prove the platform
+  operation did not happen.
+
+## Channel mapping
+
+| Channel         | Target migration                                                                                                                                                                                                                                                                                                                                               |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Telegram        | Receive ack policy plus durable final sends. Live adapter owns send plus edit preview, stale preview final send, topics, quote-reply preview skip, media fallback, and retry-after handling.                                                                                                                                                                   |
+| Discord         | Send adapter wraps existing durable payload delivery. Live adapter owns draft edit, progress draft, media/error preview cancel, reply target preservation, and message id receipts. Audit bot-authored gateway-failure echoes in shared rooms; use an outbound registry or other native equivalent if Discord cannot carry origin metadata on normal messages. |
+| Slack           | Send adapter handles normal chat posts. Live adapter chooses native stream when thread shape supports it, otherwise draft preview. Receipts preserve thread timestamps. Origin adapter maps Nodmix gateway failures to Slack `chat.postMessage.metadata` and drops tagged bot-room echoes before `allowBots` authorization.                                  |
+| WhatsApp        | Send adapter owns text/media send with durable final intents. Receive adapter handles group mention and sender identity. Live can stay absent until WhatsApp has an editable transport.                                                                                                                                                                        |
+| Matrix          | Live adapter owns draft event edits, finalization, redaction, encrypted media constraints, and reply-target mismatch fallback. Receive adapter owns encrypted event hydration and dedupe. Origin adapter should encode Nodmix gateway-failure origin into Matrix event content and drop configured-bot room echoes before `allowBots` handling.              |
+| Mattermost      | Live adapter owns one draft post, progress/tool folding, finalization in place, and fresh-send fallback.                                                                                                                                                                                                                                                       |
+| Microsoft Teams | Live adapter owns native progress and block stream behavior. Send adapter owns activities and attachment/card receipts.                                                                                                                                                                                                                                        |
+| Feishu          | Render adapter owns text/card/raw rendering. Live adapter owns streaming cards and duplicate final suppression. Send adapter owns comments, topic sessions, media, and voice suppression.                                                                                                                                                                      |
+| QQ Bot          | Live adapter owns C2C streaming, accumulator timeout, and fallback final send. Render adapter owns media tags and text-as-voice.                                                                                                                                                                                                                               |
+| Signal          | Simple receive plus send adapter. No live adapter unless signal-cli adds reliable edit support.                                                                                                                                                                                                                                                                |
+| iMessage        | Simple receive plus send adapter. iMessage send must preserve monitor echo-cache population before durable finals can bypass monitor delivery.                                                                                                                                                                                                                 |
+| Google Chat     | Simple receive plus send adapter with thread relation mapped to spaces and thread ids. Audit `allowBots=true` room behavior for tagged Nodmix gateway-failure echoes.                                                                                                                                                                                        |
+| LINE            | Simple receive plus send adapter with reply-token constraints modeled as target/relation capability.                                                                                                                                                                                                                                                           |
+| Nextcloud Talk  | SDK receive bridge plus send adapter.                                                                                                                                                                                                                                                                                                                          |
+| IRC             | Simple receive plus send adapter, no durable edit receipts.                                                                                                                                                                                                                                                                                                    |
+| Nostr           | Receive plus send adapter for encrypted DMs; receipts are event ids.                                                                                                                                                                                                                                                                                           |
+| QA Channel      | Contract-test adapter for receive, send, live, retry, and recovery behavior.                                                                                                                                                                                                                                                                                   |
+| Synology Chat   | Simple receive plus send adapter.                                                                                                                                                                                                                                                                                                                              |
+| Tlon            | Send adapter must preserve model-signature rendering and participated-thread tracking before generic durable final delivery is enabled.                                                                                                                                                                                                                        |
+| Twitch          | Simple receive plus send adapter with rate-limit classification.                                                                                                                                                                                                                                                                                               |
+| Zalo            | Simple receive plus send adapter.                                                                                                                                                                                                                                                                                                                              |
+| Zalo Personal   | Simple receive plus send adapter.                                                                                                                                                                                                                                                                                                                              |
+
+## Migration plan
+
+### Phase 1: Internal Message Domain
+
+- Add `src/channels/message/*` types for messages, targets, relations,
+  origins, receipts, capabilities, durable intents, receive context, send
+  context, live context, and failure classes.
+- Add `origin?: MessageOrigin` to the migration bridge payload type used by
+  current reply delivery, then move that field to `ChannelMessage` and rendered
+  message types as the refactor replaces reply payloads.
+- Keep this internal until adapters and tests prove the shape.
+- Add pure unit tests for state transitions and serialization.
+
+### Phase 2: Durable Send Core
+
+- Move the existing outbound queue from reply-payload durability to durable
+  message send intents.
+- Let a durable send intent carry a projected payload array or batch plan, not
+  only one reply payload.
+- Preserve the current queue recovery behavior through compatibility conversion.
+- Make `deliverOutboundPayloads` call `messages.send`.
+- Make final-send durability the default and fail closed when the durable intent
+  cannot be written in the new message lifecycle, after the adapter declares
+  replay safety. Existing channel-turn and SDK compatibility paths remain
+  direct-send by default during this phase.
+- Record receipts consistently.
+- Return receipts and delivery results to the original dispatcher caller instead
+  of treating durable send as a terminal side effect.
+- Persist message origin through durable send intents so recovery, replay, and
+  chunked sends preserve Nodmix operational provenance.
+
+### Phase 3: Channel Turn Bridge
+
+- Reimplement `channel.turn.run` and `dispatchAssembledChannelTurn` on top of
+  `messages.receive` and `messages.send`.
+- Keep current fact types stable.
+- Keep legacy behavior by default. An assembled-turn channel becomes durable
+  only when its adapter explicitly opts in with a replay-safe durability policy.
+- Keep `durable: false` as a compatibility escape hatch for paths that finalize
+  native edits and cannot replay safely yet, but do not rely on `false` markers
+  to protect unmigrated channels.
+- Default assembled-turn durability only in the new message lifecycle, after
+  the channel mapping proves the generic send path preserves the old channel
+  delivery semantics.
+
+### Phase 4: Prepared Dispatcher Bridge
+
+- Replace `deliverDurableInboundReplyPayload` with a send-context bridge.
+- Keep the old helper as a wrapper.
+- Port Telegram, WhatsApp, Slack, Signal, iMessage, and Discord first because
+  they already have durable-final work or simpler send paths.
+- Treat every prepared dispatcher as uncovered until it explicitly opts in to
+  the send context. Documentation and changelog entries must say "assembled
+  channel turns" or name the migrated channel paths rather than claiming all
+  automatic final replies.
+- Keep `recordInboundSessionAndDispatchReply`, direct-DM helpers, and similar
+  public compatibility helpers behavior-preserving. They may expose an explicit
+  send-context opt-in later, but must not automatically attempt generic durable
+  delivery before the caller-owned delivery callback.
+
+### Phase 5: Unified Live Lifecycle
+
+- Build `messages.live` with two proof adapters:
+  - Telegram for send plus edit plus stale final send.
+  - Matrix for draft finalization plus redaction fallback.
+- Then migrate Discord, Slack, Mattermost, Teams, QQ Bot, and Feishu.
+- Delete duplicated preview finalization code only after each channel has
+  parity tests.
+
+### Phase 6: Public SDK
+
+- Add `nodmix/plugin-sdk/channel-message`.
+- Document it as the preferred channel plugin API.
+- Update package exports, entrypoint inventory, generated API baselines, and
+  plugin SDK docs.
+- Include `MessageOrigin`, origin encode/decode hooks, and the shared
+  `shouldDropNodmixEcho` predicate in the channel-message SDK surface.
+- Keep compatibility wrappers for old subpaths.
+- Mark reply-named SDK helpers as deprecated in docs after bundled plugins are
+  migrated.
+
+### Phase 7: All Senders
+
+Move all non-reply outbound producers onto `messages.send`:
+
+- cron and heartbeat notifications
+- task completions
+- hook results
+- approval prompts and approval results
+- message tool sends
+- subagent completion announcements
+- explicit CLI or Control UI sends
+- automation/broadcast paths
+
+This is where the model stops being "agent replies" and becomes "Nodmix sends
+messages".
+
+### Phase 8: Deprecate Turn
+
+- Keep `channel.turn` as a wrapper for at least one compatibility window.
+- Publish migration notes.
+- Run plugin SDK compatibility tests against old imports.
+- Remove or hide old internal helpers only after no bundled plugin needs them
+  and third-party contracts have a stable replacement.
+
+## Test plan
+
+Unit tests:
+
+- Durable send intent serialization and recovery.
+- Idempotency key reuse and duplicate suppression.
+- Receipt commit and replay skip.
+- `unknown_after_send` recovery that reconciles before replay when an adapter
+  supports reconciliation.
+- Failure classification policy.
+- Receive ack policy sequencing.
+- Relation mapping for reply, followup, system, and broadcast sends.
+- Gateway-failure origin factory and `shouldDropNodmixEcho` predicate.
+- Origin preservation through payload normalization, chunking, durable queue
+  serialization, and recovery.
+
+Integration tests:
+
+- `channel.turn.run` simple adapter still records and sends.
+- Legacy assembled-event delivery does not become durable unless the channel
+  explicitly opts in.
+- `channel.turn.runPrepared` bridge still records and finalizes.
+- Public compatibility helpers call caller-owned delivery callbacks by default
+  and do not generic-send before those callbacks.
+- Durable fallback delivery replays the whole projected payload array after
+  restart and cannot leave the later payloads unrecorded after an early crash.
+- Durable assembled-event delivery returns platform message ids to the buffered
+  dispatcher.
+- Custom delivery hooks still return platform message ids when durable delivery
+  is disabled or unavailable.
+- Final reply survives restart between assistant completion and platform send.
+- Preview draft finalizes in place when allowed.
+- Preview draft is cancelled or redacted when media/error/reply-target mismatch
+  requires normal delivery.
+- Block streaming and preview streaming do not both deliver the same text.
+- Media streamed early is not duplicated in final delivery.
+
+Channel tests:
+
+- Telegram topic reply with polling ack delayed until the receive context's safe
+  completed watermark.
+- Telegram polling recovery for accepted-but-not-delivered updates covered by
+  the persisted safe-completed offset model.
+- Telegram stale preview sends fresh final and cleans up preview.
+- Telegram silent fallback sends every projected fallback payload.
+- Telegram silent fallback durability records the full projected fallback array
+  atomically, not one single-payload durable intent per loop iteration.
+- Discord preview cancel on media/error/explicit reply.
+- Discord prepared dispatcher finals route through the send context before docs
+  or changelog claim Discord final-reply durability.
+- iMessage durable final sends populate the monitor sent-message echo cache.
+- LINE, Zalo, and Nostr legacy delivery paths are not bypassed by
+  generic durable send until their adapter parity tests exist.
+- Direct-DM/Nostr callback delivery remains authoritative unless explicitly
+  migrated to a complete message target and replay-safe send adapter.
+- Slack tagged Nodmix gateway failure messages stay visible outbound, tagged
+  bot-room echoes drop before `allowBots`, and untagged bot messages with the
+  same visible text still follow normal bot authorization.
+- Slack native stream fallback to draft preview in top-level DMs.
+- Matrix preview finalization and redaction fallback.
+- Matrix tagged Nodmix gateway-failure room echoes from configured bot
+  accounts drop before `allowBots` handling.
+- Discord and Google Chat shared-room gateway-failure cascade audits cover
+  `allowBots` modes before claiming generic protection there.
+- Mattermost draft finalization and fresh-send fallback.
+- Teams native progress finalization.
+- Feishu duplicate final suppression.
+- QQ Bot accumulator timeout fallback.
+- Tlon durable final sends preserve model-signature rendering and participated
+  thread tracking.
+- WhatsApp, Signal, iMessage, Google Chat, LINE, IRC, Nostr, Nextcloud Talk,
+  Synology Chat, Tlon, Twitch, Zalo, and Zalo Personal simple durable final
+  sends.
+
+Validation:
+
+- Targeted Vitest files during development.
+- `pnpm check:changed` in Testbox for the full changed surface.
+- Broader `pnpm check` in Testbox before landing the complete refactor or after
+  public SDK/export changes.
+- Live or qa-channel smoke for at least one edit-capable channel and one
+  simple send-only channel before removing compatibility wrappers.
+
+## Open questions
+
+- Whether Telegram should eventually replace the grammY runner source with a
+  fully durable polling source that can control platform-level redelivery, not
+  only Nodmix's persisted restart watermark.
+- Whether durable live preview state should be stored in the same queue record
+  as the final send intent or in a sibling live-state store.
+- How long compatibility wrappers stay documented after
+  `plugin-sdk/channel-message` ships.
+- Whether third-party plugins should implement receive adapters directly or only
+  provide normalize/send/live hooks through `defineChannelMessageAdapter`.
+- Which receipt fields are safe to expose in public SDK versus internal runtime
+  state.
+- Whether side effects such as self-echo caches and participated-thread markers
+  should be modeled as send-context hooks, adapter-owned finalize steps, or
+  receipt subscribers.
+- Which channels have native origin metadata, which need persisted outbound
+  registries, and which cannot offer reliable cross-bot echo suppression.
+
+## Acceptance criteria
+
+- Every bundled message channel sends final visible output through
+  `messages.send`.
+- Every inbound message channel enters through `messages.receive` or a
+  documented compatibility wrapper.
+- Every preview/edit/stream channel uses `messages.live` for draft state and
+  finalization.
+- `channel.turn` is only a wrapper.
+- Reply-named SDK helpers are compatibility exports, not the recommended path.
+- Durable recovery can replay pending final sends after restart without losing
+  the final response or duplicating already committed sends; sends whose
+  platform outcome is unknown are reconciled before replay or documented as
+  at-least-once for that adapter.
+- Durable final sends fail closed when the durable intent cannot be written,
+  unless a caller explicitly selected a documented non-durable mode.
+- Legacy channel-turn and SDK compatibility helpers default to direct
+  channel-owned delivery; generic durable send is explicit opt-in only.
+- Receipts preserve all platform message ids for multi-part deliveries and a
+  primary id for threading/edit convenience.
+- Durable wrappers preserve channel-local side effects before replacing direct
+  delivery callbacks.
+- Prepared dispatchers are not counted as durable until their final delivery
+  path explicitly uses the send context.
+- Fallback delivery handles every projected payload.
+- Durable fallback delivery records every projected payload in one replayable
+  intent or batch plan.
+- Nodmix-originated gateway failure output is visible to humans but tagged
+  bot-authored room echoes are dropped before bot authorization on channels that
+  declare support for the origin contract.
+- The docs explain send, receive, live, state, receipts, relations, failure
+  policy, migration, and test coverage.
+
+## Related
+
+- [Messages](/concepts/messages)
+- [Streaming and chunking](/concepts/streaming)
+- [Progress drafts](/concepts/progress-drafts)
+- [Retry policy](/concepts/retry)
+- [Channel turn kernel](/plugins/sdk-channel-turn)