What it does
A /v1/transactions request can include an emit_event mutation. The event is appended to a durable, ordered outbox partition in the same log record as the request's other writes. Consumers read it later at least once, with offsets, bounded retry and a dead-letter record. The consume side is used by the server's own subsystems; there is no public consume endpoint.
How it works
An emit_event mutation names an outbox, an aggregate, an event type, a payload and the expected version of the aggregate. The expected version is an optimistic-concurrency check: it must equal the aggregate's current committed version, with zero for a new aggregate, and a stale value fails the whole envelope with a 409, not just the event. Events get a gapless, monotonic sequence number within their outbox partition, and appear in version order within one aggregate.
Because the event is staged into the same transaction as the document, vector and file mutations, all of them commit or none do. The envelope's own idempotency key governs the event too: a retry with the same key and the same request replays the original result with exactly one event, and the same key with a changed request is rejected whole. Tests kill the process at each commit boundary and check that the outbox and the other writes are all-or-nothing.
Consumers are named, each with its own offset, retry state and dead letters. A consumer polls the next batch, then reports each event as acknowledged, failed but retryable, or failed for good. A retryable failure backs off exponentially up to a bounded number of attempts, three by default, and then dead-letters; a non-retryable failure dead-letters at once. Replay re-reads events from a sequence number without moving the offset. An audit trail records operations without payloads.
Delivery is at least once, not exactly once. A consumer that crashes after applying an effect and before committing its offset sees the event again, so effects must be idempotent, keyed by the event's stable id. Retention bounds the event log, with drop-oldest at 4,096 events per partition by default; a consumer whose offset has aged out gets an explicit expired-offset error rather than wrong data.
Outboxes are scoped per project, so a project cannot name another project's partition, aggregate, event or receipt.
Where you reach it
- HTTP
POST /v1/transactions with a mutation {"op":"emit_event","outbox_id","aggregate","event_type","payload","expected_version"} - Library
OutboxStore: append, stage_append, create_consumer, next, report, ack, replay, dead_letters, audit_trail
Limits
- Emission is available over HTTP. The consume side (offsets, retry, dead letters, replay) is a library API that the server's agent, approval and run subsystems use; there is no public HTTP endpoint to consume events.
- Retention bounds the event log and nothing else. Idempotency receipts and the audit trail are not pruned, so a workload that uses a fresh idempotency key on every append grows receipt storage without a cap.
- Ordering is defined within an aggregate. Across aggregates the sequence reflects commit order, not a domain relationship.
- Delivery is at least once. Consumers must be idempotent.
- The emit_event mutation is not described in the generated OpenAPI document.
Evidence
- On this siteHTTP API reference
- TestsCovered in the engine repository by 34 outbox tests (gapless sequence under concurrency, stale-version rejection, idempotent re-append, offsets and redelivery, retry then dead-letter, retention expiry, restart survival, project isolation, envelope replay and stale-version cases) and 8 HTTP tests including a crash at each commit boundary
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.