Files
aevolution/include/evo/server/cellular_region_host.hpp
T
dingoandClaude Opus 5.5 7273b157d6
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 5s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m47s
Foundation / postgres-tools (push) Successful in 29s
Foundation / server-image (push) Successful in 4m42s
Foundation / image (push) Successful in 5m55s
feat(admin): live tuning revisions adopted at recorded ticks (schema 66)
ADR-0182 section 13. The admin portal's Tuning page edits the world's
rules-13 tuning (the Git revamp file format); the admin API checks it,
stores an append-only revision and queues an adopt_tuning admin command
(kind 7: revision and rules digest) for every region of the world.

- Lifecycle: adopt_tuning replaces the region's rules after births when
  a resolver names the rules for that revision and digest; the safety
  revision cannot change live. At most one adoption per batch.
- Host: fetches the revision text, rebuilds and digests the rules before
  appending the command; publication and recovery name the rules from
  the successor state, checked against the recorded digest.
- Schema 66: tuning_revisions, admin_set_tuning_v1, load_tuning_revision_v1
  (runtime), admin_tuning_revisions_v1, admin_tuning_text_v1.
- OpsServer: optional bounded request bodies (Content-Length, 413).
- Region view: rules_sha256, so the portal shows each region's revision.
- Portal: Tuning page; baseline from the mounted cellular-revamp.tuning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 19:35:09 -04:00

310 lines
16 KiB
C++

#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 <chrono>
#include <cstdint>
#include <expected>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <span>
#include <utility>
#include <vector>
namespace evo::server {
using CellularConnect =
std::function<std::expected<std::unique_ptr<persistence::Postgres>, persistence::PgFailure>()>;
struct CellularHostConfig {
persistence::RegionKey key{};
std::uint64_t frame{};
persistence::LeasePolicy lease{};
persistence::Sha256Digest build{};
std::vector<persistence::Sha256Digest> retained_builds;
std::optional<CellularTierPolicy> 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<persistence::PublicationError> publication;
std::optional<persistence::LeaseStoreFailure> store;
std::optional<persistence::ObjectError> 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<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;
// 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<std::unique_ptr<CellularRegionHost>, CellularHostError>
create(CellularHostConfig config, CellularConnect connect,
std::unique_ptr<persistence::FilesystemObjectStore> 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<void, CellularPublishFailure>
prepare_migration_freeze(const persistence::CommittedCheckpoint& destination,
const persistence::FilesystemObjectStore& destination_objects,
const CellularMigrationRequest&);
[[nodiscard]] std::expected<void, CellularPublishFailure>
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<void, CellularPublishFailure>
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<void, CellularPublishFailure> 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<std::optional<persistence::CommittedCheckpoint>,
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<void, CellularPublishFailure>
begin_publish(CellularBatch batch, std::vector<CellularActionRecord> actions,
std::vector<CellularMutationActionRecord> mutation_actions,
std::unique_ptr<CellularLives> 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<persistence::PublishedCellularBatch, CellularPublishFailure>>
poll_publish();
[[nodiscard]] std::expected<persistence::PublishedCellularBatch, CellularPublishFailure>
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);
// 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<const persistence::CellularMutationReservation>
queued_mutations() const noexcept {
return queued_mutations_;
}
// Queued choices not carried by the commit in flight: the open batch binds these.
[[nodiscard]] std::vector<persistence::CellularMutationReservation> 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<CellularAdminCommand> 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<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
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<const CellularBirthRefusal> refusals);
[[nodiscard]] std::span<const CellularTickIntents::Birth> queued_births() const noexcept {
return queued_births_;
}
[[nodiscard]] std::vector<FinalCellularAction> take_finalized_actions();
void drain();
[[nodiscard]] std::optional<persistence::LeaseGrant> authority() const;
[[nodiscard]] const HostStatus& status() const noexcept {
return status_;
}
[[nodiscard]] const CellularLives* state() const noexcept {
return state_.get();
}
[[nodiscard]] const std::optional<persistence::CommittedCheckpoint>&
committed() const noexcept {
return committed_;
}
private:
struct Pending;
struct InFlight;
[[nodiscard]] std::expected<persistence::PublishedCellularBatch, CellularPublishFailure>
finish_publication(const CellularBatch& batch, std::span<const CellularActionRecord> actions,
std::span<const CellularMutationActionRecord> mutation_actions,
std::unique_ptr<CellularLives> candidate,
std::expected<persistence::PublishedCellularBatch,
persistence::CellularPublicationFailure> published);
CellularRegionHost(CellularHostConfig config, CellularConnect connect,
std::unique_ptr<persistence::FilesystemObjectStore> 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<persistence::PublishedCellularBatch, CellularPublishFailure>
publish_population(const CellularBatch&);
void finalize_births(std::span<const CellularTickIntents::Birth> 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<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);
CellularHostConfig config_;
CellularConnect connect_;
std::unique_ptr<persistence::FilesystemObjectStore> objects_;
std::unique_ptr<persistence::Postgres> db_;
// The write-behind commit and its own connection (libpq connections are not shared).
std::unique_ptr<InFlight> in_flight_;
std::unique_ptr<persistence::Postgres> 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<CellularLives> individual;
std::unique_ptr<CellularPopulation> population;
OwnedState() = default;
OwnedState(std::unique_ptr<CellularLives> state) : individual(std::move(state)) {}
OwnedState(std::unique_ptr<CellularPopulation> state) : population(std::move(state)) {}
OwnedState& operator=(std::unique_ptr<CellularLives> state) {
population.reset();
individual = std::move(state);
return *this;
}
OwnedState& operator=(std::unique_ptr<CellularPopulation> 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<persistence::CommittedCheckpoint, CellularPublishFailure>
accept_population_publication(
std::expected<persistence::CommittedCheckpoint, persistence::PopulationPublicationFailure>,
OwnedState candidate);
OwnedState state_;
bool migration_reload_{}, migration_frozen_{};
persistence::LeaseClock::time_point migration_poll_at_{};
std::optional<persistence::CellularMigrationPrepared> migration_request_;
std::optional<persistence::CellularMigrationStagePrepared> migration_stage_request_;
std::optional<persistence::Uuid> migration_abort_;
bool interval_reload_{};
std::optional<persistence::PopulationInterval> 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<IntervalRequest> interval_request_;
std::optional<persistence::LeaseStoreFailure> interval_failure_;
std::optional<persistence::CommittedCheckpoint> committed_;
std::unique_ptr<Pending> pending_;
std::vector<FinalCellularAction> finalized_actions_;
std::vector<CellularTickIntents::Birth> queued_births_;
std::vector<CellularBirthRefusal> pending_birth_refusals_;
std::vector<persistence::CellularMutationReservation> queued_mutations_;
std::vector<CellularAdminCommand> queued_admin_;
std::map<std::uint64_t, CellularRevampRules> 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<FinalCellularMutation> finalized_mutations_;
std::vector<FinalCellularMutation> recent_mutations_; // Bounded, for exact repeats.
struct Ending {
persistence::Uuid commit{};
std::uint64_t life{};
};
std::vector<Ending> pending_endings_; // Recorded endings not yet acknowledged.
HostStatus status_{};
};
} // namespace evo::server