Skip to content

Consistency Contract Decision Record

Decision-record artifact — instantiates Shared-State Consistency Contract Design

A written record that fixes the chosen consistency contract — scope, guarantee, operation semantics, client-facing promise, and the assumptions behind them — as the single source of truth.

A Consistency Contract Decision Record is the document that pins down what the contract actually is before any protocol is chosen. Modeled on the Architecture Decision Record, it captures, for one piece of shared state: its scope, the invariant being protected, the guarantee profile selected, what each operation promises, the promise exposed to clients, and — critically — the alternatives considered, rejected, and why. Its distinguishing role among these mechanisms is that it produces no runtime behavior at all: it is the authored specification and rationale that every protocol, test, and dashboard is answerable to — the thing that makes "we chose eventual here" a deliberate, revisitable decision rather than an accident of defaults.

Example

A platform team runs a config service that pushes feature flags to thousands of app servers. A flag flip once caused a partial outage because half the fleet read the new value and half the old one for several minutes, and nobody could say whether that was supposed to be possible. Writing a decision record forces the questions into the open: scope = "a single flag key"; invariant = "no server acts on a flag combination that was never simultaneously live"; guarantee = "monotonic per server, converged fleet-wide within ≈10s"; client promise = "treat flags as eventually consistent; never assume two flags flip atomically." The record names the rejected option (strong consistency on every read — too slow for the hot path) and the assumption it rests on (bounded clock skew across the fleet). Now the next flip is designed against a written contract, and the post-incident question "was this legal?" finally has an answer.

How it works

The distinctive thing is that it is deliberation captured, not machinery. The record walks the contract-design decisions in order: define the state's scope and its invariant; state the operations and what a success response means; choose the weakest guarantee profile that still protects the invariant; write the client-facing promise in plain terms; and log the fault, partition, and clock assumptions along with the rejected alternatives. It is versioned alongside the code, and — per the archetype's warning against deploying semantic changes as configuration changes — a change to the contract is a change to this record, reviewed as such.

Tuning parameters

  • Granularity — one record per state object vs. one per service; finer records are precise but proliferate, coarser ones blur distinct guarantees together.
  • Bindingness — an advisory doc vs. a gate that must be updated and reviewed before any semantic change ships; only the latter stops silent drift.
  • Assumption depth — how explicitly clock, partition, and failure assumptions are enumerated; more depth surfaces latent fragility but costs authoring effort.
  • Alternatives captured — how much of the rejected design space is recorded; richer rationale ages better but is heavier to write.

When it helps, and when it misleads

Its strength is being the antidote to the archetype's core failure — vague labels, mechanisms chosen before invariants, and semantic changes slipped in as config — by giving clients and implementers one authoritative answer to "what does a successful operation mean here?" Its failure mode is the failure mode of all documents: it can drift from the running system until it describes a contract nobody implements, lending false confidence.[1] The classic misuse is writing it once to satisfy review, then changing consistency behavior in code without touching the record. The discipline is to bind the record to change control so a semantics change is a record change, and to periodically test the live system against what the record claims.

How it implements the components

  • shared_state_scope — it delimits exactly which state the contract covers.
  • operation_semantics_contract — it states what each operation promises and what a success response means.
  • consistency_guarantee_profile — it records the chosen guarantee level as a deliberate selection, not a default.
  • client_facing_semantics_contract — it authors the plain-language promise clients may rely on.
  • assumption_register — it logs the fault, partition, and clock assumptions the guarantee rests on.

It specifies the contract but implements none of the runtime: enforcing the order is Causal-Consistency Protocol or Leader-Based Replication, verifying conformance is Consistency History Checker, and migrating from one contract to another is Safe Consistency Migration Workflow.

Notes

This artifact is upstream of every sibling: the protocols only implement whatever guarantee it names, and the checker only tests against the model it records. It is where the archetype's essence — "choose the weakest guarantee that still protects the real invariant" — is actually exercised. If it does not exist, the other mechanisms are still making a choice; they are just making it implicitly.

References

[1] Architecture Decision Record (ADR) — a lightweight, versioned document capturing one significant design decision, its context, and its consequences (popularized by Michael Nygard). A consistency contract is exactly the kind of consequential, easily-eroded decision ADRs exist to preserve. ↩