CAP Theorem

Architecture PHP 5.0+ Advanced

debt(d9/e7/b7/t7)

d9 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'silent in production until users hit it' (d9). The detection_hints explicitly state 'automated: no' and describe the pattern as 'Distributed system design with no documented consistency/availability trade-off decision.' There is no tool that can detect a missing or incorrect CAP trade-off decision — it only manifests when real network partitions occur in production and users experience stale reads, rejected writes, or divergent data.

e7 Effort Remediation debt — work required to fix once spotted

Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix describes a conceptual choice (stay consistent or stay available during partitions), but actually implementing that choice once a system is built incorrectly requires changing data store selection, replication strategy, client retry logic, and API contract guarantees — a cross-cutting architectural change touching many components, not a single-file fix.

b7 Burden Structural debt — long-term weight of choosing wrong

Closest to 'strong gravitational pull' (b7). The choice of CP vs AP trade-off shapes every future decision about database selection, caching strategy, replication topology, and failure-mode handling. As the tags indicate (architecture, distributed, database, fundamentals), this is a foundational decision that every subsequent design choice in a distributed system must respect and work around.

t7 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'serious trap' (t7). The misconception field explicitly states the canonical wrong belief: developers believe they must choose exactly two of three properties, when in fact partition tolerance is non-negotiable and the real choice is only C vs A. Additionally, common_mistakes note conflating CAP consistency with ACID consistency — a second serious trap where the same word means different things across contexts, contradicting familiar usage.

About DEBT scoring → scored by claude-sonnet-4-6 · 2026-05-06 · reviewed by human

Also Known As

CAP theorem consistency availability partition Brewer theorem

TL;DR

A distributed system can guarantee only two of three simultaneously: Consistency, Availability, Partition Tolerance — driving fundamental design trade-offs.

Explanation

Eric Brewer's CAP theorem states that during a network partition a distributed system must choose between Consistency (all nodes see the same data — no stale reads) and Availability (every request gets a response, possibly stale). Since partitions are inevitable in production, the real choice is CP (favour consistency, refuse uncertain requests — ZooKeeper, HBase) vs AP (favour availability, serve possibly stale data — Cassandra, DynamoDB). The PACELC theorem extends this: even without partitions there is a latency/consistency trade-off. For PHP applications, CAP informs choices about distributed caching strategies, session storage backends, and distributed lock semantics.

Diagram

flowchart TD
    CAP{CAP
Theorem}
    CAP -->|Pick 2| CP[CP System<br/>Consistency +<br/>Partition Tolerance<br/>eg. MongoDB, HBase]
    CAP -->|Pick 2| AP[AP System<br/>Availability +<br/>Partition Tolerance<br/>eg. Cassandra, DynamoDB]
    CAP -->|Pick 2| CA[CA System<br/>Consistency +<br/>Availability<br/>eg. MySQL single node]
    NET[Network Partition<br/>always possible] -.->|forces trade-off| CP & AP
style CP fill:#1f6feb,color:#fff
style AP fill:#238636,color:#fff
style CA fill:#6e40c9,color:#fff

Common Misconception

✗ You must choose exactly two of consistency, availability, and partition tolerance. In practice, partition tolerance is non-negotiable in distributed systems — the real choice is between consistency and availability during a partition. PACELC is a more nuanced modern framing.

Why It Matters

CAP theorem explains why distributed systems cannot be both perfectly consistent and always available during a network partition — you must choose which property to sacrifice. Understanding this prevents architects from promising guarantees a distributed system cannot keep.

Common Mistakes

Assuming a system must be either fully CP or fully AP — real systems make different trade-offs for different operations.
Conflating CAP consistency with ACID consistency — they mean different things in different contexts.
Dismissing eventual consistency as inferior — for many use cases (shopping cart, social feed) it is the correct choice.
Ignoring the P (partition tolerance) — network partitions happen in every distributed system; the choice is really C vs A during one.

Code Examples

✗ Vulnerable

// Assuming all three are achievable simultaneously:
$system->configure([
    'consistency' => 'strong',     // All reads see latest write
    'availability' => '100%',      // Always responds
    'partition_tolerance' => true, // Works despite network splits
    // CAP theorem: during a partition, pick consistency OR availability — not both
]);

✓ Fixed

# CAP Theorem — distributed systems can guarantee only 2 of 3:
# C = Consistency    (all nodes see same data)
# A = Availability   (every request gets a response)
# P = Partition Tolerance (works despite network splits)

# Real-world choices:
# CP: MySQL (InnoDB + strict mode) — consistent, may reject requests during partition
# AP: Cassandra, CouchDB — always responds, but reads may be stale during partition
# CA: Single-node PostgreSQL — no partition tolerance (single node can't split)

# PHP app implications:
# Using Redis for sessions? Redis Cluster is AP — session may be stale after failover
# Using MySQL with read replicas? Replication lag = eventual consistency (AP)

# Practical rule:
# Financial data: prefer CP (MySQL with synchronous replication)
# User activity feeds, caches: AP is usually fine

References

https://en.wikipedia.org/wiki/CAP_theorem