feat(lifecycle): replay retained offspring plans with explicit trace version
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

This commit is contained in:
dingo
2026-10-19 14:04:52 -04:00
parent 2c3a3c65a6
commit c0c66fa11a
15 changed files with 673 additions and 35 deletions
+10
View File
@@ -705,6 +705,16 @@ if(BUILD_TESTING)
"-DTEST_DIR=${CMAKE_CURRENT_BINARY_DIR}/inheritance-restart"
-P "${CMAKE_CURRENT_SOURCE_DIR}/tests/cellular_population_restart.cmake")
set_tests_properties(cellular-inheritance-process-restart PROPERTIES TIMEOUT ${evo_cohort_timeout})
add_executable(evo-cellular-inheritance-replay-tests tests/cellular_inheritance_replay_tests.cpp)
target_link_libraries(evo-cellular-inheritance-replay-tests PRIVATE evo::lifecycle)
evo_owned_target(evo-cellular-inheritance-replay-tests)
add_test(NAME cellular-inherited-replay COMMAND evo-cellular-inheritance-replay-tests)
set_tests_properties(cellular-inherited-replay PROPERTIES TIMEOUT ${evo_cohort_timeout})
add_test(NAME cellular-inherited-replay-process-restart COMMAND "${CMAKE_COMMAND}"
"-DPOPULATION_TEST=$<TARGET_FILE:evo-cellular-inheritance-replay-tests>"
"-DTEST_DIR=${CMAKE_CURRENT_BINARY_DIR}/inheritance-replay-restart"
-P "${CMAKE_CURRENT_SOURCE_DIR}/tests/cellular_population_restart.cmake")
set_tests_properties(cellular-inherited-replay-process-restart PROPERTIES TIMEOUT ${evo_cohort_timeout})
add_executable(evo-cellular-maturation-tests tests/cellular_maturation_tests.cpp)
target_link_libraries(evo-cellular-maturation-tests PRIVATE evo::lifecycle)
evo_owned_target(evo-cellular-maturation-tests)
+7
View File
@@ -211,6 +211,13 @@ portable contract. [Format 8](schemas/cellular-lives-v8.md) is not admitted to
existing durable bundles or live entry. Control succession and behavior/UI
integration remain pending.
[Inherited-plan replay](schemas/cellular-region-batch-v4.md) uses explicit raw
trace 4 with owner 8/rules 10; old defaults remain trace 3. Build
`evo-cellular-inheritance-replay-tests`; CTest `cellular-inherited-replay` and
`cellular-inherited-replay-process-restart` compare recorded inputs and complete
results with direct execution, including same-tick selection/birth. This is a
portable prerequisite for durable admission.
M5.1 local voxel/address API and scope: [local voxel contract](docs/world/LOCAL_VOXEL_CONTRACT.md).
M5.8 process restart proof and measured costs: [world proof](docs/engineering/WORLD_PROOF.md).
@@ -12,7 +12,7 @@ spec:
env:
- {name: REGION_SESSION, value: "dev"}
- {name: REGION_SESSION_LISTEN, value: "0.0.0.0:7400"}
- {name: REGION_SESSION_WINDOW, value: "dev-20261019T173417-a98f9f06:1792445657"}
- {name: REGION_SESSION_WINDOW, value: "dev-20261019T180417-2aacb0ba:1792447457"}
- {name: REGION_M10_MAX_GRANT_LIFETIME, value: "14400"}
ports:
# QUIC (ADR-0090): UDP only; nothing listens on TCP 7400.
+15
View File
@@ -1,5 +1,20 @@
# Project status and next steps
## Portable inherited-plan replay - 2026-10-19
[ADR-0166](adr/0166-retained-plan-replay-traces.md) adds raw trace 4 exclusively
for owner format 8/rules 10. Recorded selections, same-tick funded offspring,
declines and later plan changes reproduce direct execution exactly. Action
matching uses the inherited offer even when it differs from the parent's body.
Failed batches expose no candidate or partial mutation outcome list.
Both full MSVC/GCC Release suites pass **87/87**. Fresh-process replay produces
identical final bytes on both compilers; analysis, formatting and focused
ASan/UBSan checks pass. [Validation](engineering/VALIDATION.md) records scope.
Trace 3 remains the default. Durable plan/bundle admission, population/census/
migration integration, control succession, retained NPC behavior and choice UI
remain open; this portable prerequisite does not complete M12.
## Portable retained offspring plans - 2026-10-19
[ADR-0165](adr/0165-retained-cellular-offspring-plans.md) implements an opt-in
@@ -0,0 +1,68 @@
# ADR-0166: Retained-plan replay traces
## Status and scope
Accepted portable replay segment of ADR-0163/0165, 2026-10-19. No new biology,
durable bundle, SQL admission, worker default, control handoff or UI contract.
## Context
Owner format 8/rules 10 retains inherited plans separately from expressed bodies.
Trace 3 describes the earlier in-life mutation path. Admitting the new owner
under that trace would make the same recorded selection have two meanings.
Matching an inherited offer to the expressed genome would also reject legitimate
later plan selections. Portable replay is needed before durable qualification.
## Decision
Add explicit raw cellular trace format 4, paired exclusively with owner format
8/rules 10. Keep formats 1-3 and the default trace-3 constant unchanged. Trace 4
uses the same bounded header, life/birth/selection layouts and canonical ordering
as trace 3, but its selections edit inherited plans under rules 10. No client
supplies the selected genome or biological outcome. Mixed/unknown owner/trace
versions refuse, including action matching; in-memory replay must enforce the
same version-specific payload shape as the codec.
Replay restores a detached predecessor, applies each complete tick and derives
actual plan selection outcomes, funded births, archive history and inventory.
Selection precedes budding; allocator-authorized primitive births remain after
the tick. Return the complete candidate and mutation outcomes only on full
success. Any later refusal leaves the predecessor unchanged and clears the
outcome vector, rather than exposing a partial accepted prefix. This tightens
failure reporting for earlier traces without changing successful old bytes or
biology. Outcomes are derived, not trusted trace assertions.
Reuse the existing canonical action blocks. Authoritative accounts, exact
standing offers, event/offer tick, operators and reserved identities remain
required. Under rules 10, match the offer parent to the retained offspring plan;
earlier owners fall back to their expressed genome. Choices must already be
available at the predecessor cut, as in the existing action contract. This does
not authorize choices for offers first earned midway through a recorded batch.
Existing SQL publishers/bundles, population traces, census and migration remain
unchanged and refuse this new combination. Portable decoding/replay is not
publication authority; result 4 (`offspring_plan_applied`) is not admitted by the
old durable result contract. Durable support requires a later explicit versioned
upgrade, retained-source replay, fences and fault qualification.
## Alternatives, consequences and risks
Reusing trace 3 would overload saved meaning. Changing its default would silently
move existing callers onto an unsupported durable version. Duplicating the entire
codec would add two implementations of identical bounded fields. A new semantic
version with shared field handling preserves compatibility at small cost.
Risks include accidental durable admission, mismatched action authority and
partial results surviving a failed replay. Exact allowlists, complete candidate
comparison and adversarial multi-tick tests address those risks. This supplies
replay evidence only; it does not supply account control succession or NPC policy.
## Qualification
Require direct-versus-recorded equality for earned structural selections,
selection plus same-tick funded offspring, later plan changes, declines and
active offspring with a suspended parent. Test action mismatches after a plan
differs from the body, malformed codecs, both cross-version directions, stale
choices and a failure after a successful selection prefix. A fresh process must
restore the predecessor, decode the trace and reproduce complete expected bytes.
Run Release/NDEBUG, analysis/formatting and ASan/UBSan; preserve all old goldens.
+2
View File
@@ -1,5 +1,7 @@
# Architecture decision records
- [ADR-0166: Retained-plan replay traces](0166-retained-plan-replay-traces.md) - explicit raw trace 4 for owner 8/rules 10, inherited-offer action matching and complete-result replay; durable admission remains separate.
- [ADR-0165: Retained cellular offspring plans](0165-retained-cellular-offspring-plans.md) - portable owner format 8/rules 10 keeps expressed bodies separate from earned inherited plans, repeated births and selection history; durable/control/UI integration pending.
- [ADR-0164: Distinct-genome offspring funding](0164-distinct-genome-offspring-funding.md) - pure funded reproduction separates the expressed parent's investment from the inherited child's anatomy and provision; old same-genome behavior retained, owner/control integration pending.
@@ -1,5 +1,11 @@
# Persistence and region authority
[ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds portable raw trace 4
exclusively for the retained-plan owner 8/rules 10. Replay and action matching
preserve expressed/inherited meanings and return outcomes only after the entire
candidate succeeds. Existing trace defaults, SQL bundles, population traces and
result admission remain unchanged. This is not a durable upgrade or live entry.
ADR-0158/schema 53 admits the explicit same-profile bundle-10 -> 11 maturation
upgrade through the existing immutable version journal and lease/head fence.
Recovery rederives the complete retained transformation; raw trace 3 and population
+4 -2
View File
@@ -49,8 +49,10 @@ and dead-parent history, and logout freezes the controlled parent's biology.
This scoped mode edits inherited plans only. The future operator catalog still
needs to distinguish traits that can also change during an existing life. Existing
durable bundles, census, population, migration and batch replay refuse the new
owner until their plan semantics are qualified. The birth-time control choice,
durable bundles, census, population and migration refuse the new owner until
their plan semantics are qualified. [Trace 4](../../schemas/cellular-region-batch-v4.md)
supplies portable replay and inherited-offer action matching; old traces refuse
this owner. The birth-time control choice,
persistent NPC behavior and UI remain unimplemented; default/DEV rules do not
opt into this owner.
+3 -1
View File
@@ -17,7 +17,9 @@ evidence does not close that gap or establish the intended generational gameplay
pure biological funding step with distinct parent/offspring genomes and exact
closure. [ADR-0165](../adr/0165-retained-cellular-offspring-plans.md) adds portable
retained plans and earned selections, unchanged expressed parents and repeated
funded births. Existing same-genome behavior remains. Durable plan/trace/bundle,
funded births. [ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds portable
raw trace-4 replay, action matching and exact process restart. Existing same-genome
behavior remains. Durable plan/trace/bundle,
population/migration/census admission, the in-life expression catalog, authority
handoff and NPC/UI integration are still required.
+58
View File
@@ -1,5 +1,63 @@
# Validation report
## 2026-10-19 - Portable retained-plan trace replay
[ADR-0166](../adr/0166-retained-plan-replay-traces.md) adds explicit raw trace 4
for owner format 8/rules 10. The trace-3 default and successful old canonical
bytes/biology remain unchanged. Codec and in-memory replay enforce versioned
payload shapes; both action matchers enforce owner/trace compatibility and
mutation matching uses the inherited plan. Replay now publishes its outcome
vector only after the complete candidate succeeds, including for older traces.
Decode also checks cross-tick identity/account uniqueness already required by
the encoder. No SQL or durable version admission changed.
Executed locally:
- MSVC 19.44 Release full CTest **87/87 passed, 23.95 s**, with NDEBUG.
- GCC 14.2 Release full CTest **87/87 passed, 16.98 s**, with NDEBUG.
- Clang 19.1 Debug new replay and actual process-restart tests **2/2 passed,
0.96 s**, built with clang-tidy 19 enabled. Changed implementation and tests
compiled under analysis; repository clang-format 19 and diff checks pass.
- Clang 19.1 ASan/UBSan legacy cellular owner, retained plans, new replay and
actual replay process restart **4/4 passed, 44.64 s**, without reports.
- Optional GCC persistence library and cellular session adapter rebuilt; the
session adapter contract passed **1/1, 0.14 s**. No private PostgreSQL runtime
suite was rerun; durable bundle and SQL admission are unchanged.
The new contract compares 64 directly executed ticks to encoded/decoded replay,
including an earned structural selection and real funded offspring in its first
tick, then active offspring while the parent freezes. Later selections match
standing offers whose inherited genome differs from the expressed body; decline
does not admit a genome. It covers action account/life/event/tick/operator/input
mismatches, missing actions, both owner/trace mismatch directions, malformed
counts/reserved bytes/versions, truncation, trailing bytes and stale selections.
A canonically valid trace with an incorrect second-tick living set fails after
a successful selection prefix, leaving the predecessor unchanged and the output
outcome list empty. Two ordinary allocator births reproduce through trace 4;
cross-tick reserved-identity reuse refuses during decode.
The same-tick fixture initially requested birth before enough reserve had been
acquired. It now retains the earned offer, feeds from the unchanged finite
habitat, and waits for a genuine funded birth proposal; no free resources or
biology changes were added. Initial analysis also caught a test optional access;
an explicit runtime guard fixes it. All checks above ran after those corrections.
The process test saves a predecessor with an inherited plan different from its
body, a trace selecting a later plan and the direct expected final owner. A fresh
process restores that predecessor and replays the trace, checking its derived
selection result and complete final bytes. MSVC and GCC expected checkpoints
share SHA-256
`7d6091c4460e0ebcf57e0b0557c7c97a16561c941a83389068db73651e7e758a`.
This is deterministic replay evidence, not durable publication, account authority
or NPC behavior continuity. Existing SQL bundles/results, population traces,
census and migration remain unadmitted for owner 8/rules 10. No private database,
target-host, TSan, actual-days, client/UI or M12 completion evidence is claimed.
The refreshed DEV window expires **2026-10-19 22:04:17 UTC**. Rendered deployment
policy passes: 75 objects in 74 files, 138 rendered objects in 17 overlays, zero
failures. The unchanged policy self-test matrix was not repeated. No deployment
or World0 operation occurred; unrelated untracked work was preserved.
## 2026-10-19 - Portable retained cellular offspring plans
[ADR-0165](../adr/0165-retained-cellular-offspring-plans.md) adds opt-in owner
@@ -20,6 +20,8 @@ struct CellularBatchHeader {
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 {
@@ -98,11 +100,13 @@ 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.
// Owner format 8/rules 10 requires separately qualified trace admission and is refused.
// 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{};
+3 -2
View File
@@ -1,8 +1,9 @@
# Cellular owner format 8: retained offspring plans
Authority: [ADR-0165](../docs/adr/0165-retained-cellular-offspring-plans.md).
Portable opt-in format 8/rules 10 only. No existing durable bundle, population
envelope, batch trace, migration or census adapter admits this version. Earlier
Portable opt-in format 8/rules 10 only. [Raw trace 4](cellular-region-batch-v4.md)
now supplies portable replay. No existing durable bundle, population envelope,
migration or census adapter admits this version. Earlier
canonical formats and their meanings are unchanged.
Little-endian, no native padding. Magic `AEVCLV08`. The first 308 bytes retain
+60
View File
@@ -0,0 +1,60 @@
# Cellular region batch trace 4: retained offspring plans
Authority: [ADR-0166](../docs/adr/0166-retained-plan-replay-traces.md). This is a
portable raw-owner trace, paired exclusively with owner format 8/rules 10.
Existing durable bundles and population traces do not admit it. The default
cellular trace remains format 3. Formats 1-3 keep their successful canonical
bytes and earlier biological meanings.
All integers are little-endian. The layout is identical to
[trace 3](cellular-region-batch-v3.md) except the format field is 4:
| Offset | Bytes | Field |
|---:|---:|---|
| 0 | 8 | Magic `EVLCBT01` |
| 8 | 4 | Format 4 |
| 12 | 4 | Raw cellular profile discriminator 4 |
| 16 | 24 | World, region and frame, three u64s |
| 40 | 16 | Nonzero predecessor commit |
| 56 | 32 | Nonzero predecessor manifest digest |
| 88 | 16 | Begin/end ticks, two u64s |
| 104 | 4 | Tick count, 1 through 64, exactly end minus begin |
| 108 | 4 | Reserved zero |
| 112 | variable | Complete consecutive tick records |
Each tick starts with u32 counts for life intentions, allocator births and
mutation selections, then a zero u32. Arrays follow in that order: existing
24-byte intentions, 40-byte births and 40-byte selections. A selection records
life, event index, offer tick and reserved successor ID as u64s, operator as u16
and six zero bytes. Operator zero declines. Inputs contain no trusted biological
outcome, child genome payload, construction price or parent body replacement.
Use the existing per-tick life bounds and `max_cellular_batch_bytes`; check every
encoded count against remaining bytes before allocation. Refuse unknown formats,
reserved bits, unordered/duplicate keys, cross-tick allocator identity or birth
account reuse, cross-selection successor reuse, truncation and trailing bytes.
The codec and in-memory replay enforce the same version-specific payload shape:
trace 1 has no births/selections; trace 2 has no selections.
Replay binds world/region/frame/begin tick to the predecessor and restores a
detached owner. Only trace 4 with owner 8/rules 10 is accepted; both cross-version
directions refuse before execution, including both action matchers. Apply the
normal rules-10 step, selections and funded budding, then allocator-authorized
primitive births. Existing phase ordering and closure remain mandatory. A later
failed tick/birth returns no candidate or partial mutation outcomes; the input
owner stays byte-identical. Successful outcomes are derived in tick/life order.
The new `offspring_plan_applied` enum value is 4; historical values remain 0-3.
This derived result is not admitted by the old durable result-byte contract.
Canonical movement and mutation action blocks retain their existing layouts.
They must match the authenticated predecessor account/life and exact recorded
input. Mutation selections must match the standing offer's event, tick, operator
and inherited plan, even when that plan differs from the expressed genome.
Offers first earned inside the batch cannot be authorized by that predecessor.
Allocator authority and exact successor reservation binding still belong to
the eventual durable publisher; these portable functions do not grant them.
Before publication, a later bundle must bind manifests, input digests, actions,
reservations, replayed results and the entire final checkpoint under the proper
head/lease fence, with retained-source upgrade and crash/retry qualification.
Merely decoding trace 4 grants no database, worker, migration or census admission.
+44 -28
View File
@@ -32,6 +32,24 @@ bool valid_header(const CellularBatchHeader& h, std::size_t ticks) {
!all_zero(h.predecessor_digest) && h.end_tick > h.begin_tick &&
h.end_tick - h.begin_tick == ticks && ticks > 0 && ticks <= max_cellular_batch_ticks;
}
bool known_format(std::uint32_t format) {
return format == cellular_batch_legacy_format || format == cellular_batch_v2_format ||
format == cellular_batch_format || format == cellular_batch_inheritance_format;
}
bool owner_version_matches(const CellularLives& owner, const CellularBatch& batch) {
if (!known_format(batch.format_version))
return false;
if (batch.format_version == cellular_batch_inheritance_format)
return owner.format_version() == cellular_lives_inheritance_format &&
owner.rules_version() == cellular_lives_inheritance_rules;
return owner.format_version() < cellular_lives_inheritance_format;
}
bool payload_version_matches(const CellularBatch& batch) {
return std::ranges::all_of(batch.ticks, [&](const auto& tick) {
return (batch.format_version >= cellular_batch_v2_format || tick.births.empty()) &&
(batch.format_version >= cellular_batch_format || tick.mutations.empty());
});
}
bool valid_intent(const CellularLifeIntent& life) {
const auto& step = life.intent;
return life.life_id != 0 && step.movement.x >= -movement_limit &&
@@ -153,21 +171,11 @@ void put_intent(std::vector<std::uint8_t>& out, const CellularLifeIntent& life)
std::expected<std::vector<std::uint8_t>, CellularBatchError>
encode_cellular_batch(const CellularBatch& batch) {
if ((batch.format_version != cellular_batch_format &&
batch.format_version != cellular_batch_v2_format &&
batch.format_version != cellular_batch_legacy_format) ||
if (!known_format(batch.format_version) || !payload_version_matches(batch) ||
!valid_header(batch.header, batch.ticks.size()) || !valid_ticks(batch.ticks))
return std::unexpected{CellularBatchError::format};
if (batch.format_version == cellular_batch_legacy_format &&
std::ranges::any_of(batch.ticks, [](const auto& tick) {
return !tick.births.empty() || !tick.mutations.empty();
}))
return std::unexpected{CellularBatchError::format};
if (batch.format_version == cellular_batch_v2_format &&
std::ranges::any_of(batch.ticks, [](const auto& tick) { return !tick.mutations.empty(); }))
return std::unexpected{CellularBatchError::format};
const auto tick_header_bytes =
batch.format_version == cellular_batch_format ? cellular_batch_tick_header_bytes
batch.format_version >= cellular_batch_format ? cellular_batch_tick_header_bytes
: batch.format_version == cellular_batch_v2_format ? cellular_batch_v2_tick_header_bytes
: cellular_batch_v1_tick_header_bytes;
std::size_t size = cellular_batch_header_bytes;
@@ -176,7 +184,7 @@ encode_cellular_batch(const CellularBatch& batch) {
(batch.format_version >= cellular_batch_v2_format
? tick.births.size() * cellular_batch_birth_bytes
: 0) +
(batch.format_version == cellular_batch_format
(batch.format_version >= cellular_batch_format
? tick.mutations.size() * cellular_batch_mutation_bytes
: 0);
if (records > max_cellular_batch_bytes - size - tick_header_bytes)
@@ -202,7 +210,7 @@ encode_cellular_batch(const CellularBatch& batch) {
put(out, tick.lives.size(), 4);
if (batch.format_version >= cellular_batch_v2_format)
put(out, tick.births.size(), 4);
if (batch.format_version == cellular_batch_format) {
if (batch.format_version >= cellular_batch_format) {
put(out, tick.mutations.size(), 4);
put(out, 0, 4);
}
@@ -217,7 +225,7 @@ encode_cellular_batch(const CellularBatch& batch) {
put(out, birth.identity, 8);
}
for (const auto& mutation : tick.mutations) {
if (batch.format_version != cellular_batch_format)
if (batch.format_version < cellular_batch_format)
break;
put(out, mutation.life_id, 8);
put(out, mutation.event_index, 8);
@@ -238,9 +246,8 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
!std::ranges::equal(bytes.first(magic.size()), magic))
return std::unexpected{CellularBatchError::format};
const auto format = get(bytes, 8, 4);
if ((format != cellular_batch_format && format != cellular_batch_v2_format &&
format != cellular_batch_legacy_format) ||
get(bytes, 12, 4) != 4)
if (format > cellular_batch_inheritance_format ||
!known_format(static_cast<std::uint32_t>(format)) || get(bytes, 12, 4) != 4)
return std::unexpected{CellularBatchError::version};
if (get(bytes, 108, 4) != 0)
return std::unexpected{CellularBatchError::format};
@@ -266,7 +273,7 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
out.ticks.reserve(static_cast<std::size_t>(tick_count));
for (std::uint64_t tick_index = 0; tick_index < tick_count; ++tick_index) {
const auto tick_header_bytes =
format == cellular_batch_format ? cellular_batch_tick_header_bytes
format >= cellular_batch_format ? cellular_batch_tick_header_bytes
: format == cellular_batch_v2_format ? cellular_batch_v2_tick_header_bytes
: cellular_batch_v1_tick_header_bytes;
if (bytes.size() - offset < tick_header_bytes)
@@ -279,7 +286,7 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
offset += 4;
}
std::uint64_t mutation_count{};
if (format == cellular_batch_format) {
if (format >= cellular_batch_format) {
mutation_count = get(bytes, offset, 4);
if (get(bytes, offset + 4, 4) != 0)
return std::unexpected{CellularBatchError::format};
@@ -358,7 +365,7 @@ decode_cellular_batch(std::span<const std::uint8_t> bytes) {
}
out.ticks.push_back(std::move(step));
}
if (offset != bytes.size())
if (offset != bytes.size() || !valid_ticks(out.ticks))
return std::unexpected{CellularBatchError::format};
return out;
}
@@ -407,11 +414,11 @@ std::expected<std::unique_ptr<CellularLives>, CellularBatchError>
replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
std::vector<CellularMutationOutcome>& mutation_outcomes) {
mutation_outcomes.clear();
// ADR-0165: this trace has no admitted offspring-plan outcome contract.
if (base.format_version() >= cellular_lives_inheritance_format)
if (!owner_version_matches(base, batch))
return std::unexpected{CellularBatchError::version};
const auto& h = batch.header;
if (!valid_header(h, batch.ticks.size()) || !valid_ticks(batch.ticks))
if (!payload_version_matches(batch) || !valid_header(h, batch.ticks.size()) ||
!valid_ticks(batch.ticks))
return std::unexpected{CellularBatchError::format};
if (base.world() != h.world || base.region() != h.region || base.frame() != h.frame ||
base.tick() != h.begin_tick)
@@ -420,12 +427,13 @@ replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
base.tick());
if (!replay)
return std::unexpected{CellularBatchError::state};
std::vector<CellularMutationOutcome> complete_outcomes;
for (const auto& tick : batch.ticks) {
const auto executed = (*replay)->advance_tick_with_mutations(tick.lives, tick.mutations);
if (!executed)
return std::unexpected{CellularBatchError::state};
for (const auto& mutation : executed->mutations)
mutation_outcomes.push_back(
complete_outcomes.push_back(
{(*replay)->tick(), mutation.life_id, mutation.successor_id, mutation.result});
for (const auto& birth : tick.births) {
const LifeRequest request{birth.account, birth.request};
@@ -440,6 +448,7 @@ replay_cellular_batch(const CellularLives& base, const CellularBatch& batch,
*replay = std::move(*born);
}
}
mutation_outcomes = std::move(complete_outcomes);
return std::move(*replay);
}
@@ -530,7 +539,10 @@ decode_cellular_mutation_action_block(std::span<const std::uint8_t> bytes, std::
std::expected<void, CellularActionBlockError>
match_cellular_actions_to_trace(const CellularLives& predecessor, const CellularBatch& batch,
std::span<const CellularActionRecord> actions) {
if (!valid_header(batch.header, batch.ticks.size()) || !valid_ticks(batch.ticks) ||
if (!owner_version_matches(predecessor, batch))
return std::unexpected{CellularActionBlockError::mismatch};
if (!payload_version_matches(batch) || !valid_header(batch.header, batch.ticks.size()) ||
!valid_ticks(batch.ticks) ||
!valid_actions(actions, batch.header.begin_tick, batch.header.end_tick))
return std::unexpected{CellularActionBlockError::format};
if (predecessor.world() != batch.header.world || predecessor.region() != batch.header.region ||
@@ -569,7 +581,10 @@ std::expected<void, CellularActionBlockError>
match_cellular_mutation_actions_to_trace(const CellularLives& predecessor,
const CellularBatch& batch,
std::span<const CellularMutationActionRecord> actions) {
if (!valid_header(batch.header, batch.ticks.size()) || !valid_ticks(batch.ticks) ||
if (!owner_version_matches(predecessor, batch))
return std::unexpected{CellularActionBlockError::mismatch};
if (!payload_version_matches(batch) || !valid_header(batch.header, batch.ticks.size()) ||
!valid_ticks(batch.ticks) ||
!valid_mutation_actions(actions, batch.header.begin_tick, batch.header.end_tick))
return std::unexpected{CellularActionBlockError::format};
if (predecessor.world() != batch.header.world || predecessor.region() != batch.header.region ||
@@ -618,7 +633,8 @@ match_cellular_mutation_actions_to_trace(const CellularLives& predecessor,
selection->operator_id != action.input.operator_id ||
life->mutation.event_index != action.input.event_index ||
life->mutation.offer_tick != action.input.offer_tick ||
life->identity.life != action.input.life_id || offer.parent != life->identity.genome ||
life->identity.life != action.input.life_id ||
offer.parent != cellular_offspring_genome(*life) ||
(action.input.operator_id != 0 &&
!std::ranges::any_of(offer.candidates, [&](const auto& candidate) {
return candidate.operator_id == action.input.operator_id;
+387
View File
@@ -0,0 +1,387 @@
#include "evo/biology/budding.hpp"
#include "fixtures/cellular_ecology.hpp"
#include <fstream>
#include <iterator>
namespace {
using namespace evo;
using namespace evo::server;
using namespace evo::fixture;
std::vector<CellularLifeIntent> idle(const CellularLives& state, bool bud = false,
bool frozen = false) {
std::vector<CellularLifeIntent> result;
for (const auto& life : state.lives()) {
CellularLifeIntent input{life.identity.life, {}};
if (life.account != LifeAccount{}) {
input.intent.bud = bud && !frozen;
input.intent.frozen = frozen;
}
result.push_back(input);
}
return result;
}
const CellularOwnedLife& parent(const CellularLives& state) {
const auto found =
std::ranges::find(state.lives(), 100, [](const auto& life) { return life.identity.life; });
require(found != state.lives().end(), "missing replay parent");
return *found;
}
Owner old_owner(bool populated = true, std::uint32_t count = 1) {
auto state = opening(7, true, count, populated);
state = checked(state->migration_upgrade_candidate(), "replay boundary upgrade");
return checked(state->maturation_upgrade_candidate(), "replay maturation upgrade");
}
Owner inherited_owner() {
return checked(old_owner()->inheritance_upgrade_candidate(), "replay inheritance upgrade");
}
CellularMutationSelection await_structure(Owner& state, std::uint64_t successor) {
for (unsigned tick = 0; tick < 60'000; ++tick) {
const auto cell = parent(*state);
if (cell.mutation.offer) {
const auto& offer = *cell.mutation.offer;
const auto candidate = std::ranges::find_if(offer.candidates, [](const auto& value) {
return value.target == biology::Capability::membrane ||
value.target == biology::Capability::target_size;
});
const CellularMutationSelection choice{
100, cell.mutation.event_index, cell.mutation.offer_tick, successor,
candidate == offer.candidates.end() ? std::uint16_t{0} : candidate->operator_id};
if (choice.operator_id != 0)
return choice;
checked(state->advance_tick_with_mutations(idle(*state), std::span{&choice, 1}),
"replay fixture decline");
} else
checked(state->advance_tick_with_mutations(idle(*state), {}), "earn replay offer");
}
throw std::runtime_error("finite fixture failed to earn structural offer");
}
CellularBatch trace(const CellularLives& base, std::uint64_t count = 1) {
CellularBatch batch;
batch.format_version = cellular_batch_inheritance_format;
batch.header = {base.world(), base.region(), base.frame(), {},
{}, base.tick(), base.tick() + count};
batch.header.predecessor.fill(1);
batch.header.predecessor_digest.fill(2);
return batch;
}
struct Recorded {
CellularBatch batch;
Owner candidate;
std::vector<CellularMutationOutcome> outcomes;
std::vector<CellularBudExecution> buds{};
};
Recorded record(const CellularLives& base, CellularMutationSelection choice, bool bud,
std::uint64_t count = 1) {
Recorded result{trace(base, count), restore(base), {}};
for (std::uint64_t tick = 0; tick < count; ++tick) {
CellularTickIntents input{idle(*result.candidate, tick == 0 && bud, tick != 0), {}, {}};
if (tick == 0)
input.mutations.push_back(choice);
const auto executed =
checked(result.candidate->advance_tick_with_mutations(input.lives, input.mutations),
"direct recorded tick");
for (const auto& mutation : executed.mutations)
result.outcomes.push_back({result.candidate->tick(), mutation.life_id,
mutation.successor_id, mutation.result});
result.buds.insert(result.buds.end(), executed.buds.begin(), executed.buds.end());
require(result.candidate->current_total() == result.candidate->opening_total(),
"direct replay fixture did not close");
result.batch.ticks.push_back(std::move(input));
}
return result;
}
void prepare_birth(Owner& state, const CellularMutationSelection& choice) {
const auto expressed =
checked(state->archive().find(parent(*state).identity.genome), "birth expressed genome");
const auto plan =
checked(state->archive().find(parent(*state).offspring_genome), "birth inherited genome");
const auto offer = parent(*state).mutation.offer;
if (!offer)
throw std::runtime_error("birth offer missing");
const auto selected =
checked(biology::select_mutation(plan, offer->context, *offer, choice.operator_id,
choice.successor_id, choice.successor_id),
"birth selected genome");
for (unsigned tick = 0; tick < 30'000; ++tick) {
const auto& cell = parent(*state);
if (biology::fund_offspring(expressed, selected, cell.growth, cell.reserve,
state->ambient_temperature_millikelvin())) {
const auto probe = record(*state, choice, true);
if (std::ranges::any_of(probe.buds, [](const auto& bud) {
return bud.result == CellularBudResult::budded;
}))
return;
}
checked(state->advance_tick_with_mutations(idle(*state), {}), "fund recorded birth");
}
throw std::runtime_error("finite food never funded same-tick inherited birth");
}
void compare(const CellularLives& base, const Recorded& expected) {
const auto before = base.snapshot();
const auto encoded = checked(encode_cellular_batch(expected.batch), "encode inherited trace");
const auto decoded = checked(decode_cellular_batch(encoded), "decode inherited trace");
require(decoded == expected.batch &&
checked(encode_cellular_batch(decoded), "reencode trace") == encoded,
"trace canonical roundtrip");
std::vector<CellularMutationOutcome> outcomes{{999, 999, 999, CellularMutationResult::applied}};
const auto replayed = checked(replay_cellular_batch(base, decoded, outcomes), "plan replay");
require(replayed->snapshot() == expected.candidate->snapshot() &&
outcomes == expected.outcomes && base.snapshot() == before,
"recorded plans/outcomes differ from direct execution");
}
void put(std::span<std::uint8_t> bytes, std::size_t at, std::uint64_t value, unsigned width = 8) {
require(at <= bytes.size() && width <= bytes.size() - at, "test byte offset");
for (unsigned index = 0; index < width; ++index)
bytes[at + index] = static_cast<std::uint8_t>(value >> (index * 8U));
}
void action_checks(const CellularLives& base, const CellularBatch& batch) {
const auto& choice = batch.ticks.front().mutations.front();
const CellularMutationActionRecord action{
parent(base).account,
41,
base.tick() + 1,
{100, choice.event_index, choice.offer_tick, choice.operator_id}};
const auto block = checked(encode_cellular_mutation_action_block(
std::span{&action, 1}, base.tick(), batch.header.end_tick),
"encode inherited action");
const auto decoded =
checked(decode_cellular_mutation_action_block(block, base.tick(), batch.header.end_tick),
"decode inherited action");
require(match_cellular_mutation_actions_to_trace(base, batch, decoded).has_value(),
"inherited action did not match standing plan offer");
const auto rejects = [&](CellularMutationActionRecord wrong) {
require(!match_cellular_mutation_actions_to_trace(base, batch, std::span{&wrong, 1}),
"mismatched inherited action accepted");
};
auto wrong = action;
++wrong.account[0];
rejects(wrong);
wrong = action;
++wrong.input.life_id;
rejects(wrong);
wrong = action;
++wrong.input.event_index;
rejects(wrong);
wrong = action;
++wrong.input.offer_tick;
rejects(wrong);
wrong = action;
wrong.input.operator_id = 0xFFFF;
rejects(wrong);
wrong = action;
++wrong.tick;
rejects(wrong);
require(!match_cellular_mutation_actions_to_trace(base, batch, {}), "missing action accepted");
CellularActionRecord movement{parent(base).account, 42, {}};
put(movement.input, 0, base.tick() + 1);
movement.input[12] = batch.ticks.front().lives.front().intent.bud ? 3 : 0;
require(match_cellular_actions_to_trace(base, batch, std::span{&movement, 1}).has_value(),
"controlled intent action mismatch");
put(movement.input, 8, 1000, 2);
require(!match_cellular_actions_to_trace(base, batch, std::span{&movement, 1}),
"changed movement action matched");
}
void refuse(const CellularLives& base, const CellularBatch& batch, CellularBatchError error) {
const auto before = base.snapshot();
std::vector<CellularMutationOutcome> outcomes{{999, 999, 999, CellularMutationResult::applied}};
const auto replayed = replay_cellular_batch(base, batch, outcomes);
if (replayed)
throw std::runtime_error("invalid inherited replay accepted");
require(replayed.error() == error && outcomes.empty() && base.snapshot() == before,
"failed replay changed predecessor or exposed partial outcomes");
}
void version_checks(const CellularLives& base, const CellularBatch& batch) {
for (std::uint32_t version = 1; version <= 3; ++version) {
auto old_trace = batch;
old_trace.format_version = version;
refuse(base, old_trace, CellularBatchError::version);
require(!match_cellular_actions_to_trace(base, old_trace, {}) &&
!match_cellular_mutation_actions_to_trace(base, old_trace, {}),
"action matcher admitted old trace on new owner");
}
auto old = old_owner();
auto empty = trace(*old);
empty.ticks.push_back({idle(*old), {}, {}});
refuse(*old, empty, CellularBatchError::version);
require(!match_cellular_actions_to_trace(*old, empty, {}) &&
!match_cellular_mutation_actions_to_trace(*old, empty, {}),
"action matcher admitted new trace on old owner");
empty.format_version = cellular_batch_format;
require(replay_cellular_batch(*old, empty).has_value(), "old replay control failed");
empty.format_version = 5;
refuse(*old, empty, CellularBatchError::version);
require(!encode_cellular_batch(empty), "unknown trace encoded");
auto scope = batch;
++scope.header.region;
refuse(base, scope, CellularBatchError::scope);
auto malformed = batch;
malformed.header.end_tick = malformed.header.begin_tick;
refuse(base, malformed, CellularBatchError::format);
}
void codec_checks(const CellularBatch& batch) {
const auto bytes = checked(encode_cellular_batch(batch), "hostile trace opening");
const auto corrupt = [&](std::size_t at, std::uint64_t value, unsigned width = 4) {
auto altered = bytes;
put(altered, at, value, width);
require(!decode_cellular_batch(altered), "malformed trace accepted");
};
corrupt(8, 5);
corrupt(12, 5);
corrupt(104, 65);
corrupt(108, 1);
corrupt(112, 0xFFFF'FFFFULL);
corrupt(124, 1);
const auto selection = 112 + 16 + batch.ticks.front().lives.size() * 24;
corrupt(selection + 34, 1, 1);
for (const auto length : {std::size_t{0}, std::size_t{111}, std::size_t{127}, bytes.size() - 1})
require(!decode_cellular_batch(std::span{bytes}.first(length)), "truncated trace accepted");
auto trailing = bytes;
trailing.push_back(0);
require(!decode_cellular_batch(trailing), "trailing trace byte accepted");
}
void selected_replay() {
auto base = inherited_owner();
const auto choice = await_structure(base, 1'000'000);
// Retain the earned offer while acquiring actual finite food until birth is affordable.
prepare_birth(base, choice);
const auto proof = record(*base, choice, true, 64);
compare(*base, proof);
require(proof.outcomes.size() == 1 &&
proof.outcomes.front().result == CellularMutationResult::offspring_plan_applied &&
parent(*proof.candidate).identity.genome == parent(*base).identity.genome &&
parent(*proof.candidate).offspring_genome == choice.successor_id,
"recorded selection rebuilt parent or lost plan");
bool born = false;
for (const auto& life : proof.candidate->lives())
if (life.parent_life == 100) {
require(life.identity.genome == choice.successor_id &&
life.offspring_genome == choice.successor_id &&
life.identity.born.value == base->tick() + 1,
"same-tick offspring used predecessor plan");
born = true;
}
if (!born)
throw std::runtime_error("same-tick birth result: " +
(proof.buds.empty() ? std::string{"missing"}
: std::to_string(static_cast<unsigned>(
proof.buds.front().result))));
action_checks(*base, proof.batch);
version_checks(*base, proof.batch);
codec_checks(proof.batch);
auto broken = proof.batch;
broken.ticks[1].lives.front().life_id = 9999;
const auto canonical =
checked(decode_cellular_batch(checked(encode_cellular_batch(broken), "encode bad set")),
"decode bad set");
refuse(*base, canonical, CellularBatchError::state);
auto stale = proof.batch;
++stale.ticks.front().mutations.front().event_index;
refuse(*base, stale, CellularBatchError::state);
auto later = restore(*proof.candidate);
const auto next = await_structure(later, 1'000'001);
const auto offer = parent(*later).mutation.offer;
if (!offer)
throw std::runtime_error("second inherited offer missing");
require(offer->parent != parent(*later).identity.genome,
"second offer did not differ from expressed body");
const auto changed = record(*later, next, false);
compare(*later, changed);
action_checks(*later, changed.batch);
auto decline = next;
decline.operator_id = 0;
const auto declined = record(*later, decline, false);
compare(*later, declined);
action_checks(*later, declined.batch);
require(declined.outcomes.front().result == CellularMutationResult::declined &&
parent(*declined.candidate).offspring_genome == parent(*later).offspring_genome &&
!declined.candidate->archive().find(decline.successor_id),
"decline edited inherited plan");
}
void allocator_births() {
auto base = checked(old_owner(false, 2)->inheritance_upgrade_candidate(), "empty upgrade");
auto direct = restore(*base);
auto batch = trace(*base, 2);
for (std::uint64_t index = 0; index < 2; ++index) {
CellularTickIntents tick{idle(*direct), {}, {}};
LifeAccount account{};
account.back() = static_cast<std::uint8_t>(index + 1);
tick.births.push_back({account, 1, 1, 100 + index});
checked(direct->advance_tick_with_mutations(tick.lives, {}), "allocated birth tick");
const auto id = 100 + index;
direct = checked(direct->birth_candidate({account, 1}, {id, id, id, id, {direct->tick()}}),
"direct allocator birth");
batch.ticks.push_back(std::move(tick));
}
compare(*base, Recorded{batch, std::move(direct), {}});
auto bytes = checked(encode_cellular_batch(batch), "allocated birth trace");
put(bytes, bytes.size() - 8, 100); // Duplicate the first tick's reserved identity.
require(!decode_cellular_batch(bytes), "cross-tick identity reuse decoded");
auto old = old_owner(false, 2);
batch.format_version = cellular_batch_legacy_format;
require(!encode_cellular_batch(batch), "legacy trace encoded births");
refuse(*old, batch, CellularBatchError::format);
}
void save(const std::string& path, std::span<const std::uint8_t> bytes) {
std::ofstream file(path, std::ios::binary | std::ios::trunc);
file.write(reinterpret_cast<const char*>(bytes.data()),
static_cast<std::streamsize>(bytes.size()));
require(file.good(), "write replay fixture");
}
std::vector<std::uint8_t> read(const std::string& path, std::size_t bound) {
std::ifstream file(path, std::ios::binary);
require(file.good(), "read replay fixture");
std::vector<std::uint8_t> bytes{std::istreambuf_iterator<char>{file}, {}};
require(bytes.size() <= bound, "replay fixture bound");
return bytes;
}
void checkpoint(const char* path, const char* expected) {
auto base = inherited_owner();
const auto initial = await_structure(base, 1'000'000);
auto first = record(*base, initial, false);
base = std::move(first.candidate);
const auto choice = await_structure(base, 1'000'001);
prepare_birth(base, choice);
const auto proof = record(*base, choice, true, 64);
compare(*base, proof);
action_checks(*base, proof.batch);
save(path, base->snapshot());
save(std::string{path} + ".trace", checked(encode_cellular_batch(proof.batch), "save trace"));
save(expected, proof.candidate->snapshot());
}
void resume(const char* path, const char* output) {
const auto bytes = read(path, max_cellular_lives_bytes);
require(bytes.size() >= 324, "replay predecessor length");
std::uint64_t tick = 0;
for (unsigned offset = 0; offset < 8; ++offset)
tick |= std::uint64_t{bytes[40 + offset]} << (offset * 8U);
const auto base = checked(CellularLives::restore(bytes, 207, 1, 1, tick), "fresh replay base");
const auto batch =
checked(decode_cellular_batch(read(std::string{path} + ".trace", max_cellular_batch_bytes)),
"fresh trace decode");
action_checks(*base, batch);
std::vector<CellularMutationOutcome> outcomes;
const auto candidate = checked(replay_cellular_batch(*base, batch, outcomes), "fresh replay");
require(outcomes.size() == 1 &&
outcomes.front().result == CellularMutationResult::offspring_plan_applied,
"fresh replay lost selected outcome");
save(output, candidate->snapshot());
}
} // namespace
int main(int argc, char** argv) try {
if (argc == 4 && std::string_view{argv[1]} == "--checkpoint") {
checkpoint(argv[2], argv[3]);
return 0;
}
if (argc == 4 && std::string_view{argv[1]} == "--resume") {
resume(argv[2], argv[3]);
return 0;
}
require(argc == 1, "unknown inherited replay arguments");
selected_replay();
allocator_births();
return 0;
} catch (const std::exception& error) {
std::cerr << error.what() << '\n';
return 1;
}