diff --git a/apps/evo-server/cellular_bridge.hpp b/apps/evo-server/cellular_bridge.hpp index 1cd8566..2cea7d8 100644 --- a/apps/evo-server/cellular_bridge.hpp +++ b/apps/evo-server/cellular_bridge.hpp @@ -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 diff --git a/apps/evo-server/main.cpp b/apps/evo-server/main.cpp index 35cb756..e1f17f2 100644 --- a/apps/evo-server/main.cpp +++ b/apps/evo-server/main.cpp @@ -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(mutation.tick), + static_cast(mutation.result)); + static_cast(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) { diff --git a/docs/adr/0121-durable-cellular-mutation-selection.md b/docs/adr/0121-durable-cellular-mutation-selection.md index 6f2b3d9..2e93f56 100644 --- a/docs/adr/0121-durable-cellular-mutation-selection.md +++ b/docs/adr/0121-durable-cellular-mutation-selection.md @@ -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). diff --git a/docs/engineering/M11_4_DELIVERY_PLAN.md b/docs/engineering/M11_4_DELIVERY_PLAN.md index 0875dbb..7db3928 100644 --- a/docs/engineering/M11_4_DELIVERY_PLAN.md +++ b/docs/engineering/M11_4_DELIVERY_PLAN.md @@ -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. \ No newline at end of file + 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. \ No newline at end of file diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 35f714d..76d1acc 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -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. \ No newline at end of file +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. diff --git a/include/evo/client/region_session.hpp b/include/evo/client/region_session.hpp index dbe90a6..5297499 100644 --- a/include/evo/client/region_session.hpp +++ b/include/evo/client/region_session.hpp @@ -66,6 +66,13 @@ class RegionSessionClient { std::int16_t move_y, std::optional> 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. diff --git a/include/evo/server/cellular_region_host.hpp b/include/evo/server/cellular_region_host.hpp index e03ff7b..cd78ff2 100644 --- a/include/evo/server/cellular_region_host.hpp +++ b/include/evo/server/cellular_region_host.hpp @@ -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 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 - publish(const CellularBatch& batch, std::span actions = {}); + publish(const CellularBatch& batch, std::span actions = {}, + std::span 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 + queued_mutations() const noexcept { + return queued_mutations_; + } + [[nodiscard]] std::vector 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 births); void queue_birth(const CellularTickIntents::Birth& birth); + void reload_mutations(); + void finalize_mutations(std::span actions, + std::span 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_; std::vector finalized_actions_; std::vector queued_births_; + std::vector queued_mutations_; + // A reservation may exist that the queue does not show; reload before publishing. + bool mutations_uncertain_{}; + std::vector finalized_mutations_; + std::vector recent_mutations_; // Bounded, for exact repeats. HostStatus status_{}; }; } // namespace evo::server diff --git a/include/evo/server/region_sessions.hpp b/include/evo/server/region_sessions.hpp index 6016894..d1fa85e 100644 --- a/include/evo/server/region_sessions.hpp +++ b/include/evo/server/region_sessions.hpp @@ -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 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 + 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 diff --git a/migrations/0035_cellular_mutation_publication.sql b/migrations/0035_cellular_mutation_publication.sql index cadf87a..1abf90b 100644 --- a/migrations/0035_cellular_mutation_publication.sql +++ b/migrations/0035_cellular_mutation_publication.sql @@ -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), diff --git a/src/client/session/region_session.cpp b/src/client/session/region_session.cpp index 991bf8a..3a5f0e8 100644 --- a/src/client/session/region_session.cpp +++ b/src/client/session/region_session.cpp @@ -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 || diff --git a/src/server/cellular_region_host.cpp b/src/server/cellular_region_host.cpp index 205210e..d8c25fd 100644 --- a/src/server/cellular_region_host.cpp +++ b/src/server/cellular_region_host.cpp @@ -14,6 +14,7 @@ struct CellularRegionHost::Pending { std::unique_ptr candidate; std::vector actions; std::vector births; + std::vector mutation_actions; }; namespace { @@ -76,6 +77,31 @@ std::optional 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 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 actions, + std::span 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(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 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 CellularRegionHost::publish(const CellularBatch& batch, - std::span actions) { + std::span actions, + std::span 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{published.error().prepared, - std::move(*candidate), - {actions.begin(), actions.end()}, - births_in(batch)}); + pending_ = std::make_unique( + 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 results; + results.reserve(published->mutation_results.size()); + for (const auto result : published->mutation_results) + results.push_back(static_cast(result)); + finalize_mutations(mutation_actions, results); ++status_.commits; status_.committed_sequence = committed_->head.sequence; status_.committed_tick = committed_->head.end_tick; diff --git a/src/server/session/region_sessions.cpp b/src/server/session/region_sessions.cpp index b748d1c..886ef04 100644 --- a/src/server/session/region_sessions.cpp +++ b/src/server/session/region_sessions.cpp @@ -638,6 +638,26 @@ struct RegionSessions::Impl { answer(c, *receipt); return; } + if (const auto* m = std::get_if(&*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(&*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; diff --git a/tests/cellular_publication_tests.cpp b/tests/cellular_publication_tests.cpp index eec1c85..64cf001 100644 --- a/tests/cellular_publication_tests.cpp +++ b/tests/cellular_publication_tests.cpp @@ -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, 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 " diff --git a/tests/quic_sessions.cpp b/tests/quic_sessions.cpp index 563db2c..5161f5a 100644 --- a/tests/quic_sessions.cpp +++ b/tests/quic_sessions.cpp @@ -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 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;