Files
aevolution/docs/adr/0058-region-durability-contract.md
T

3.9 KiB

ADR-0058: Region durability through full checkpoint batches

Status

Accepted for M7.1 design, 2026-09-27. Implementation belongs to M7.2-7.9. This scopes ADR-0016's proposed production architecture; it does not accept ADR-0013's client recommendation or select a database/object-store release.

Context

M6 proves complete buffer restore for one environmental fixture. Domain events alone omit source residuals, finite resources, lifecycle and retry history. No production host exists to record all exogenous inputs. LineageArchive has no whole-archive codec or enumeration interface, and is not owned by the M6 fixture. Calling its envelope a complete biological region would discard independent state.

Decision

Use immutable full checkpoint batches first. Each successful batch replaces the region head with an exact, validated state at its end tick. Publish its object reference, permanent outcomes, request receipts and outbox in one fenced database transaction. Recovery loads the latest committed full checkpoint, not a semantic event tail. Preserve the predecessor chain for audit and conflict detection. No event replay codec is implied; complete replay batches remain a future ADR.

Adopt REGION_DURABILITY.md and the logical manifest schema. PostgreSQL is authority; object storage contains immutable payloads. Candidate bytes may be uploaded before commit but have no published authority. The transaction atomically makes the candidate a committed checkpoint and advances committed_tick. This refines the architecture's rule that published snapshots cannot represent speculative state.

Start with one in-flight batch per region, at most 64 ticks, explicit state/receipt byte limits, and a whole-region barrier at any irreversible outcome. Storage I/O never runs inside the headless process library. Failed or ambiguous commits do not authorize another batch, final ACK or outcome rollback; reconcile exact commit ID.

The initial environmental profile admits only the state it actually owns. Missing genome/ancestry/session/population state is unsupported, never implicitly empty. M7's ancestry acceptance remains open until a separately versioned closure/profile and archive codec/binding are implemented. No automatic migration or founder seeding.

Alternatives Considered

Semantic events cannot reconstruct arbitrary intermediate state. Full deterministic input journals are attractive later but need complete input capture and retained executable versions. Per-tick SQL is unnecessary. An object manifest alone cannot atomically enforce leases, decisions, history and head changes. A broker is not the commit authority. Embedding payloads in PostgreSQL is deferred to measured need.

Benefits

An explicit recoverable consistency cut; bounded speculative work; no hidden state reconstruction. Strict terminal outcomes share the same commit as physical state.

Costs

Full payload writes per batch, retained orphan objects and a stop during I/O. These are intentional correctness baselines, to be measured at M7.9. At the M6 50ms quantum a full 64-tick batch spans 3.2 simulation seconds; hosts should flush earlier for latency, shutdown or irreversible outcomes. This is not a player SLA.

Risks

Object/database durability can differ; final ACK needs both. Same-host backups do not prove host-loss recovery. A checksum cannot prove a compromised worker's state is a legitimate simulation result; process isolation and validation remain required. Durable deduplication/history retention must outlive the 64-tick process cache.

Consequences

No deployable pod or database is created by this gate. M7.2 selects/pins adapters and migrations; M7.3 implements fencing; M7.4 adds codecs/state closure, immutable publication and necessary history integration; M7.5 implements atomic outcomes; M7.6-7.9 exercise real worker failures. World0 needs independent durability evidence.