Files
aevolution/docs/adr/0123-dev-cellular-region-and-life-allocator-provisioning.md
dingoandClaude Opus 5.5 1675bb688d
Foundation / checks (ecs) (push) Successful in 2m18s
Foundation / checks (deploy) (push) Successful in 3m50s
Foundation / checks (tsan) (push) Successful in 9m44s
Foundation / checks (client) (push) Successful in 16m45s
Foundation / checks (network) (push) Successful in 19m6s
Foundation / checks (checks) (push) Successful in 42m3s
Foundation / checks (postgres) (push) Successful in 44m10s
Foundation / postgres-tools (push) Successful in 1m8s
Foundation / image (push) Successful in 3m20s
Foundation / server-image (push) Successful in 3m25s
Let cellular sessions use the DEV grant ceiling
The cellular profile refused --m10-max-grant-lifetime and the Deployment never
passed it, so playtest grants were capped at the 300 s default. The cellular
bridge now applies the DEV-only ceiling like lineage, and the Deployment passes
the overlay's ceiling (4 h in DEV) to both profiles. Recorded in ADR-0123.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 12:14:45 -04:00

8.2 KiB

ADR-0123: Dev cellular region and life-allocator provisioning

Status

Accepted 2026-10-13 for the M11.3 cellular probe in evolution-dev, at the maintainer's direction. It changes DEV deployment and the owner provisioning tool only; no gameplay rule, protocol or runtime authority changes.

Context

The M11.3 probe (docs/playtests/M11_3_CELLULAR_PROBE.md) needs a cellular region in DEV. Bringing one up exposed four gaps:

  1. Region 100/1 cannot host the cellular profile. It holds profile-3 lineage history; evo-server --profile cellular needs a cellular-v1 (profile-4) genesis. Resetting or rewriting region history is forbidden, and unnecessary, because regions are independent.
  2. The DEV schema was v11. The store Jobs still pinned the 2026-10-05 postgres-tools image, so PostgreSQL refused the profile-4 genesis manifest (cellular provision refused 5, PublicationError::rejected).
  3. No life allocator existed for world 100. reserve_primitive_life raises life allocator not provisioned (EVL04) without a life_allocators row. schemas/life-reservations-v1.md assigns that row to the owner after an audit, and nothing in Git created it. The server reported every first-life request as unknown and never ticked.
  4. Cellular grants are scoped and short. Grants name their region, so region-1 bundles are refused with wrong_scope. The cellular bridge keeps the default 300-second grant ceiling and refuses --m10-max-grant-lifetime.

Decision

  • DEV serves region 100/2 with the cellular profile. The single evo-region Deployment switches to region 2. Region 1's database rows and objects stay untouched and are no longer served. The base Deployment and provision Job take REGION_PROFILE, REGION_LIFE_ROUTES, REGION_OPENING and REGION_OPENING_ARGS. Their defaults keep stage on lineage with the development opening. For a single-region world, the life-route catalog is the region's own endpoint: 2=void.aeternalisgames.com:7400=void.aeternalisgames.com.

  • Trial opening (tunable, not a world rule). The opening is:

    • a 10 x 10 mm arena at 293.15 K;
    • nursery funding for eight founders (8 x primitive_endowment());
    • eight spawn sites;
    • four rich, three lean and one empty 1,000 µm patch;
    • a stable genesis commit 18ff2e1ab8cef4c9cd73d4cc6e322496.

    It is written once, so changing it means a new region.

  • DEV schema v33. The store Jobs pin postgres-tools from Gitea run 350 (source ae3b2b4), the run that built the promoted DEV server image.

  • The provisioner creates the life allocator. The owner provisioning tool takes evo-world-clone provision --life-allocator-start N, accepted only with the primitive-v1 and cellular-v1 openings:

    • The run inserts life_allocators(world, N) once, before the genesis check, so an already provisioned region still gets the row.
    • A later run leaves the counter untouched and reports it; the counter only advances.
    • A run whose start is above an existing counter refuses with exit 4.

    There is still no runtime initializer or reset.

  • DEV world 100 starts at 1,000,000,000,000. The audited range required by life-reservations-v1 is satisfied by choosing a start far above every identity the DEV lineage run could have issued. That run was about 43,000 ticks, with lineage identities held in region-1 checkpoints rather than in SQL. Identities are 64-bit, so the gap is free.

  • Cellular reprovisioning survives image promotions. The genesis manifest records the build that wrote it, and every promotion changes --build, so the provision hook refused region 2 after the first promotion (provision refused existing cellular region, although the commit was unchanged). The check also could never have passed once the head moved past genesis.

    • At sequence 0, an existing cellular region is now matched exactly under its own recorded build, so a different commit or opening is still refused.
    • Past genesis, as for the lineage and primitive openings, a matching profile and frame identify it.
  • The first playable run moved DEV to region 100/3. Two findings forced it:

    • Region 2's opening was energy-starved. In this trial only a patch's energy channel feeds the reserve; matter is never converted. Founder intake is up to 1,148,000 pJ/s against 152,000 pJ/s maintenance, so the 4M and 16M pJ patches emptied in 3.5 and 14 seconds and the cell starved while feeding.
    • Region 3 keeps the layout with 200M pJ rich and 50M pJ lean patches, about 3 minutes and 45 seconds of full-rate feeding, under genesis commit 71e7a3f03c74613a6f55e72c77671f77. Region 2 stays unserved.
  • Cellular actions are admitted once per tick. A cellular action carries one tick's movement and intake, and a tick without one is idle, so the client sends one every tick. The default probe admission (4 actions per 8-tick window) refused every other one. The cellular bridge allows two per tick of window, which leaves headroom for arrival jitter.

  • A departed account's birth waits instead of fencing the region. A second account requested a birth and disconnected. Its queued birth kept the host ticking, and the cellular publisher's check_life_control refused the batch with SQLSTATE EVL02. That is the same code as a lost region lease, so the host fenced itself, reacquired and failed again every 20 seconds, refusing logins (region 3, 2026-10-13 20:18 UTC).

    • The host now includes and ticks only births whose account holds a session.
    • Other births stay queued until the account returns.
    • Restarting the pod cleared the in-memory queue. The reservation is durable, and the client's query re-queues it.
  • A refused life request no longer breaks the session. The cellular host reports the reserved identity on a pending or refused request. RegionSessions forwarded it unchanged, and the codec rejects any identity or commit on a non-born outcome. The client closed with protocol and retried with the next grant until the account was rate-limited. The client picks a new birth request per launch, so every account that already had a cell was refused as existing_life and could not log in from a fresh launch. The session layer now sends the identity and commit only with born.

  • Grants for region 3 must be minted with --region 3 --lifetime 300 or less. Longer probe sessions require a separate, reviewed change to the cellular grant ceiling; this ADR does not make it.

Consequences

  • Any new primitive or cellular world must choose and record its allocator start in its provision Job. Stage and World0 do not use this flag until their own audited starts are decided.
  • DEV world 100 now mixes an unserved lineage region 1 and a cellular region 2. Returning DEV to lineage means reverting the overlay values. Region 1's history remains recoverable.
  • The 300-second grant ceiling caps each probe session at about five minutes, and a bundle expires five minutes after it is minted.

Later DEV change (2026-10-14): region 4 for the M11.9 playtests

DEV now serves region 100/4, provisioned with the cellular-v4 opening (rules 5, owner format 6: engulfment, detritus, budding wildlife, permadeath and offline freeze; ADR-0124, ADR-0125, ADR-0127, ADR-0128) from server image e891f942 (CI run 376) and postgres-tools fe3558e9 (schema v38). The opening matches region 3's (same arena, nursery, sites and patches) under a new genesis commit. Regions 1, 2 and 3 stay in the stores untouched and unserved; rules 1-4 regions cannot be migrated to rules 5. An account whose life is still active in region 3 (no ending was recorded there, since region 3 ran a pre-v37 image) is routed to region 3, which is no longer served, so playtests use fresh accounts.

Later DEV change (2026-10-14): cellular grant ceiling

At the maintainer's request for playtests longer than five minutes, the cellular profile now honours --m10-max-grant-lifetime (DEV only, 60-14400 s), and the region Deployment passes the overlay ceiling to both profiles. DEV's route overlay already sets 14400 s (4 h), so cellular grants may now last up to 4 hours. The 300 s default still applies wherever no ceiling is configured.