REPLICATION RUNTIME ARCHITECTURE¶

+------------------+
| Primary Runtime  |
+------------------+
|
| WAL Segments (immutable)
v
+------------------+       +------------------+
| WAL Receiver     | ----> | WAL Validator    |
+------------------+       +------------------+
|
v
+------------------+
| WAL Applier      |
+------------------+
|
v
+------------------+
| Replica State    |
+------------------+
|
v
+------------------+
| Read Safety Gate |
+------------------+

````

---

## 4. Primary-Side Architecture (Minimal)

### 4.1 Primary Responsibilities

The Primary:
- Assigns CommitIds
- Appends WAL
- Exposes WAL segments for shipping

Primary replication logic MUST be:
- Read-only with respect to replication
- Passive (no push, only serve)

There are **no replication threads on the Primary**.

---

## 5. Replica-Side Architecture (Authoritative)

All replication runtime complexity lives on the **Replica**.

---

### 5.1 Replica Supervisor

**Role:** Top-level state owner

Responsibilities:
- Replica lifecycle
- Crash recovery orchestration
- State transitions between stages

Properties:
- Single-threaded
- Owns replica global state enum
- Exposes state to DX

Forbidden:
- Performing WAL IO directly
- Applying WAL
- Serving reads

---

### 5.2 WAL Receiver

**Role:** WAL ingress only

Responsibilities:
- Receive WAL segments
- Enforce ordering
- Persist raw WAL bytes

Properties:
- Single-threaded or async task
- No validation
- No state mutation beyond WAL storage

Input:
- Primary WAL stream

Output:
- Immutable WAL segments

Forbidden:
- Applying WAL
- Advancing CommitId
- Skipping segments

---

### 5.3 WAL Validator

**Role:** WAL correctness proof

Responsibilities:
- Check checksums
- Verify continuity
- Validate segment boundaries

Properties:
- Deterministic
- Stateless across runs (except checkpoints)
- Restart-safe

Input:
- WAL segments from Receiver

Output:
- Validated WAL segments OR explicit failure

Forbidden:
- Mutating storage
- Advancing CommitId

---

### 5.4 WAL Applier

**Role:** State mutation engine

Responsibilities:
- Apply validated WAL to storage
- Advance replica CommitId
- Maintain replay checkpoints

Properties:
- Single-threaded
- Crash-safe
- Deterministic

Input:
- Validated WAL segments

Output:
- Updated replica storage

Forbidden:
- Serving reads
- Skipping validation
- Applying speculative WAL

---

### 5.5 Replica State Store

**Role:** Canonical replica metadata

Responsibilities:
- Store:
  - Replica CommitId
  - Applied WAL offset
  - Snapshot bootstrap metadata
- Persist restart-safe state

Properties:
- Mutated only by:
  - Replica Supervisor
  - WAL Applier (scoped)

Forbidden:
- Concurrent mutation
- Hidden derived state

---

### 5.6 Read Safety Gate

**Role:** Read authorization

Responsibilities:
- Evaluate read safety predicates
- Enforce MVCC visibility rules
- Refuse unsafe reads

Properties:
- Read-only
- Pure function of observable state
- Explainable via DX

Forbidden:
- Heuristics
- Timing assumptions
- Lag-based shortcuts

---

## 6. State Machines (Mandatory)

### 6.1 Replica Global State

```text
Disabled
  ↓
Initializing
  ↓
ReceivingWAL
  ↓
ValidatingWAL
  ↓
ApplyingWAL
  ↓
Recovering
  ↓
Ready (read-safe OR read-blocked)
````

Transitions MUST:

* Be explicit
* Be logged
* Be observable

---

### 6.2 WAL Segment State

```text
Received → Validated → Applied