# Consistency Models > Choosing distributed consistency guarantees as an engineering decision: linearizability, sequential/causal ordering, session guarantees (read-your-writes, monotonic reads), bounded staleness and eventual convergence, stated as observable contracts rather than a false total ladder; CAP stated correctly—the choice between C and A exists only while partitioned—and PACELC, replica paths and transaction isolation boundaries. Use when a user cannot see their own write, when a read after a write returns the previous value, when a design names a model instead of an observable requirement, when reads are being routed to replicas, or when someone cites "pick two". Does not cover multi-service atomicity (distributed-transactions-and-sagas), quorum arithmetic (consensus-and-quorums), caches (caching-strategies), replicated cache topology (cache-sharding-and-replication), or the JMM's happens-before (java-memory-model). - Skill: `robsonkades/consistency-models` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add robsonkades/consistency-models` - Raw SKILL.md: https://api.skillmd.com/api/skills/robsonkades/consistency-models/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: robsonkades (https://skillmd.com/u/robsonkades) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/robsonkades/consistency-models --- # Consistency Models ## Purpose Specify the weakest set of guarantees that satisfies observable requirements and price it. The models are not one total ladder: recency, ordering, session, convergence and multi-object atomicity are different dimensions. Stronger coordination often costs latency or partition availability, but the cost depends on topology, implementation and workload. The failure this prevents is the requirement expressed as a model name. "We need strong consistency" cannot be verified, priced, or tested. "A user must never see their own comment disappear after posting it because a replica has not applied the write" names an observation. Eventual convergence alone is insufficient; it can coexist with read-your-writes for that session. No global linearizability requirement follows from this observation alone. ## Workflow 1. **State the requirement as something a client observes.** "Two users must never both be assigned seat 14C." "A user must never see their own write disappear." "A balance may lag by up to five seconds but must never go backwards." No model names yet. 2. **Ask who observes it.** Requirements that hold only for the session that performed the write may need session guarantees. Compare their routing and metadata costs with the coordination required by the actual cross-client contract. 3. **Map each requirement to guarantees and scope**, using `references/requirement-to-model.md`: object/key range, session versus all clients, normal operation versus partition, and any time bound. Record the cost and fallback. 4. **Trace the whole read path, not the database.** A linearizable store behind a read-replica router, a CDN, or a cache delivers the weakest link in the chain. The path has a consistency model; the store only has one of its components. 5. **Separate but connect isolation from consistency explicitly.** Decide the transaction isolation level for interactions among concurrent transactions, and the distributed model for ordering and recency across nodes; a product may bundle these as strict serializability. 6. **Write a test that fails under the model you rejected.** Stale-read detection with a deliberately lagged replica, or a partition injected with a network fault. Techniques are in `references/read-your-writes-in-java.md`. Inspect the project's JDK, resolved Spring/driver versions, transaction manager, replication mode, commit acknowledgement policy and read routing before proposing implementation details. The Java reference contains partial Spring sketches, not a declared runnable Java baseline. When evidence is absent, state the candidate guarantee and the missing configuration or experiment; do not infer semantics from annotations or topology names. Deliver the observable contract, affected path, supporting evidence, failure behavior and one test that distinguishes it from a rejected design. ## Rules - Do not stop at a model name. Name the observation, scope, failure condition and time bound, then map it. A model name in a requirements document is an unpriced, untestable assertion. - **CAP is about behaviour during a partition, not a general "pick two".** With no partition, the theorem does not force a choice between consistency and availability; it says that while a partition is in progress, a system cannot both stay linearizable and satisfy CAP's availability definition for every request to a non-failing node. That theorem-level availability is not an SLO percentage, and real systems may reject only affected keys/operations. - **PACELC is a useful design heuristic, not a replacement theorem.** If Partitioned, choose Availability or Consistency; Else, choose Latency or Consistency. The else-branch concerns operation without a partition, including choices such as replica routing, quorum sizes, cache TTLs. - Linearizability gives each operation an instantaneous point between invocation and response and respects real-time precedence. It is compositional across independently linearizable objects, but two separate operations still do not become one atomic multi-key transaction. Cross-object invariants need an invariant-preserving protocol. Compensation is an option only when the business contract permits temporary violations and subsequent repair. - **Serializable isolation is not a recency guarantee.** Serializability says the outcome equals _some_ serial order of transactions; linearizability constrains that order to respect real time. A serializable transaction may legally read a stale snapshot. Strict serializability is the conjunction. Isolation level and distributed consistency are orthogonal axes; naming one does not constrain the other. - Read-your-writes, monotonic reads, monotonic writes and writes-follow-reads are **session guarantees**—often cheaper than global ordering, but session identity, failover, roaming clients, expiry and watermark storage are part of their cost. - Causal consistency orders causally related operations and permits different orders for concurrent ones. Highly available causal designs exist under specific replication/conflict assumptions; do not convert that into a universal “strongest AP model” claim. - **Eventual consistency promises convergence only under its stated conditions**, typically after updates stop and communication/reconciliation resumes. It has no deadline. A numeric requirement is bounded staleness/SLA evidence, not plain eventual consistency; measure end-to-end visibility, not just transport lag. - A cache in front of a strongly consistent store downgrades the path to the cache's own staleness behavior. If the requirement is read-your-writes, use a commit/version token or route to an authoritative path known to include the write; invalidation alone has stale-fill races. Cache mechanics are `caching-strategies` and `cache-sharding-and-replication`. - `@Transactional(readOnly = true)` is transaction metadata that frameworks/drivers may use for routing or optimization; effects vary by stack. By itself it chooses no replica and promises no recency. - **This is not the Java Memory Model.** `happens-before`, `volatile` and `synchronized` concern visibility between threads sharing one memory; that subject is `java-memory-model`. The vocabulary overlaps ("sequential consistency" exists in both) and the scales do not. Do not reason about replica lag with JMM rules, or the reverse. ## Primary sources - [Herlihy and Wing — Linearizability](https://cs.brown.edu/~mph/HerlihyW90/p463-herlihy.pdf) - [Brewer — CAP twelve years later](https://www.infoq.com/articles/cap-twelve-years-later-how-the-rules-have-changed/) - [Terry et al. — Session Guarantees](https://www.cs.cornell.edu/courses/cs734/2000FA/cached%20papers/SessionGuaranteesPDIS_1.html) - [etcd API guarantees](https://etcd.io/docs/v3.6/learning/api_guarantees/) ## References - [Requirement to model](references/requirement-to-model.md) — a decision table from an observable business requirement to sufficient guarantees, with costs and counterexamples when a needed guarantee is absent. Read when a requirement is being written, or when a chosen model needs justifying. - [Read-your-writes in Java and Spring](references/read-your-writes-in-java.md) — routing a session's reads to the primary for a bounded window after a write, why `@Transactional(readOnly = true)` is not a guarantee, the `LazyConnectionDataSourceProxy` trap in routing data sources, and how to detect stale reads in tests. Read when reads are being sent to replicas.