Files
aevolution/include/evo/server/cellular_region_host.hpp
T
dingo 817a830a8a
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 2m23s
Foundation / checks (tsan) (push) Successful in 10m11s
Foundation / checks (client) (push) Failing after 14m26s
Foundation / checks (network) (push) Successful in 18m54s
Foundation / checks (checks) (push) Successful in 42m9s
Foundation / checks (postgres) (push) Successful in 43m51s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
ADR 0127
2026-10-15 09:32:51 -04:00

180 lines
8.6 KiB
C++

#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 <chrono>
#include <cstdint>
#include <expected>
#include <functional>
#include <memory>
#include <optional>
#include <span>
#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;
};
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 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();
[[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);
// 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
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;
CellularRegionHost(CellularHostConfig config, CellularConnect connect,
std::unique_ptr<persistence::FilesystemObjectStore> objects);
bool database();
void acquire();
void upkeep();
void resolve();
void refresh();
void finalize_births(std::span<const CellularTickIntents::Birth> 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<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_;
persistence::LeaseAuthority authority_;
std::unique_ptr<CellularLives> state_;
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_;
// 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