name: cap-theorem-tradeoffs
# description: routing-facing summary of when this skill activates and what it covers.
description: "Use when reasoning about the consistency-availability-partition-tolerance trade-off for distributed data systems: Brewer's CAP conjecture (2000), Gilbert & Lynch's 2002 formal proof, why P is not optional in any real distributed system, the CP-vs-AP dichotomy that follows, PACELC as the extension that names the latency-vs-consistency trade-off that exists even without partition, the relationship between CAP's C and ACID's C (different concepts with the same letter), and the choice procedure of naming what the system must guarantee under partition. Do NOT use for single-node transactional guarantees (use transaction-isolation), choosing an isolation level (use transaction-isolation), the design of replication topologies (use replication-patterns), or sharding decisions (use sharding-strategy)."
# license: SPDX-compatible license identifier for the skill content.
license: MIT
allowed-tools: Read Grep
# metadata: Skill Metadata Protocol fields encoded under Agent Skills-compatible frontmatter.
metadata:
# schema_version: protocol contract version this skill conforms to.
# Integer 8. Prior contract retrievable via `git show schema-v7:schemas/skill.schema.json`.
# version: skill content version (semver). Bumped when the instructional content changes.
# === v8 Classification (subject + public; polyhierarchy via subjects[]) — see ADR-0020 ===
# subject: primary browse shelf — what the skill teaches. One of twelve closed values:
# backend-engineering / frontend-engineering / software-architecture / data-engineering / agent-ops / ai-engineering /
# quality-assurance / design / reasoning-strategy / software-engineering-method / knowledge-organization / product-domain.
subject: data-engineering
# public: publishability / private-data gate. true = safe for public release; false = private/internal.
# Project anchoring lives in project[] and requires grounding when present.
# scope: free-text PRD-style statement of what the skill teaches and where it deploys
# (v8 required; not an enum). Positive scope + portability/grounding + explicit exclusions.
scope: "The consistency-availability-partition-tolerance trade-off for distributed data systems — Brewer's CAP conjecture (2000), Gilbert & Lynch's 2002 proof, why P is not optional, the CP-vs-AP dichotomy, PACELC as the latency-vs-consistency extension that holds even without partition, the CAP-C vs ACID-C distinction, and the choice procedure of naming what the system must guarantee under partition. Portable across any distributed data system; principle-grounded, not repo-bound. Excludes single-node transactional guarantees (transaction-isolation), choosing an isolation level (transaction-isolation), replication topology design (replication-patterns), and sharding decisions (sharding-strategy)."
# public: publishability / private-data gate. true = safe for public release; false = private/internal.
public: true
# taxonomy_domain: optional hierarchical sub-path within `subject`. Slash-delimited
# lowercase kebab-case segments. rename of the original v8 `domain`. Remove when the flat
# `subject` is sufficient.
taxonomy_domain: engineering/data
# owner: team handle, GitHub username, or tool name responsible for keeping this skill current.
# freshness: ISO date the skill body was last reviewed or updated.
# drift_check: truth-source verification record. Object with required `last_verified`
# (ISO date) and optional `truth_source_hashes`. Record hashes with:
# `node scripts/skill-graph-drift.js --record --apply <skill-dir>`.
# === Evaluation Status: three orthogonal axes ===
# eval_artifacts: disk-truth — does an eval file exist on disk?
# none (no intent) / planned (intent declared, no file yet) / present (file exists).
# eval_state: runtime-truth — has the eval been run and passed?
# unverified (no run yet, or no file) / passing (one-shot green) / monitored (cadenced green).
# `monitored` is strictly stronger than `passing` — a forward state for continuous runs.
# routing_eval: routing-coverage — is the skill's activation verified by the harness?
# absent (not verified) / present (gated by lint check 12; harness must exit 0).
# comprehension_state: marker that this skill has populated v6+ Understanding fields
# (mental_model, purpose, boundary, analogy, misconception). Value: `present` or absent.
# stability: lifecycle marker. One of:
# experimental (active development) / stable (production-ready) /
# frozen (no further changes expected) / deprecated.
# When `deprecated`, schema's allOf REQUIRES `superseded_by: <real-skill-name>`.
stability: experimental
# keywords: semantic phrases for fuzzy router activation. v8 cap: max 10.
# Keep terms a user would actually type when starting a task in this skill's domain.
keywords: ["CAP theorem","Brewer","Gilbert Lynch","consistency availability partition","CP system","AP system","PACELC","eventual consistency","linearizability","distributed system"]
# triggers: explicit-match activation phrases the router fires on literally.
# Use when label-based routing is intended; usually keywords + examples are enough.
triggers: ["CAP theorem","CP or AP","what should we do on partition","is this strongly consistent","PACELC"]
# examples: 2-5 realistic user prompts the skill SHOULD activate for.
# Written in the user's voice. Improves retrieval recall beyond keywords alone.
examples: ["decide whether a new distributed service should be CP or AP given its workload","explain why CAP's C and ACID's C are different concepts despite sharing the letter","diagnose a system claiming 'CA' (consistency + availability without P) — likely confused, since P is not optional","design the partition-mode behavior of a multi-region service"]
# anti_examples: near-miss prompts that should route ELSEWHERE.
# Pair with relations.suppresses to indicate the confusable territory's owner.
anti_examples: ["choose a transaction isolation level (use transaction-isolation)","explain the four ACID properties (use transaction-isolation)","design the replication topology of a database (use replication-patterns)"]
# relations: typed graph edges to sibling skills. Six edge types:
# related (adjacency for browse / co-routing expansion) /
# suppresses (exclude listed skills from co-routing when THIS skill wins;
# write reason as "I own this exclusively over X", not "use X instead") /
# verify_with (cross-check; co-loaded as one-hop expansion) /
# depends_on (composition; transitive — A→B→C loads all three) /
# broader / narrower (SKOS-style generalization; broader drives co-load, narrower does not).
# === Understanding fields (when comprehension_state: present) ===
# mental_model: the primitives of the concept and how they relate. One paragraph.
mental_model: |
CAP is Brewer's 2000 conjecture (formal proof by Gilbert & Lynch 2002) that in a distributed data system you cannot simultaneously guarantee all three of: *Consistency* (every read returns the most recent write or an error — replica agreement, often linearizability), *Availability* (every request receives a non-error response), *Partition tolerance* (the system continues despite arbitrary message loss between nodes). Real-world networks partition; P is *not optional*. The choice is between C and A *during a partition*: a *CP system* refuses to serve some requests during partition to preserve consistency (Spanner, etcd, MongoDB with majority, ZooKeeper); an *AP system* serves all requests but may return stale data (Cassandra default, DynamoDB default, Riak). "CA" is not a real choice — partitions happen, and systems that claim it have not actually been tested under partition.
*PACELC* (Abadi 2010) extends CAP by naming the *Else* case: even without partition, the system must trade Latency against Consistency, because synchronous replication for strong consistency takes time. Four PACELC quadrants: *PA/EL* (Cassandra, DynamoDB default, MongoDB default), *PA/EC* (rare; often misconfiguration), *PC/EL* (mixed-mode systems), *PC/EC* (Spanner, Cosmos DB strong, MongoDB with majority-read). Most systems spend the overwhelming majority of their time *not* partitioned, so the steady-state latency-vs-consistency trade-off is where most users' actual experience lives. The consistency-model spectrum — linearizability, sequential, causal, read-your-writes, monotonic reads, eventual — is the vocabulary for naming the C side of the trade-off precisely.
# purpose: the problem this concept solves and why the field exists. One paragraph.
purpose: |
Replaces contradictory distributed-systems claims with shape. Before CAP, the industry claimed simultaneous strong consistency, full availability, and partition tolerance; after Brewer's conjecture and Gilbert & Lynch's formal proof, those claims have constraints. The discipline is making the C-vs-A choice *per workload, intentionally*: a banking core ledger is right to be CP (correctness over availability); a shopping cart's session state is right to be AP (availability over strict consistency); a multi-region CDN is right to be AP with eventual consistency; a schema registry or coordination service is right to be CP. PACELC makes the frame practical — a team that designs for CAP without PACELC has optimized for the rare event (partition) and ignored the daily one (steady-state latency vs consistency). The choice procedure: name what the system must do under partition (lose money if stale → CP; lose users if unavailable → AP), then choose the steady-state PACELC quadrant for the common case.
# boundary: what this concept is NOT. Distinguishes from adjacent skills by naming the
# MECHANISM that differs, not just the label. Universal terms only — no repo-specific nouns.
concept_boundary: |
Distinct from transaction-isolation, which owns the single-system transactional frame — this skill owns the distributed-system frame; CAP's C (replica agreement) is *not* ACID's C (constraint satisfaction), and conflating them is the most common misconception in the space. Distinct from transaction-isolation, which owns single-cluster concurrency correctness — this skill owns multi-replica consistency under network partition; the two layers can compose (a CP system may run at serializable isolation locally) but address different threats. Distinct from replication-patterns, which owns the operational design patterns (primary-replica, multi-primary, leaderless quorum) — this skill owns the theoretical C/A/P trade-off that motivates choosing among them; replication-patterns is the operational realization. Distinct from sharding-strategy, which owns horizontal partitioning across nodes — this skill owns the C/A trade-off when those shards must coordinate or recover from partition between them. Distinct from high-availability or reliability frameworks for single-node systems (HA on a single node is not a CAP concern; CAP applies to distributed-data systems specifically).
# analogy: one-sentence metaphor preserving the core mechanism.
analogy: "CAP is to a distributed database what the Heisenberg uncertainty principle is to physics — you cannot simultaneously have a fully consistent reading and a fully available reading when the network has partitioned, just as you cannot simultaneously measure a precise position and a precise momentum. The trade-off is not a limit of the engineering, it is a limit of the physics; pretending otherwise is the source of every 'CA' system that claims to defy CAP and chooses one side anyway on its first partition."
# misconception: the wrong mental model people bring; corrected explicitly.
misconception: |
The wrong mental model is that CAP says "pick any two of three" as if all three combinations are real choices. They are not. P is mandatory in real networks — physics imposes partitions, and a system that claims "CA" has not been tested under partition; when partition arrives, the system chooses C or A and the team finds out which. Adjacent misconceptions: that CAP-C is the same as ACID-C (they share the letter but measure different things — replica agreement vs constraint satisfaction; a multi-region banking system can have CAP-inconsistent replicas while every replica satisfies the balance ≥ 0 constraint, and can have CAP-consistent replicas while one of them violates the constraint); that CAP is the dominant design concern (most systems are not partitioned most of the time; PACELC's E case — the steady-state latency-vs-consistency trade-off — is the daily experience and the dominant design question); that "strong consistency" is precise (the consistency-model spectrum is wide — linearizability, sequential, causal, read-your-writes, monotonic, eventual; "strong" without specification is imprecise and the choice within the spectrum affects achievable throughput); that single-node systems need CAP analysis (they don't); and that AP means "no consistency at all" (it means *eventually* consistent, with a chosen convergence strategy: vector clocks, CRDTs, last-write-wins, anti-entropy — tunable systems like Cassandra and DynamoDB let the application choose per-operation, and the default settings are not assumed correct without verification per workload). A final misconception: that partition behavior is theoretical — it isn't; chaos engineering and network-partition simulation are how teams verify the system behaves as designed when partition actually arrives.
# concept: legacy v5 nested Understanding block. DEPRECATED — flat fields above
# (mental_model, purpose, boundary, analogy, misconception) win when both are present.
# === Export provenance (set by the export pipeline; do not hand-author) ===
# skill_graph_protocol is a content-label claim distinct from `schema_version` semantics.
# See AGENTS.md § Version Labels Are Earned, Not Bumped.
skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
skill_graph_project: Skill Graph
skill_graph_canonical_skill: skills/data-engineering/cap-theorem-tradeoffs/SKILL.md
# === Health Block (written by the audit loop, not hand-authored) ===
# See SKILL_AUDIT_LOOP.md § The Health Block. UNVERIFIED is the honest default.
#
# structural_verdict: form/export shape (gates 1-2, 7 — external mandates only).
# PASS / PASS_WITH_FIXES / FAIL / UNVERIFIED.
# truth_verdict: truth sources vs declared hashes (gates 3-6).
# PASS / DRIFT / BROKEN / UNVERIFIED.
# comprehension_verdict: gate 8 — cheap recitation smoke test. Never alone certifies.
# PASS / SHALLOW / REDUNDANT / UNVERIFIED / PROVISIONAL / SKIPPED_BASELINE_HIGH / NA.
# application_verdict: gate 9 — the primary quality signal. APPLICABLE is the only verdict
# that certifies the skill is USEFUL (grader-confirmed). PROVISIONAL = one model self-assessed.
# APPLICABLE / REDUNDANT / HARMFUL / MIXED / FALSE_POSITIVE / PROVISIONAL / UNVERIFIED.
relations:
related: ["transaction-isolation","transaction-isolation","replication-patterns","sharding-strategy"]
suppresses: ["replication-patterns","sharding-strategy"]
verify_with: ["transaction-isolation","replication-patterns"]
CAP is Brewer's 2000 conjecture, formalized by Gilbert and Lynch in 2002: during a network partition, a distributed data system cannot guarantee both replica consistency and availability. Partition tolerance is not a selectable feature in real networks; the practical design question is what the system must do when messages are delayed or lost.
Use this skill to name the partition-mode choice and then extend it with PACELC for the more common steady-state latency-vs-consistency tradeoff. It is a distributed-data-systems frame, distinct from ACID's single-transaction guarantees, isolation-level tuning, replication topology design, or sharding mechanics.
The consistency-availability-partition-tolerance trade-off that physics imposes on distributed data systems. Covers Brewer's 2000 conjecture, Gilbert & Lynch's 2002 formal proof, why P is mandatory in real networks (the practical choice is CP vs AP, not "any two of three"), the PACELC extension (Abadi 2010) that names the latency-vs-consistency trade-off in the non-partition case, the CAP-C vs ACID-C confusion that is the most-common misconception in the space, the spectrum of consistency models from linearizability to eventual consistency, the four PACELC quadrants (PA/EL, PA/EC, PC/EL, PC/EC) and the systems that occupy each, and the partition-mode choice procedure.
CAP is the frame that made distributed-systems design honest. Before Brewer's 2000 conjecture and Gilbert & Lynch's 2002 proof, the industry made contradictory claims about consistency, availability, and fault tolerance; after CAP, those claims have shape. Under partition — which physics guarantees will happen — you preserve consistency at the cost of availability, or availability at the cost of consistency.
PACELC is the frame that made CAP practical. Most systems spend the overwhelming majority of their time not partitioned; PACELC's E (else) case names the latency-vs-consistency trade-off in the common case, which is where most users' actual experience lives. A team that designs for CAP without PACELC has optimized for the rare event and ignored the daily one.
The two C's measure different things. The system needs both to be operationally correct.
Choosing for the steady-state matters more than choosing for partition in most workloads.