Domain Events, Outbox, and Delivery

Dashboard chat requests, user-scoped thread history, and authenticated SSE belong to api/domains/web_chat/ and use Communications delivery. See /guides/agents/web-chat; chat and telemetry updates are not automatically Domain Events.

Event Delivery and Communication Delivery are different domain types. Do not use the terms interchangeably or display them through the same operational monitor.

The current Organization Agent Settings event is organization.agent_settings.changed. It is Organization-scoped, emits only when a setting meaningfully changes, names the setting, carries previous and current safe values, and records the number of inheriting Agents. The mutation and Outbox rows commit atomically; the event records a settings transition, not restarts of affected Agents, and contains no credentials or raw prompt content. Running Agents retain their current Runtime value until restarted.

Current Communications events are communication.connection.health.changed, communication.connection.reconnect.requested, communication.delivery.dead_lettered, communication.delivery.retry.requested, and communication.delivery.recovered. They record observed Connection health, an authorized reconnect request, exhausted automatic Delivery attempts, an authorized dead-letter retry request, and a later success after manual retry. These Organization-scoped business and operational transitions are suitable for selective audit projection; they do not turn every provider attempt, poll, claim, reply, timing measurement, or journal row into a Domain Event.

Domain Event: immutable, typed business fact; Outbox Message: durable event-publication intent; Event Delivery: mutable execution state for one registered Event Handler.

Communication Delivery: durable inbound or outbound communication work; Communications operation journal: content-free diagnostics for Connection and Delivery processing.

Conversation Message: canonical Communications-owned content, including built-in Web Chat delivery; Tool Call or Tool Result: Ingest-owned Runtime telemetry; Security Audit Record: deletion-independent projection from selected Domain Events.

Organization Agent Settings and Communications mutations that emit Domain Events use this same repository transaction: changed business state, immutable Outbox Message, and one Event Delivery per currently registered handler commit together. Routes do not stage events, the generic persistence delegate receives no optional event parameters, and services enqueue committed Event Deliveries only after the repository transaction succeeds.

Immediate Redis or Dramatiq enqueue remains best effort. A publish failure does not roll back committed Agent Settings or Communications state; reconciliation repairs eligible Event Deliveries later. Do not write a Domain Event in a second transaction after the setting or Delivery mutation.

This lifecycle belongs to Event Handler execution. A Communication Delivery has its own Communications-owned status and retry lifecycle. Dead-lettering a Communication Delivery may produce a Domain Event, but it does not become an Event Delivery. The Platform Event Delivery Monitor reads Domain Event Deliveries only; it does not display Communication Delivery queues, Connection journal entries, provider ingress attempts, or Conversation Messages. Use /guides/observe-and-govern/communication-diagnostics for Connection-specific diagnostics.

Dramatiq messages carry only a Delivery ID and safe diagnostics. Workers reload PostgreSQL state, claim atomically, and invoke a statically registered handler. Handler names are durable contracts. Every handler must be idempotent because a crash can occur after its side effect commits but before delivery success is recorded.

Selected Organization Agent Settings and Communications events may project into deletion-independent Security Audit Records. The projection uses the Domain Event ID as its idempotency key and receives only the event’s bounded, validated payload. Do not add a Communications journal processor as a Domain Event Handler.

Communications event payloads may carry scoped resource IDs, lifecycle status, bounded attempt metadata, and safe actor or subject display snapshots. They never carry provider credentials, authorization headers, raw webhook bodies, message content, provider URLs, sender identity, or exception text. A Connection-health event may carry a validated content-free envelope such as category, operation, HTTP status, provider code, retryability, bounded retry-after, and provider request ID; request IDs are diagnostic references, not credentials.

Raw provider payloads remain outside Domain Events, Conversation content remains in Communications-owned message storage, and Tool inputs and results remain outside event payloads. Audit projection is selective rather than automatic for every registered event.

The Communications journal is not a Domain Event stream. It records intermediate Connection and Delivery stages, attempts, timings, retryability, and bounded failure diagnostics for per-Connection troubleshooting and Delivery drill-down. It contains no message content, credentials, or sender identity; is retained and pruned by Communications policy; creates no Outbox Messages or Event Deliveries; and is not replayed through Dramatiq.

Domain Events are selected immutable business facts with typed names, schema versions, Outbox and handler deliveries, selective audit projection, event-framework lifecycle, and the Platform Event Delivery Monitor. The Communications journal instead provides stage and attempt metadata, troubleshooting and recovery context, Communications retention and pruning, and Connection diagnostics and journal UI. Continue with /guides/develop/domain-events, /guides/observe-and-govern/organization-agent-settings, /guides/observe-and-govern/communication-diagnostics, /guides/activity-conversations-and-telemetry, and /guides/testing-and-verification for focused guidance.