Files
aevolution/include/evo/server/cellular_region_host.hpp
T
dingoandClaude Opus 5.5 f77956e579 Send the owner its outstanding mutation offer over v10
Session protocol v10 adds type 26: the life's earned offer with its unranked
candidates in operator order and each successor's capability value,
maintenance and total mass. The cellular bridge sends it when the offer or the
owner's session changes and clears a consumed offer; the client keeps the
latest one for the maintainer's choice UI (ADR-0121, 11.4d server half).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 23:07:50 -04:00

165 lines
7.8 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; no offer gives an empty view that clears the client's.
[[nodiscard]] network::CellularMutationOffer offer_view(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);
[[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();
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<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.
HostStatus status_{};
};
} // namespace evo::server