Files
aevolution/docs/engineering/M12_DURABLE_POPULATIONS.md
T
dingo 627411983f
Foundation / checks (ecs) (push) Successful in 2m41s
Foundation / checks (tsan) (push) Failing after 18m12s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 20m41s
Foundation / checks (postgres) (push) Canceled after 20m43s
Foundation / checks (checks) (push) Canceled after 20m49s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (client) (push) Failing after 17m4s
Foundation / postgres-tools (push) Canceled after 0s
M12.3: publish and recover durable exact populations
2026-10-17 17:10:17 -04:00

4.2 KiB

M12.3b durable exact populations

ADR-0142 implements the persistence boundary identified in the remaining-gate audit. This is an opt-in engineering path; no live region was migrated or enabled. The optional cellular worker accepts --cellular-populations on|off, default off. When unattended rules-8 wildlife is present, entry can wrap its exact biological state as profile 5. A returning player, queued birth or mutation requires the durable reverse transition before processing player operations.

State and publication

There is exactly one owning biological store in the host. Profile 4 owns raw CellularLives; profile 5 owns a CellularPopulation containing that store and its exact membership tags. Common callers receive only a const biological view. Entering, leaving and oscillating cannot heal, move, reproduce or fund a life. Every profile-5 generation starts membership sequence zero, while the immutable region publication sequence and source/target evidence preserve its identity.

Migration 44 retains all old parsers, histories and raw cellular formats. It adds dedicated immutable population publication and profile-transition records, fenced publish/resolve/load functions and generic-publication bypass guards. Entry and new mutation reservations serialize on the same region lease. Entry refuses outstanding player choices; profile 5 refuses new choices. Existing unrelated reservation contracts retain their original behavior.

Payloads and traces are immutable content-addressed objects. The publisher checks their SHA-256 and complete read-back before the atomic SQL head/evidence update. Recovery verifies the exact predecessor and full source/target bytes. Biological traces record intentions and exact membership boundaries; replay does not rerun the wildlife controller. Unknown replies stop publication until exact-byte resolution/retry succeeds under current authority.

Evidence and qualification limits

The portable contract covers canonical codec/manifest/profile confusion, sampled truncations, appended bytes, membership/sequence tampering, controlled-input refusal, manual conversions and full biological replay equality. Native Release tests run under NDEBUG; sanitizer and static-analysis evidence is recorded in VALIDATION.

The private PostgreSQL fixture creates real reserved founders and waits for a funded player-derived descendant. It exercises durable membership oscillation, fresh-connection recovery, reverse materialization, generic bypass rejection, mutation/profile race guards, duplicates/conflicts and stale authority. Missing and corrupt payloads refuse recovery. Lease-row contention creates real adapter timeouts: one backend commits after its client disconnects; another is terminated before commit. Both resolve/retry the retained exact request.

SIGKILL tests use forked publisher processes at the pre-transaction boundary (after immutable uploads), after SQL commit and after a pipe acknowledgement. The parent restores through a new database connection and compares every retained byte. These are real process kills, but the pipe acknowledgement is a fixture signal, not an actual network client acknowledgement or an independently exec'd worker restart. The actual CellularRegionHost is separately drained/recreated and restores a profile-5 head with entry disabled, then materializes before a returning-player operation. Previous raw worker process drills remain regression coverage, not additional population-specific fault evidence.

The worker collects one second of due unattended time before publication and services at most 64 fixed steps per batch. The portable input builder matches an independent per-tick fixture. This removes per-tick SQL publication from the new population path; it does not yet make local pacing debt a durable admission queue.

Still open: profile-5 executable/network fault drills, deployment-host tail costs, durable ecological interval admission and biological migration escrow, jointly owned environmental budgets, world-level history/extinction reconciliation and actual multi-day/returning-player evidence. This work changes neither biological versions nor goldens, and does not establish useful compression or M13 readiness.