68 lines
3.9 KiB
Markdown
68 lines
3.9 KiB
Markdown
# 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.
|