Durable and Live Delivery

After-commit timing promises the message follows the commit: staged in the same transaction, the change and its message share one fate. An emits effect is a domain event the aggregate raises, and persistence stages that event in the outbox in the same commit as the aggregate, as litespec/backend/application#emit-declared-integration-events-after-commit requires. An effect sent from memory instead would vanish on a crash between the commit and the send. litespec/core/use-cases#declare-every-effect-with-one-verb-and-its-timing states the effect verbs and their timing, and async effects dispatch without the transaction.

Reviewed forEach after-commit emits and runs effect stages in the outbox in the same transaction as its changes, with each domain event staged in the same commit as its aggregate.

Marked guidance: a reviewer answers this question.

A published fact without a record is a promise nobody versioned: readers depend on fields no page states, and a field change breaks them without a diff. The integration-event record states the direction, the payload with its classifications, and the trust readers place in it. The edges page states the declaration and the record.

Reviewed forEach emits effect names an integration-event record carrying direction, payload, and trust.

Marked guidance: a reviewer answers this question.

Delivery crosses a system boundary, so the team agrees up front on the guarantee, the boundary, the duplicate behavior, the retry horizon, and the runbook that recovers when delivery fails. Without that agreement, the writer assumes once-only delivery while the target assumes retries, and both discover the mismatch in production. The agreement lands before the first message does.

Reviewed forEach delivery specification documents guarantee, downstream boundary, duplicate behavior, retry horizon, and recovery runbook.

Marked guidance: a reviewer answers this question.

Outbox storage, dispatch, retries, and replay exist to prevent loss; a reaction or job whose loss the operators accept and can repeat by hand needs none of that machinery. The reaction's or job's onFailure states its handling, and the use case page records the accepted gap.

Reviewed forReactions and jobs whose loss the operators accept and can repeat manually carry no outbox records.

Marked guidance: a reviewer answers this question.

Without an outbox record, nothing survives a crash between the commit and the emit, so the reaction or job emits immediately after its commit succeeds and accepts the gap. Emitting before the commit risks worse: it fires for a change the database then rolls back.

Reviewed forExcluded reactions and jobs emit after commit success with no staged outbox record.

Marked guidance: a reviewer answers this question.

The business change and its message share one fate: both persist or neither does. Staging the message in the same scoped business session as the aggregate changes puts both under one commit, so a crash can never leave an accepted change without its message or a message without its change.

Reviewed forPending durable messages stage in the same scoped session as their aggregate changes.

Marked guidance: a reviewer answers this question.

The command scope ends when the request ends, while dispatch happens later in a Worker that never saw the request. Serializing the message into an outbox record gives that Worker everything it needs after the scope is gone.

Reviewed forEach pending durable message lands serialized in an outbox record.

Marked guidance: a reviewer answers this question.

The dispatcher, the retry logic, and the operator each read the record: identity and type route it, the schema version selects its reader, time and tenant scope it, and state, attempt, and next-attempt data drive the retry. A field stored nowhere forces one of those readers to guess.

Reviewed forEach outbox record carries identity, kind, type, schema version, time, payload, tenant, state, attempt, and next-attempt data.

Marked guidance: a reviewer answers this question.

When delivery stalls, the operator opens the record first: the last error summary says why the previous attempt failed, and the completion time says which records finished. Without that evidence on the record, each investigation starts from scattered logs instead.

Reviewed forEach outbox record retains its last error summary and completion time.

Marked guidance: a reviewer answers this question.

An integration event, a journey-step command, and a provider side effect dispatch through different owners and transports, so the record names which one it holds. The integration event cites its integration-event record, so the staged message traces to the published fact it carries.

Reviewed forEach outbox record names integration event, journey-step command, or provider side effect, with integration events citing their integration-event record.

Marked guidance: a reviewer answers this question.

Two commits on two connections can split around a crash: the business change persists while the message rolls back, or the message persists for a change that never happened. Sharing one PostgreSQL database does not make separate transactions atomic, so the message joins the business transaction instead.

Reviewed forWriter sources stage through the business session with no separate connection or commit.

Marked guidance: a reviewer answers this question.

Dispatch needs time, retries, and network calls that no request transaction can hold. The Worker claims pending records, dispatches a bounded batch, and records each outcome, so the request commits fast while delivery proceeds on its own schedule.

Reviewed forThe Worker claims pending records, dispatches bounded batches, and records each outcome.

Marked guidance: a reviewer answers this question.

A network call inside the request transaction holds database locks while the outside world answers, and a slow target slows every request behind it. The request commits only to make the message eligible; the Worker performs the delivery later.

Reviewed forRequest paths commit eligibility only, with dispatch living in the Worker.

Marked guidance: a reviewer answers this question.

Several Workers poll the same store, so each dispatch attempt needs one owner: the lease owner, the lease expiry, and the fencing value name it. The short transaction takes the claim without holding locks into the delivery itself.

Reviewed forEach claim takes owner, expiry, and fencing value in a short transaction.

Marked guidance: a reviewer answers this question.

A network call to a slow target can last seconds or minutes. Holding the claim transaction open across that call pins database locks and connection slots, starving the Workers behind it; releasing the claim first lets the database serve other work while the call runs.

Reviewed forClaim transactions close before the Worker makes network calls.

Marked guidance: a reviewer answers this question.

A Worker that lost its lease, through a crash, a pause, or an expiry, can wake up after another Worker claimed the same record. Checking the lease and fencing value before each update stops the stale Worker from overwriting the current owner's result.

Reviewed forRecord updates succeed only under the current lease and fencing value.

Marked guidance: a reviewer answers this question.

A Worker can die between claiming a record and dispatching it. Returning expired claims to eligible work lets a live Worker pick them up, so one crash delays a message instead of losing it.

Reviewed forExpired claims return to eligible work for a live Worker.

Marked guidance: a reviewer answers this question.

The target can accept a message while the Worker crashes before recording completion, and the requeued claim then dispatches it again. Delivery promises at-least-once, so every event handler handles the same message more than once without corrupting its state.

Reviewed forEach event handler keeps correct state when the same message arrives twice.

Marked guidance: a reviewer answers this question.

Handling a repeat means recognizing it: the message ID or a business idempotency key gives the event handler a stable identity to check at its command or side-effect boundary. Without that key, the handler processes the repeat as new work and pays, notifies, or ships twice.

Reviewed forEach event handler checks message ID or business key at its Command or side-effect boundary.

Marked guidance: a reviewer answers this question.

One delivery for all handlers retries every handler when one fails. Each handler therefore gets its own delivery with its own retries and dead letter, and each delivery still ends in repeat-safe handling under litespec/ext/outbox#accept-repeated-delivery.

A loan-borrowed event feeds a due-notice handler and a statistics handler. The notice delivery retries on its own schedule while the statistics delivery stays complete.

Reviewed forEach event reaches each of its handlers as a separate delivery with its own retries and dead letter.

Marked guidance: a reviewer answers this question.

Marking a record complete before the target accepts it declares a delivery that never happened, and no retry follows because the record looks done. The Worker waits for the target boundary's acceptance before recording completion.

Reviewed forCompletion records follow target acceptance, with no early completion.

Marked guidance: a reviewer answers this question.

A failing target with ten thousand pending messages meets a retry storm when every message retries at once on a fixed interval. Bounded exponential backoff with jitter spreads the retries over time and caps the total, so the target recovers instead of drowning.

Reviewed forRetries run bounded exponential backoff with jitter.

Marked guidance: a reviewer answers this question.

Some failures never clear on retry: a deleted destination, a rejected payload, a revoked credential. Retrying those forever burns resources and buries the real backlog, so the dispatcher classifies them, stops at its retry bound, and keeps the evidence an operator needs to investigate and replay safely.

Reviewed forPermanent failures stop at the retry bound with safe investigation and replay data retained.

Marked guidance: a reviewer answers this question.

A dead outbox store and a failed delivery ask for different recoveries: the first needs a database restored, the second needs one destination investigated. Each carries its own signal. The store's availability is a gauge the readiness endpoint reads, while a claimed message's outcome is a counter carrying the result, following the OpenTelemetry metrics specification. A single error counter cannot tell an operator whether to restore a database or investigate one destination.

Reviewed forStore availability reads as a gauge while claimed-message outcomes read as a counter.

Marked guidance: a reviewer answers this question.

A Worker that polls a dead store on a tight loop writes an exception per iteration and fills disks and log quotas before anyone reads the first one. Bounded backoff with rate-limited logging keeps the Worker alive and quiet until the store returns.

Reviewed forPolling during a store outage backs off with rate-limited logging.

Marked guidance: a reviewer answers this question.

Retry and poison handling act on a claimed message; when the store itself is down, no claim exists and no message waits for delivery. Running retry logic against the outage double-counts attempts and can dead-letter messages whose only fault was an unreachable store.

Reviewed forRetry and poison handling touch claimed records only.

Marked guidance: a reviewer answers this question.

A host that reports unready still serves traffic it cannot finish when its Workers keep polling dead stores. Gating dispatch on readiness stops the polling, so the host fails fast and recovers instead of churning against storage that cannot answer.

Reviewed forUnready hosts stop dispatch and dead-store polling.

Marked guidance: a reviewer answers this question.

An outbox record outlives the deployment that wrote it, so the dispatcher meets records written by several versions at once. A stable type name with an explicit schema version tells the dispatcher which reader parses each record; without the pair, one shape change breaks every record written before it.

Reviewed forEach message carries a stable type name with an explicit schema version.

Marked guidance: a reviewer answers this question.

During rollout and rollback, several application versions share one store and write different valid shapes into it. The dispatcher reads from every version that can coexist, or the deployment itself causes delivery failures.

Each message record therefore carries its own shape version, and the dispatcher selects a reader from that value. Adding an optional member with a defined absent-value behavior needs no new version. Removing a member, renaming one, narrowing a type, or changing a discriminator needs a new version, and the reader for each version stays until no record carries that version.

Reviewed forThe dispatcher reads records from every coexisting application version.

Marked guidance: a reviewer answers this question.

Pending count, failed count, oldest pending age, attempts, dispatch duration, and success rate together show whether delivery keeps up: growth in the backlog or age reveals a stall, while duration and success rate reveal a struggling target. Without these indicators, the first sign of failure is a customer asking where their message went.

Reviewed forThe deployment publishes pending count, failed count, oldest pending age, attempts, dispatch duration, and success rate.

Marked guidance: a reviewer answers this question.

A shipment notice delayed an hour and a receipt delayed a week carry different business consequences, so each use case sets alert thresholds from its own delivery target. Setting records hold those thresholds, so the alert fires when delay passes what the business accepted.

Reviewed forAlert thresholds sit in setting records derived from each use-case delivery target.

Marked guidance: a reviewer answers this question.

pending becomes processing, and processing becomes dispatched, pending, or dead-letter, while audited replay moves dead-letter back to pending. Three of the four states carry data the others do not: processing holds a lease expiry, dispatched holds a dispatch time, and dead-letter holds a failure reason and an attempt count. A four-value label forces those onto nullable columns that mean something in one state each, which is the shape litespec/backend/domain#model-every-closed-set-of-domain-values-as-a-closed-type-hierarchy removes everywhere else.

OutboxState.Processing carries one unexpired lease before a dispatcher records OutboxState.Dispatched or a retry state.

Reviewed forOutbox lifecycle states form sealed records over an abstract base with documented transitions.

Marked guidance: a reviewer answers this question.

The target suppresses a repeat by recognizing its identity, which works only when every retry and replay carries the same message ID. A dispatcher that mints a new ID per attempt turns each retry into a new message the target processes again.

Reviewed forMessage ID stays identical across retry and replay.

Marked guidance: a reviewer answers this question.

A replay dispatches a message the system already handled or dead-lettered, so the team records who replayed it, why, when, and which failure it answers. Without that record, a duplicate delivery looks like a dispatcher bug instead of an operator's decision, and nobody can reconstruct the choice.

Reviewed forEach replay records actor, reason, time, and failure without editing the payload.

Marked guidance: a reviewer answers this question.

WebApi writers and Worker dispatchers deploy independently, so a writer can run ahead of the oldest active Worker. When the writer emits a shape that Worker cannot read, those messages dead-letter on arrival through no fault of their own.

Reviewed forEvery active Worker reads the type and schema version of new messages.

Marked guidance: a reviewer answers this question.

In a mixed-version rollout, old and new records sit in one store. Deploying compatible readers before the writers that emit new shapes keeps every record dispatchable at every step; the reverse order strands new records until the readers catch up.

Reviewed forReleases deploy compatible readers before additive writers.

Marked guidance: a reviewer answers this question.

Rolling back the deployment does not roll back the store: records the new writer staged but nobody dispatched stay behind. The rollback Runbook names how the previous version handles them, or they sit undispatched with no owner and no reader.

Reviewed forThe rollback Runbook covers records the new writer staged but nobody dispatched.

Marked guidance: a reviewer answers this question.

Open connections cost memory, CPU, and operating attention on every host, so the team writes down what polling costs, what the update target requires, and how many connections to expect before choosing transport. The use case page carries that record, so a later reader sees which measurements justified the choice.

Reviewed forThe use case page holds the polling record, measured cost, update target, expected connections, and recovery behavior.

Marked guidance: a reviewer answers this question.

Realtime transport that serves only a feeling of immediacy spends connection capacity and operating attention without moving any target. The extension asks for a measured update requirement first, so polling stays where polling suffices.

Reviewed forThe realtime decision cites a measured update requirement.

Marked guidance: a reviewer answers this question.

A notification that flows one way, from server to browser, needs no bidirectional channel with groups and fallback. Server-sent events carry it over plain HTTP, which passes through proxies and firewalls without extra negotiation.

Reviewed forEach one-way notification travels over the server-sent events boundary in code.

Marked guidance: a reviewer answers this question.

Two-way messages, server-managed groups, and transport fallback need a channel built for interaction, which one-way events cannot provide. SignalR supplies all three, so the use case that needs them takes SignalR instead of stretching events past their shape.

Reviewed forEach bidirectional use case runs on SignalR groups, messages, or fallback in code.

Marked guidance: a reviewer answers this question.

Hosted platforms limit connection duration, idle timeouts, and transport upgrades in ways that differ per host. Recording the transport choice with its expected platform support surfaces the mismatch before deployment instead of during the first long-lived connection.

Reviewed forThe use case page names its transport choice with the expected hosted-platform support.

Marked guidance: a reviewer answers this question.

A realtime channel delivers an update seconds after the change, so the served query promises {"mode": "immediate"}; where the pushed value still awaits a later decision, it promises {"mode": "advisory", "authority": "<record id>"} naming the record that holds the authoritative value. Without the declared freshness, a reader cannot tell whether the live value is final or provisional.

Reviewed forWhich realtime-served queries lack an immediate or advisory freshness object on their output? Look at the served query beside the realtime use case.

Marked guidance: a reviewer answers this question.

Connecting proves who the caller is; it says nothing about which user's, tenant's, or resource's updates the caller may hear. Each user-, tenant-, or resource-scoped subscription checks its own authorization, so one valid connection cannot listen in on another tenant's data.

Reviewed forThe connection tests show authenticated connections only, with each scoped subscription authorized.

Marked guidance: a reviewer answers this question.

A connection can outlive the grant that opened it: tokens expire, roles change, sessions end. Revalidating access on token and session lifetime closes the connection whose grant died instead of streaming updates to a caller who no longer qualifies.

Reviewed forA connection whose token or session expired loses access in the revalidation tests.

Marked guidance: a reviewer answers this question.

Connections drop, and a notification sent during the gap never arrives. Bounded backoff reconnects without hammering the server, and refreshing authoritative state after the gap replaces whatever the missed notifications would have changed.

Reviewed forThe client reconnects with bounded backoff and refreshes authoritative state after a gap in the recovery tests.

Marked guidance: a reviewer answers this question.

The transport can deliver a notification twice or deliver two of them out of order. A client that applies each notification as an absolute update corrupts its state on the first duplicate; a client built for repeats and reordering converges on the truth either way.

Reviewed forDuplicate and reordered notifications leave client state correct in the client tests.

Marked guidance: a reviewer answers this question.

Each open connection holds memory, each message costs CPU, and a flood of either starves the host. The deployment sets four bounds as setting records - concurrent connections per host, receive message size, parallel invocations per connection, and client timeout - with each value drawn from the deployment's own connection count and message size and the observation that produced it. The platform's realtime security guidance names the same settings.

Reviewed forThe four deployment bounds live as setting records with their values beside the deployment.

Marked guidance: a reviewer answers this question.

A client that reads slower than the server writes grows its buffer without end, consuming host memory meant for every subscriber. Bounded buffering with backpressure disconnects or slows the laggard instead of letting one slow reader starve the rest.

Reviewed forSlow-client buffering in the server code is bounded with backpressure.

Marked guidance: a reviewer answers this question.