M12.3: publish and recover durable exact populations
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

This commit is contained in:
dingo
2026-10-17 17:10:17 -04:00
parent d5d10a0cc7
commit 627411983f
35 changed files with 2637 additions and 102 deletions
@@ -0,0 +1,86 @@
# 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.