Files
dingoandClaude Opus 5.5 69f3ad7cf8
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m47s
Foundation / checks (network) (push) Successful in 9m30s
Foundation / checks (client) (push) Successful in 12m19s
Foundation / checks (tsan) (push) Successful in 7m43s
Foundation / checks (checks) (push) Successful in 31m29s
Foundation / checks (postgres) (push) Successful in 36m39s
Foundation / postgres-tools (push) Successful in 19s
Foundation / image (push) Successful in 2m15s
Foundation / server-image (push) Successful in 20m37s
Add M10.4b durable action records (schema v11)
Each batch's actions are recorded in the same statement as its checkpoint: one
region_actions row per (world, account, action id) and the block in an append-only
table, compared on exact retries and resolution. The region host attaches actions to
the ticks they ride and reports acknowledgements and drops, keeping unknown-outcome
batches unresolved. Outcomes come from the durable record via ActionLedger, so
crashes before or after a commit, unknown publications and cross-region moves all
resolve to one answer; a repeated id keeps its first record instead of stalling a
region. ADR-0092.

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

162 lines
6.9 KiB
C++

#pragma once
#include "evo/persistence/region_lease.hpp"
#include "evo/processes/environmental_community.hpp"
#include <array>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <span>
#include <vector>
// M7.5 batch evidence (ADR-0063, schemas/region-batch.md): the ordered validation
// trace of host inputs and reports for one checkpoint batch, and the permanent
// outcomes (decisions) derived from it. Portable and storage-free.
namespace evo::persistence {
enum class BatchError : std::uint8_t {
format, // Malformed trace or decision bytes.
sealed, // The batch holds a pending permanent outcome or is full.
empty, // Nothing to commit.
state, // The simulation refused the tick; nothing was recorded.
mismatch, // Replay, receipt or reconciliation disagrees with the record.
};
// Encoded as u32; decoding refuses unknown values rather than truncating them.
enum class Actor : std::uint8_t { producer = 0, consumer = 1 };
enum class Outcome : std::uint8_t { death = 1 };
// One permanent outcome. Identity is (region, outcome, actor, tick); a death is
// terminal, so each actor has at most one. organism is the archived organism for
// the lineage profile and 0 for environmental-v1.
struct BatchDecision {
std::uint64_t tick{};
Actor actor{};
Outcome outcome{Outcome::death};
std::uint64_t organism{};
friend bool operator==(const BatchDecision&, const BatchDecision&) = default;
};
struct TraceStep {
processes::EnvironmentalInput input{};
processes::EnvironmentalReport report{};
friend bool operator==(const TraceStep&, const TraceStep&) = default;
};
// Binds a trace to its place in the chain so it cannot be replayed elsewhere.
struct TraceHeader {
std::uint32_t profile{};
RegionKey key{};
Uuid predecessor_commit{};
Sha256Digest predecessor_digest{};
std::uint64_t begin_tick{}, end_tick{};
friend bool operator==(const TraceHeader&, const TraceHeader&) = default;
};
inline constexpr std::size_t trace_header_bytes = 96;
inline constexpr std::size_t trace_step_bytes = 304;
inline constexpr std::size_t decision_bytes = 24;
// Two actors, each dies at most once; the wire cap leaves room for later profiles.
inline constexpr std::size_t max_batch_decisions = 8;
[[nodiscard]] constexpr std::size_t trace_bytes_for(std::uint64_t ticks) noexcept {
return trace_header_bytes + (static_cast<std::size_t>(ticks) * trace_step_bytes);
}
// M10.4b durable action records (schema v11, ADR-0092): the actions that rode a batch,
// committed in the same statement as its checkpoint. Not part of the trace or manifest.
inline constexpr std::size_t action_record_bytes = 34;
inline constexpr std::size_t max_batch_actions = 1024;
struct ActionRecord {
Uuid account{};
std::uint64_t action_id{}, tick{};
std::uint16_t kind{1}; // 1 = probe (no effect).
friend bool operator==(const ActionRecord&, const ActionRecord&) = default;
};
// Canonical block: sorted by (tick, account, id); refuses zero accounts or ids, other kinds,
// ticks outside (begin, end], duplicates and more than max_batch_actions records.
[[nodiscard]] std::expected<std::vector<std::uint8_t>, BatchError>
encode_actions(std::span<const ActionRecord> actions, std::uint64_t begin_tick,
std::uint64_t end_tick);
// One step per tick, begin_tick+1..end_tick, at most 64.
[[nodiscard]] std::expected<std::vector<std::uint8_t>, BatchError>
encode_trace(const TraceHeader& header, std::span<const TraceStep> steps);
struct DecodedTrace {
TraceHeader header;
std::vector<TraceStep> steps;
};
[[nodiscard]] std::expected<DecodedTrace, BatchError>
decode_trace(std::span<const std::uint8_t> bytes);
// Sorted by (tick, actor), unique actors, death only, ticks within the batch.
[[nodiscard]] std::expected<std::vector<std::uint8_t>, BatchError>
encode_decisions(std::span<const BatchDecision> decisions, std::uint64_t begin_tick,
std::uint64_t end_tick);
[[nodiscard]] std::expected<std::vector<BatchDecision>, BatchError>
decode_decisions(std::span<const std::uint8_t> bytes, std::uint64_t begin_tick,
std::uint64_t end_tick);
// Every terminal transition in the trace yields exactly one decision, in order.
[[nodiscard]] std::vector<BatchDecision> derive_decisions(std::span<const TraceStep> steps,
std::uint64_t producer_organism,
std::uint64_t consumer_organism);
// Records one pending batch over a single-owner state (EnvironmentalCommunity or
// LineageRegion). Seals itself after any tick with a terminal transition, or at
// 64 ticks; a sealed batch refuses further ticks until confirm() records durable
// confirmation. Nothing here is durable: outcomes are provisional until then.
template <typename State> class RegionBatch {
public:
explicit RegionBatch(State& state) : state_(&state), begin_(tick_of(state)) {}
[[nodiscard]] std::expected<processes::EnvironmentalReport, BatchError>
advance(const processes::EnvironmentalInput& input) {
if (sealed_)
return std::unexpected{BatchError::sealed};
const auto tick = tick_of(*state_) + 1;
auto report = state_->advance(tick, input);
if (!report)
return std::unexpected{BatchError::state};
steps_.push_back({input, *report});
if (report->terminal_transition == 1 || report->consumer_transition == 1 ||
steps_.size() == max_ticks)
sealed_ = true;
return *report;
}
// Host deadline or shutdown: stop and commit what exists.
void seal() noexcept {
sealed_ = true;
}
// Durable confirmation for exactly this batch: the next batch starts here.
[[nodiscard]] std::expected<void, BatchError> confirm(std::uint64_t committed_end_tick) {
if (!sealed_ || steps_.empty() || committed_end_tick != end_tick())
return std::unexpected{BatchError::mismatch};
begin_ = committed_end_tick;
steps_.clear();
sealed_ = false;
return {};
}
[[nodiscard]] bool sealed() const noexcept {
return sealed_;
}
[[nodiscard]] std::uint64_t begin_tick() const noexcept {
return begin_;
}
[[nodiscard]] std::uint64_t end_tick() const noexcept {
return begin_ + steps_.size();
}
[[nodiscard]] std::span<const TraceStep> steps() const noexcept {
return steps_;
}
[[nodiscard]] const State& state() const noexcept {
return *state_;
}
private:
static constexpr std::size_t max_ticks = 64;
static std::uint64_t tick_of(const State& s) {
if constexpr (requires { s.community(); })
return s.community().progress().tick;
else
return s.progress().tick;
}
State* state_;
std::uint64_t begin_;
std::vector<TraceStep> steps_;
bool sealed_{};
};
} // namespace evo::persistence