diff --git a/CMakeLists.txt b/CMakeLists.txt index f53badc..c880fda 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -74,7 +74,8 @@ target_compile_features(evo_biology PUBLIC cxx_std_23) evo_owned_target(evo_biology) # M11.2 portable lifecycle orchestration; no dependency from the foundation proof. -add_library(evo_lifecycle STATIC src/server/lifecycle/primitive_lives.cpp) +add_library(evo_lifecycle STATIC src/server/lifecycle/primitive_lives.cpp + src/server/lifecycle/primitive_batch.cpp) add_library(evo::lifecycle ALIAS evo_lifecycle) target_link_libraries(evo_lifecycle PUBLIC evo::biology) evo_owned_target(evo_lifecycle) diff --git a/docs/adr/0100-primitive-lives-and-persistent-control.md b/docs/adr/0100-primitive-lives-and-persistent-control.md index 2fead04..aec874d 100644 --- a/docs/adr/0100-primitive-lives-and-persistent-control.md +++ b/docs/adr/0100-primitive-lives-and-persistent-control.md @@ -200,6 +200,17 @@ and are never reported as organisms. The owner must provision an audited unused identity range; runtime cannot initialize it. Control/lease expiry is checked after lock waits. This precedes atomic body/checkpoint publication in 11.2c-2. +## 11.2c-2a: Creation replay evidence + +The [primitive-batch-v1](../../schemas/primitive-batch-v1.md) trace records funded +births with world/region/frame, predecessor commit/digest, batch tick interval and +control generations. Replay creates a detached candidate; any failed birth +discards all changes. The owner retains the checkpoint tick in the manifest; +empty creation batches advance that tick without advancing any biology. This +does not introduce offline progress or reserve consumption. Publication must bind +the trace to its predecessor and atomically validate reservations/control before +recording life ownership. The portable trace alone does not provide durability. + New-life request IDs use a separate operation namespace from M10 no-effect probe actions. The future protocol must make that explicit rather than overloading the existing probe result lookup. This avoids silently changing deployed probe rules. diff --git a/docs/engineering/M11_2_DELIVERY_PLAN.md b/docs/engineering/M11_2_DELIVERY_PLAN.md index a034cfc..70b86f7 100644 --- a/docs/engineering/M11_2_DELIVERY_PLAN.md +++ b/docs/engineering/M11_2_DELIVERY_PLAN.md @@ -72,6 +72,8 @@ Local checks do not close ADR-0097's reference-worker qualification. full migration/process, backup/restore, upgrade and privilege regressions pass. - 11.2c-1 adapter: typed C++ reserve/refuse API, full unsigned identity range and uncertain-response reconciliation validated in Release and ASan+UBSan. +- 11.2c-2a: bounded creation-batch codec and detached funded replay. Empty batches + preserve all biology. Host/manifest chain authorization remains required. - 11.2c-2 and 11.2d remain: atomic funded checkpoint publication, reconciliation, host/session integration and crash-boundary qualification. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 3923f9b..3d56d8a 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5558,3 +5558,19 @@ adapter and both affected test files; full format-check, shell syntax and diff checks. All passed. The full PostgreSQL/process suite above belongs to the schema subsection; it was not repeated for these adapter-only changes. No wire format, deployed world or SQL migration changed in this subsection. + +## 2026-10-10 — M11.2c-2a creation-batch replay + +Added bounded primitive-batch-v1 trace encoding and detached funded replay. +Checks cover canonical round trips, every truncated prefix, length/version and +reserved fields, maximum counts, ordered unique births, scope and tick bounds, +duplicate old requests, exact replay equivalence and channel conservation. A +second birth with insufficient funding discards the first candidate birth too; +empty batches preserve the complete biological payload. + +Executed: Linux GCC 14 debug lifecycle test; Clang 19 ASan+UBSan lifecycle test; +Windows MSVC Release/NDEBUG full 62/62 CTest checks; clang-tidy 19 on new source +and affected lifecycle tests; repository format-check and diff checks. All passed. +The static-analysis session was interrupted across the chat pause and rerun to +confirmed completion. No existing network type, golden, database profile or +deployment changed; atomic database publication remains unimplemented. diff --git a/include/evo/server/lifecycle/primitive_batch.hpp b/include/evo/server/lifecycle/primitive_batch.hpp new file mode 100644 index 0000000..daab1c4 --- /dev/null +++ b/include/evo/server/lifecycle/primitive_batch.hpp @@ -0,0 +1,45 @@ +#pragma once +#include "evo/server/lifecycle/primitive_lives.hpp" + +namespace evo::server { +// Creation-only trace. Publication binds this header to the committed predecessor. +// Generation records authorization evidence; replay grants no authority. +struct PrimitiveBatchHeader { + std::uint64_t world{}, region{}, frame{}; + std::array predecessor{}; + std::array predecessor_digest{}; + std::uint64_t begin_tick{}, end_tick{}; + friend bool operator==(const PrimitiveBatchHeader&, const PrimitiveBatchHeader&) = default; +}; +struct PrimitiveBirth { + LifeRequest request{}; + std::uint64_t identity{}, generation{}; + Tick born{}; + friend bool operator==(const PrimitiveBirth&, const PrimitiveBirth&) = default; +}; +struct PrimitiveBatch { + PrimitiveBatchHeader header{}; + std::vector births; + friend bool operator==(const PrimitiveBatch&, const PrimitiveBatch&) = default; +}; +inline constexpr std::uint32_t primitive_batch_format = 1; +inline constexpr std::size_t primitive_batch_header_bytes = 112; +inline constexpr std::size_t primitive_birth_bytes = 48; +inline constexpr std::size_t max_primitive_batch_bytes = + primitive_batch_header_bytes + primitive_birth_bytes * max_primitive_lives; +enum class PrimitiveBatchError : std::uint8_t { format, version, scope, state }; + +// 1..64 ticks, <=256 births, ordered by (born, account, request), unique accounts +// and identities. Empty batches advance the owner's checkpoint tick without +// progressing biology. No implicit reserve consumption or timer advancement. +[[nodiscard]] std::expected, PrimitiveBatchError> +encode_primitive_batch(const PrimitiveBatch& batch); +[[nodiscard]] std::expected +decode_primitive_batch(std::span bytes); +// Clones the base and applies every funded birth; all-or-nothing. Caller MUST +// match predecessor/digest/begin tick to its trusted committed manifest, then +// compare replayed payload bytes with the proposed checkpoint. Allocation uses +// the same value in each of the four distinct world identity namespaces. +[[nodiscard]] std::expected, PrimitiveBatchError> +replay_primitive_batch(const PrimitiveLives& base, const PrimitiveBatch& batch); +} // namespace evo::server diff --git a/schemas/primitive-batch-v1.md b/schemas/primitive-batch-v1.md new file mode 100644 index 0000000..e5ff294 --- /dev/null +++ b/schemas/primitive-batch-v1.md @@ -0,0 +1,46 @@ +# Primitive creation batch v1 + +M11.2c-2 portable replay evidence for ADR-0100. This format alone does not register +a durable checkpoint profile or authorize a spawn. It records only funded births; +later biological actions require an explicit format/rules extension. + +All integers are little-endian unsigned. Exact length is `112 + count * 48`. +No padding, trailing bytes or unknown versions are admitted. The enclosing +checkpoint must bind the entire trace by SHA-256; there is no independent checksum. + +| Offset | Bytes | Meaning | +|---|---|---| +| 0 | 8 | Magic `EVLIFTB1` | +| 8 | 4 | Format 1 | +| 12 | 4 | Birth count, 0..256 | +| 16 | 24 | World, region, frame (three u64, nonzero) | +| 40 | 16 | Predecessor commit, nonzero | +| 56 | 32 | Predecessor manifest SHA-256, nonzero | +| 88 | 8 | Begin tick, exclusive | +| 96 | 8 | End tick, inclusive; begin < end <= begin + 64 | +| 104 | 8 | Reserved zero | +| 112 | 48 each | Birth records | + +A birth is account bytes[16], new-life request u64, allocated identity u64, +control generation u64, and birth tick u64. Account and all identity/control +values are nonzero. Birth ticks lie within the batch. Records are strictly +ordered by (tick, account bytes, request), with unique accounts and identities. +The shared allocated value names four distinct namespaces: life, organism, +genome and founding event. It is never a client-chosen identity. + +Replay checks region scope and that existing births precede the batch. It +restores a detached copy and calls funded creation for every record. Any refusal +discards the entire candidate. A successful retry is not admitted as a new birth. +Replay uses the recorded order for deterministic placement and funding. The +caller must compare the resulting canonical snapshot with the proposed payload. + +The owner's checkpoint tick is stored in its manifest. An empty creation batch +may advance that tick while all biology remains unchanged; it implies no offline +progress, reserve consumption or biological timer advancement. Before replay, +the caller must match predecessor commit, predecessor digest and begin tick with +the trusted committed head. These chain checks and durable control/reservation +validation belong to publication, not to this storage-free codec. + +Existing environmental trace formats and payload goldens are unchanged. Durable +profile registration, atomic life publication and session integration remain +separate delivery subsections. diff --git a/src/server/lifecycle/primitive_batch.cpp b/src/server/lifecycle/primitive_batch.cpp new file mode 100644 index 0000000..74bb4ec --- /dev/null +++ b/src/server/lifecycle/primitive_batch.cpp @@ -0,0 +1,149 @@ +#include "evo/server/lifecycle/primitive_batch.hpp" +#include +#include + +namespace evo::server { +namespace { +constexpr std::uint64_t magic = 0x31425446494C5645ULL; +bool zero(const auto& bytes) { + return std::ranges::all_of(bytes, [](auto b) { return b == 0; }); +} +bool valid(const PrimitiveBatch& batch) { + const auto& h = batch.header; + if (h.world == 0 || h.region == 0 || h.frame == 0 || zero(h.predecessor) || + zero(h.predecessor_digest) || h.end_tick <= h.begin_tick || + h.end_tick - h.begin_tick > 64 || batch.births.size() > max_primitive_lives) + return false; + for (std::size_t i = 0; i < batch.births.size(); ++i) { + const auto& b = batch.births[i]; + if (zero(b.request.account) || b.request.action == 0 || b.identity == 0 || + b.generation == 0 || b.born.value <= h.begin_tick || b.born.value > h.end_tick) + return false; + if (i > 0) { + const auto& p = batch.births[i - 1]; + if (std::tie(p.born.value, p.request.account, p.request.action) >= + std::tie(b.born.value, b.request.account, b.request.action)) + return false; + } + for (std::size_t j = 0; j < i; ++j) + if (batch.births[j].request.account == b.request.account || + batch.births[j].identity == b.identity) + return false; + } + return true; +} +void put(std::vector& out, std::uint64_t value, unsigned width) { + for (unsigned i = 0; i < width; ++i) { + out.push_back(static_cast(value & 255U)); + value >>= 8U; + } +} +class Reader { + public: + explicit Reader(std::span bytes) : bytes_(bytes) {} + std::uint64_t get(unsigned width) { + std::uint64_t value{}; + for (unsigned i = 0; i < width; ++i) + value |= std::uint64_t{bytes_[at_++]} << (8U * i); + return value; + } + template std::array array() { + std::array out{}; + for (auto& b : out) + b = bytes_[at_++]; + return out; + } + + private: + std::span bytes_; + std::size_t at_{}; +}; +} // namespace + +std::expected, PrimitiveBatchError> +encode_primitive_batch(const PrimitiveBatch& batch) { + if (!valid(batch)) + return std::unexpected{PrimitiveBatchError::format}; + std::vector out; + out.reserve(primitive_batch_header_bytes + batch.births.size() * primitive_birth_bytes); + put(out, magic, 8); + put(out, primitive_batch_format, 4); + put(out, batch.births.size(), 4); + const auto& h = batch.header; + for (const auto v : {h.world, h.region, h.frame}) + put(out, v, 8); + out.insert(out.end(), h.predecessor.begin(), h.predecessor.end()); + out.insert(out.end(), h.predecessor_digest.begin(), h.predecessor_digest.end()); + put(out, h.begin_tick, 8); + put(out, h.end_tick, 8); + put(out, 0, 8); + for (const auto& b : batch.births) { + out.insert(out.end(), b.request.account.begin(), b.request.account.end()); + for (const auto v : {b.request.action, b.identity, b.generation, b.born.value}) + put(out, v, 8); + } + return out; +} + +std::expected +decode_primitive_batch(std::span bytes) { + if (bytes.size() < primitive_batch_header_bytes || bytes.size() > max_primitive_batch_bytes) + return std::unexpected{PrimitiveBatchError::format}; + Reader r{bytes}; + if (r.get(8) != magic) + return std::unexpected{PrimitiveBatchError::format}; + if (r.get(4) != primitive_batch_format) + return std::unexpected{PrimitiveBatchError::version}; + const auto count = r.get(4); + if (count > max_primitive_lives || + bytes.size() != primitive_batch_header_bytes + count * primitive_birth_bytes) + return std::unexpected{PrimitiveBatchError::format}; + PrimitiveBatch out; + auto& h = out.header; + h.world = r.get(8); + h.region = r.get(8); + h.frame = r.get(8); + h.predecessor = r.array<16>(); + h.predecessor_digest = r.array<32>(); + h.begin_tick = r.get(8); + h.end_tick = r.get(8); + if (r.get(8) != 0) + return std::unexpected{PrimitiveBatchError::format}; + out.births.reserve(static_cast(count)); + for (std::uint64_t i = 0; i < count; ++i) { + PrimitiveBirth b; + b.request.account = r.array<16>(); + b.request.action = r.get(8); + b.identity = r.get(8); + b.generation = r.get(8); + b.born.value = r.get(8); + out.births.push_back(b); + } + if (!valid(out)) + return std::unexpected{PrimitiveBatchError::format}; + return out; +} + +std::expected, PrimitiveBatchError> +replay_primitive_batch(const PrimitiveLives& base, const PrimitiveBatch& batch) { + if (!valid(batch)) + return std::unexpected{PrimitiveBatchError::format}; + const auto& c = base.config(); + const auto& h = batch.header; + if (c.world != h.world || c.region != h.region || c.frame != h.frame || + std::ranges::any_of(base.lives(), [&](const auto& life) { + return life.identity.born.value > h.begin_tick; + })) + return std::unexpected{PrimitiveBatchError::scope}; + auto candidate = PrimitiveLives::restore(base.snapshot(), c.world, c.region, c.frame); + if (!candidate) + return std::unexpected{PrimitiveBatchError::state}; + for (const auto& b : batch.births) { + const LifeAllocation allocation{b.identity, b.identity, b.identity, b.identity, b.born}; + const auto created = (*candidate)->spawn(b.request, allocation); + if (!created || created->identity != allocation) + return std::unexpected{PrimitiveBatchError::state}; + } + return std::move(*candidate); +} +} // namespace evo::server diff --git a/tests/primitive_lives_tests.cpp b/tests/primitive_lives_tests.cpp index 7f7184d..10c33ef 100644 --- a/tests/primitive_lives_tests.cpp +++ b/tests/primitive_lives_tests.cpp @@ -1,3 +1,4 @@ +#include "evo/server/lifecycle/primitive_batch.hpp" #include "evo/server/lifecycle/primitive_lives.hpp" #include @@ -249,6 +250,97 @@ void recover_complete_creation_state() { changed.assign(max_primitive_lives_bytes + 1, 0); CHECK(!PrimitiveLives::restore(changed, 90, 1, 7)); } +void creation_batches_are_atomic_and_replayable() { + PrimitiveBatch batch; + batch.header = {90, 1, 7, {}, {}, 0, 20}; + batch.header.predecessor.back() = 1; + batch.header.predecessor_digest.back() = 2; + batch.births = {{request(1), 101, 9, {5}}, {request(2), 102, 10, {10}}}; + const auto encoded = encode_primitive_batch(batch); + CHECK(encoded && encoded->size() == primitive_batch_header_bytes + 2 * primitive_birth_bytes); + const auto decoded = decode_primitive_batch(*encoded); + CHECK(decoded && *decoded == batch); + CHECK(encode_primitive_batch(*decoded) == *encoded); + auto base = PrimitiveLives::create(config()); + CHECK(base); + const auto opening = (*base)->snapshot(); + auto replayed = replay_primitive_batch(**base, batch); + CHECK(replayed && (*replayed)->lives().size() == 2); + CHECK((*base)->snapshot() == opening); + CHECK((*replayed)->totals() == (*base)->totals()); + auto direct = PrimitiveLives::create(config()); + CHECK(direct); + CHECK((*direct)->spawn(request(1), {101, 101, 101, 101, {5}})); + CHECK((*direct)->spawn(request(2), {102, 102, 102, 102, {10}})); + CHECK((*direct)->snapshot() == (*replayed)->snapshot()); + // Failure of a later birth discards the earlier funded birth too. + auto scarce = PrimitiveLives::create(config(1)); + CHECK(scarce); + const auto before = (*scarce)->snapshot(); + CHECK(!replay_primitive_batch(**scarce, batch)); + CHECK((*scarce)->snapshot() == before); + auto wrong_scope = batch; + wrong_scope.header.region = 2; + CHECK(!replay_primitive_batch(**base, wrong_scope)); + CHECK(!replay_primitive_batch(**replayed, batch)); // Base includes births after begin. + auto idle = batch; + idle.header.begin_tick = 20; + idle.header.end_tick = 40; + idle.births.clear(); + const auto idle_bytes = encode_primitive_batch(idle); + CHECK(idle_bytes && idle_bytes->size() == primitive_batch_header_bytes); + auto advanced = replay_primitive_batch(**replayed, idle); + CHECK(advanced && (*advanced)->snapshot() == (*replayed)->snapshot()); + auto duplicate = idle; + duplicate.births = {{request(1), 101, 11, {21}}}; + CHECK(!replay_primitive_batch(**replayed, duplicate)); // Retry isn't a new birth. + + for (std::size_t size = 0; size < encoded->size(); ++size) + CHECK(!decode_primitive_batch(std::span{*encoded}.first(size))); + auto trailing = *encoded; + trailing.push_back(0); + CHECK(!decode_primitive_batch(trailing)); + CHECK(!decode_primitive_batch(std::vector(max_primitive_batch_bytes + 1))); + for (const auto offset : {std::size_t{0}, std::size_t{8}, std::size_t{12}, std::size_t{104}}) { + auto bad = *encoded; + bad[offset] ^= 1U; + CHECK(!decode_primitive_batch(bad)); + } + const auto refuses = [&](auto mutate) { + auto bad = batch; + mutate(bad); + CHECK(!encode_primitive_batch(bad)); + CHECK(!replay_primitive_batch(**base, bad)); + CHECK((*base)->snapshot() == opening); + }; + refuses([](auto& b) { b.header.world = 0; }); + refuses([](auto& b) { b.header.predecessor = {}; }); + refuses([](auto& b) { b.header.predecessor_digest = {}; }); + refuses([](auto& b) { b.header.begin_tick = 20; }); + refuses([](auto& b) { b.header.end_tick = 65; }); + refuses([](auto& b) { b.births[0].born.value = 0; }); + refuses([](auto& b) { b.births[1].born.value = 21; }); + refuses([](auto& b) { b.births[0].generation = 0; }); + refuses([](auto& b) { b.births[0].identity = 0; }); + refuses([](auto& b) { b.births[0].request.action = 0; }); + refuses([](auto& b) { b.births[0].request.account = {}; }); + refuses([](auto& b) { b.births[1].identity = b.births[0].identity; }); + refuses([](auto& b) { b.births[1].request.account = b.births[0].request.account; }); + refuses([](auto& b) { std::swap(b.births[0], b.births[1]); }); + auto bound = batch; + bound.births.clear(); + for (std::size_t i = 1; i <= max_primitive_lives; ++i) { + auto r = request(1); + r.account[14] = static_cast(i >> 8U); + r.account[15] = static_cast(i & 255U); + bound.births.push_back({r, i, 1, {1}}); + } + auto maximum = encode_primitive_batch(bound); + CHECK(maximum && maximum->size() == max_primitive_batch_bytes); + CHECK(decode_primitive_batch(*maximum) == bound); + bound.births.push_back(bound.births.back()); + CHECK(!encode_primitive_batch(bound)); +} } // namespace int main() try { @@ -257,6 +349,7 @@ int main() try { every_channel_must_be_funded(); invalid_sites_and_bounds(); recover_complete_creation_state(); + creation_batches_are_atomic_and_replayable(); std::puts("PASS primitive lives: funded bodies, equal starts, atomic refusals and retries"); return 0; } catch (const std::exception& e) {