ADR-0063: manifest v2 (360 bytes) binds a per-tick validation trace object and a canonical decision block by SHA-256. Publication replays the trace from the committed predecessor's verified payload and requires every report and the candidate bytes, derives deaths deterministically, uploads payload and trace with verified read-back, then sends manifest and decisions to one fenced statement. RegionBatch seals at a terminal transition or 64 ticks and refuses ticks until durable confirmation. Schema v5 records the checkpoint, its decisions and outbox rows atomically; a unique index keeps one terminal outcome per actor (EVL08), triggers make commits/decisions immutable (EVL09), an exact retry of a committed ID returns the original receipt, changed bytes conflict, and read-only resolve_region_commit answers committed/absent/ conflict. Outbox pending/acknowledge give idempotent at-least-once delivery. Recovery reconciles durable deaths with restored lifecycle (and archive deaths for the lineage profile). Validated: Windows CTest 58/58; Linux GCC Debug/Release, clang-tidy and ASan/UBSan CTest 58/58 each; PostgreSQL suites Release, analysis, ASan (lost response, committed-after-timeout, terminated orphan retry, changed bytes, repeated/partial/reordered decisions, gap, outbox redelivery, history quarantine); five mutations each caught. No Docker/Gitea CI, process kill, broker or deployment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
146 lines
6.0 KiB
C++
146 lines
6.0 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);
|
|
}
|
|
|
|
// 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
|