---
type: Axis
title: consistency (concurrency-control axis)
description: The consistency/concurrency architecture axis — how concurrent writes to the same state are reconciled (last-writer-wins → optimistic → pessimistic → MVCC → consensus). A system-singleton axis whose commitment surface is durable runtime state. DEEP (RFC #75 5A.4 / P1 #851 → promoted 4.5.0a6 #856); worked example is the sqlite-WAL embedded MVCC + single-writer-per-project posture, with the #769 spawn-race split-brain as the guard that keeps it single-writer.
tags: [axis, architecture, consistency, concurrency, mvcc, consensus, rfc-75, deep]
timestamp: 2026-06-18T00:00:00Z
---

# Consistency (concurrency-control axis)

> **DEEP axis (P1 #851 → 4.5.0a6 #856).** Full §6 depth with a worked example
> from the skill's own history — the canonical store leans on sqlite WAL mode
> (embedded MVCC: readers take a stable snapshot and never block the writer)
> while keeping effectively single-writer-per-project, so it gets MVCC's
> read-concurrency without ever needing application-level optimistic/pessimistic
> control; the #769 split-brain fix is the guard that preserves the single-writer
> assumption MVCC-without-app-locking depends on.

## Concept

Consistency is the **concurrency-control** axis (RFC #75 §3): how concurrent
writes to the same state are reconciled. The ladder runs last-writer-wins (no
control; the last write clobbers) → optimistic (detect a conflict at commit via
a version check; retry) → pessimistic (lock the state for the duration of the
write) → MVCC (multi-version snapshots; readers never block writers) →
consensus (a quorum agrees on the order of writes — distributed). Its
**commitment surface is durable runtime state** (§4): version columns, lock
tables, snapshot machinery, and consensus logs are runtime state that must be
reconstructable. Its **scope is system-singleton** (§5).

## Why it is an axis (discriminator test — §2)

1. **Ordered tiers** — each rung handles a stronger concurrency guarantee.
2. **Cross-cutting bundle** — a rung dictates version/lock columns, the commit
   protocol, the retry/backoff, the deadlock story, and the concurrency tests.
3. **Asymmetric migration cost** — adding optimistic version checks means
   retrofitting a version column + a retry loop on every contended write;
   consensus is a wholesale rewrite of the write path.
4. **Requirement-keyed selection** — falsifiable probes pick the rung.

## Schema view (the §6 entry — validated by `axis_catalog`)

```yaml
id: consistency
kind: architecture-axis
scope: system-singleton
selection:
  probes:
    - "Is concurrent write to the same row rare/harmless (last write fine)? → last-writer-wins."
    - "Are conflicts occasional + a retry acceptable? → optimistic (version check at commit)."
    - "Are conflicts frequent + a retry storm unacceptable? → pessimistic (lock)."
    - "Must readers never block writers under heavy concurrency? → MVCC (snapshots)."
    - "Must distributed nodes agree on a single write order? → consensus."
composes_with:
  - "conflict resolution = consistency × collaboration"
  - "CAP positioning = consistency × distribution"
applies_when: []
tiers:
  - tier: last-writer-wins
    commitment_delta:
      surface: durable-runtime-state
      delta: "no concurrency control; the last write to land overwrites. Lost updates are possible + accepted."
    admin_tool: "none."
    enforcement:
      - "writes are unconditional; conflicts are not detected."
    tests:
      - "two concurrent writes both succeed; the later value persists."
    forecloses: "detecting/preventing a lost update."
    migration_cost_to_next: "medium — add a version column + a compare-and-set commit."
  - tier: optimistic
    commitment_delta:
      surface: durable-runtime-state
      delta: "each row carries a version; a write commits only if the version is unchanged, else it conflicts + retries. No locks held."
    admin_tool: "conflict-rate metric; retry telemetry."
    enforcement:
      - "every write is a compare-and-set on the version; a conflict retries from a fresh read."
    tests:
      - "a stale write is rejected + retried; the winner's version advances."
    forecloses: "ignoring concurrent edits; a retry loop is now required."
    migration_cost_to_next: "medium — hold a lock to avoid retry storms under heavy contention."
  - tier: pessimistic
    commitment_delta:
      surface: durable-runtime-state
      delta: "a write acquires a lock on the state for its duration; concurrent writers wait. No conflicts, but contention + deadlock risk."
    admin_tool: "lock/wait monitor; deadlock detector."
    enforcement:
      - "writes acquire locks in a consistent order (deadlock avoidance); locks are released on commit/abort."
    tests:
      - "concurrent writers serialize correctly; a deadlock is detected + resolved."
    forecloses: "lock-free read-write concurrency; readers may block."
    migration_cost_to_next: "high — snapshot reads so readers never block (MVCC)."
  - tier: mvcc
    commitment_delta:
      surface: durable-runtime-state
      delta: "multiple versions are kept; each reader sees a consistent snapshot + never blocks a writer. Garbage-collection of old versions is required."
    admin_tool: "snapshot/version-GC monitor."
    enforcement:
      - "reads take a snapshot; writes create new versions; old versions are reclaimed safely."
    tests:
      - "a long reader sees a stable snapshot while writes proceed; GC doesn't reclaim a live snapshot."
    forecloses: "single-version simplicity; version bookkeeping is now intrinsic."
    migration_cost_to_next: "high — agree write order across distributed nodes (consensus)."
  - tier: consensus
    commitment_delta:
      surface: durable-runtime-state
      delta: "a quorum of nodes agrees on a total order of writes (Raft/Paxos); the system tolerates node loss while staying consistent."
    admin_tool: "cluster/quorum dashboard; leader-election monitor."
    enforcement:
      - "a write commits only after quorum acknowledgement; the log order is agreed."
    tests:
      - "a minority node loss keeps the cluster consistent; a partition does not split-brain."
    forecloses: "single-node write reasoning; every write is a distributed agreement."
    migration_cost_to_next: "n/a — top of the ladder."
examples:
  - "The skill sits at MVCC — but borrowed from the engine, not built at the application level. The canonical store is sqlite in WAL mode: readers take a consistent snapshot and never block the single writer, which is precisely the MVCC rung's read-write-concurrency property, supplied by the embedded engine for free. The daemon then keeps the system effectively SINGLE-WRITER-per-project (it serializes every write through one process), which is why the application never had to climb the *lower* rungs — there is no version-column compare-and-set (optimistic) and no application lock table (pessimistic), because contention between application writers simply does not arise. The hard lesson on this axis was a violation of that single-writer assumption: the #769 spawn-race split-brain (two daemons racing to open the same store) produced an 82MB WAL and a poisoned plan_entries projection — the classic lost-update / corruption failure mode of having no concurrency control between *two writers* — and the fix was an operational flock boot-lock (open spawn-once-then-poll) plus a WAL-truncate watchdog, i.e. enforcing single-writer rather than reaching for optimistic/pessimistic reconciliation. CONSENSUS (a quorum agreeing write order) is the unreached top rung; it would only matter if the store became multi-host, which the system-singleton distribution posture (single per-project daemon) has never required."
```

## Selection procedure (§8)

Bidirectional check; chosen once. Recorded in the system architecture record.

## Composition (§5)

Consistency × collaboration = **conflict resolution**; consistency ×
distribution = **CAP positioning**. Rules authored in 5A.3.
