Declare portable primitive checkpoint profile (M11.2c-2b)
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m59s
Foundation / checks (client) (push) Successful in 12m24s
Foundation / checks (network) (push) Successful in 13m51s
Foundation / checks (tsan) (push) Successful in 8m7s
Foundation / checks (checks) (push) Successful in 33m53s
Foundation / checks (postgres) (push) Successful in 46m23s
Foundation / server-image (push) Successful in 24s
Foundation / postgres-tools (push) Successful in 1m36s
Foundation / image (push) Successful in 2m45s

This commit is contained in:
dingo
2026-10-10 05:00:15 -04:00
parent 41237bd289
commit 7b6f722b1b
9 changed files with 215 additions and 22 deletions
+1 -1
View File
@@ -111,7 +111,7 @@ evo_owned_target(evo_ops)
# Portable checkpoint manifest codec and environmental-v1 payload validation.
add_library(evo_region_checkpoint STATIC src/persistence/region_checkpoint.cpp src/persistence/region_batch.cpp)
add_library(evo::region_checkpoint ALIAS evo_region_checkpoint)
target_link_libraries(evo_region_checkpoint PUBLIC evo::region_lease evo::processes)
target_link_libraries(evo_region_checkpoint PUBLIC evo::region_lease evo::processes evo::lifecycle)
evo_owned_target(evo_region_checkpoint)
include(CTest)
+3
View File
@@ -74,6 +74,9 @@ Local checks do not close ADR-0097's reference-worker qualification.
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-2b: portable primitive checkpoint profile 3, history profile 2, complete
payload closure and bounded birth traces. SQL admission remains disabled until
guarded publication atomically binds bodies and reservations.
- 11.2c-2 and 11.2d remain: atomic funded checkpoint publication, reconciliation,
host/session integration and crash-boundary qualification.
+27
View File
@@ -5574,3 +5574,30 @@ and affected lifecycle tests; repository format-check and diff checks. All passe
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.
## 2026-10-10 — M11.2c-2b portable checkpoint profile
Primitive profile 3 declares history profile 2, its version bundle, exact 50 ms
quantum, funded payload closure and bounded creation traces. Tests cover genesis,
successors, idle cuts, future/zero births, scope, versions, lengths, trace bounds,
foreign identity allocations and rejection of unsupported clone genesis. Existing
environmental profile tests and goldens are unchanged. SQL v15 still rejects
profile 3; portable support does not yet enable durable life publication.
Executed successfully: Linux GCC 14 debug 62/62, Clang 19 ASan+UBSan 62/62,
Windows MSVC Release/NDEBUG 62/62, Windows network preset 2/2, and Windows QUIC
preset 5/5 on an isolated rerun. The first QUIC run failed the existing healthy-idle
heartbeat check at network_session.cpp:618 while network compilation and sanitizer
tests ran concurrently; every other QUIC check passed. The same binary passed all
five checks without competing build/test load. No network source was changed.
Clang-tidy 19 on the changed implementation/tests, full format-check and diff checks
passed. No database migration, provisioning or deployment was performed here.
The PostgreSQL server/clone caller build exposed GCC 14 Release's
`free-nonheap-object` diagnostic in the new trace encoder's vector growth path.
The encoder now allocates its exact bounded size once and writes through a cursor;
no warning suppression or format change. The final GCC Release server/clone build
and both lifecycle/checkpoint tests passed. The revised encoder was rechecked with
ASan+UBSan (both tests), clang-tidy/format, and Windows Release 62/62. WSL temporary
logs disappeared after process exit; the reproduced build log was retained under
`build/m112-profile-callers.log` instead.
+15 -2
View File
@@ -3,6 +3,7 @@
#include "evo/persistence/region_lease.hpp"
#include "evo/processes/environmental_community.hpp"
#include "evo/processes/lineage_region.hpp"
#include "evo/server/lifecycle/primitive_batch.hpp"
#include <cstddef>
#include <cstdint>
#include <expected>
@@ -20,9 +21,12 @@ enum class CheckpointProfile : std::uint8_t {
unknown = 0,
environmental_v1 = 1, // Environmental envelope only; history_profile 0.
environmental_lineage_v1 = 2, // LineageRegion container; history_profile 1.
primitive_lives_v1 = 3, // Funded creation state; history_profile 2.
};
// history_profile 1: lineage archive format 1 with genome schema 1.
inline constexpr std::uint32_t lineage_history_profile = 1;
// Archive format 1, genome schema 2, development 2, founder-life rules 1.
inline constexpr std::uint32_t primitive_history_profile = 2;
// Declared durability, verified at deployment. Development: one volume, no host-loss claim.
enum class DurabilityPolicy : std::uint8_t { unknown = 0, single_volume_development = 1 };
@@ -34,6 +38,8 @@ struct VersionBundle {
friend bool operator==(const VersionBundle&, const VersionBundle&) = default;
};
inline constexpr VersionBundle environmental_v1_versions{};
// No field or terrain state in this explicitly provisioned nursery profile.
inline constexpr VersionBundle primitive_v1_versions{1, 1, 1, 0, 0, 1, 1, 1, 1};
// Batch evidence bound by manifest v2 (ADR-0063); all zero at genesis.
struct BatchDigests {
@@ -63,7 +69,7 @@ struct CheckpointManifest {
VersionBundle versions{};
Sha256Digest build{}; // Retained immutable build artifact identity.
std::uint32_t rng_streams{}; // These rules use no randomness: 0.
std::uint32_t history_profile{}; // 0 environmental-v1; 1 environmental-lineage-v1.
std::uint32_t history_profile{}; // 0 environmental; 1 lineage; 2 primitive lives.
DurabilityPolicy durability{DurabilityPolicy::single_volume_development};
std::uint64_t payload_bytes{};
Sha256Digest payload_sha256{};
@@ -79,7 +85,8 @@ inline constexpr std::size_t max_lineage_payload_bytes = processes::max_lineage_
[[nodiscard]] constexpr std::size_t max_payload_bytes(CheckpointProfile profile) noexcept {
return profile == CheckpointProfile::environmental_v1 ? max_environmental_payload_bytes
: profile == CheckpointProfile::environmental_lineage_v1 ? max_lineage_payload_bytes
: 0;
: profile == CheckpointProfile::primitive_lives_v1 ? server::max_primitive_lives_bytes
: 0;
}
inline constexpr std::uint64_t max_checkpoint_ticks = 64;
@@ -133,4 +140,10 @@ restore_environmental_payload(std::span<const std::uint8_t> payload,
[[nodiscard]] std::expected<std::unique_ptr<processes::LineageRegion>, CheckpointError>
restore_lineage_payload(std::span<const std::uint8_t> payload, const CheckpointManifest& manifest,
std::size_t budget);
// Creation-only profile: canonical funded closure, all births <= manifest tick,
// no organisms at genesis. Manifest owns the checkpoint clock; no biology steps.
// Length and SHA-256 must be verified by the object-store caller as above.
[[nodiscard]] std::expected<std::unique_ptr<server::PrimitiveLives>, CheckpointError>
restore_primitive_payload(std::span<const std::uint8_t> payload,
const CheckpointManifest& manifest);
} // namespace evo::persistence
+32
View File
@@ -0,0 +1,32 @@
# Primitive creation checkpoint profile 3
ADR-0100, M11.2c-2b. This is the portable profile declaration. Database schema v15
still refuses profile 3; database admission requires atomic life publication and
must not be enabled by merely widening the SQL manifest parser.
The manifest uses the existing 360-byte version 2 layout. Profile is 3; history
profile is 2 (lineage archive format 1, genome schema 2, development 2, founder-life
rules 1). Quantum is exactly 50,000 microseconds. RNG stream count is zero;
durability policy is single-volume development (1).
The version bundle is `(1,1,1,0,0,1,1,1,1)`: founder-life rules, primitive-lives
envelope, inventory contract, no field state, no terrain state, micrometre-local
coordinates, founder generation contract, material accounting, and rate conversion
contract. Zero fields/terrain mean absent in this explicitly provisioned nursery,
not an implicit terrain simulation. New biological state needs versioned closure.
Payload is [primitive-lives-v1](primitive-lives-v1.md), bounded by
`200 + 184*256 + biology::max_archive_bytes`. Full canonical restore checks its
scope, funding, body/reserve/heat, placement and archive. Every birth is at a tick
in `1..manifest.end_tick`; one reserved identity is used in the four distinct
life/organism/genome/event namespaces. Provisioned genesis has no organisms.
Non-genesis trace is [primitive-batch-v1](primitive-batch-v1.md), 112..12,400 bytes
in 48-byte increments. Its SHA-256 is nonzero. Environmental two-actor decisions
are absent: count zero and digest zero. Genesis has no trace or decisions.
The manifest owns the checkpoint clock; an idle batch advances no biology.
Clone genesis is refused until life/account bindings and world allocator ranges
have a reviewed isolated-clone mapping. Existing environmental profiles, clone
contracts and goldens remain unchanged. Portable support does not yet imply
publication, backup/audit or server-host support for this new profile.
+5
View File
@@ -1,5 +1,10 @@
# Region commit manifest contract v1 (M7.1 design, M7.4a encoding)
M11.2 adds the portable [primitive creation profile 3](primitive-checkpoint-v1.md)
using manifest v2. Its history, versions, payload and trace rules differ from the
environmental profiles below. Schema v15 does not yet admit profile 3; guarded
atomic publication is a separate migration requirement.
## Canonical manifest encoding v1/v2 (ADR-0061, ADR-0063)
The encoder, decoder and `supported()` check live in
+48 -4
View File
@@ -58,6 +58,10 @@ bool structural(const CheckpointManifest& m) noexcept {
m.payload_bytes > limit || zero(m.payload_sha256))
return false;
const auto& b = m.batch;
const bool primitive = m.profile == CheckpointProfile::primitive_lives_v1;
if (primitive && (m.manifest_version != 2 || m.tick_microseconds != 50000 ||
b.decision_count != 0 || !zero(b.decisions_sha256)))
return false;
if (m.manifest_version != 1 && m.manifest_version != 2)
return false;
const bool no_batch = b == BatchDigests{};
@@ -66,6 +70,9 @@ bool structural(const CheckpointManifest& m) noexcept {
b.trace_bytes == 0 && zero(b.trace_sha256);
if (zero(m.predecessor_commit) && zero(m.predecessor_digest))
return genesis && m.end_tick == 0 && no_batch;
// Primitive cloning needs explicit life-binding remapping; not admitted yet.
if (primitive)
return false;
// Clone genesis (ADR-0067, v2 only): the origin is the source commit and
// manifest digest; the block digests inherited permanent outcomes.
return genesis && m.manifest_version == 2 && !zero(m.predecessor_commit) &&
@@ -79,14 +86,24 @@ bool structural(const CheckpointManifest& m) noexcept {
m.end_tick - m.begin_tick <= max_checkpoint_ticks;
if (m.manifest_version == 1)
return link && no_batch;
// v2: the trace has exactly one step per tick; decisions are bounded.
return link && b.trace_bytes == trace_bytes_for(m.end_tick - m.begin_tick) &&
!zero(b.trace_sha256) && b.decision_count <= max_batch_decisions &&
const bool trace_shape = primitive
? b.trace_bytes >= server::primitive_batch_header_bytes &&
b.trace_bytes <= server::max_primitive_batch_bytes &&
(b.trace_bytes - server::primitive_batch_header_bytes) %
server::primitive_birth_bytes ==
0
: b.trace_bytes == trace_bytes_for(m.end_tick - m.begin_tick);
return link && trace_shape && !zero(b.trace_sha256) &&
b.decision_count <= max_batch_decisions &&
(b.decision_count == 0) == zero(b.decisions_sha256);
}
} // namespace
bool supported(const CheckpointManifest& m) noexcept {
if (m.profile == CheckpointProfile::primitive_lives_v1)
return m.manifest_version == 2 && m.history_profile == primitive_history_profile &&
m.versions == primitive_v1_versions && m.tick_microseconds == 50000 &&
m.rng_streams == 0 && m.durability == DurabilityPolicy::single_volume_development;
const bool profile =
(m.profile == CheckpointProfile::environmental_v1 && m.history_profile == 0) ||
(m.profile == CheckpointProfile::environmental_lineage_v1 &&
@@ -197,6 +214,10 @@ genesis_manifest(RegionKey key, std::uint64_t frame, Uuid commit, std::uint64_t
m.profile = profile;
m.history_profile =
profile == CheckpointProfile::environmental_lineage_v1 ? lineage_history_profile : 0;
if (profile == CheckpointProfile::primitive_lives_v1) {
m.history_profile = primitive_history_profile;
m.versions = primitive_v1_versions;
}
m.key = key;
m.frame = frame;
m.commit = commit;
@@ -213,7 +234,7 @@ std::expected<CheckpointManifest, CheckpointError>
clone_manifest(const CheckpointManifest& source, const Sha256Digest& source_digest,
RegionKey target, Uuid commit, std::uint64_t payload_bytes,
const Sha256Digest& payload_sha256, const BatchDigests& inherited) {
if (!supported(source))
if (!supported(source) || source.profile == CheckpointProfile::primitive_lives_v1)
return std::unexpected{CheckpointError::unsupported};
if (!structural(source) || target.world == source.key.world || commit == source.commit ||
inherited.trace_bytes != 0 || !zero(inherited.trace_sha256))
@@ -318,4 +339,27 @@ restore_lineage_payload(std::span<const std::uint8_t> payload, const CheckpointM
return std::unexpected{CheckpointError::payload};
return std::move(*restored);
}
std::expected<std::unique_ptr<server::PrimitiveLives>, CheckpointError>
restore_primitive_payload(std::span<const std::uint8_t> payload, const CheckpointManifest& m) {
if (!structural(m))
return std::unexpected{CheckpointError::format};
if (!supported(m) || m.profile != CheckpointProfile::primitive_lives_v1)
return std::unexpected{CheckpointError::unsupported};
if (payload.size() != m.payload_bytes)
return std::unexpected{CheckpointError::payload};
auto restored = server::PrimitiveLives::restore(payload, m.key.world, m.key.region, m.frame);
if (!restored)
return std::unexpected{restored.error() == server::LifeCodecError::version
? CheckpointError::unsupported
: CheckpointError::payload};
if ((m.sequence == 0 && !(*restored)->lives().empty()) ||
std::ranges::any_of((*restored)->lives(), [&](const auto& life) {
return life.identity.born.value == 0 || life.identity.born.value > m.end_tick ||
life.identity.life != life.identity.organism ||
life.identity.life != life.identity.genome ||
life.identity.life != life.identity.event;
}))
return std::unexpected{CheckpointError::payload};
return std::move(*restored);
}
} // namespace evo::persistence
+20 -15
View File
@@ -32,9 +32,9 @@ bool valid(const PrimitiveBatch& batch) {
}
return true;
}
void put(std::vector<std::uint8_t>& out, std::uint64_t value, unsigned width) {
void put(std::span<std::uint8_t> out, std::size_t& at, std::uint64_t value, unsigned width) {
for (unsigned i = 0; i < width; ++i) {
out.push_back(static_cast<std::uint8_t>(value & 255U));
out[at++] = static_cast<std::uint8_t>(value & 255U);
value >>= 8U;
}
}
@@ -64,23 +64,28 @@ std::expected<std::vector<std::uint8_t>, PrimitiveBatchError>
encode_primitive_batch(const PrimitiveBatch& batch) {
if (!valid(batch))
return std::unexpected{PrimitiveBatchError::format};
std::vector<std::uint8_t> 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);
std::vector<std::uint8_t> out(primitive_batch_header_bytes +
batch.births.size() * primitive_birth_bytes);
std::size_t at{};
const auto array = [&](const auto& bytes) {
for (const auto b : bytes)
out[at++] = b;
};
put(out, at, magic, 8);
put(out, at, primitive_batch_format, 4);
put(out, at, 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);
put(out, at, v, 8);
array(h.predecessor);
array(h.predecessor_digest);
put(out, at, h.begin_tick, 8);
put(out, at, h.end_tick, 8);
put(out, at, 0, 8);
for (const auto& b : batch.births) {
out.insert(out.end(), b.request.account.begin(), b.request.account.end());
array(b.request.account);
for (const auto v : {b.request.action, b.identity, b.generation, b.born.value})
put(out, v, 8);
put(out, at, v, 8);
}
return out;
}
+64
View File
@@ -336,6 +336,69 @@ void clone_genesis() {
half.predecessor_commit = {};
CHECK(encode_manifest(half).error() == CheckpointError::format);
}
void primitive_profile() {
using namespace evo::server;
const auto endowment = evo::biology::primitive_endowment();
CHECK(endowment);
auto funding = endowment->body;
funding.energy.value = endowment->reserve.energy.value + endowment->construction.value;
auto state = PrimitiveLives::create({7, 3, 9, 1, funding, {{0, 0}}});
CHECK(state);
const auto opening = (*state)->snapshot();
auto g = genesis_manifest(key, 9, filled<16>(1), 50000, build, opening.size(), filled<32>(2),
CheckpointProfile::primitive_lives_v1);
CHECK(g && supported(*g) && g->history_profile == primitive_history_profile &&
g->versions == primitive_v1_versions);
CHECK(restore_primitive_payload(opening, *g));
CHECK(decode_manifest(*encode_manifest(*g)) == *g);
CHECK(!restore_environmental_payload(opening, *g, 8000000));
CHECK(!restore_lineage_payload(opening, *g, 8000000));
CHECK(!clone_manifest(*g, filled<32>(1), {8, 3}, filled<16>(3), opening.size(), filled<32>(2),
{}));
LifeRequest r{filled<16>(4), 1};
CHECK((*state)->spawn(r, {12, 12, 12, 12, {5}}));
const auto born = (*state)->snapshot();
auto n = successor_manifest(
*g, filled<32>(3), filled<16>(2), lease(), 5, build, born.size(), filled<32>(4),
{primitive_batch_header_bytes + primitive_birth_bytes, filled<32>(5), 0, {}});
CHECK(n && supported(*n));
CHECK(restore_primitive_payload(born, *n));
const auto invalid = [&](auto mutate, CheckpointError error) {
auto changed = *n;
mutate(changed);
const auto result = restore_primitive_payload(born, changed);
CHECK(!result && result.error() == error);
};
invalid([](auto& m) { m.end_tick = 4; }, CheckpointError::payload);
invalid([](auto& m) { m.key.region = 99; }, CheckpointError::payload);
invalid([](auto& m) { m.frame = 99; }, CheckpointError::payload);
invalid([](auto& m) { --m.payload_bytes; }, CheckpointError::payload);
invalid([](auto& m) { ++m.versions.envelope; }, CheckpointError::unsupported);
invalid([](auto& m) { m.history_profile = 1; }, CheckpointError::unsupported);
invalid([](auto& m) { m.tick_microseconds = 100000; }, CheckpointError::format);
invalid([](auto& m) { ++m.batch.trace_bytes; }, CheckpointError::format);
invalid([](auto& m) { m.batch.trace_bytes = 0; }, CheckpointError::format);
invalid(
[](auto& m) { m.batch.trace_bytes = max_primitive_batch_bytes + primitive_birth_bytes; },
CheckpointError::format);
invalid(
[](auto& m) {
m.batch.decision_count = 1;
m.batch.decisions_sha256 = filled<32>(6);
},
CheckpointError::format);
auto forged_genesis = *g;
forged_genesis.payload_bytes = born.size();
CHECK(!restore_primitive_payload(born, forged_genesis));
// An idle checkpoint preserves biology while the manifest advances its clock.
auto idle =
successor_manifest(*n, filled<32>(6), filled<16>(3), lease(), 10, build, born.size(),
filled<32>(4), {primitive_batch_header_bytes, filled<32>(7), 0, {}});
CHECK(idle && restore_primitive_payload(born, *idle));
auto mismatched_ids = PrimitiveLives::create({7, 3, 9, 1, funding, {{0, 0}}});
CHECK(mismatched_ids && (*mismatched_ids)->spawn(r, {12, 13, 14, 15, {5}}));
CHECK(!restore_primitive_payload((*mismatched_ids)->snapshot(), *n));
}
} // namespace
int main() {
@@ -346,6 +409,7 @@ int main() {
payload_validation_and_restored_trajectory();
lineage_profile();
clone_genesis();
primitive_profile();
std::puts("region checkpoint contracts passed");
return 0;
} catch (const std::exception& e) {