Events and choreography

Events and event-driven choreography#

A business event reports a committed fact. A command requests an operation from a specific owner. A receipt reports authoritative acceptance or outcome. A human notification helps a person discover information or work. Keeping these meanings separate prevents transport delivery from being mistaken for business completion.

Workflow can consume approved events to start or resume a process. Other independently configured applications can subscribe to the same event and own their own reactions. This is event-driven choreography; it does not imply executable BPMN choreography support.

Event envelope#

The messaging contract selects CloudEvents 1.0.2 using structured JSON, with specversion set to 1.0. It also pins AsyncAPI 3.0.0 and an AMQP binding baseline for the asynchronous description. These are contract baselines, not claims about the newest specification versions.

CloudEvents source and subject are strings, not nested JSON objects. Authentication and enrolled publisher/source mapping establish provenance; a claimed source name alone does not.

Publishing a committed fact#

Write the business change and its outgoing event intent through the producer's transactional outbox or another explicitly recoverable ownership boundary. If the source transaction rolls back, no committed event should remain.

A representation bridge preserves source and id when meaning and semantic content stay unchanged. A semantic transformation creates a new event identity and records the original through causation or provenance. A changed transformation must not produce different content under an existing identity.

Event identity is unique within its registered source across tenant scopes. Reassigning the same source/id pair to a different tenant is a conflict. Tenant isolation remains necessary in storage and access checks.

Start and catch behavior#

A start binding selects explicit source, type, schema, scope and business filters. The initial ingress retains the selected binding and process version so replay after an activation update does not start a second instance on a newer definition.

Message catches use exact approved correlation, not an arbitrary correlationId lookup. The documented runtime retains bounded early events and durable waits. Ambiguous eligible matches become visible recovery work rather than choosing an arbitrary winner.

For the documented event-start adapter, subjectversion supplies the expected subject revision, and optional runid preserves declared execution lineage. Catch-only events do not require those start-specific extensions. Confirm the selected adapter's schema and lineage rules before publishing.

Subscriber custody#

RabbitMQ's configured durable queues isolate required logical subscribers. Replicas of one subscriber may compete on its queue. Each required subscriber retains its own durable acceptance obligation.

A positive broker confirm does not prove every required subscriber has committed its inbox. The receiver validates authority and schema, then commits its inbox, owner state and receipt/outbox before acknowledging transport delivery. Source custody remains recoverable until the required application receipts establish the handoff.

One subscriber's receipt cannot release another subscriber's obligation. Retry, dead-letter and retention policies must preserve outstanding work or another authoritative replay copy. Best-effort observers need explicit classification rather than an implied replay guarantee.

State and recovery#

PostgreSQL owns Workflow's timers, retry scheduling and durable correlation state. Broker TTL can assist transport policy but does not define business expiry. Redis cache loss must not lose execution state.

Preserve immutable identities during redelivery. Changed payloads, wrong publishers, stale lineage and mismatched tenants must fail independently of successful broker delivery. See durable operation reconciliation for uncertain effects and human tasks for the separate notification lifecycle.