Consistency models are part of the API contract

pattern
established
fragment

Scope. Consistency is a vector of guarantees, not a single scale: causal consistency and session guarantees cover different axes and do not form a total order. The only thing strictly ordered is the cost of real time: linearizability requires it, sequential and causal do not.

Conflicts with: Linearizability ↔ latency/availability (PACELC)

Primary sources: Herlihy, Wing — Linearizability: A Correctness Condition for Concurrent Objects

“Read your writes” is not a property of the database but a guarantee the service either gives or doesn’t, and it must be written into the contract. Consistency is not a single “stronger/weaker” scale but a set of observable guarantees: operation order, visibility of other clients’ writes, freshness, behavior within a session, binding to real time. Linearizability is the most expensive because it demands the last one: an operation must appear to take effect at a single instant between invocation and response. Most features are well served by session guarantees (read-your-writes, monotonic reads) — paying for linearizability by default means paying for something you don’t use.

fragment

Java

// read-your-writes via a version token, no sticky sessions
record WriteResult(OrderId id, long lsn) {}          // the write's LSN/HLC goes back to the client

Order read(OrderId id, long minLsn) {
    var replica = pool.any();
    replica.waitForLsn(minLsn, TIMEOUT);             // replica catches up, or we route to primary
    return replica.get(id);
}
// client carries lsn in a cookie/header → its own writes are visible,
// others' only eventually; that is a session guarantee, declared explicitly

// same at the contract level: the request/response type carries the guarantee
type ReadConsistency int

const (
    Eventual ReadConsistency = iota
    ReadYourWrites
    Linearizable // documented as expensive: goes through the leader
)

func (s *Store) Get(ctx context.Context, id OrderID, c ReadConsistency) (Order, error)

A design-review test question: “which anomaly will the user pay for this optimization with — and do they know about it from the contract?”

Exposing long lsn leaks PostgreSQL into the contract. What goes out is an opaque consistency token with documented semantics, a wait timeout and defined behavior when it expires (fall back to reading from the leader or an explicit error).