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
+77 -9
View File
@@ -34,20 +34,29 @@ bool valid_header(const CellularBatchHeader& h, std::size_t ticks) {
}
bool known_format(std::uint32_t format) {
return format == cellular_batch_legacy_format || format == cellular_batch_v2_format ||
format == cellular_batch_format || format == cellular_batch_inheritance_format;
format == cellular_batch_format || format == cellular_batch_inheritance_format ||
format == cellular_batch_admin_format;
}
bool owner_version_matches(const CellularLives& owner, const CellularBatch& batch) {
if (!known_format(batch.format_version))
return false;
if (batch.format_version == cellular_batch_admin_format)
return owner.format_version() == cellular_lives_revamp_format &&
owner.rules_version() >= cellular_lives_revamp_rules;
if (batch.format_version == cellular_batch_inheritance_format)
return owner.format_version() >= cellular_lives_inheritance_format &&
cellular_retained_plans(owner.rules_version());
return owner.format_version() < cellular_lives_inheritance_format;
}
bool payload_version_matches(const CellularBatch& batch) {
// ADR-0182: trace 5 only with a command; a batch without one is trace 4.
if (batch.format_version == cellular_batch_admin_format &&
std::ranges::none_of(batch.ticks, [](const auto& tick) { return !tick.admin.empty(); }))
return false;
return std::ranges::all_of(batch.ticks, [&](const auto& tick) {
return (batch.format_version >= cellular_batch_v2_format || tick.births.empty()) &&
(batch.format_version >= cellular_batch_format || tick.mutations.empty());
(batch.format_version >= cellular_batch_format || tick.mutations.empty()) &&
(batch.format_version == cellular_batch_admin_format || tick.admin.empty());
});
}
bool valid_intent(const CellularLifeIntent& life) {
@@ -84,6 +93,12 @@ bool valid_ticks(std::span<const CellularTickIntents> ticks) {
if (!identities.insert(birth.identity).second || !accounts.insert(birth.account).second)
return false;
}
if (tick.admin.size() > max_cellular_tick_admin_commands)
return false;
for (std::size_t i = 0; i < tick.admin.size(); ++i)
if (!cellular_admin_command_valid(tick.admin[i]) ||
(i > 0 && tick.admin[i - 1].id >= tick.admin[i].id))
return false;
for (std::size_t i = 0; i < tick.mutations.size(); ++i) {
const auto& mutation = tick.mutations[i];
if (mutation.life_id == 0 || mutation.event_index == 0 || mutation.offer_tick == 0 ||
@@ -198,7 +213,8 @@ encode_cellular_batch(const CellularBatch& batch) {
: 0) +
(batch.format_version >= cellular_batch_format
? tick.mutations.size() * cellular_batch_mutation_bytes
: 0);
: 0) +
tick.admin.size() * cellular_batch_admin_bytes;
if (records > max_cellular_batch_bytes - size - tick_header_bytes)
return std::unexpected{CellularBatchError::format};
size += tick_header_bytes + records;
@@ -224,7 +240,7 @@ encode_cellular_batch(const CellularBatch& batch) {
put(out, tick.births.size(), 4);
if (batch.format_version >= cellular_batch_format) {
put(out, tick.mutations.size(), 4);
put(out, 0, 4);
put(out, tick.admin.size(), 4); // Zero before format 5.
}
for (const auto& life : tick.lives)
put_intent(out, life);
@@ -247,6 +263,16 @@ encode_cellular_batch(const CellularBatch& batch) {
put(out, mutation.become ? 1 : 0, 1); // Byte 34 (rules 13).
put(out, 0, 5);
}
for (const auto& command : tick.admin) {
put(out, command.id, 8);
put(out, static_cast<std::uint16_t>(command.kind), 2);
put(out, command.count, 2);
put(out, 0, 4);
put(out, command.target, 8);
put(out, command.amount.energy.value, 8);
for (const auto& channel : command.amount.matter)
put(out, channel.value, 8);
}
}
if (out.size() != size)
return std::unexpected{CellularBatchError::format};
@@ -259,8 +285,8 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
!std::ranges::equal(bytes.first(magic.size()), magic))
return std::unexpected{CellularBatchError::format};
const auto format = get(bytes, 8, 4);
if (format > cellular_batch_inheritance_format ||
!known_format(static_cast<std::uint32_t>(format)) || get(bytes, 12, 4) != 4)
if (format > cellular_batch_admin_format || !known_format(static_cast<std::uint32_t>(format)) ||
get(bytes, 12, 4) != 4)
return std::unexpected{CellularBatchError::version};
if (get(bytes, 108, 4) != 0)
return std::unexpected{CellularBatchError::format};
@@ -298,13 +324,16 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
birth_count = get(bytes, offset, 4);
offset += 4;
}
std::uint64_t mutation_count{};
std::uint64_t mutation_count{}, admin_count{};
if (format >= cellular_batch_format) {
mutation_count = get(bytes, offset, 4);
if (get(bytes, offset + 4, 4) != 0)
admin_count = get(bytes, offset + 4, 4);
if (format != cellular_batch_admin_format && admin_count != 0)
return std::unexpected{CellularBatchError::format};
offset += 8;
}
if (admin_count > max_cellular_tick_admin_commands)
return std::unexpected{CellularBatchError::format};
if (count > biology::max_cellular_tick_lives ||
count > (bytes.size() - offset) / cellular_batch_intent_bytes ||
birth_count > biology::max_cellular_tick_lives ||
@@ -381,9 +410,29 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
step.mutations.push_back(mutation);
offset += cellular_batch_mutation_bytes;
}
if (admin_count > (bytes.size() - offset) / cellular_batch_admin_bytes)
return std::unexpected{CellularBatchError::format};
for (std::uint64_t i = 0; i < admin_count; ++i) {
const auto record = bytes.subspan(offset, cellular_batch_admin_bytes);
CellularAdminCommand command;
command.id = get(record, 0, 8);
const auto kind = get(record, 8, 2);
if (kind > 0xFF)
return std::unexpected{CellularBatchError::format};
command.kind = static_cast<CellularAdminKind>(kind);
command.count = static_cast<std::uint16_t>(get(record, 10, 2));
command.target = get(record, 16, 8);
command.amount.energy.value = get(record, 24, 8);
for (std::size_t c = 0; c < command.amount.matter.size(); ++c)
command.amount.matter[c].value = get(record, 32 + 8 * c, 8);
if (!all_zero(record.subspan(12, 4)))
return std::unexpected{CellularBatchError::format};
step.admin.push_back(command);
offset += cellular_batch_admin_bytes;
}
out.ticks.push_back(std::move(step));
}
if (offset != bytes.size() || !valid_ticks(out.ticks))
if (offset != bytes.size() || !valid_ticks(out.ticks) || !payload_version_matches(out))
return std::unexpected{CellularBatchError::format};
return out;
}
@@ -433,7 +482,16 @@ decode_cellular_mutation_input(const std::array<std::uint8_t, 16>& account, std:
std::expected<std::unique_ptr<CellularLives>, CellularBatchError>
replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
std::vector<CellularMutationOutcome>& mutation_outcomes) {
std::vector<CellularAdminResult> ignored;
return replay_cellular_batch(base, batch, mutation_outcomes, ignored);
}
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) {
mutation_outcomes.clear();
admin_results.clear();
if (!owner_version_matches(base, batch))
return std::unexpected{CellularBatchError::version};
const auto& h = batch.header;
@@ -448,6 +506,7 @@ replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
if (!replay)
return std::unexpected{CellularBatchError::state};
std::vector<CellularMutationOutcome> complete_outcomes;
std::vector<CellularAdminResult> complete_admin;
for (const auto& tick : batch.ticks) {
const auto executed = (*replay)->advance_tick_with_mutations(tick.lives, tick.mutations);
if (!executed)
@@ -467,8 +526,17 @@ replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
return std::unexpected{CellularBatchError::state};
*replay = std::move(*born);
}
if (!tick.admin.empty()) {
std::vector<CellularAdminResult> results;
auto applied = (*replay)->admin_candidate(tick.admin, &results);
if (!applied)
return std::unexpected{CellularBatchError::state};
*replay = std::move(*applied);
complete_admin.insert(complete_admin.end(), results.begin(), results.end());
}
}
mutation_outcomes = std::move(complete_outcomes);
admin_results = std::move(complete_admin);
return std::move(*replay);
}