Files
aevolution/docs/engineering/M12_DURABLE_POPULATIONS.md
T
dingo 0a8962b57e
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 2m28s
Foundation / checks (tsan) (push) Failing after 18m22s
Foundation / checks (network) (push) Successful in 20m38s
Foundation / checks (client) (push) Failing after 21m6s
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 46m54s
Foundation / checks (checks) (push) Canceled after 47m3s
M12.4: retain and settle owned population intervals
2026-10-17 17:31:05 -04:00

74 lines
4.5 KiB
Markdown

# 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](VALIDATION.md).
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.
M12.4b subsequently adds the [owned interval journal](M12_OWNED_POPULATION_INTERVALS.md).
It restricts new entry/work to fully suspended controlled cells, preserving the
vulnerable linger/death path on profile 4. Earlier traces remain verifiable, and
retained owned corpses are reconciled after either profile's recovery.
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.