#pragma once #include "evo/network/session_protocol.hpp" #include "evo/persistence/checkpoint_store.hpp" #include "evo/persistence/life_reservation_store.hpp" #include "evo/server/lifecycle/cellular_batch.hpp" #include "evo/server/ops.hpp" #include #include #include #include #include #include #include #include namespace evo::server { using CellularConnect = std::function, persistence::PgFailure>()>; struct CellularHostConfig { persistence::RegionKey key{}; std::uint64_t frame{}; persistence::LeasePolicy lease{}; persistence::Sha256Digest build{}; std::vector retained_builds; }; enum class CellularHostError : std::uint8_t { configuration, not_ready, invalid_batch, publication }; struct CellularPublishFailure { // Safe persistence diagnostics only: category and SQLSTATE, never server text. CellularHostError kind{}; std::optional publication; std::optional store; std::optional object; }; struct FinalCellularAction { CellularActionRecord action; 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; // The owner's view of a life's outstanding offer at `tick` (11.4d): candidates in their // stable operator order, each with its cost to this cell from its reserve (ADR-0129); no offer // gives an empty view that clears the client's. [[nodiscard]] network::CellularMutationOffer offer_view(const CellularLives& state, const CellularOwnedLife& life, std::uint64_t tick); // 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. class CellularRegionHost { public: [[nodiscard]] static std::expected, CellularHostError> create(CellularHostConfig config, CellularConnect connect, std::unique_ptr objects); CellularRegionHost(const CellularRegionHost&) = delete; CellularRegionHost& operator=(const CellularRegionHost&) = delete; ~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 = {}, 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 create_primitive_life(const persistence::Uuid& account, std::uint64_t generation, std::uint64_t request); [[nodiscard]] network::PrimitiveLifeOutcome query_primitive_life(const persistence::Uuid& account, std::uint64_t generation, std::uint64_t request); // Call only after the scheduler's batch is confirmed published. Persists expected // birth refusals without blocking the region; uncertain replies stay out of the birth // queue and reconcile on the account's next exact request/query (including takeover). void refuse_births(std::span refusals); [[nodiscard]] std::span queued_births() const noexcept { return queued_births_; } [[nodiscard]] std::vector take_finalized_actions(); void drain(); [[nodiscard]] std::optional authority() const; [[nodiscard]] const HostStatus& status() const noexcept { return status_; } [[nodiscard]] const CellularLives* state() const noexcept { return state_.get(); } [[nodiscard]] const std::optional& committed() const noexcept { return committed_; } private: struct Pending; CellularRegionHost(CellularHostConfig config, CellularConnect connect, std::unique_ptr objects); bool database(); void acquire(); void upkeep(); void resolve(); void refresh(); void finalize_births(std::span births); void queue_birth(const CellularTickIntents::Birth& birth); void reload_mutations(); // 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); void flush_endings(); 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); CellularHostConfig config_; CellularConnect connect_; std::unique_ptr objects_; std::unique_ptr db_; persistence::LeaseAuthority authority_; std::unique_ptr state_; std::optional committed_; std::unique_ptr pending_; std::vector finalized_actions_; std::vector queued_births_; std::vector pending_birth_refusals_; 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. struct Ending { persistence::Uuid commit{}; std::uint64_t life{}; }; std::vector pending_endings_; // Recorded endings not yet acknowledged. HostStatus status_{}; }; } // namespace evo::server