#pragma once #include "evo/network/session_protocol.hpp" #include "evo/persistence/cellular_migration_store.hpp" #include "evo/persistence/checkpoint_store.hpp" #include "evo/persistence/life_reservation_store.hpp" #include "evo/persistence/population_checkpoint_store.hpp" #include "evo/persistence/population_interval_store.hpp" #include "evo/server/lifecycle/cellular_batch.hpp" #include "evo/server/ops.hpp" #include #include #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; std::optional population_policy{}; // Opt-in profile-5 entry. }; 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/5 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(); // Explicit source-only preparation/abort. Preparation pauses the whole region; // restart and lease expiry never imply abort or destination activation. [[nodiscard]] std::expected prepare_migration_freeze(const persistence::CommittedCheckpoint& destination, const persistence::FilesystemObjectStore& destination_objects, const CellularMigrationRequest&); [[nodiscard]] std::expected abort_migration_freeze(const persistence::Uuid& request); // Explicit destination staging. The ghost stays read-only until a future // paired publication receipt; source abort releases this pause. [[nodiscard]] std::expected stage_migration(const persistence::CommittedCheckpoint& source, const persistence::FilesystemObjectStore& source_objects, const CellularMigrationTrace&); // Explicit no-tick fenced transition. Uncertain publication pauses the host. [[nodiscard]] std::expected set_population_mode(bool enabled); [[nodiscard]] bool population_mode() const noexcept; // Service a recorded interval even when new due time is zero after restart. // Otherwise admit a bounded prefix of due ticks before computing it. [[nodiscard]] std::expected, CellularPublishFailure> advance_unattended(std::uint64_t due_ticks); // Write-behind commit (rules-12 regions, Cellular_Region_Movement_Plan.md): commits a raw // batch on a worker thread with its own connection while the caller keeps simulating. // `candidate` is the state the batch's builder already computed, so nothing is replayed. // At most one commit is in flight; its result is applied on this thread by poll_publish. [[nodiscard]] std::expected begin_publish(CellularBatch batch, std::vector actions, std::vector mutation_actions, std::unique_ptr candidate); [[nodiscard]] bool commit_in_flight() const noexcept { return in_flight_ != nullptr; } // The finished background commit's outcome, applied exactly as publish applies its own; // nullopt while none has finished. [[nodiscard]] std::optional< std::expected> poll_publish(); [[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); // A queued choice the builder refused (its tick passed): reload the queue from the // store, which keeps only reservations for the head's next tick. void recheck_mutations() noexcept { mutations_uncertain_ = true; } // Reserved choices, in reservation order (ADR-0121 amendment, schema 59: a durable // queue; each binds at a tick at or after its reservation's). [[nodiscard]] std::span queued_mutations() const noexcept { return queued_mutations_; } // Queued choices not carried by the commit in flight: the open batch binds these. [[nodiscard]] std::vector unbound_mutations() const; // ADR-0182: queued admin commands (rules 13) not carried by the commit in flight, oldest // first, at most one tick's worth. Publication binds each to its queue row once. [[nodiscard]] std::vector unbound_admin_commands() const; // ADR-0182: the tuning revisions this host fetched and verified, for adopt_tuning commands. [[nodiscard]] CellularTuningResolver tuning_resolver() const; [[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; struct InFlight; [[nodiscard]] std::expected finish_publication(const CellularBatch& batch, std::span actions, std::span mutation_actions, std::unique_ptr candidate, std::expected published); CellularRegionHost(CellularHostConfig config, CellularConnect connect, std::unique_ptr objects); bool database(); void acquire(); void upkeep(); void resolve(); void refresh(); bool recover_state(const persistence::LeaseGrant&); void reconcile_interval(); void reconcile_migration_freeze(); void finish_interval(); [[nodiscard]] std::expected publish_population(const CellularBatch&); void finalize_births(std::span births); void queue_birth(const CellularTickIntents::Birth& birth); void reload_mutations(); void reload_admin_commands(); // ADR-0127: owned lives that died record their ending so the account may start again. void note_endings(const CellularLives& before, const CellularLives& after, const persistence::Uuid& commit); 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_; // The write-behind commit and its own connection (libpq connections are not shared). std::unique_ptr in_flight_; std::unique_ptr commit_db_; persistence::LeaseAuthority authority_; // Exactly one owner. The common interface is a const biological view, never // a second independently spendable cellular copy alongside a population. struct OwnedState { std::unique_ptr individual; std::unique_ptr population; OwnedState() = default; OwnedState(std::unique_ptr state) : individual(std::move(state)) {} OwnedState(std::unique_ptr state) : population(std::move(state)) {} OwnedState& operator=(std::unique_ptr state) { population.reset(); individual = std::move(state); return *this; } OwnedState& operator=(std::unique_ptr state) { individual.reset(); population = std::move(state); return *this; } void reset() { individual.reset(); population.reset(); } const CellularLives* get() const { return population ? &population->state() : individual.get(); } const CellularLives* operator->() const { return get(); } const CellularLives& operator*() const { return *get(); } explicit operator bool() const { return get() != nullptr; } }; [[nodiscard]] std::expected accept_population_publication( std::expected, OwnedState candidate); OwnedState state_; bool migration_reload_{}, migration_frozen_{}; persistence::LeaseClock::time_point migration_poll_at_{}; std::optional migration_request_; std::optional migration_stage_request_; std::optional migration_abort_; bool interval_reload_{}; std::optional admitted_interval_; // An uncertain admission must retry its exact source/target, never select again. struct IntervalRequest { persistence::RegionHead source; std::uint64_t end_tick{}; }; std::optional interval_request_; std::optional interval_failure_; std::optional committed_; std::unique_ptr pending_; std::vector finalized_actions_; std::vector queued_births_; std::vector pending_birth_refusals_; std::vector queued_mutations_; std::vector queued_admin_; std::map verified_tuning_; // By revision. std::chrono::steady_clock::time_point next_admin_reload_{}; // A reservation may exist that the queue does not show; reload before publishing. bool mutations_uncertain_{}; std::vector 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