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
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:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user