Files
aevolution/docs/engineering/M12_CELLULAR_REFERENCE.md
T
dingo bee57e5829
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 2m47s
Foundation / checks (tsan) (push) Successful in 13m32s
Foundation / checks (client) (push) Failing after 17m9s
Foundation / checks (network) (push) Successful in 19m58s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 20m34s
Foundation / checks (checks) (push) Canceled after 20m49s
M12.2c: qualify the current cellular reference instrument
2026-10-17 11:44:00 -04:00

144 lines
7.7 KiB
Markdown

# M12.2c: Current cellular population reference
## Result - 2026-10-17
The rules-8 exact control passes all eight full cases on MSVC 19.44 and GCC 14.2.
Every tick is compared through 1-tick canonical replay; 16/64-tick partitions
also match at every completed boundary. Each case advances 8192 ticks at 50 ms,
for 65,536 reference ticks and 70,656 compared replay boundaries per platform.
Each replay lane additionally performs 512 explicit checkpoint restores across
the suite. All non-timing output, including final-state fingerprints, matches
between platforms. Conserved totals remain exactly equal to finite opening stock.
This completes M12.2c's reference instrument under
[ADR-0138](../adr/0138-cellular-population-reference-instrument.md), not M12.2's
active/cohort qualification. No approximate population model or automatic tier
selector is introduced. M11.9 is closed for now by the maintainer; it no longer
blocks M12 continuation. See [the scoped closure](M11_9_CLOSURE_AND_UI_REVIEW.md).
Raw outputs: [MSVC](results/m12-2c-cellular-msvc1944.jsonl) and
[GCC](results/m12-2c-cellular-gcc14.jsonl).
## Reference and method
`evo-cellular-reference` links the existing portable lifecycle/biology owner. It
does not depend on renderer, network, database or a running world. The baseline is
owner format 6, rules 8, habitat format 2, schema/development 4 and trace format 3:
percentage mutation steps, skilled/twin budding, hunting wildlife and finite
contact-fed pools/motes. Proposed colonies, infall and photosynthesis are excluded.
Four equally funded player-origin founders start each case. Seeded finite food
has rich and scarce regimes; initial contact food in rich cases is explicitly
funded in the habitat, never credited directly to organisms. Source totals include
nursery, bodies, reserves, deposits and heat. There is no refill or boundary inflow.
Seeds 0/1 are development and 2/3 held out. The driver asks owned cells to feed,
occasionally bud/engulf, and later move; only real earned, affordable mutation
offers are selected. It does not write a successor genome or biological inventory
directly. Wildlife intentions are obtained from the actual shared controller and
recorded once. One controlled founder freezes for 256 ticks per 1024-tick cycle,
passing through linger/suspension and then requesting resume. Surviving frozen
members retain exact position, body, reserve, growth, identity and mutation state.
An engulfed frozen member would still be allowed to die under ADR-0128.
Three replay lanes independently encode/decode the recorded inputs and call the
production replay helper with batch widths 1/16/64. Each comparison is full
canonical byte equality, so it includes archive parent/revision links, identity,
demographics, inventory, eligibility and rate state. Batch partitioning keeps the
fixed tick quantum; it never integrates biology once at a larger timestep.
Checkpoint restoration checks identical bytes again at completed 128-tick boundaries.
This is an in-memory recovery control, not a process/SQL failure drill.
## Observed coverage
| Seed | Split | Food | Wildlife births | Mutations | Deaths | Peak living | Maximum capability profiles |
|---|---|---|---:|---:|---:|---:|---:|
| 0 | development | rich | 0 | 4 | 0 | 4 | 4 |
| 0 | development | scarce | 0 | 0 | 4 | 4 | 1 |
| 1 | development | rich | 1 | 4 | 0 | 5 | 4 |
| 1 | development | scarce | 0 | 0 | 4 | 4 | 1 |
| 2 | holdout | rich | 2 | 4 | 1 | 5 | 4 |
| 2 | holdout | scarce | 0 | 0 | 4 | 4 | 1 |
| 3 | holdout | rich | 1 | 4 | 2 | 4 | 3 |
| 3 | holdout | scarce | 0 | 0 | 4 | 4 | 1 |
Across the suite: four wildlife births, 16 applied mutations, 19 deaths,
10,240 frozen controlled-life ticks and 2240 suspended-life ticks. All observed
deaths are starvation; successful engulfment and blocked resume are **not** covered.
Twin capability is enabled by the rules but these counts do not establish a
successful twin-birth case. Those paths need separate cellular cohort scenarios.
Distinct living genome IDs and distinct capability profiles are separate outputs:
identical founders have different genome IDs without different capabilities.
Neither count is a species. Structural body matter is also reported per channel;
it is not a wet-biomass or climate estimate. A local empty population does not
assert reconciled terminal extinction.
The 512-tick CTest matrix covers mutation, freeze/suspension/resume and state closure,
but no births or deaths in the observed short runs. Rich-case guards require real
mutation and offline-state coverage. The long suite additionally requires at least
one birth and death across its cases, preventing a vacuous all-empty control.
## Local costs and limits
One measurement pass on the Ryzen 7 9800X3D development workstation, Windows x64
MSVC Release and Ubuntu WSL2 GCC Release, without affinity/frequency locks. Total
milliseconds across all 65,536 reference ticks follow; these are observations,
not repeated-sample budgets, per-tick tail latency or production capacity.
| Measured work | MSVC ms | GCC ms |
|---|---:|---:|
| Direct owner stepping | 525.265 | 388.244 |
| Encode/decode/replay, width 1 | 5897.060 | 4883.169 |
| Encode/decode/replay, width 16 | 849.758 | 654.428 |
| Encode/decode/replay, width 64 | 596.156 | 438.871 |
Direct timing excludes experiment input generation, canonical comparisons and
metric collection. Replay timing includes codec work and replay's owner restore;
explicit extra checkpoint checks/comparisons are excluded. Reduced codec overhead
at larger batches is not an aggregation speedup or permission to delay gameplay
outcomes. Only 4-5 simultaneous lives are measured. Peak serialized state is
10,188 bytes; serialized bytes do not measure RSS, scratch or worker memory.
## Reproduce and validation
```powershell
./tools/windows-check.ps1 -Preset release -Action check
./build/release/evo-cellular-reference.exe
```
`--verify` runs the 512-tick matrix without timing. Default is the full 8192-tick
matrix. The declared seeds/regimes/partitions are fixed research inputs.
Linux builds use the same checked-in presets with separate binary directories:
```sh
cmake --preset release -B build/linux-release
cmake --build build/linux-release --target evo-cellular-reference
./build/linux-release/evo-cellular-reference
cmake --preset analysis -B build/linux-analysis
cmake --build build/linux-analysis --target evo-cellular-reference format-check
ctest --test-dir build/linux-analysis -R cellular-population-reference --output-on-failure
cmake --preset asan -B build/linux-asan
cmake --build build/linux-asan --target evo-cellular-reference
ctest --test-dir build/linux-asan -R cellular-population-reference --output-on-failure
```
Executed on final source: native Release **71/71 CTests**, GCC Release reference
CTest, clang-format/tidy 19 with debug reference CTest, and GCC ASan/UBSan reference
CTest (19.51 s, no reports). Tests use runtime checks under NDEBUG. Both full raw
outputs parse as one metadata, eight case and 24 partition records; all non-timing
case/partition fields and final-state fingerprints match across compilers.
## Next qualification boundary
The synthetic reserve strata still cannot represent cellular positions/contact,
deposits, reproductive placement and presence closure. No adapter admits these
states into that model. Use this reference to compare a separately specified
cellular population model, with appropriate diversity/demographic/biomass bounds,
bin/interval sensitivity, unsupported-state admission and active fallback policy.
Measure representative full-region and conversion/recovery costs on the target
host. This small WSL/workstation control does not satisfy those requirements.
M12.3 automatic transitions and later unattended/migration/coupling gates remain
dependent on genuine M12.2 model qualification, not on further M11.9 approval.