deploy(dev): promote d46de25's images on region 16; ADR-0182 admin portal
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m38s
Foundation / postgres-tools (push) Successful in 6s
Foundation / server-image (push) Successful in 5s
Foundation / image (push) Successful in 5s

Server and postgres-tools images from Gitea run 540 (d46de25, all checks green):
reproduction safety revision 1 and resizable cellular panels. Region 16 keeps
running on its recorded rules; the staged safety tuning profile stays unmounted,
so the safety trial still needs a fresh opening. 51f979a's build (222fa3de) is
retained. Refreshes the session window.

ADR-0182 records the admin portal direction: world tuning revisions in SQL,
adopted per tick and recorded in region history; admin commands with a named
game source; drip/source settings; data-defined mutations; bans and session
intervals; a Keycloak-gated admin API and portal at srs.aeternalisgames.com.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-27 10:10:05 -04:00
co-authored by Claude Opus 5.5
parent d46de25bef
commit 477ea8980b
6 changed files with 183 additions and 9 deletions
@@ -0,0 +1,172 @@
# ADR-0182: Admin portal, world tuning in SQL and per-tick amendments
## Status and scope
Accepted direction, 2026-10-27, from the maintainer's decisions in chat; implementation
pending. DEV (world 100) only; stage and World0 need their own review. Applies to a new owner
format and new openings only:
regions 12-16 keep their recorded rules and Git-mounted tuning. Supersedes, for that new
format, ADR-0181's "Git tuning affects future openings only. No live retune."
## Context
Every balance change so far has meant a Git tuning edit, a new image or ConfigMap and a new
DEV region (regions 14, 15 and 16 in a week). The maintainer wants an admin portal to review
accounts, act on regions and tune the cellular game while it runs. This is a game, not a
pure simulation: designer-controlled resource sources are acceptable when they are named and
counted.
The constraint is determinism. A region's history must replay to the same state, so nothing
may change a running region except an event recorded at a tick.
## Decision
### 1. World tuning lives in SQL
- Schema 61 adds append-only `world_tuning_revisions(world, revision, parent_revision,
format, canonical_text, digest, author_subject, reason, created_at)`. A revision is the
complete canonical tuning text (`encode_cellular_revamp_tuning`), never a diff, so the
existing parser and validator are the only interpretation.
- All regions of a world share its tuning and mutation definitions (maintainer decision).
Per-region values are not offered.
- Revisions are immutable. Undo is a new revision whose text equals an earlier one.
- Git keeps the seed file for creating a world and the test fixtures. It is not consulted
by a running region, and Argo no longer carries tuning for regions on the new format.
### 2. Amendments are recorded per tick
- A region polls for a newer world revision on its existing database connection, bounded
and off the tick path (at most once a second).
- It validates the revision with its own parser. If it can parse it, it adopts it at its next
tick boundary and records `tuning_adopted(revision, digest)` at that tick in its own
history, published with that tick. If it cannot, for example because the revision uses
keys its image does not know, it keeps its current revision and reports `tuning_refused`
with the revision number. The portal shows each region's adopted revision.
- Replay and recovery read the recorded revision by number and digest, never "the latest".
- Amendments change future calculations only. Heritable values already in a genome are not
rewritten (for example, a new `mutation.min_points` does not change existing traits).
- Every tuning key is classified **live** or **opening-only**. Opening-only keys (geometry
and size, tick rate, world/frame, liquid profile structure) can be revised, but a running
region ignores them and the portal labels them "next opening".
### 3. Admin commands
- Schema 61 adds `admin_commands(world, region, command_id, kind, payload, author_subject,
reason, created_at, applied_tick, outcome)`. The admin API inserts and the region host
drains them at tick boundaries in id order, publishing each with that tick. This is the
same pattern as the durable mutation queue (schema 59).
- Kinds:
- `kill_cell(life)`: the cell dies with an "admin" outcome. Its body and reserve go to
the spent pool and drip back.
- `grant_reserve(life, inventory)`: a **game-source import** into that cell's reserve.
- `add_region_bubbles(inventory, count)`: a game-source import as bubbles at random
spots, at most the region's bubble limit per tick; the rest follows on later ticks.
- `add_pool(inventory)`: a game-source import into the spent pool.
- `release_pool(inventory)`: moves pool matter into the region through the drip settings
below, so a large release is spread over drips, never one tick.
- **Game source** is a named import in the region's accounting, like emergence is a named
export. Conservation still holds: every unit is either from the starting stock, imported
by a recorded source or exported by a recorded sink.
### 4. Drip and source settings
The spent-pool drip (today: interval, largest energy bubble, largest matter bubble per
channel) becomes one settings group used by both the pool drip and the game-source spawn:
| Setting | Meaning |
|---|---|
| `drip.interval_ticks` | how often a drip happens (0: never) |
| `drip.bubbles_per_drip` | the most bubbles one drip creates |
| `drip.bubble_max.<channel>` | the most of that channel one bubble may carry (energy pj; carbon, nitrogen, phosphorus, other fg) |
| `drip.scale_percent.<channel>` | per channel, how much faster or slower that channel is released |
| `source.per_drip.<channel>` | game-source import per drip and channel (0: none) |
For the pool, scale changes how quickly the pool drains; it never releases more than the
pool holds. For the source, scale multiplies the import.
### 5. Data-defined mutations
- Mutation definitions move from the compiled catalog into the world revision:
`mutation.<key>.*` gains the definition itself (name, description, effect, primary and
paired traits, steps, costs, triggers and requirements), not only overrides.
- A definition may use only effects, traits, triggers and requirement predicates the image
implements. Requirements come from a fixed predicate set (carbon burned, buds made, a
trait at or above a value, a mutation held). New behaviour needs code and a new image;
the region then refuses revisions using it until promoted.
- The per-cell affinity scores become a vector keyed by mutation id. New entries start at
zero. This is part of the new owner format.
- Mutations are never deleted from a running world. `enabled = 0` stops new offers;
applied mutations stay applied because their effect already changed the genome.
Replacement is disable plus a new definition.
- Session protocol: the client receives definitions (name, description, costs) instead of
using compiled names.
### 6. Accounts
- **Status**: logged in (an open session interval), banned, alive or dead, the region of
the active life, and current mutations (applied mutation results along the life's line).
- **Ban**: `account_bans(account, author_subject, reason, created_at, lifted_at)`. The grant
broker refuses a banned account (`403 account_banned`) and the ban runs the existing
logout (`revoke_account_grants`), so a live session closes within 5 s.
- **Log out**: the existing `revoke_account_grants`.
- **Grant resource**: `grant_reserve` against the account's active life.
- **Death count**: the account's lives with a death outcome.
- **Reset count**: the account's founder births after its first (a new life after death).
- **Living offspring**: living wildlife descended from any of the account's lives, using
the parent links kept since format 5.
- **Time played**: `session_intervals(account, region, started_at, ended_at)` written by the
region host on session open and close. Intervals still open at a region start are closed
at that start. History begins with this schema; earlier play is not recoverable.
### 7. Admin API and portal
- `evo-admin-api`: a C++ service built like the grant broker. It verifies Keycloak access
tokens against the realm keys pinned in Git, requires audience `aevolution-admin` and
realm role `aevolution-admin`, and has its own database login limited to the read views
and the admin tables. Configured world allowlist; World0 is refused in code.
- Every write records the token subject and a reason.
- The region view: the region host's internal ops port gains a bounded snapshot route (cell
id, position, radius, wildlife/player and account, bubbles), reachable only from the admin
API by NetworkPolicy. The admin API serves it to the portal at up to 1 Hz.
- The portal is a static browser application at `https://srs.aeternalisgames.com`
(section **Cellular** now, **3D** later) using authorization code with PKCE. Its toolchain is chosen in the implementation change
with dependency evidence (DEPENDENCY_EVALUATION.md).
- Keycloak (maintainer setup): realm role `aevolution-admin`; public client
`aevolution-admin-portal` with PKCE S256; an audience mapper adding `aevolution-admin`;
MFA required for the role.
## Delivery order
1. Read-only portal: login, accounts (from existing data), regions, census, region view.
2. Schema 61 and the new owner format: world revisions, adoption records, admin commands,
game source, drip settings, the score vector, session intervals and bans. One new
opening on that format.
3. Admin commands and account actions in the portal.
4. Live tuning in the portal.
5. Data-defined mutations in the portal.
## Deferred
- **Cell migration between regions.** With world-shared tuning and mutations it no longer
meets per-region mismatches, but still needs the paired transfer extended to the new
format and to player lives, and a client handoff.
- **New matter types.** `accounting::Element` has four channels throughout accounting,
traits, bubbles, the protocol and the client. A later decision; a fixed number of matter
slots is the expected approach.
## Alternatives
- **Export portal changes to Git and reopen regions.** Rejected: more steps for the same
result, and not live.
- **Change values in a running region's memory.** Rejected: replay and recovery would diverge.
- **Per-region tuning.** Rejected: all regions of a world share rules.
- **Database push instead of polling.** Not needed at one adoption check per second.
## Consequences
- Balance changes become data: no image, ConfigMap or region per change.
- Balance history moves from Git review to the revision table (author, reason, full text).
It is covered by database backups and history domains (ADR-0155).
- Argo no longer shows tuning drift for new-format regions; the portal shows each region's
adopted revision instead.
- One more opening is required, for the new owner format.
+2
View File
@@ -1,5 +1,7 @@
# Architecture decision records
- [ADR-0182: Admin portal, world tuning in SQL and per-tick amendments](0182-admin-portal-and-world-tuning.md) - accepted direction: world tuning revisions in SQL adopted per tick and recorded in region history, admin commands with a named game source, drip/source settings, data-defined mutations, bans and session intervals, and a Keycloak-gated admin API and portal; migration and new matter types deferred.
- [ADR-0181: Reproduction safety revision 1](0181-cellular-reproduction-safety.md) - opt-in controlled-cell mutation share, retained budding provision, outward mutation launch and a protected growth fuel buffer; historical declarations unchanged.
- [ADR-0180: DEV starting wildlife](0180-dev-starting-wildlife.md) - opt-in, nursery-funded random-genome roots for disposable playtest openings, exact recovery and no restart replenishment; a scoped exception to player-origin biology.