Files
aevolution/include/evo/server/lifecycle/cellular_batch.hpp
T
dingo c0c66fa11a
Foundation / checks (ecs) (push) Successful in 2m23s
Foundation / checks (deploy) (push) Successful in 4m29s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 12m39s
Foundation / checks (client) (push) Canceled after 12m44s
Foundation / checks (checks) (push) Canceled after 12m48s
Foundation / checks (tsan) (push) Canceled after 10m18s
Foundation / checks (postgres) (push) Canceled after 12m44s
feat(lifecycle): replay retained offspring plans with explicit trace version
2026-10-19 14:04:52 -04:00

149 lines
8.1 KiB
C++

#pragma once
#include "evo/server/lifecycle/cellular_lives.hpp"
#include <array>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <memory>
#include <optional>
#include <span>
#include <vector>
namespace evo::server {
struct CellularBatchHeader {
std::uint64_t world{}, region{}, frame{};
std::array<std::uint8_t, 16> predecessor{};
std::array<std::uint8_t, 32> predecessor_digest{};
std::uint64_t begin_tick{}, end_tick{};
friend bool operator==(const CellularBatchHeader&, const CellularBatchHeader&) = default;
};
inline constexpr std::uint32_t cellular_batch_format = 3;
// ADR-0166: explicit opt-in for owner format 8/rules 10; the default remains 3.
inline constexpr std::uint32_t cellular_batch_inheritance_format = 4;
inline constexpr std::uint32_t cellular_batch_v2_format = 2;
inline constexpr std::uint32_t cellular_batch_legacy_format = 1;
struct CellularTickIntents {
// One intention for each life alive at the start of this tick, sorted by life_id.
std::vector<CellularLifeIntent> lives;
// Owner-authorized births are sorted by (account, request). Biology and
// placement are derived during replay after the existing-life step.
struct Birth {
LifeAccount account{};
std::uint64_t request{}, generation{}, identity{};
friend bool operator==(const Birth&, const Birth&) = default;
};
std::vector<Birth> births;
// Choices accepted against the preceding checkpoint and scheduled for this tick.
// The successor identity is durably reserved before the batch is replayed.
std::vector<CellularMutationSelection> mutations;
friend bool operator==(const CellularTickIntents&, const CellularTickIntents&) = default;
};
// Transient scheduler report, not part of the replay trace. A refused birth changes
// no biology; its final request result is recorded in the existing reservation store.
struct CellularBirthRefusal {
CellularTickIntents::Birth birth;
CellularLivesError reason{};
};
struct CellularBatch {
CellularBatchHeader header{};
std::vector<CellularTickIntents> ticks;
std::uint32_t format_version{cellular_batch_format};
friend bool operator==(const CellularBatch&, const CellularBatch&) = default;
};
struct CellularActionRecord {
std::array<std::uint8_t, 16> account{};
std::uint64_t action_id{};
std::array<std::uint8_t, 24> input{};
friend bool operator==(const CellularActionRecord&, const CellularActionRecord&) = default;
};
struct CellularMutationActionInput {
std::uint64_t life_id{}, event_index{}, offer_tick{};
std::uint16_t operator_id{};
friend bool operator==(const CellularMutationActionInput&,
const CellularMutationActionInput&) = default;
};
struct CellularMutationActionRecord {
std::array<std::uint8_t, 16> account{};
std::uint64_t action_id{}, tick{};
CellularMutationActionInput input{};
friend bool operator==(const CellularMutationActionRecord&,
const CellularMutationActionRecord&) = default;
};
inline constexpr std::size_t cellular_batch_header_bytes = 112;
inline constexpr std::size_t cellular_batch_v1_tick_header_bytes = 4;
inline constexpr std::size_t cellular_batch_v2_tick_header_bytes = 8;
inline constexpr std::size_t cellular_batch_tick_header_bytes = 16;
inline constexpr std::size_t cellular_batch_intent_bytes = 24;
inline constexpr std::size_t cellular_batch_birth_bytes = 40;
inline constexpr std::size_t cellular_batch_mutation_bytes = 40;
inline constexpr std::size_t max_cellular_batch_ticks = 64;
inline constexpr std::size_t max_cellular_batch_bytes =
cellular_batch_header_bytes +
max_cellular_batch_ticks * (cellular_batch_tick_header_bytes +
biology::max_cellular_tick_lives *
(cellular_batch_intent_bytes + cellular_batch_birth_bytes +
cellular_batch_mutation_bytes));
enum class CellularBatchError : std::uint8_t { format, version, scope, state };
inline constexpr std::size_t cellular_action_record_bytes = 48;
inline constexpr std::size_t max_cellular_action_records = 1'024;
inline constexpr std::size_t cellular_mutation_action_record_bytes = 64;
enum class CellularActionBlockError : std::uint8_t { format, mismatch };
// Canonical replay input: one bounded, life-ID-ordered intention set per tick.
[[nodiscard]] std::expected<std::vector<std::uint8_t>, CellularBatchError>
encode_cellular_batch(const CellularBatch& batch);
[[nodiscard]] std::expected<CellularBatch, CellularBatchError>
decode_cellular_batch(std::span<const std::uint8_t> bytes);
// Replays from an immutable predecessor snapshot. The caller must first bind the
// header identity, predecessor commit/digest and tick range to trusted manifests.
// Every tick must cover its living set; the caller compares the returned snapshot.
// Trace 4 requires owner format 8/rules 10; traces 1-3 require earlier owners.
// Portable replay grants no durable admission or publication authority.
[[nodiscard]] std::expected<std::unique_ptr<CellularLives>, CellularBatchError>
replay_cellular_batch(const CellularLives& base, const CellularBatch& batch);
// The same replay, also reporting every mutation selection's final result in trace order
// (ADR-0121): the authority for the results a publication binds and recovery compares.
// Failure leaves the predecessor unchanged and clears the complete outcome vector.
struct CellularMutationOutcome {
std::uint64_t tick{}, life_id{}, successor_id{};
CellularMutationResult result{};
friend bool operator==(const CellularMutationOutcome&,
const CellularMutationOutcome&) = default;
};
[[nodiscard]] std::expected<std::unique_ptr<CellularLives>, CellularBatchError>
replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
std::vector<CellularMutationOutcome>& mutation_outcomes);
// The canonical 34-byte reserved choice (schema v29): tick, life, event and offer tick as
// u64 and the operator as u16, little-endian.
inline constexpr std::size_t cellular_mutation_input_bytes = 34;
[[nodiscard]] std::array<std::uint8_t, cellular_mutation_input_bytes>
encode_cellular_mutation_input(const CellularMutationActionRecord& action);
[[nodiscard]] std::optional<CellularMutationActionRecord>
decode_cellular_mutation_input(const std::array<std::uint8_t, 16>& account, std::uint64_t action_id,
std::span<const std::uint8_t> input);
[[nodiscard]] std::expected<std::vector<std::uint8_t>, CellularActionBlockError>
encode_cellular_action_block(std::span<const CellularActionRecord> actions,
std::uint64_t begin_tick, std::uint64_t end_tick);
[[nodiscard]] std::expected<std::vector<CellularActionRecord>, CellularActionBlockError>
decode_cellular_action_block(std::span<const std::uint8_t> bytes, std::uint64_t begin_tick,
std::uint64_t end_tick);
[[nodiscard]] std::expected<std::vector<std::uint8_t>, CellularActionBlockError>
encode_cellular_mutation_action_block(std::span<const CellularMutationActionRecord> actions,
std::uint64_t begin_tick, std::uint64_t end_tick);
[[nodiscard]] std::expected<std::vector<CellularMutationActionRecord>, CellularActionBlockError>
decode_cellular_mutation_action_block(std::span<const std::uint8_t> bytes, std::uint64_t begin_tick,
std::uint64_t end_tick);
// Every durable action must match the canonical input for that account's life
// in the corresponding replay tick. An action cannot create a life or intent.
[[nodiscard]] std::expected<void, CellularActionBlockError>
match_cellular_actions_to_trace(const CellularLives& predecessor, const CellularBatch& batch,
std::span<const CellularActionRecord> actions);
[[nodiscard]] std::expected<void, CellularActionBlockError>
match_cellular_mutation_actions_to_trace(const CellularLives& predecessor,
const CellularBatch& batch,
std::span<const CellularMutationActionRecord> actions);
} // namespace evo::server