Single-Writer Generation Fence
A replicated system may have many copies, but only one current writer for each durable fact. Make that authority structural: replicas reject writes, promotions change generation, and stale writers cannot author truth after failover.
Problem
Systems often preserve single-writer discipline during normal operation and lose it during failure. A replica becomes writable "just for now." An old primary comes back. A backup is restored and accepts current writes. A repair tool bypasses the normal gate. Truth splits while the system still looks operational.
Context
Use this pattern when facts are replicated, restored, promoted, repaired, or copied across machines, services, storage engines, queues, projections, or operational tools.
Forces
- Copies are necessary for scale, reads, standby behavior, and recovery.
- Availability pressure makes writable standbys tempting.
- Stale writers often look healthy locally.
- Logical replay can drift from the original committed truth.
- Recovery paths are write paths too.
Solution
Name the current authoritative writer and make every write prove it belongs to the current writer era. Replicas may serve reads and receive committed truth, but they reject ordinary writes. If a replica is promoted, the system advances a generation, epoch, lease, or term. Any writer presenting an older fence is rejected.
Prefer copying persisted truth when possible. In CapDB, this is physical WAL streaming: replicas receive the committed bytes rather than recomputing the primary's intent. The same principle travels beyond databases: copies may derive or recover, but they do not become authors without current authority.
Consequences
The system degrades honestly. It may lose write availability, require explicit promotion, or force snapshot recovery, but it does not quietly accept two authors for the same fact. Stale authority is rejected by the system rather than remembered by people.
Failure Modes
- Replica write rejection exists only in documentation or UI.
- Promotion changes routing but not the authority generation.
- A returned primary can write because clients can still reach it.
- Backfill, import, restore, or support tools bypass the writer fence.
- Restore or repair work can half-commit without proving current writer authority.
- Logical replication turns copies into independent interpreters of truth.
Proof Points
replicas reject write operations, and generation fencing rejects stale authority after failover.
before it lets two writers create divergent truth.
Full source pattern: single-writer-generation-fence.md.