diff --git a/deploy/kubernetes/region/dev-session-route/listener.yaml b/deploy/kubernetes/region/dev-session-route/listener.yaml index 8e88273..0533f9f 100644 --- a/deploy/kubernetes/region/dev-session-route/listener.yaml +++ b/deploy/kubernetes/region/dev-session-route/listener.yaml @@ -12,7 +12,7 @@ spec: env: - {name: REGION_SESSION, value: "dev"} - {name: REGION_SESSION_LISTEN, value: "0.0.0.0:7400"} - - {name: REGION_SESSION_WINDOW, value: "dev-20261027T133850-778f1d68:1793122730"} + - {name: REGION_SESSION_WINDOW, value: "dev-20261027T140222-02077e44:1793124142"} - {name: REGION_M10_MAX_GRANT_LIFETIME, value: "14400"} ports: # QUIC (ADR-0090): UDP only; nothing listens on TCP 7400. diff --git a/deploy/kubernetes/region/dev/kustomization.yaml b/deploy/kubernetes/region/dev/kustomization.yaml index 601f7cc..952c38b 100644 --- a/deploy/kubernetes/region/dev/kustomization.yaml +++ b/deploy/kubernetes/region/dev/kustomization.yaml @@ -13,7 +13,7 @@ components: images: - name: aevolution-server newName: registry.aeternalisgames.com/aeternalis/aevolution-server - digest: sha256:222fa3dea0cb25335234678fa0d628222fc92c9ff38a1869330d973b8c4b4e53 + digest: sha256:f235d14aa06924010ac9e1a4cfad6148ed24447eafb33ef2df968a285f467457 patches: - path: region-values.yaml # The Git tuning files for the provision Job's liquid (rules 12) and revamp (rules 13) diff --git a/deploy/kubernetes/region/dev/region-values.yaml b/deploy/kubernetes/region/dev/region-values.yaml index 1328e07..97b1e10 100644 --- a/deploy/kubernetes/region/dev/region-values.yaml +++ b/deploy/kubernetes/region/dev/region-values.yaml @@ -18,12 +18,12 @@ spec: env: - {name: REGION_WORLD, value: "100"} - {name: REGION_ID, value: "16"} - - {name: REGION_BUILD, value: 222fa3dea0cb25335234678fa0d628222fc92c9ff38a1869330d973b8c4b4e53} + - {name: REGION_BUILD, value: f235d14aa06924010ac9e1a4cfad6148ed24447eafb33ef2df968a285f467457} - {name: REGION_PROFILE, value: cellular} # The whole world's catalog: dev world 100 has only this region. - {name: REGION_LIFE_ROUTES, value: "16=void.aeternalisgames.com:7400=void.aeternalisgames.com"} # Keep the currently promoted build plus prior committed builds recoverable. - - {name: REGION_RETAINED, value: "f1183f4476bac87c09504a574112df4663931f67e88cc38dc08f867ce98ff726 815153514ca4a53967932bb46456ff4cb4e1784f9db247bc3b613b7e8365c59f 21507d4369cebef83ee05152daea5ac2f581ea86a9dc85276ef54e3f9f6388c5 5a77cf9e96e7a0e40ea07e9394a3fa458184ce54f8f774a8fb59cbec1db75c54 e17c62bc8dbad089da57e8b30adc391ff8b947cc7182b3160f5e2709103ded78 6c96629eb3c26513d55207b109fe2a9873a58f43510bd067b7d5422572e3fb42 7952185d5ef96504b5793b76fe72e42cbe9c9ac19149bf912adb2c3a735f8dbf f378a43d6146eeed864110b90848df0bec9672fa4c9941a2d04de249068a4a09 ecac8f9f2489c547ce58f12ed01baaa3939c8adbf8aed05c313abbf422cdc855 4af7209941643e0c6a100e2b4e2fef8a959b87fdbfac2173b7867cfc1808bd66 edb39f956df1f481d7ba724cac4ceb3a4fe494efc02f994d31d6c96dfae04a78 0ded41070dd3e0c0daa43e13dadc58c449865eec00530cfceff3c1579c66e916 754446fe4e5f33e9c0d5a1a74a02444a01de1700673442c90827c708aba62cee c597c0bac8b4a796e1e8b70344f9866cb047cc90cfb15af774d38860594ea27a e83c333a87056c678b5e835947647ef42370b43dbfc31997744f28d993f9c4aa db2b0e6a6071502381a768d70fd9bab8c08c64e4717fc23da45dbe8adc5fa3d6 cdc10712ff8bf956f8f5900709500046493523b51dc670d5b2d01eaf604bcd38 028571f257b485acafbe79b704a80f273d899485c4bb264d9c8137bf51e33217 566c29329433934f1436faf94652a7b925df8b4587ab04470322172f47c31c02 1dd640eba3e9dbdd10106698215a0a06df89c5cdf801c53c4c26fb923116552a faeb26fc5db5c4aae9ae9eb4388e807ab4d59499d7639fcab3d878843a740037 5e13e0096eb4010253c270ab98f0e9bbc11571c221eb779d428333e8cd63c955 e891f9427d5ec81b32595d70be9d00bb66c6d8223b4747d12be8c388c2fc0c8e 58aab8aaa538c0c6e5ad7281fd27e50374b489942aa317296dbf9c2ec5ca3434 4a8b0a9dc9f6be491e9eacb464aa7ef7c0d449de3018c4172c01448ce39a5108 3e5b8cef06838821113c8bba064e9415e8c627bca552fb978f830d40027b80f2 67e6bb3d138e7d489850ac99b5915ef8659178a68140b963e282b24020a288e2 f178f7f44251fdc9ae9ccaaecc5ea6f10aa534caa25d506abc3fbde21c69db17 6532f97e9b7d1492f1a17d1228ce7e563016c2187735f44e58ff1e9f786019aa 7c5462391a9bff4f7c25f2761098e7189b7ae204af0a7be61a652e4482f63e6a 9ba005f9216a2211491afd0e335ac5c6f20af1166fbb7518bcc8cec2e536f5ce 7eb84318234e23c223d4279ac01e925ba0b08d6d6950f7ba328f0ce909af8307 0fcdbf1518b677829322dc18e1feebd354a6e39700bd9cdb60ab47dc0465c3a6 801a9ae4fe1049dd27cfd9c356f21f29c6e07238448c201c08d288b5cc8e7e9a f0869be511179866f9a71a63a6a5f65e577e851fd7851184734bb5c56940b1a6 178cd8ffcdfe9fe14f39084d78341a8705ca72e78947bada31ab0356508fc232 0fd4807f67ab317561f115f12c0d8540e04596fdea389d7c2104e97dda5a0351 effea9180d802e50abed76a5da665374f3591eda8aeb99c0fff085ed6df618ae 7a35cc170b935508b9b88379f4fb581acb852ebe769ac269f1596861aca2ffa7 2d1307493202464773734b0a2d33f4a737b0a897cb179de05bdf433cbdb1aec1 a5b70d945b63618a2897a848320e9af6b73a1a4f3bf8fb052d8286a93f6f8ada"} + - {name: REGION_RETAINED, value: "f1183f4476bac87c09504a574112df4663931f67e88cc38dc08f867ce98ff726 815153514ca4a53967932bb46456ff4cb4e1784f9db247bc3b613b7e8365c59f 21507d4369cebef83ee05152daea5ac2f581ea86a9dc85276ef54e3f9f6388c5 5a77cf9e96e7a0e40ea07e9394a3fa458184ce54f8f774a8fb59cbec1db75c54 e17c62bc8dbad089da57e8b30adc391ff8b947cc7182b3160f5e2709103ded78 6c96629eb3c26513d55207b109fe2a9873a58f43510bd067b7d5422572e3fb42 7952185d5ef96504b5793b76fe72e42cbe9c9ac19149bf912adb2c3a735f8dbf f378a43d6146eeed864110b90848df0bec9672fa4c9941a2d04de249068a4a09 ecac8f9f2489c547ce58f12ed01baaa3939c8adbf8aed05c313abbf422cdc855 4af7209941643e0c6a100e2b4e2fef8a959b87fdbfac2173b7867cfc1808bd66 edb39f956df1f481d7ba724cac4ceb3a4fe494efc02f994d31d6c96dfae04a78 0ded41070dd3e0c0daa43e13dadc58c449865eec00530cfceff3c1579c66e916 754446fe4e5f33e9c0d5a1a74a02444a01de1700673442c90827c708aba62cee c597c0bac8b4a796e1e8b70344f9866cb047cc90cfb15af774d38860594ea27a e83c333a87056c678b5e835947647ef42370b43dbfc31997744f28d993f9c4aa db2b0e6a6071502381a768d70fd9bab8c08c64e4717fc23da45dbe8adc5fa3d6 cdc10712ff8bf956f8f5900709500046493523b51dc670d5b2d01eaf604bcd38 028571f257b485acafbe79b704a80f273d899485c4bb264d9c8137bf51e33217 566c29329433934f1436faf94652a7b925df8b4587ab04470322172f47c31c02 1dd640eba3e9dbdd10106698215a0a06df89c5cdf801c53c4c26fb923116552a faeb26fc5db5c4aae9ae9eb4388e807ab4d59499d7639fcab3d878843a740037 5e13e0096eb4010253c270ab98f0e9bbc11571c221eb779d428333e8cd63c955 e891f9427d5ec81b32595d70be9d00bb66c6d8223b4747d12be8c388c2fc0c8e 58aab8aaa538c0c6e5ad7281fd27e50374b489942aa317296dbf9c2ec5ca3434 4a8b0a9dc9f6be491e9eacb464aa7ef7c0d449de3018c4172c01448ce39a5108 3e5b8cef06838821113c8bba064e9415e8c627bca552fb978f830d40027b80f2 67e6bb3d138e7d489850ac99b5915ef8659178a68140b963e282b24020a288e2 f178f7f44251fdc9ae9ccaaecc5ea6f10aa534caa25d506abc3fbde21c69db17 6532f97e9b7d1492f1a17d1228ce7e563016c2187735f44e58ff1e9f786019aa 7c5462391a9bff4f7c25f2761098e7189b7ae204af0a7be61a652e4482f63e6a 9ba005f9216a2211491afd0e335ac5c6f20af1166fbb7518bcc8cec2e536f5ce 7eb84318234e23c223d4279ac01e925ba0b08d6d6950f7ba328f0ce909af8307 0fcdbf1518b677829322dc18e1feebd354a6e39700bd9cdb60ab47dc0465c3a6 801a9ae4fe1049dd27cfd9c356f21f29c6e07238448c201c08d288b5cc8e7e9a f0869be511179866f9a71a63a6a5f65e577e851fd7851184734bb5c56940b1a6 178cd8ffcdfe9fe14f39084d78341a8705ca72e78947bada31ab0356508fc232 0fd4807f67ab317561f115f12c0d8540e04596fdea389d7c2104e97dda5a0351 effea9180d802e50abed76a5da665374f3591eda8aeb99c0fff085ed6df618ae 7a35cc170b935508b9b88379f4fb581acb852ebe769ac269f1596861aca2ffa7 2d1307493202464773734b0a2d33f4a737b0a897cb179de05bdf433cbdb1aec1 a5b70d945b63618a2897a848320e9af6b73a1a4f3bf8fb052d8286a93f6f8ada 222fa3dea0cb25335234678fa0d628222fc92c9ff38a1869330d973b8c4b4e53"} --- apiVersion: batch/v1 kind: Job @@ -37,7 +37,7 @@ spec: env: - {name: REGION_WORLD, value: "100"} - {name: REGION_ID, value: "16"} - - {name: REGION_BUILD, value: 222fa3dea0cb25335234678fa0d628222fc92c9ff38a1869330d973b8c4b4e53} + - {name: REGION_BUILD, value: f235d14aa06924010ac9e1a4cfad6148ed24447eafb33ef2df968a285f467457} # Region 16 (rules 13): cellular-v10, 60 x 60 mm at 20 C, taken through one empty tick, # the durable upgrades to rules 11 with light, the liquid upgrade from the mounted # tuning file (whose region size must match) and the revamp upgrade from the mounted diff --git a/deploy/kubernetes/stores/dev/kustomization.yaml b/deploy/kubernetes/stores/dev/kustomization.yaml index 9db6190..74d23a2 100644 --- a/deploy/kubernetes/stores/dev/kustomization.yaml +++ b/deploy/kubernetes/stores/dev/kustomization.yaml @@ -10,12 +10,12 @@ resources: images: - name: aevolution-postgres-tools newName: registry.aeternalisgames.com/aeternalis/aevolution-postgres-tools - # Gitea CI run 525 for 131ed5f (schema v60, bundle 15: the cellular revamp); the server - # image is from the same run. - digest: sha256:c99484a6bb4cc5a8366103bd180c337017a9cb866f19080793a3d7d0c2650ef4 + # Gitea CI run 540 for d46de25 (schema v60, bundle 15, reproduction safety revision 1); + # the server image is from the same run. + digest: sha256:dc3e43ede086f3a8ab8e966fa57bb03766f9d39975681b5848b9f9245db9f04e - name: aevolution-server newName: registry.aeternalisgames.com/aeternalis/aevolution-server - digest: sha256:222fa3dea0cb25335234678fa0d628222fc92c9ff38a1869330d973b8c4b4e53 + digest: sha256:f235d14aa06924010ac9e1a4cfad6148ed24447eafb33ef2df968a285f467457 patches: - target: kind: Job diff --git a/docs/adr/0182-admin-portal-and-world-tuning.md b/docs/adr/0182-admin-portal-and-world-tuning.md new file mode 100644 index 0000000..9dc4aff --- /dev/null +++ b/docs/adr/0182-admin-portal-and-world-tuning.md @@ -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.` | the most of that channel one bubble may carry (energy pj; carbon, nitrogen, phosphorus, other fg) | +| `drip.scale_percent.` | per channel, how much faster or slower that channel is released | +| `source.per_drip.` | 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..*` 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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 749b557..d75adb9 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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.