Set consistency requirements one user action at a time

Choose consistency by user action, not by database marketing label. For each read or write, name the anomaly that would harm the user, the freshness bound, whether session order matters, and the recovery behavior. The same product can require strong coordination for a username claim, read-your-writes for profile edits, monotonic reads for a workflow, and eventual consistency for aggregate counts.

Describe the bad history

A consistency model constrains which operation histories are legal. Jepsen’s consistency reference explains models in terms of histories, phenomena, and dependencies. Translate that abstraction into a sentence a product engineer can test: “After I save my address, this browser must not show the older address,” or “Two buyers must not both acquire the last item.”

Start with four common needs. Strong or linearizable behavior makes a completed write visible to subsequent operations in a single real-time order. Read-your-writes prevents a session from losing its own successful update. Monotonic reads prevent one session from moving backward after observing a newer value. Eventual consistency permits staleness while replicas converge, with no useful freshness bound unless the system adds one.

Do not ask whether the whole application is “eventually consistent.” Ask whether the post-save confirmation, another device, a background job, and a public feed may each observe different versions, and for how long.

Fill out a workflow worksheet

For “rename project,” record:

• The command must reject a stale version rather than overwrite a concurrent rename.
• The submitting browser must read its new name immediately.
• Other regions may show the old name for up to 30 seconds.
• Audit history must preserve ordered facts even if the projection lags.
• If propagation exceeds the bound, show pending state and retry asynchronously.

This worksheet separates write conflict, session visibility, global freshness, ordering, and failure UX. It also gives observability a target: measure propagation delay and stale-read rate against the declared bounds.

Azure Cosmos DB’s consistency documentation distinguishes strong, bounded staleness, session, consistent prefix, and eventual levels. Its session consistency uses a session token as a minimum version barrier for read-your-writes and write-follows-reads within the relevant scope. The portable lesson is that session guarantees need context to travel with the user request. If a follow-up lands on another service instance and the token or version is lost, the promised guarantee may disappear.

Implement the narrowest sufficient mechanism

Use a transaction or conditional write for uniqueness and inventory. Carry a session or consistency token after a user write. Route a workflow to the same leader when monotonic state matters. Include resource versions in caches and reject older invalidations. For feeds and counts, expose update time or pending status rather than paying coordination cost that produces no user value.

Be precise about multi-object actions. A linearizable read of each record separately does not necessarily give a consistent snapshot across all records. If an invoice total must match its lines, read them in one snapshot or store a versioned materialization with defined rebuild behavior.

Test promises during failure

Run scenarios with replica lag, failover, cache delay, a new browser session, concurrent writers, and a retry after an ambiguous timeout. Assert user-observable histories, not vendor setting names. A test for read-your-writes should send the write response’s token or version through the same frontend and gateway path production uses.

Pick one frustrating “saved but disappeared” workflow. Write its anomaly sentence, freshness bound, session scope, and fallback. Then instrument the write version and subsequent read version. Once that pair is visible, you can choose a targeted token, routing rule, or stronger read instead of upgrading every query.

Name the acceptable sequence explicitly for every client surface.