feat(admin): live admin commands in trace 5 (schema 63)
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / postgres-tools (push) Successful in 30s
Foundation / server-image (push) Successful in 4m44s
Foundation / image (push) Successful in 5m33s

The admin portal can now spawn wildlife, add bubbles, add to or release the
spent pool, remove a cell and grant a cell's reserve on a running rules-13
region (ADR-0182 section 10). No new owner format or region opening.

- Trace 5: trace 4 plus 64-byte command records counted in the tick header's
  last word; a batch without commands stays trace 4 (older builds replay it).
  Bundle 15 admits trace 5.
- CellularLives::admin_candidate applies a tick's commands after its births,
  each on a copy kept only when it applies and closes: imports through the
  boundary ledger, removals into the spent pool with a new `removed` corpse
  cause, spawned roots via the ADR-0180 seed (now a shared helper) funded by
  an exact import. Refused commands change nothing.
- Schema 63: the immutable admin_commands queue (spawn identities from the
  life allocator), pending/history reads, and binding of every recorded
  command exactly once inside both cellular publishers; the SQL trace parsers
  read trace 5 through its trace-4 normal form.
- The region polls pending commands every 2 s and appends up to 16 per tick;
  the admin API and portal gain region actions, per-cell Remove/Grant and the
  command history.
- Fixes an existing test that did not advance its head after a tick commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-27 17:14:04 -04:00
co-authored by Claude Opus 5.5
parent b075198040
commit b1cc3b121b
32 changed files with 1487 additions and 138 deletions
+2 -1
View File
@@ -120,7 +120,8 @@ enum class CellularDeathCause : std::uint8_t {
starved = 1,
engulfed = 2,
merged = 3,
emerged = 4
emerged = 4,
removed = 5 // ADR-0182: an operator removed the cell (rules 13).
};
struct CellularCorpseCandidate {
std::uint64_t life_id{};
@@ -118,6 +118,14 @@ cellular_checkpoint_trace_format(const CellularVersionBundle& b) noexcept {
: server::cellular_batch_v2_format;
}
// ADR-0182: a bundle-15 commit may carry admin commands in trace 5; every other format is
// exactly the bundle's.
[[nodiscard]] constexpr bool cellular_checkpoint_trace_admits(const CellularVersionBundle& b,
std::uint32_t format) noexcept {
return format == cellular_checkpoint_trace_format(b) ||
(format == server::cellular_batch_admin_format && b == cellular_v15_versions);
}
// Batch evidence bound by manifest v2 (ADR-0063); all zero at genesis.
struct BatchDigests {
std::uint64_t trace_bytes{};
+8
View File
@@ -31,6 +31,11 @@
// opens or extends the window for M (1..240) minutes
// from now, or closes it (M = 0), as the signed-in admin
// (ADR-0087 amendment). No request body.
// GET /api/regions/<n>/commands the region's last admin commands and where they applied
// POST /api/regions/<n>/commands?kind=K[&count=N][&target=ID][&energy=PJ][&carbon=FG]
// [&nitrogen=FG][&phosphorus=FG][&other=FG][&reason=R]
// queues a command (remove_cell, grant_reserve,
// add_bubbles, add_pool, release_pool, spawn_wildlife)
namespace evo::server::admin {
struct AdminAsset {
std::string path; // "/index.html", ...; "/" serves "/index.html".
@@ -64,6 +69,9 @@ class AdminApi {
[[nodiscard]] OpsResponse regions();
[[nodiscard]] OpsResponse view(std::uint64_t region, std::chrono::steady_clock::time_point now);
[[nodiscard]] OpsResponse window(std::uint64_t region);
[[nodiscard]] OpsResponse commands(std::uint64_t region);
[[nodiscard]] OpsResponse enqueue(std::uint64_t region, std::string_view query,
const broker::AccessTokenClaims& admin);
[[nodiscard]] OpsResponse set_window(std::uint64_t region, std::string_view query,
const broker::AccessTokenClaims& admin);
[[nodiscard]] std::optional<persistence::PgRows> query(const std::string& sql,
@@ -152,6 +152,9 @@ class CellularRegionHost {
}
// Queued choices not carried by the commit in flight: the open batch binds these.
[[nodiscard]] std::vector<persistence::CellularMutationReservation> unbound_mutations() const;
// ADR-0182: queued admin commands (rules 13) not carried by the commit in flight, oldest
// first, at most one tick's worth. Publication binds each to its queue row once.
[[nodiscard]] std::vector<CellularAdminCommand> unbound_admin_commands() const;
[[nodiscard]] std::vector<FinalCellularMutation> take_finalized_mutations();
// v5 requests allocate durably, then wait for the scheduler to include the exact
// reservation in a profile-4 batch. Repeating the request is idempotent.
@@ -207,6 +210,7 @@ class CellularRegionHost {
void finalize_births(std::span<const CellularTickIntents::Birth> births);
void queue_birth(const CellularTickIntents::Birth& birth);
void reload_mutations();
void reload_admin_commands();
// ADR-0127: owned lives that died record their ending so the account may start again.
void note_endings(const CellularLives& before, const CellularLives& after,
const persistence::Uuid& commit);
@@ -285,6 +289,8 @@ class CellularRegionHost {
std::vector<CellularTickIntents::Birth> queued_births_;
std::vector<CellularBirthRefusal> pending_birth_refusals_;
std::vector<persistence::CellularMutationReservation> queued_mutations_;
std::vector<CellularAdminCommand> queued_admin_;
std::chrono::steady_clock::time_point next_admin_reload_{};
// A reservation may exist that the queue does not show; reload before publishing.
bool mutations_uncertain_{};
std::vector<FinalCellularMutation> finalized_mutations_;
+10 -3
View File
@@ -58,7 +58,8 @@ class CellularSessionBatchBuilder {
append(std::uint64_t tick, std::span<const CellularLifeIntent> baseline,
std::span<const network::CarriedAction> actions,
std::span<const CellularTickIntents::Birth> births = {},
std::span<const persistence::CellularMutationReservation> mutations = {});
std::span<const persistence::CellularMutationReservation> mutations = {},
std::span<const CellularAdminCommand> admin = {});
// Scheduler path: expected placement/funding/existing-life refusals are reported
// separately, so they cannot prevent other births or the ordinary tick. Unexpected
// failures retain append's all-or-nothing behavior. Persist reports only after publish.
@@ -66,13 +67,18 @@ class CellularSessionBatchBuilder {
std::uint64_t tick, std::span<const CellularLifeIntent> baseline,
std::span<const network::CarriedAction> actions,
std::span<const CellularTickIntents::Birth> births = {},
std::span<const persistence::CellularMutationReservation> mutations = {});
std::span<const persistence::CellularMutationReservation> mutations = {},
std::span<const CellularAdminCommand> admin = {});
[[nodiscard]] std::span<const CellularBirthRefusal> refused_births() const noexcept {
return refused_births_;
}
[[nodiscard]] const CellularBatch& batch() const noexcept {
return batch_;
}
// ADR-0182: each admin command appended so far and whether it applied, in trace order.
[[nodiscard]] std::span<const CellularAdminResult> admin_results() const noexcept {
return admin_results_;
}
[[nodiscard]] std::span<const CellularActionRecord> actions() const noexcept {
return actions_;
}
@@ -106,7 +112,7 @@ class CellularSessionBatchBuilder {
std::span<const network::CarriedAction> actions,
std::span<const CellularTickIntents::Birth> births,
std::span<const persistence::CellularMutationReservation> mutations,
bool allow_refusals);
std::span<const CellularAdminCommand> admin, bool allow_refusals);
explicit CellularSessionBatchBuilder(std::unique_ptr<CellularLives> working)
: working_{std::move(working)} {}
std::unique_ptr<CellularLives> working_;
@@ -114,6 +120,7 @@ class CellularSessionBatchBuilder {
std::vector<CellularActionRecord> actions_;
std::vector<CellularMutationActionRecord> mutation_actions_;
std::vector<CellularBirthRefusal> refused_births_;
std::vector<CellularAdminResult> admin_results_;
std::optional<CellularLivesError> last_lives_error_;
};
} // namespace evo::server
@@ -22,6 +22,8 @@ struct CellularBatchHeader {
inline constexpr std::uint32_t cellular_batch_format = 3;
// ADR-0166: explicit opt-in for owner format 8/rules 10; the default remains 3.
inline constexpr std::uint32_t cellular_batch_inheritance_format = 4;
// ADR-0182: trace 4 plus admin commands, for rules 13 only. A batch without commands stays 4.
inline constexpr std::uint32_t cellular_batch_admin_format = 5;
inline constexpr std::uint32_t cellular_batch_v2_format = 2;
inline constexpr std::uint32_t cellular_batch_legacy_format = 1;
struct CellularTickIntents {
@@ -38,6 +40,8 @@ struct CellularTickIntents {
// Choices accepted against the preceding checkpoint and scheduled for this tick.
// The successor identity is durably reserved before the batch is replayed.
std::vector<CellularMutationSelection> mutations;
// Format 5 (ADR-0182): operator commands applied after the births, by ascending id.
std::vector<CellularAdminCommand> admin{};
friend bool operator==(const CellularTickIntents&, const CellularTickIntents&) = default;
};
// Transient scheduler report, not part of the replay trace. A refused birth changes
@@ -81,13 +85,17 @@ inline constexpr std::size_t cellular_batch_tick_header_bytes = 16;
inline constexpr std::size_t cellular_batch_intent_bytes = 24;
inline constexpr std::size_t cellular_batch_birth_bytes = 40;
inline constexpr std::size_t cellular_batch_mutation_bytes = 40;
// Format 5: id u64, kind u16, count u16, zero u32, target u64, energy and four matter u64.
inline constexpr std::size_t cellular_batch_admin_bytes = 64;
inline constexpr std::size_t max_cellular_tick_admin_commands = 16;
inline constexpr std::size_t max_cellular_batch_ticks = 64;
inline constexpr std::size_t max_cellular_batch_bytes =
cellular_batch_header_bytes +
max_cellular_batch_ticks * (cellular_batch_tick_header_bytes +
biology::max_cellular_tick_lives *
(cellular_batch_intent_bytes + cellular_batch_birth_bytes +
cellular_batch_mutation_bytes));
cellular_batch_mutation_bytes) +
max_cellular_tick_admin_commands * cellular_batch_admin_bytes);
enum class CellularBatchError : std::uint8_t { format, version, scope, state };
inline constexpr std::size_t cellular_action_record_bytes = 48;
inline constexpr std::size_t max_cellular_action_records = 1'024;
@@ -118,6 +126,11 @@ struct CellularMutationOutcome {
[[nodiscard]] std::expected<std::unique_ptr<CellularLives>, CellularBatchError>
replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
std::vector<CellularMutationOutcome>& mutation_outcomes);
// ADR-0182: also reports every admin command's result in trace order.
[[nodiscard]] std::expected<std::unique_ptr<CellularLives>, CellularBatchError>
replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
std::vector<CellularMutationOutcome>& mutation_outcomes,
std::vector<CellularAdminResult>& admin_results);
// The canonical 34-byte reserved choice (schema v29): tick, life, event and offer tick as
// u64 and the operator as u16, little-endian.
inline constexpr std::size_t cellular_mutation_input_bytes = 34;
@@ -179,6 +179,33 @@ struct CellularLifeIntent {
biology::CellularStepIntent intent{};
auto operator<=>(const CellularLifeIntent&) const = default;
};
// ADR-0182 admin commands: operator inputs recorded in the trace (batch format 5) and applied
// after a tick's births, in ascending id. Imports enter the boundary ledger as a named game
// source; removed matter goes to the spent pool. A command whose target is gone or that does
// not fit is refused and changes nothing; the others still apply.
enum class CellularAdminKind : std::uint8_t { // A u16 in the trace.
remove_cell = 1, // `target` life: body and reserve go to the spent pool.
grant_reserve = 2, // `amount` imported into the `target` life's reserve.
add_bubbles = 3, // `amount` imported as `count` (1..256) bubbles sharing it.
add_pool = 4, // `amount` imported into the spent pool.
release_pool = 5, // Up to `amount` moved from the spent pool into `count` bubbles.
spawn_wildlife = 6, // `count` (1..64) random-genome roots, identities `target`.., imported.
};
struct CellularAdminCommand {
std::uint64_t id{}; // The durable queue id.
CellularAdminKind kind{};
std::uint16_t count{};
std::uint64_t target{};
accounting::Inventory amount{};
friend bool operator==(const CellularAdminCommand&, const CellularAdminCommand&) = default;
};
// Shape only (kind, counts, amounts, identity range); whether it applies is decided at its tick.
[[nodiscard]] bool cellular_admin_command_valid(const CellularAdminCommand& command) noexcept;
struct CellularAdminResult {
std::uint64_t id{};
bool applied{};
friend bool operator==(const CellularAdminResult&, const CellularAdminResult&) = default;
};
struct CellularMutationSelection {
std::uint64_t life_id{}, event_index{}, offer_tick{}, successor_id{};
std::uint16_t operator_id{};
@@ -412,6 +439,11 @@ class CellularLives {
[[nodiscard]] std::expected<CellularTickExecution, CellularLivesError>
advance_tick_with_mutations(std::span<const CellularLifeIntent> intents,
std::span<const CellularMutationSelection> selections);
// ADR-0182: a detached candidate after `commands` (valid, strictly ascending ids) at the
// current tick, after its births. Rules 13 only. `results` reports each command, in order.
[[nodiscard]] std::expected<std::unique_ptr<CellularLives>, CellularLivesError>
admin_candidate(std::span<const CellularAdminCommand> commands,
std::vector<CellularAdminResult>* results = nullptr) const;
private:
friend class CellularMigration;
@@ -432,6 +464,11 @@ class CellularLives {
migration_replacement(std::vector<CellularOwnedLife>, const biology::LineageArchive&,
CellularBoundaryLedger) const;
struct State;
// ADR-0180/0182: one randomized founder root `id` placed at a seeded free spot, funded
// from the nursery, or (with `imported`) by a game-source import added to it.
[[nodiscard]] static std::optional<CellularLivesError>
seed_wildlife_root(State& next, std::uint64_t world, std::uint64_t region, std::uint64_t tick,
std::uint64_t id, accounting::Inventory* imported);
explicit CellularLives(std::unique_ptr<State> state);
std::unique_ptr<State> state_;
std::vector<CellularLifeTickFeedback> last_tick_feedback_;
@@ -121,6 +121,13 @@ cellular_mutation_cost(const biology::CellularMutationTuning& tuning) noexcept;
const CellularRevampRules& rules, std::uint64_t world,
std::uint64_t region, std::uint64_t tick,
std::uint64_t source);
// ADR-0182 admin bubbles: `amount` as `count` bubbles, each channel split evenly (the remainder
// in the last), at seeded random spots nudged east past taken addresses, with the next deposit
// ids and `source`. False, with `config` unchanged, when the habitat cannot take them all.
[[nodiscard]] bool cellular_scatter_bubbles(biology::CellularHabitatConfig& config,
const accounting::Inventory& amount,
std::uint16_t count, std::uint64_t seed,
std::uint64_t source);
// A body's handling carrying reserve matter: thrust, reverse thrust and turning scale by
// body / (body + load), full-output costs by (body + load) / body, where load is the declared
// share of `carried` matter. Drag is unchanged. No load leaves the handling as it is.