Files
aevolution/docs/adr/0049-bounded-world-proof.md
T
2026-10-08 12:08:53 -04:00

55 lines
2.8 KiB
Markdown

[Reviewed]
# ADR-0049: Bounded world restart proof and measurements
## Status
Accepted for M5.8 development evidence; no world format or simulation rule change.
## Context
Individual codecs and file tests do not demonstrate a full create/edit/journal/
compaction/restart workflow or explain its cost. M5 closes with a reproducible
bounded workload before environmental coupling begins.
## Decision
Add the host tool `evo-world-proof <prepare|compact|verify> <workload> <root>`.
CTest launches separate processes for each phase. Prepare refuses an existing root,
publishes a base plus a journal, compact recovers and publishes its exact state,
and verify requires the compacted generation and compares full canonical bytes to
a freshly reconstructed uninterrupted fixture. No phase deletes files.
Three seed-123456 fixtures each own eight 16-cube chunks at chunk Z=-1000:
uniform (empty journal), sparse (widely spaced chunks, one full-cell excavation),
and heavy (64 commands, 64 cuts each across four chunks, 4096 distinct varying fills).
An independent analytical cell oracle checks every fill/material and the exact
debris sum; retained retries and clean eviction/regeneration are checked separately.
Freeze canonical hashes as shared Windows/Linux regression expectations. A hash
observed on one platform does not claim another platform has run it.
Report JSON phase timings in nanoseconds and store-accounted bytes, snapshot/journal
sizes, command/cut counts and hash. Timings include validation where the API performs
it. No performance threshold: record several independent runs and their range.
Store-accounted bytes exclude host vectors, replay candidates and OS/allocator
overhead; do not label them process peak memory. The explicitly chosen resident
budget and retained output sizes make these limits visible.
## Alternatives Considered
A single-process close/reopen misses process-local state dependencies. A planet
stress test before the bounded proof would obscure correctness and capacity limits.
Existing generation reference fixtures remain the independent base-version checks.
## Benefits
Real process restart, conservation evidence and portable regression fixtures with
reproducible measurements; the headless kernel gains no tooling or IO dependency.
## Costs
Full reconstruction and repeated restore are deliberately validation-heavy. Retained
local files accumulate because this gate supplies no deletion policy.
## Risks
Eight chunks cannot establish planet capacity. Filesystem cache, antivirus and host
load affect timings. A graceful process restart is not a physical power-cut test.
## Consequences
Run the same CTest workflow on supported presets/CI, preserve frozen fingerprints,
document local results and unexecuted platforms. M6 must define volume/matter and
habitat coupling before resources become biologically consumable.