Files
aevolution/docs/adr/0058-region-durability-contract.md
T
2026-10-08 12:08:53 -04:00

69 lines
3.9 KiB
Markdown

[Reviewed]
# 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](../architecture/REGION_DURABILITY.md) and the
[logical manifest schema](../../schemas/region-commit.md). 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.