Durable acceptance before delivery#
Messages is an independent backend with its own store, migrations, worker and receipt ledger. Its foundation accepts versioned publications through authenticated boundaries and records a durable outcome. Workflow execution, application mutations and the human inbox are separate responsibilities built around that foundation.
Keep four events distinct: acceptance of a publication, expansion to recipients, a person reading it, and completion of any related business work. A successful acceptance receipt proves the service committed its acceptance transaction. It does not mean every recipient has received the item or that someone completed a task.
Identity and immutable publication semantics#
The publication's source and id form a global immutable semantic identity, including across tenants. The service serializes that identity, checks the tenant and canonical semantic digest, and rejects a conflicting replay. Reusing the same identifier for changed content is not an update mechanism.
The authenticated publisher must be enrolled for the relevant source, tenant and subscriber or publication capabilities. JWT validation precedes the neutral identity boundary. A tenant, principal or caller name inside a payload cannot authenticate the sender. Receipt queries also require permission and matching enrollment; knowledge of a source/id pair grants no access.
| Boundary | Required check |
|---|---|
| Publisher ingress | Validated workload identity and approved source/tenant capabilities |
| Payload | Supported versioned schema, valid bounded JSON and immutable semantic identity |
| Receipt query | Authenticated caller, permission and exact enrollment scope |
| Human inbox | Current human identity, tenant and own-recipient eligibility |
Neutral contracts are pinned artifacts rather than sibling source-project imports. Messages' neutral domain and application layers do not depend on the Workflow engine or Matrix UI packages. The optional Activity adapter is a separate package edge.
Transaction and acknowledgement#
Acceptance writes the inbox delivery, acceptance marker, immutable receipt and terminal notification together. A crash before commit rolls back the transaction. A crash after commit but before broker acknowledgement permits redelivery to recover the committed identity. The worker manually acknowledges only after commit.
Terminal acceptance notifications use an outbox and confirmed publication. Replays can re-arm the same notification; they do not create new business identities. Terminal receipts do not recursively generate more terminal receipt traffic. Publisher confirms and manual acknowledgements support recovery, but they are not a universal exactly-once guarantee for application side effects.
For the common-message API, the documented routes include:
| Method and route | Meaning |
|---|---|
POST /api/messages/v1/publications |
Accept a publication durably; delivery can remain pending |
GET /api/messages/v1/publications/receipt?source=…&id=… |
Read scoped delivery progress and original acceptance |
POST /api/messages/v1/publications/retract?source=…&id=… |
Retract a publisher-owned publication |
Retraction creates a durable visibility boundary so a resumed delivery batch cannot restore withdrawn content. It does not erase the immutable accepted publication or rewrite history.
Audience expansion is recoverable work#
The common inbox adds recipient discovery and fanout after acceptance. Directory observations establish current tenant membership, roles and approved groups. Incomplete or changing observations leave delivery incomplete rather than claiming a complete audience. The documented implementation uses bounded discovery; large directories require qualification against the selected release.
Recipient batches persist their state and checkpoint in one transaction. Retraction uses the same ownership lock. Change cursors are ordered through a counter held until commit so a cursor cannot acknowledge a change that is not yet visible. Installation-wide publication is a controlled request producing children with explicit tenants, not a wildcard business event.
Integrate and verify#
Enroll publisher identities and sources first, then pin the contract artifacts and migration history. Test malformed input, wrong tenant, conflicting duplicate identity, crash before commit, lost acknowledgement and replay after commit. Check receipt access with both permitted and denied callers. Verify delivery separately using the intended identity provider, recipient directory and inbox integration.
Keep migration credentials outside API and Worker runtime. Runtime table grants are explicit and do not grant general schema, delete or migration authority. An image build, a local acceptance suite and an accepted customer installation are separate release facts.