EXPLANATION MODEL — PHASE 4¶

{
  "explanation_type": "<type>",
  "observed_snapshot": {
    "snapshot_id": "<id>",
    "commit_id": <number>
  },
  "inputs": { ... },
  "rules_applied": [
    {
      "rule_id": "<stable identifier>",
      "description": "<exact rule reference>",
      "evaluation": "true | false",
      "evidence": { ... }
    }
  ],
  "conclusion": { ... }
}
````

Rules:

* `rule_id` MUST map to a documented invariant or rule
* `evaluation` MUST be explicit
* `evidence` MUST be raw state, not interpretation

---

## 5. Rule References

### 5.1 Rule Identity

Every rule referenced in explanations MUST:

* Have a stable identifier
* Map to one of:

  * INVARIANTS.md
  * PHASE*_INVARIANTS.md
  * MVCC rules
  * Replication rules
  * Failure model rules

Free-form rules are forbidden.

---

### 5.2 Rule Application Semantics

Rules MUST be applied:

* In a defined order
* Explicitly
* Without short-circuiting unless documented

Skipping a rule is a correctness violation.

---

## 6. Explanation Types (Mandatory)

The following explanation types MUST be supported.

---

### 6.1 Read Visibility Explanation

**Type:** `mvcc.read_visibility`

Explains:

* Why a specific document version is visible or invisible

Inputs:

* Document ID
* Snapshot CommitId

Rules Applied:

* MVCC visibility rules
* CommitId comparisons
* Tombstone handling

Conclusion:

* Visible version ID OR
* Explicit “no visible version” result

---

### 6.2 Query Execution Explanation

**Type:** `query.execution`

Explains:

* How a query was executed

Inputs:

* Query
* Snapshot CommitId

Rules Applied:

* Query planning rules
* Bounds enforcement
* Index advisory usage

Conclusion:

* Deterministic execution plan
* Guarantees enforced

---

### 6.3 Recovery Explanation

**Type:** `recovery.process`

Explains:

* How recovery proceeded after a crash

Inputs:

* Last known durable state

Rules Applied:

* Checkpoint selection rules
* WAL replay rules
* Checksum validation rules

Conclusion:

* Final recovered CommitId
* State validity result

---

### 6.4 Checkpoint Safety Explanation

**Type:** `checkpoint.safety`

Explains:

* Why a checkpoint is valid or not

Inputs:

* Checkpoint marker
* Snapshot metadata
* WAL offsets

Rules Applied:

* Durability ordering rules
* Snapshot completeness rules

Conclusion:

* Checkpoint accepted or rejected

---

### 6.5 Replication Safety Explanation (Conditional)

**Type:** `replication.safety`

Explains:

* Why a replica is safe to serve reads

Inputs:

* Replica WAL prefix
* Snapshot CommitId

Rules Applied:

* WAL prefix rule
* MVCC snapshot safety rule

Conclusion:

* Read-safe or not read-safe

---

## 7. Determinism Requirements

Explanations MUST be:

* Deterministic
* Stable across restarts
* Independent of timing
* Independent of UI context

If two identical states produce different explanations,
that is a correctness bug.

---

## 8. Failure and Partial-State Handling

### 8.1 Incomplete Evidence

If evidence is missing:

* The explanation MUST say so explicitly
* No inferred conclusion is allowed

Example:

```json
{
  "conclusion": {
    "status": "undetermined",
    "reason": "WAL segment missing"
  }
}