Admit v10 mutation choices through the cellular host and sessions

The region host checks a choice against the committed offer, reserves the
successor for the next tick, and publishes it with that tick's batch; the
owner's v10 session gets the receipt and final outcome. Schema v35 now
refuses a checkpoint that skips a reserved choice, and the host reloads
pending reservations after uncertainty, refusal or recovery (ADR-0121).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-13 19:45:23 -04:00
co-authored by Claude Opus 5.5
parent 1bbac48543
commit f59c8498b1
14 changed files with 583 additions and 12 deletions
+12
View File
@@ -94,6 +94,18 @@ class CellularBridge {
std::uint64_t generation, std::uint64_t request) {
return host.query_primitive_life(account.bytes, generation, request);
};
config.select_cellular_mutation = [&host](const network::AccountId& account,
std::uint64_t generation,
const network::CellularMutationAction& m) {
const auto reply =
host.select_mutation(account.bytes, generation, m.action_id,
{m.life_identity, m.event_index, m.offer_tick, m.operator_id});
server::CellularMutationAnswer answer{
server::admit_status(reply.status), reply.tick, {}};
if (reply.outcome)
answer.outcome = server::action_outcome(*reply.outcome);
return answer;
};
auto sessions = server::RegionSessions::create(std::move(config));
if (!sessions)
return fail(sessions.error() == server::RegionSessionsError::transport
+13 -2
View File
@@ -952,6 +952,15 @@ int serve_cellular(Options& o) {
bridge->committed(committed, finalized.commit_sequence);
awaiting_outcomes.erase(pending);
}
for (const auto& mutation : host.take_finalized_mutations()) {
network::AccountId account;
account.bytes = mutation.account;
std::printf("mutation committed tick=%llu result=%u\n",
static_cast<unsigned long long>(mutation.tick),
static_cast<unsigned>(mutation.result));
static_cast<void>(bridge->sessions().send_mutation_outcome(
account, server::action_outcome(mutation)));
}
};
const auto finish = [&](int code) {
set_ready(false);
@@ -1051,13 +1060,15 @@ int serve_cellular(Options& o) {
if (!builder) {
bridge->dropped(actions, true);
} else {
const auto appended = builder->append(tick, baseline, actions, held_births);
const auto appended = builder->append(tick, baseline, actions, held_births,
host.queued_mutations());
if (!appended) {
bridge->dropped(actions, true);
} else {
awaiting_outcomes.insert(awaiting_outcomes.end(), actions.begin(),
actions.end());
auto published = host.publish(builder->batch(), builder->actions());
auto published = host.publish(builder->batch(), builder->actions(),
builder->mutation_actions());
if (!published && host.status().phase != server::HostPhase::resolving) {
bridge->dropped(actions, true);
std::erase_if(awaiting_outcomes, [&](const auto& action) {
@@ -93,3 +93,34 @@ crash/retry tests. The biology generator and funded-transition APIs remain pure.
Candidate ranking, automatic mutation, new-life creation, and presentation
belong to no part of this contract. The operation is not player-accessible until
the later 11.4d client action and review UI are complete.
## Implementation notes
- 11.4c-1 (schema v35): a checkpoint whose trace carries selections publishes
only through `publish_cellular_mutation_checkpoint`, with the canonical
64-byte mutation block and one result byte per choice, taken from the
publisher's own replay. Recovery reloads the bound choices and requires the
replay's results to equal them.
- 11.4c-2 (host and session admission, 2026-10-13): the region host admits a
v10 `CellularMutationAction` only when it names the account's living cell,
its exact outstanding offer (event index and offer tick) and one of the
offered operators, checked against the committed state. It reserves the
successor for the next tick (head + 1), queues the reservation, and the
scheduler includes it in that tick's batch. Exact repeats are idempotent;
a second choice while one waits is refused as `too_many_unresolved`, and a
changed reuse of an action ID as `invalid_action`. The receipt names the
publishing tick; once published, the owner receives an `ActionOutcome`:
`committed` when applied, `committed_no_effect` for a durable refusal (life
died, insufficient funding). A repeat after publication returns the same
outcome (`duplicate`) while the host remembers it.
- A reserved choice must never be skipped: schema v35 also refuses any
checkpoint whose tick range contains an unbound reservation of the region
that the checkpoint does not carry. Without this, an uncertain reservation
(the reply was lost but the row committed) could pass its tick unpublished
and block its account's next choice forever. The host treats an uncertain
reservation, a refused publication or a recovery as "reload pending
reservations under the current lease before the next publication".
- The wire `tick` of the choice is the client's latest simulated tick (after
the offer); the server, not the client, chooses the publishing tick.
- Not yet done: replicating the offer's unranked candidates to the owner
(11.4d server half) and the client choice and review UI (maintainer).
+8 -1
View File
@@ -83,4 +83,11 @@ pending; no gameplay balance is treated as final by this plan.
the four-argument publisher now refuses traces with selections. C++
publication takes its results from its own replay, and recovery reloads the
bound choices and requires the replay's results to equal them. Host and
session admission (11.4c-2) remain.
session admission (11.4c-2) remain.
- 11.4c-2 (ADR-0121 implementation notes): the region host admits a v10 choice
of the exact outstanding offer, reserves it for the next tick and publishes
it with that tick; the owner receives the receipt and final outcome over the
session. SQL now refuses a checkpoint that skips a reserved choice, and the
host reloads pending reservations after uncertainty or restart. 11.4c is
complete once CI passes; 11.4d's server half (offer replication to the
owner) is next, and the choice UI stays with the maintainer.
+25 -1
View File
@@ -7293,4 +7293,28 @@ offer, reserves and publishes a choice, recovers it, and restarts a host.
Executed locally: MSVC Debug `ctest` 68/68; g++-14 `-Werror`, clang-tidy-19
and clang-format 19.1.5 on the persistence, batch, host and test sources. The
migration and PostgreSQL tests run only in CI.
migration and PostgreSQL tests run only in CI.
## 2026-10-13 — M11.4c-2 mutation choice admission (CI pending)
`CellularRegionHost::select_mutation` checks a v10 choice against the
committed offer, reserves it for head + 1 through `reserve_cellular_mutation`,
and queues it; `serve_cellular` passes the queue to the session batch builder
and publishes `mutation_actions()` with the batch; finalized choices go to the
owner's v10 session as `ActionOutcome`. Uncertain reservations, refused
publications and recovery reload pending reservations before the next publish.
`RegionSessions` dispatches `CellularMutationAction` to the new
`select_cellular_mutation` handler and adds `send_mutation_outcome`; the client
adds `send_cellular_mutation` (protocol only, no UI). Migration 35 gains
`cellular_mutations_due` and a `(world, region, target_tick)` index: both
publishers refuse a checkpoint that omits a reserved choice in its range.
Tests: `cellular_host_admits_mutation_choices` (PostgreSQL, world 9765) covers
invalid and stale choices, admission, an idempotent repeat, `busy`, reload
after a host restart, refusal of a checkpoint that skips the choice,
publication with its tick, the finalized outcome and its wire form, and the
final repeat. `quic-sessions` sends a v10 choice and receives the receipt and
outcome; a v7 session cannot send one.
Executed locally: MSVC Debug `ctest` 68/68; client-network QUIC/session 8/8;
g++-14 `-Werror`, clang-tidy-19 and clang-format 19.1.5 on the host, session,
server main and test sources. The PostgreSQL tests run only in CI.
+7
View File
@@ -66,6 +66,13 @@ class RegionSessionClient {
std::int16_t move_y,
std::optional<std::pair<std::uint32_t, std::uint32_t>> intake_target = {},
bool engulf = false);
// Protocol v10 (ADR-0121): choose one candidate of the life's outstanding offer. The
// receipt names the tick it publishes with; the outcome follows that commit. `tick` is
// the client's latest simulated tick (after the offer); the server schedules the next.
[[nodiscard]] bool send_cellular_mutation(std::uint64_t action_id, std::uint64_t tick,
std::uint64_t life_identity,
std::uint64_t event_index, std::uint64_t offer_tick,
std::uint16_t operator_id);
[[nodiscard]] bool query_action(std::uint64_t action_id);
// Primitive profile v5 only. The account and generation are always supplied by the
// authenticated session; callers choose only a stable request id.
+47 -1
View File
@@ -43,6 +43,31 @@ struct FinalCellularAction {
std::uint64_t commit_sequence{};
friend bool operator==(const FinalCellularAction&, const FinalCellularAction&) = default;
};
// v10 mutation choice admission (ADR-0121). `admitted` means the successor identity is
// durably reserved for `tick`, the next simulated tick; the choice publishes with it.
enum class CellularMutationAdmission : std::uint8_t {
admitted,
not_ready, // No current authority, or an uncertain reservation is being reconciled.
invalid, // Not this account's life, or not its outstanding offer and candidate.
busy, // Another choice of this account is still waiting for its tick.
final, // This action already published; `outcome` repeats its result.
conflict // The action id was used for different bytes or an earlier tick.
};
struct FinalCellularMutation {
persistence::Uuid account{};
std::uint64_t action_id{}, tick{}, commit_sequence{};
CellularMutationResult result{};
friend bool operator==(const FinalCellularMutation&, const FinalCellularMutation&) = default;
};
struct CellularMutationReply {
CellularMutationAdmission status{};
std::uint64_t tick{};
std::optional<FinalCellularMutation> outcome;
};
// The wire forms (v10): an applied choice is `committed`; a durable refusal (life died,
// insufficient funding) is `committed_no_effect`, and the owner's view shows the cell.
[[nodiscard]] network::AdmitStatus admit_status(CellularMutationAdmission admission) noexcept;
[[nodiscard]] network::ActionOutcome action_outcome(const FinalCellularMutation& mutation) noexcept;
// Single-writer profile-4 authority. The caller supplies a complete bounded trace;
// the host replays it from its recovered state and advances only on a confirmed head.
@@ -58,7 +83,20 @@ class CellularRegionHost {
// Acquires/renews authority, recovers fully, or resolves the exact pending commit.
const HostStatus& step();
[[nodiscard]] std::expected<persistence::PublishedCellularBatch, CellularPublishFailure>
publish(const CellularBatch& batch, std::span<const CellularActionRecord> actions = {});
publish(const CellularBatch& batch, std::span<const CellularActionRecord> actions = {},
std::span<const CellularMutationActionRecord> mutation_actions = {});
// Revalidates the exact outstanding offer and candidate against the committed state,
// then reserves the successor for the next tick. Exact repeats are idempotent.
[[nodiscard]] CellularMutationReply select_mutation(const persistence::Uuid& account,
std::uint64_t generation,
std::uint64_t action_id,
const CellularMutationActionInput& input);
// Reserved choices for the next tick, in reservation order; pass them to the builder.
[[nodiscard]] std::span<const persistence::CellularMutationReservation>
queued_mutations() const noexcept {
return queued_mutations_;
}
[[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.
[[nodiscard]] network::PrimitiveLifeOutcome
@@ -95,6 +133,9 @@ class CellularRegionHost {
void refresh();
void finalize_births(std::span<const CellularTickIntents::Birth> births);
void queue_birth(const CellularTickIntents::Birth& birth);
void reload_mutations();
void finalize_mutations(std::span<const CellularMutationActionRecord> actions,
std::span<const std::uint8_t> results);
[[nodiscard]] network::PrimitiveLifeOutcome query_birth(const persistence::Uuid& account,
std::uint64_t generation,
std::uint64_t request, bool enqueue);
@@ -109,6 +150,11 @@ class CellularRegionHost {
std::unique_ptr<Pending> pending_;
std::vector<FinalCellularAction> finalized_actions_;
std::vector<CellularTickIntents::Birth> queued_births_;
std::vector<persistence::CellularMutationReservation> queued_mutations_;
// A reservation may exist that the queue does not show; reload before publishing.
bool mutations_uncertain_{};
std::vector<FinalCellularMutation> finalized_mutations_;
std::vector<FinalCellularMutation> recent_mutations_; // Bounded, for exact repeats.
HostStatus status_{};
};
} // namespace evo::server
+15
View File
@@ -64,6 +64,13 @@ struct HandoffKey {
struct LifeOwnerRoute {
network::RegionAddress address;
};
// A host's answer to one v10 choice: the receipt status and target tick, plus the final
// outcome when the same action already published.
struct CellularMutationAnswer {
network::AdmitStatus status{};
std::uint64_t tick{};
std::optional<network::ActionOutcome> outcome;
};
struct RegionSessionsConfig {
network::quic::ServerConfig transport;
network::ControlConfig control; // `epoch` is the initial ownership epoch.
@@ -115,6 +122,11 @@ struct RegionSessionsConfig {
// M11.3 v7 durable cellular actions and v8/v9 owner-filtered perception. Requires durable
// control and action ledgers; the caller forwards carried inputs to profile 4.
bool accept_cellular_actions{};
// M11.4c v10 mutation choices (ADR-0121), answered with an ActionReceipt and, once
// published, an ActionOutcome. Without a handler a v10 choice closes as a protocol error.
std::function<CellularMutationAnswer(const network::AccountId&, std::uint64_t,
const network::CellularMutationAction&)>
select_cellular_mutation;
};
// The region host's authority, read once per poll.
struct HostFacts {
@@ -168,6 +180,9 @@ class RegionSessions {
[[nodiscard]] bool send_cellular_perception(const network::AccountId& account,
const network::CellularPerception& perception);
void clear_cellular_perceptions(std::uint64_t tick);
// A published v10 choice's outcome, to the account's current v10 session if any.
[[nodiscard]] bool send_mutation_outcome(const network::AccountId& account,
const network::ActionOutcome& outcome);
[[nodiscard]] network::ReplicationStats replication_stats() const;
// M10.9a (ADR-0097): the host's load governor output. While `refuse_logins`, a Hello
// carrying a grant is closed with `capacity` before signature work (handoff tickets are
@@ -203,6 +203,24 @@ BEGIN
RETURN n;
END $$;
-- Choices of this region reserved for a tick in (begin, end] and not bound to another
-- commit. A checkpoint must carry every one of them: a reserved choice that a later
-- checkpoint skipped could never publish and would block its account's next choice.
CREATE INDEX cellular_mutation_reservations_by_tick
ON evolution.cellular_mutation_reservations(world_id, region_id, target_tick);
CREATE FUNCTION evolution.cellular_mutations_due(p_manifest bytea)
RETURNS integer LANGUAGE plpgsql STABLE SECURITY INVOKER
SET search_path = pg_catalog, pg_temp AS $$
DECLARE c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
BEGIN
RETURN (SELECT count(*) FROM evolution.cellular_mutation_reservations r
WHERE r.world_id = c.world_id AND r.region_id = c.region_id
AND r.target_tick > c.begin_tick AND r.target_tick <= c.end_tick
AND NOT EXISTS (SELECT 1 FROM evolution.cellular_mutation_action_publications p
WHERE p.world_id = r.world_id AND p.account_id = r.account_id
AND p.action_id = r.action_id AND p.commit_id <> c.commit_id));
END $$;
-- True when this commit already bound exactly these actions with these results.
CREATE FUNCTION evolution.cellular_mutation_publications_match(p_world evolution.u64,
p_commit uuid, p_mutations bytea, p_results bytea)
@@ -242,6 +260,11 @@ BEGIN
IF EXISTS (SELECT 1 FROM evolution.cellular_mutation_selections(p_trace, p_manifest)) THEN
RAISE EXCEPTION 'cellular mutation selections need their action block' USING ERRCODE = '22023';
END IF;
IF NOT EXISTS (SELECT 1 FROM evolution.region_commits x
WHERE x.commit_id = (evolution.parse_checkpoint_manifest(p_manifest)).commit_id)
AND evolution.cellular_mutations_due(p_manifest) <> 0 THEN
RAISE EXCEPTION 'cellular checkpoint omits a reserved mutation' USING ERRCODE = '22023';
END IF;
RETURN QUERY SELECT * FROM evolution.publish_cellular_birth_checkpoint(
p_manifest, p_decisions, p_actions, p_trace);
END $$;
@@ -270,6 +293,9 @@ BEGIN
p_manifest, p_decisions, p_actions, p_trace);
RETURN;
END IF;
IF evolution.cellular_mutations_due(p_manifest) <> n THEN
RAISE EXCEPTION 'cellular checkpoint omits a reserved mutation' USING ERRCODE = '22023';
END IF;
-- A choice binds to one commit only; another commit's binding is a reused identity.
FOR i IN 0 .. n - 1 LOOP
IF EXISTS (SELECT 1 FROM evolution.cellular_mutation_action_publications p
@@ -342,6 +368,7 @@ BEGIN
END $$;
REVOKE ALL ON FUNCTION evolution.cellular_mutation_selections(bytea, bytea),
evolution.cellular_mutations_due(bytea),
evolution.check_cellular_mutation_block(bytea, bytea, bytea, bytea),
evolution.cellular_mutation_publications_match(evolution.u64, uuid, bytea, bytea),
evolution.publish_cellular_checkpoint(bytea, bytea, bytea, bytea),
+14
View File
@@ -289,6 +289,20 @@ bool RegionSessionClient::send_cellular_action(
intake_target ? intake_target->second : 0, engulf});
}
bool RegionSessionClient::send_cellular_mutation(std::uint64_t action_id, std::uint64_t tick,
std::uint64_t life_identity,
std::uint64_t event_index,
std::uint64_t offer_tick,
std::uint16_t operator_id) {
auto& m = *impl_;
return m.protocol_version == network::session_protocol_v10 &&
m.state == RegionSessionState::established && m.welcome && action_id != 0 &&
offer_tick != 0 && tick > offer_tick &&
m.send(network::CellularMutationAction{m.welcome->session, m.welcome->epoch, action_id,
tick, life_identity, event_index, offer_tick,
operator_id});
}
bool RegionSessionClient::query_action(std::uint64_t action_id) {
auto& m = *impl_;
return (m.protocol_version == network::session_protocol_version ||
+172 -7
View File
@@ -14,6 +14,7 @@ struct CellularRegionHost::Pending {
std::unique_ptr<CellularLives> candidate;
std::vector<CellularActionRecord> actions;
std::vector<CellularTickIntents::Birth> births;
std::vector<CellularMutationActionRecord> mutation_actions;
};
namespace {
@@ -76,6 +77,31 @@ std::optional<persistence::Uuid> commit_id(const persistence::CommittedCheckpoin
}
} // namespace
network::AdmitStatus admit_status(CellularMutationAdmission admission) noexcept {
switch (admission) {
case CellularMutationAdmission::admitted:
return network::AdmitStatus::admitted;
case CellularMutationAdmission::not_ready:
return network::AdmitStatus::not_ready;
case CellularMutationAdmission::busy:
return network::AdmitStatus::too_many_unresolved;
case CellularMutationAdmission::final:
return network::AdmitStatus::duplicate;
case CellularMutationAdmission::invalid:
case CellularMutationAdmission::conflict:
break;
}
return network::AdmitStatus::invalid_action;
}
network::ActionOutcome action_outcome(const FinalCellularMutation& mutation) noexcept {
return {mutation.action_id,
mutation.result == CellularMutationResult::applied
? network::ActionResult::committed
: network::ActionResult::committed_no_effect,
mutation.tick, mutation.commit_sequence};
}
CellularRegionHost::CellularRegionHost(CellularHostConfig config, CellularConnect connect,
std::unique_ptr<persistence::FilesystemObjectStore> objects)
: config_{std::move(config)}, connect_{std::move(connect)}, objects_{std::move(objects)},
@@ -139,6 +165,8 @@ void CellularRegionHost::acquire() {
}
state_ = std::move(recovered->state);
committed_ = std::move(recovered->committed);
queued_mutations_.clear();
mutations_uncertain_ = true; // Reserved choices are reloaded under the new lease.
status_.phase = HostPhase::running;
status_.simulated_tick = committed_->head.end_tick;
status_.committed_tick = committed_->head.end_tick;
@@ -261,6 +289,7 @@ void CellularRegionHost::resolve() {
for (const auto& action : pending_->actions)
finalized_actions_.push_back({action, committed_->head.sequence});
finalize_births(pending_->births);
finalize_mutations(pending_->mutation_actions, pending_->prepared.results);
pending_.reset();
++status_.commits;
status_.committed_sequence = committed_->head.sequence;
@@ -290,15 +319,142 @@ const HostStatus& CellularRegionHost::step() {
resolve();
else if (!state_)
acquire();
if (!pending_ && state_ && mutations_uncertain_ && status_.phase == HostPhase::running)
reload_mutations();
refresh();
return status_;
}
void CellularRegionHost::reload_mutations() {
const auto grant = authority_.grant();
if (!grant || !committed_ || !database())
return;
auto pending = persistence::load_pending_cellular_mutations(*db_, config_.key, *grant,
config_.lease.commit_timeout);
if (!pending) {
if (pending.error().kind == persistence::LifeReservationError::fenced) {
authority_.fence();
status_.ready = false;
}
db_.reset();
++status_.store_failures;
return;
}
// Every reservation targets the tick after the head it was made at, and SQL refuses a
// checkpoint that skips one, so an unbound choice is always for the next tick.
queued_mutations_.clear();
for (const auto& reservation : *pending)
if (reservation.target_tick == committed_->head.end_tick + 1)
queued_mutations_.push_back(reservation);
mutations_uncertain_ = false;
}
void CellularRegionHost::finalize_mutations(std::span<const CellularMutationActionRecord> actions,
std::span<const std::uint8_t> results) {
if (!committed_)
return;
const auto sequence = committed_->head.sequence;
for (std::size_t i = 0; i < actions.size() && i < results.size(); ++i) {
const auto& action = actions[i];
std::erase_if(queued_mutations_, [&](const auto& queued) {
return queued.account == action.account && queued.action_id == action.action_id;
});
const FinalCellularMutation done{action.account, action.action_id, action.tick, sequence,
static_cast<CellularMutationResult>(results[i])};
finalized_mutations_.push_back(done);
std::erase_if(recent_mutations_,
[&](const auto& recent) { return recent.account == done.account; });
if (recent_mutations_.size() >= 1024)
recent_mutations_.erase(recent_mutations_.begin());
recent_mutations_.push_back(done);
}
}
std::vector<FinalCellularMutation> CellularRegionHost::take_finalized_mutations() {
return std::exchange(finalized_mutations_, {});
}
CellularMutationReply
CellularRegionHost::select_mutation(const persistence::Uuid& account, std::uint64_t generation,
std::uint64_t action_id,
const CellularMutationActionInput& input) {
using enum CellularMutationAdmission;
if (account == persistence::Uuid{} || generation == 0 || action_id == 0)
return {invalid, 0, {}};
if (const auto recent = std::ranges::find_if(recent_mutations_,
[&](const auto& done) {
return done.account == account &&
done.action_id == action_id;
});
recent != recent_mutations_.end())
return {final, recent->tick, *recent};
if (!status_.ready || mutations_uncertain_ || pending_ || !state_ || !committed_ ||
!authority_.may_begin_commit(LeaseClock::now()) || !database())
return {not_ready, 0, {}};
const auto tick = committed_->head.end_tick + 1;
const CellularMutationActionRecord record{account, action_id, tick, input};
const auto bytes = encode_cellular_mutation_input(record);
for (const auto& queued : queued_mutations_) {
if (queued.account != account)
continue;
if (queued.action_id != action_id)
return {busy, queued.target_tick, {}};
return queued.input == bytes ? CellularMutationReply{admitted, tick, {}}
: CellularMutationReply{conflict, 0, {}};
}
// The choice must name this account's living cell and its exact outstanding offer.
const auto life = std::ranges::find(state_->lives(), account, &CellularOwnedLife::account);
if (life == state_->lives().end() || life->identity.life != input.life_id ||
input.event_index == 0 || life->mutation.event_index != input.event_index ||
life->mutation.offer_tick != input.offer_tick || input.offer_tick >= tick)
return {invalid, 0, {}};
const auto& offer = life->mutation.offer;
if (!offer || !std::ranges::any_of(offer->candidates, [&](const auto& candidate) {
return candidate.operator_id == input.operator_id;
}))
return {invalid, 0, {}};
const auto grant = authority_.grant();
if (!grant)
return {not_ready, 0, {}};
auto reserved =
persistence::reserve_cellular_mutation(*db_, config_.key, *grant, account, generation,
action_id, bytes, config_.lease.commit_timeout);
if (!reserved) {
switch (reserved.error().kind) {
case persistence::LifeReservationError::pending_mutation:
return {busy, 0, {}};
case persistence::LifeReservationError::identity_conflict:
return {conflict, 0, {}};
case persistence::LifeReservationError::fenced:
authority_.fence();
status_.ready = false;
return {not_ready, 0, {}};
case persistence::LifeReservationError::unknown:
case persistence::LifeReservationError::store:
// The reservation may have committed: nothing publishes until it is reloaded.
mutations_uncertain_ = true;
db_.reset();
++status_.store_failures;
return {not_ready, 0, {}};
default:
return {invalid, 0, {}};
}
}
if (reserved->region != config_.key.region || reserved->target_tick != tick ||
reserved->input != bytes) {
mutations_uncertain_ = true;
return {not_ready, 0, {}};
}
queued_mutations_.push_back(*reserved);
return {admitted, tick, {}};
}
std::expected<persistence::PublishedCellularBatch, CellularPublishFailure>
CellularRegionHost::publish(const CellularBatch& batch,
std::span<const CellularActionRecord> actions) {
std::span<const CellularActionRecord> actions,
std::span<const CellularMutationActionRecord> mutation_actions) {
const auto grant = authority_.grant();
if (!status_.ready || !state_ || !committed_ || !grant ||
if (!status_.ready || mutations_uncertain_ || !state_ || !committed_ || !grant ||
!authority_.may_begin_commit(LeaseClock::now()))
return std::unexpected{CellularPublishFailure{CellularHostError::not_ready, {}, {}, {}}};
auto candidate = replay_cellular_batch(*state_, batch);
@@ -315,13 +471,15 @@ CellularRegionHost::publish(const CellularBatch& batch,
CellularPublishFailure{CellularHostError::invalid_batch, {}, {}, {}}};
auto published = persistence::publish_cellular_batch(
*db_, *objects_, grant.value_or(persistence::LeaseGrant{}), *committed_, batch, **candidate,
*commit, config_.build, config_.lease.commit_timeout, {}, actions);
*commit, config_.build, config_.lease.commit_timeout, {}, actions, mutation_actions);
if (!published) {
if (published.error().kind == persistence::PublicationError::unknown) {
pending_ = std::make_unique<Pending>(Pending{published.error().prepared,
std::move(*candidate),
{actions.begin(), actions.end()},
births_in(batch)});
pending_ = std::make_unique<Pending>(
Pending{published.error().prepared,
std::move(*candidate),
{actions.begin(), actions.end()},
births_in(batch),
{mutation_actions.begin(), mutation_actions.end()}});
status_.phase = HostPhase::resolving;
status_.ready = false;
++status_.unknown_outcomes;
@@ -333,6 +491,8 @@ CellularRegionHost::publish(const CellularBatch& batch,
status_.phase = HostPhase::acquiring;
status_.ready = false;
++status_.fences;
} else {
mutations_uncertain_ = true; // A refusal may name a choice the queue lacks.
}
return std::unexpected{
CellularPublishFailure{CellularHostError::publication, published.error().kind,
@@ -344,6 +504,11 @@ CellularRegionHost::publish(const CellularBatch& batch,
finalized_actions_.push_back({action, committed_->head.sequence});
const auto births = births_in(batch);
finalize_births(births);
std::vector<std::uint8_t> results;
results.reserve(published->mutation_results.size());
for (const auto result : published->mutation_results)
results.push_back(static_cast<std::uint8_t>(result));
finalize_mutations(mutation_actions, results);
++status_.commits;
status_.committed_sequence = committed_->head.sequence;
status_.committed_tick = committed_->head.end_tick;
+33
View File
@@ -638,6 +638,26 @@ struct RegionSessions::Impl {
answer(c, *receipt);
return;
}
if (const auto* m = std::get_if<network::CellularMutationAction>(&*decoded)) {
if (c.protocol_version != network::session_protocol_v10 ||
!config.select_cellular_mutation)
return close(c, SessionCloseReason::protocol, now);
CellularMutationAnswer answer{
m->session != c.session ? network::AdmitStatus::unknown_session
: m->epoch != control.epoch() ? network::AdmitStatus::stale_epoch
: m->action_id == 0 ? network::AdmitStatus::invalid_action
: !facts.ready || c.generation == 0 ? network::AdmitStatus::not_ready
: network::AdmitStatus::admitted,
0,
{}};
if (answer.status == network::AdmitStatus::admitted)
answer = config.select_cellular_mutation(c.account_id, c.generation, *m);
send(c, network::ActionReceipt{m->action_id, answer.status, facts.simulated_tick,
answer.tick});
if (answer.outcome)
send(c, *answer.outcome);
return;
}
if (const auto* m = std::get_if<network::ActionQuery>(&*decoded)) {
if (c.protocol_version == network::session_protocol_v5 ||
c.protocol_version == network::session_protocol_v6)
@@ -915,6 +935,19 @@ bool RegionSessions::send_cellular_perception(const network::AccountId& account,
return false;
}
bool RegionSessions::send_mutation_outcome(const network::AccountId& account,
const network::ActionOutcome& outcome) {
auto& m = *impl_;
for (const auto& c : m.connections) {
if (c.state != Impl::State::established ||
c.protocol_version != network::session_protocol_v10 || c.account_id != account)
continue;
return m.endpoint->send_message(c.id, network::encode_session(outcome, c.protocol_version))
.has_value();
}
return false;
}
void RegionSessions::clear_cellular_perceptions(std::uint64_t tick) {
if (tick == 0)
return;
+157
View File
@@ -463,12 +463,169 @@ void cellular_mutation_publication_binds_results() {
CHECK(restarted->step().ready && restarted->state()->snapshot() == (*candidate)->snapshot());
restarted->drain();
}
// ADR-0121 11.4c-2: the host admits an exact choice of the outstanding offer, reserves it for
// the next tick, keeps it across a restart, refuses a checkpoint that skips it, publishes it
// with that tick and answers a repeat with the final outcome.
void cellular_host_admits_mutation_choices() {
using namespace evo::biology;
constexpr RegionKey key{9765, 1};
auto owner = connect_as(env("PGUSER"));
auto runtime = connect_as(env("EVO_PG_RUNTIME_USER"));
const auto build = filled<32>(0xDA);
CHECK(owner->query("INSERT INTO evolution.retained_builds(build_identity) VALUES "
"(decode(repeat('da',32),'hex')) ON CONFLICT DO NOTHING",
{}, 5s));
auto endowed = primitive_endowment();
CHECK(endowed);
auto funding = endowed->body;
funding.energy.value = endowed->reserve.energy.value + endowed->construction.value;
auto primitive = PrimitiveLives::create({key.world, key.region, 1, 17, funding, {{0, 0}}});
CHECK(primitive);
constexpr std::uint64_t stock = 100'000'000;
auto habitat = CellularHabitat::create(
{key.world,
key.region,
1,
1'000,
1'000,
{{{0, 0}, 29, {{stock}, {{{stock}, {stock}, {stock}, {stock}}}}}}});
CHECK(habitat);
auto opening =
CellularLives::create(**primitive, std::move(*habitat), {{1'000, 1'000}, 0, 293'150},
CellularLivesProfile::engulf);
CHECK(opening);
auto objects = FilesystemObjectStore::open(env("PGHOST"), key, max_cellular_lives_bytes);
CHECK(objects);
CHECK(provision_cellular_region(*owner, **objects, key, 1, **opening, filled<16>(0x70), build,
5s));
CHECK(owner->query("INSERT INTO evolution.life_allocators VALUES(9765,1000) "
"ON CONFLICT DO NOTHING",
{}, 5s));
const auto connect = [&]() -> std::expected<std::unique_ptr<Postgres>, PgFailure> {
return Postgres::connect({env("PGHOST"),
{},
env("PGPORT"),
env("PGDATABASE"),
env("EVO_PG_RUNTIME_USER"),
{},
{}},
5s);
};
CellularHostConfig config{key, 1, {}, build, {build}};
auto made = CellularRegionHost::create(config, connect, std::move(*objects));
CHECK(made);
auto host = std::move(*made);
CHECK(host->step().ready);
const auto account = filled<16>(0x74);
const auto control = claim_account_control(*runtime, key, checked_value(host->authority()),
account, 1, 1, 60'000ms, 5s);
CHECK(control);
CHECK(host->create_primitive_life(account, control->generation, 11).result ==
evo::network::PrimitiveLifeResult::pending);
const auto header = [&](const CellularRegionHost& at, std::uint64_t ticks) {
const auto& committed = checked_value(at.committed());
const auto digest = sha256(committed.manifest);
CHECK(digest);
return CellularBatchHeader{key.world,
key.region,
1,
committed.head.commit,
checked_value(digest),
at.state()->tick(),
at.state()->tick() + ticks};
};
CellularBatch birth;
birth.header = header(*host, 1);
birth.ticks.push_back({{}, {host->queued_births().front()}, {}});
CHECK(host->publish(birth));
const auto life_id = host->state()->lives().front().identity.life;
for (int round = 0; round < 4 && !host->state()->lives().front().mutation.offer; ++round) {
CHECK(host->step().ready);
CellularBatch feeding;
feeding.header = header(*host, 64);
CellularStepIntent feed{};
feed.intake_target = CellularPatchAddress{0, 0};
for (int tick = 0; tick < 64; ++tick)
feeding.ticks.push_back({{{life_id, feed}}, {}, {}});
CHECK(host->publish(feeding));
}
const auto& life = host->state()->lives().front();
const auto offer = checked_value(life.mutation.offer);
const CellularMutationActionInput choice{life_id, life.mutation.event_index,
life.mutation.offer_tick,
offer.candidates.front().operator_id};
const auto next = host->state()->tick() + 1;
auto wrong = choice;
wrong.operator_id = 0xFFFF;
CHECK(host->select_mutation(account, control->generation, 31, wrong).status ==
CellularMutationAdmission::invalid);
auto stale = choice;
++stale.event_index;
CHECK(host->select_mutation(account, control->generation, 31, stale).status ==
CellularMutationAdmission::invalid);
const auto admitted = host->select_mutation(account, control->generation, 31, choice);
CHECK(admitted.status == CellularMutationAdmission::admitted && admitted.tick == next);
const auto repeated = host->select_mutation(account, control->generation, 31, choice);
CHECK(repeated.status == CellularMutationAdmission::admitted && repeated.tick == next);
CHECK(host->select_mutation(account, control->generation, 32, choice).status ==
CellularMutationAdmission::busy);
CHECK(host->queued_mutations().size() == 1);
const auto reservation = host->queued_mutations().front();
// A restarted host reloads the reserved choice for the same next tick.
host->drain();
host.reset();
auto reopened = FilesystemObjectStore::open(env("PGHOST"), key, max_cellular_lives_bytes);
CHECK(reopened);
auto restarted_made = CellularRegionHost::create(config, connect, std::move(*reopened));
CHECK(restarted_made);
host = std::move(*restarted_made);
CHECK(host->step().ready && host->state()->tick() + 1 == next);
CHECK(host->queued_mutations().size() == 1 && host->queued_mutations().front() == reservation);
// A checkpoint for that tick without the choice is refused; the queue survives it.
CellularBatch skipped;
skipped.header = header(*host, 1);
skipped.ticks.push_back({{{life_id, {}}}, {}, {}});
CHECK(!host->publish(skipped));
CHECK(host->step().ready && host->queued_mutations().size() == 1);
CellularBatch chosen;
chosen.header = header(*host, 1);
chosen.ticks.push_back({{{life_id, {}}},
{},
{{life_id, choice.event_index, choice.offer_tick,
reservation.successor_identity, choice.operator_id}}});
const std::array records{CellularMutationActionRecord{account, 31, next, choice}};
const auto published = host->publish(chosen, {}, records);
CHECK(published && published->mutation_results.size() == 1);
CHECK(host->queued_mutations().empty());
const auto finalized = host->take_finalized_mutations();
CHECK(finalized.size() == 1 && finalized.front().account == account &&
finalized.front().action_id == 31 && finalized.front().tick == next &&
finalized.front().result == published->mutation_results.front() &&
finalized.front().commit_sequence == published->committed.head.sequence);
const auto outcome = action_outcome(finalized.front());
CHECK(outcome.action_id == 31 && outcome.tick == next &&
outcome.result == (finalized.front().result == CellularMutationResult::applied
? evo::network::ActionResult::committed
: evo::network::ActionResult::committed_no_effect));
// A repeat after publication answers with the same final outcome.
const auto final_repeat = host->select_mutation(account, control->generation, 31, choice);
CHECK(final_repeat.status == CellularMutationAdmission::final && final_repeat.outcome &&
*final_repeat.outcome == finalized.front());
CHECK(admit_status(final_repeat.status) == evo::network::AdmitStatus::duplicate);
host->drain();
}
} // namespace
void run_cellular_publication_tests() {
cellular_birth_publication_is_durable();
cellular_profile_migration_is_durable_and_recovers_without_a_tick();
cellular_mutation_publication_binds_results();
cellular_host_admits_mutation_choices();
auto owner = connect_as(env("PGUSER"));
const auto build = filled<32>(0xD9);
CHECK(owner->query("INSERT INTO evolution.retained_builds(build_identity) VALUES "
+22
View File
@@ -651,6 +651,12 @@ void cellular_v5_spawn_and_v7_action_share_region_sessions(const Files& f) {
c.query_primitive_life = [](const AccountId&, std::uint64_t, std::uint64_t request) {
return PrimitiveLifeOutcome{request, PrimitiveLifeResult::pending, 0, 0};
};
c.select_cellular_mutation = [](const AccountId& a, std::uint64_t generation,
const CellularMutationAction& m) {
return a == account(0xBB) && generation != 0 && m.event_index == 1
? server::CellularMutationAnswer{AdmitStatus::admitted, 103, {}}
: server::CellularMutationAnswer{AdmitStatus::invalid_action, 0, {}};
};
}};
auto spawn_client = h.connect(h.issuer.grant(account(0xB5), 1), session_protocol_v5);
auto action_client = h.connect(h.issuer.grant(account(0xB7), 1), session_protocol_v7);
@@ -699,6 +705,22 @@ void cellular_v5_spawn_and_v7_action_share_region_sessions(const Files& f) {
engulfing.front().cellular_input ==
std::optional{encode_cellular_action_input({102, 0, 0, false, 0, 0, true})});
// ADR-0121: a v10 mutation choice reaches the host with the session's account and
// generation; its receipt names the publishing tick and the outcome follows the commit.
CHECK(!action_client->send_cellular_mutation(77, 102, 901, 1, 90, 3));
CHECK(engulf_client->send_cellular_mutation(77, 102, 901, 1, 90, 3));
CHECK(h.until([&] { return !(receipts = engulf_client->take_action_receipts()).empty(); }));
CHECK(receipts.front() ==
ActionReceipt{77, AdmitStatus::admitted, receipts.front().server_tick, 103});
CHECK(engulf_client->send_cellular_mutation(78, 102, 901, 2, 90, 3));
CHECK(h.until([&] { return !(receipts = engulf_client->take_action_receipts()).empty(); }));
CHECK(receipts.front().status == AdmitStatus::invalid_action);
CHECK(h.server->send_mutation_outcome(account(0xBB), {77, ActionResult::committed, 103, 9}));
std::vector<ActionOutcome> outcomes;
CHECK(h.until([&] { return !(outcomes = engulf_client->take_action_outcomes()).empty(); }));
CHECK(outcomes.front() == ActionOutcome{77, ActionResult::committed, 103, 9});
CHECK(!h.server->send_mutation_outcome(account(0xB7), {55, ActionResult::committed, 103, 9}));
h.server->set_default_interest({0, 0, 0, 7});
h.source = [](const SessionInterest&) {
ReplicationSource source;