Files
aevolution/include/evo/server/cellular_region_host.hpp
T
dingoandClaude Opus 5.5 71d195d4e8
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 5s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m24s
Foundation / postgres-tools (push) Successful in 1m31s
Foundation / server-image (push) Successful in 4m25s
Foundation / image (push) Successful in 4m50s
feat: durable mutation queue (schema 59)
A mutation choice's reserved tick is now the earliest tick it may bind
at, not the only one (ADR-0121 amendment). With write-behind commits, a
choice reserved for head + 1 landed in ticks already being simulated or
committed: the batch was refused, or the reservation was orphaned for a
past tick and stalled the region.

Schema 59: a bound record carries the tick it applied at and the rest of
its input must equal the reservation's; the "omits a reserved mutation"
refusals are removed. Existing rows are unchanged, so an orphaned
reservation binds at the next commit that carries it.

The host keeps every unbound reservation queued and the open batch binds
those the commit in flight does not carry, at its next tick; the earlier
hold on new choices is removed. A choice that outlives its life binds as
life_died (owner, trace matching and recovery accept it when no life with
that ID remains). Recovery takes a bound choice's tick from its trace.

Tests: a choice skipped by one checkpoint binds a tick late and recovers;
builder late binding, refusal before the earliest tick, and a departed
life's life_died outcome. Full local PostgreSQL qualification passes.

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

300 lines
15 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 <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;
[[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();
// 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_;
// 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