---
name: "Adr 0007 Projection Replay"
description: "Projection purity and replay determinism contract"
depth: 2
links: ["../index.md", "../modules/core-events-submodule-spec.md", "./adr-0006-event-store-append-only.md"]
---

# ADR-0007: Projection & Replay Determinism Contract

**status:** accepted
**date:** 08.05.2026
**deciders:** Kami

---

## context

Projections and replay are responsible for reconstructing system state from event streams. Any nondeterminism in projection logic or replay execution breaks system consistency guarantees.

The system requires strict guarantees that state reconstruction is reproducible across time, environment, and implementation.

This ADR formalizes projection and replay correctness requirements.

---

## content

### 1. projection purity

* Projection MUST be a pure function:
  `EventStream → State`
* no hidden state or external dependencies are allowed
* projections MUST NOT mutate shared state

### 2. determinism requirement

* identical event streams MUST produce identical state
* ordering of events MUST be respected (sequence order)

### 3. replay invariance

* replay MUST produce identical results regardless of:

    * runtime environment
    * execution timing
    * storage backend implementation

### 4. environment independence

* replay MUST NOT depend on:

    * live services
    * LLM calls
    * external APIs
* replay MUST be fully deterministic offline

### 5. disposable projections

* projection state MUST be rebuildable at any time
* no projection state is authoritative; only event log is

---

## consequences

**positive:**

* enables safe rebuild of entire system state
* guarantees consistency across infrastructure implementations
* simplifies debugging (full replayability)
* enables future snapshotting and caching layers

**negative:**

* prohibits non-deterministic projection logic
* forces strict separation of computation vs external effects
* requires careful handling of ordering assumptions

---

## status

accepted
