Files
aevolution/docs/adr/0142-durable-exact-population-profile.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

5.1 KiB

ADR-0142: Durable exact population profile and publication

Status

Accepted for M12's opt-in engineering implementation, 2026-10-17. Extends ADR-0139/0140 with a dedicated durable profile. Production enabling and target-host qualification remain separate; no deployment or World0 operation is authorized.

Context

The exact cohort envelope carries membership and policy beyond raw cellular bytes. Reusing profile 4 would make retained manifests ambiguous. Portable restoration alone cannot prove atomic publication, current authority or recovery after a lost database reply.

Decision

Checkpoint profile 5 contains population envelope 1 and nested cellular bundle 9, with history profile 5 identifying exact retained membership. Profile 4 retains its raw cellular bytes and meaning. No biological version or golden is replaced.

Use explicit fenced, no-tick profile transitions: rules-8 profile 4 to population 5 wraps the same biology with empty membership, sequence zero and a persisted policy; population 5 to profile 4 materializes the retained individuals by unwrapping the identical biology. Both require the exact current predecessor, current region fence, retained build and immutable transition evidence. Recovery checks the complete source/target pair, not just their aggregate inventory. Conversion sequence starts at zero for each entry generation; the region commit sequence remains monotonic and the transition records identify every generation.

Initially profile 5 admits unattended ecological batches only: controlled cells receive frozen intentions; player births, mutation selections and session action receipts remain profile-4 operations. A host must finish the reverse transition before processing those operations. This restriction avoids bypassing their existing account-control/reservation transactions. It does not freeze wildlife or erase controlled/suspended stock. An explicit profile selector is opt-in. The cellular worker accepts --cellular-populations on|off (default off). It may enter only for unattended rules-8 wildlife, with no waiting player birth or mutation. Session demand or a player operation completes the reverse transition first. SQL serializes profile entry and mutation reservation under the same region lease: entry refuses outstanding choices, and new choices require profile 4 in the current host. Historical reservation contracts remain unchanged outside profile 5. An existing profile-5 head remains recoverable with entry disabled. The worker collects at least 20 due ticks (one second) and services at most 64 per unattended publication, consuming local debt only on confirmation. This is bounded publication batching; durable interval admission/restart backlog is the next M12.4 segment, not supplied by a wall-clock inference on recovery.

Population batch format 1 records the unchanged canonical cellular intentions and an exact membership/sequence boundary for each tick. Biological replay reads the recorded intentions, never reruns the wildlife controller. It verifies each recorded boundary against the persisted deterministic policy. Manual conversion records operate on an entire wildlife genome group at the same biological tick. No random materialization sample exists in this exact model. Restoration installs the recorded checkpoint; validation cannot resample a different member set.

Store immutable payload and trace objects with SHA-256/read-back verification, then commit the manifest and publication evidence in one database transaction under the existing serialized lease/head guard. Unknown replies retain the exact prepared request; read-only resolution never grants a stale writer permission to continue. Dedicated evidence triggers prohibit generic publication bypasses. Retain all old formats, histories and source checkpoints. Do not prune objects.

Validation and limits

Require malformed/profile-confusion rejection, whole-state source/target equality, conversion oscillation, trace/payload mismatch refusal, frozen controlled biology, duplicate/conflicting retries, expired writers and missing/corrupt objects. Exercise real PostgreSQL and process death before publication and after commit/receipt. Portable codec success alone does not close the durable gate.

This profile supplies a place for bounded unattended intervals and later escrow; it does not itself implement biological migration or environmental coupling. Existing player actions, NPC heredity and fixed 50 ms biology retain their rules.

Alternatives, costs and consequences

Relabeling the raw profile breaks retained recovery; persisting only aggregate stock loses exact members. Reconstructing policy on restart can choose a different representation. Keep explicit profiles and recorded boundaries instead.

This retains every member and full trace, so it adds durable bytes and replay work and makes no compression claim. SQL parsers, grants and source/target verification must evolve together. Target-host cost and executable/network fault qualification remain risks before production enablement. All old objects and histories remain retained; no garbage collection or compatibility reset follows.