diff --git a/CMakeLists.txt b/CMakeLists.txt index 7195f5f..a281008 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -47,7 +47,7 @@ target_link_libraries(evo_biology PUBLIC evo::accounting) target_compile_features(evo_biology PUBLIC cxx_std_23) evo_owned_target(evo_biology) -add_library(evo_ecology STATIC src/ecology/cohort.cpp) +add_library(evo_ecology STATIC src/ecology/cohort.cpp src/ecology/collapse.cpp) add_library(evo::ecology ALIAS evo_ecology) target_include_directories(evo_ecology PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") target_link_libraries(evo_ecology PUBLIC evo::accounting evo::biology) @@ -115,6 +115,11 @@ if(BUILD_TESTING) evo_owned_target(evo-cohort-tests) add_test(NAME cohort-contracts COMMAND evo-cohort-tests) set_tests_properties(cohort-contracts PROPERTIES TIMEOUT 60) + add_executable(evo-collapse-tests tests/collapse_tests.cpp) + target_link_libraries(evo-collapse-tests PRIVATE evo::ecology) + evo_owned_target(evo-collapse-tests) + add_test(NAME collapse-contracts COMMAND evo-collapse-tests) + set_tests_properties(collapse-contracts PROPERTIES TIMEOUT 60) add_executable(evo-ledger-tests tests/ledger_tests.cpp) target_link_libraries(evo-ledger-tests PRIVATE evo::accounting) evo_owned_target(evo-ledger-tests) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index c1a2cf7..3938be1 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -106,6 +106,19 @@ genome and refuses replacement under a wrong worker or an older epoch, so ECOLOGY_MODEL's "no inventory spendable in two tiers" is enforced rather than described. No collapse, advance or materialization exists yet. +M4.2 moves individuals into that record (ADR-0037). Collapse is two phases over +one sample: `plan_collapse` reads the members once and returns an immutable plan +carrying an already-validated cohort, and `commit_collapse` applies exactly that +plan without deriving anything, so a replay cannot resample. A controlled, +suspended, dead or unsettled member refuses the whole plan instead of being +skipped, because filtering would make adversarial selection indistinguishable from +honest use. Ages are carried into declared classes and a member that fits none +refuses the plan rather than being moved. Conservation runs through the ledger as +one atomic transaction of one leg per member, each moving that member's whole +reserve, and the destination is proved available before anything moves, so every +rejection leaves both the ledger and the registry exactly as they were. What this +cannot check is that the caller offered every member it had. + M3.6 closes M3 by making the pieces meet (ADR-0035): `strategy_for` turns a genome into the `StrategyConfig` the M2.6 driver already takes, founders are pre-diverged variants of one ancestor admitted to the archive, and `evo-sim --ensemble` runs diff --git a/docs/STATUS.md b/docs/STATUS.md index 89b15e4..0e45284 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged. ## Completed implementation - Vision, architectural pillars, risks, open-question register, architecture - diagrams, biological contracts, engineering constitution and 36 ADRs. + diagrams, biological contracts, engineering constitution and 37 ADRs. Proposed/deferred choices remain distinct from accepted proof decisions. - M0–M4 task breakdowns with dependencies, acceptance evidence and risks, plus M5–M14 gates in [ROADMAP.md](ROADMAP.md). @@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic | Priority | Work | Completion evidence | |---|---|---| -| 1 | M4.2 collapse active individuals | Transfer IDs and reserves into one cohort atomically, with exact ledger conservation | +| 1 | M4.3 advance local cohorts | Conservative birth, death, predation and migration accounting per interval | | 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it | | Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes | @@ -332,3 +332,37 @@ classes while keeping its identities, and the registry then accepted through a move exactly what `create` rejects by name; the type is now copy-only, as ADR-0030 already made the genome for the same reason. That precedent existed and should have been applied when the type was written. + +M4.2 moves individuals into that record (ADR-0037), and does only that: there is +no population advance, no materialization back into individuals, no transfer +between habitats and no persistence. Collapse is two phases over one sample. +`plan_collapse` reads the members once and returns an immutable plan that already +carries a validated cohort; `commit_collapse` applies exactly that plan and +derives nothing, so ECOLOGY_MODEL's rule that recovery replays a committed sample +rather than sampling again is a property of the types. + +A controlled, suspended, dead or unsettled member refuses the whole plan rather +than being skipped. That is the answer to adversarial selection: filtering would +let a caller obtain a plan by omitting whoever was inconvenient, and the result +would be indistinguishable from an honest conversion. Ages are carried into +declared classes and a member fitting none refuses the plan, so a conversion +cannot quietly move anyone to a different class or discard one for having nowhere +to go. Reserves are summed per class, never redistributed. + +Conservation runs through the ledger rather than beside it: one atomic transaction +of one leg per member, each moving that member's entire reserve, so the conserved +total is unchanged by construction. Dual representation is closed from both ends. +A member must be emptied exactly, and a reservoir holding anything other than what +was sampled makes the plan stale rather than partly applicable. The destination is +proved available before anything moves, so no rejection can strand inventory in a +reservoir nothing owns, and every refusal leaves the ledger and the registry as +they were. Committing one plan twice is refused without moving inventory again. + +Two limits are stated rather than implied to be covered. The function cannot tell +whether the members it was given are all the members there were, so completeness +is a caller obligation. And emptying a reservoir is not withdrawing the right to +use it: the ledger has no removal, so nothing prevents a later transfer crediting +that reservoir again. Durable conversion sequences, escrow and replay across a +process boundary are M7 and M8. All ten construction and commit guards were +confirmed load-bearing by removing each and observing a failing run. Native +Release, analysis, ASan and formatting passed 35/35; Linux CI has not run yet. diff --git a/docs/adr/0037-collapse-to-cohort.md b/docs/adr/0037-collapse-to-cohort.md new file mode 100644 index 0000000..bcd9af2 --- /dev/null +++ b/docs/adr/0037-collapse-to-cohort.md @@ -0,0 +1,132 @@ +# ADR-0037: Collapsing individuals into a cohort as one sampled transaction + +## Status + +Adopted for M4.2. It converts identified individuals into the ADR-0036 record and +nothing else: there is no population advance, no materialization back into +individuals, no transfer between habitats and no persistence. Those are M4.3, +M4.4 and M7. ADR-0036 is unchanged. The only change outside this milestone is +additive: `ReservoirId` and `Transfer` gain the defaulted comparisons every other +value type in the project already has, so a plan's legs can be compared. No +accounting behaviour changes. + +## Context + +ECOLOGY_MODEL's headline risk for this step is dual representation: the same +biomass existing as individuals and as a cohort at once, or existing as neither +because a conversion stopped halfway. It also forbids an adversarial conversion +that selects only healthy or high-energy members, or that resets age, injury, +fertility or incubation on the way in. + +M4.1 gave the destination and proved it cannot be double-owned. What is missing is +the move itself, and the move is where conservation is either exact or quietly +wrong. The project already has the instrument for that: `accounting::Ledger` +applies ordered legs to a candidate copy and commits only if every leg holds, so +an atomic transfer is available rather than something this ADR has to invent. + +## Decision + +Collapse is two phases over one sample. `plan_collapse` reads the members once and +returns a `CollapsePlan`; `commit_collapse` applies exactly that plan and derives +nothing new. ECOLOGY_MODEL requires that recovery replays the committed sample and +never samples again, so the plan is the sample: it is immutable, it carries the +already-validated cohort, and committing it twice cannot resample. + +A member that is controlled, suspended, dead or unsettled refuses the whole plan +rather than being skipped. This is the part that answers adversarial selection. +Filtering would mean a caller could always obtain a plan by quietly omitting +whoever was inconvenient, and the result would look identical to an honest one. +Refusing loudly means an excluded member is a plan that failed and named who. +What this cannot establish is that the caller offered every member it had; +completeness of the input set is outside what this function can see, and is stated +as a limit rather than implied to be covered. + +Age is carried, never reset. The request declares class bounds, each member enters +the class containing its age, and a member whose age falls outside every declared +bound refuses the plan. A conversion therefore cannot quietly move anyone to a +different age class, and cannot discard one by having nowhere to put it. + +Conservation runs through the ledger rather than beside it. The plan holds one leg +per member, moving that member's entire reserve to the cohort's reservoir, and +commit submits them as a single transaction. The ledger's conserved total is +unchanged by construction, so conservation is a property of the instrument rather +than an assertion this code makes about itself. + +Dual representation is closed from both ends. A member must be emptied exactly: at +commit each member's reservoir has to hold precisely what the plan sampled, and +anything else means the world moved since the sample and the plan is stale. +Leaving a remainder behind would be the same biomass in two tiers, which +ECOLOGY_MODEL locks against. + +Ordering inside commit is chosen so no failure can strand inventory. The +destination is checked before anything moves: the registry must not already hold +this habitat and genome and must have room. Only then does the ledger transaction +run, and only then is the cohort installed, which cannot fail because the plan +carries a cohort already validated and the destination was already proved +available. Every rejection therefore leaves the ledger and the registry exactly as +they were. + +## Alternatives Considered + +Skipping ineligible members instead of refusing would make adversarial selection +indistinguishable from ordinary use, which is the risk this step is named after. +Moving inventory first and installing afterwards would allow a transfer whose +destination then refuses, stranding biomass in a reservoir nothing owns. Building +the cohort during commit rather than during planning would let commit fail on +validity after the ledger had already moved. Summing member reserves into a single +total and redistributing it across classes would conserve mass while destroying +the distribution ADR-0036 exists to keep. Letting the collapse write directly into +a cohort's inventory without a ledger transaction would make conservation +something this code claims rather than something the instrument enforces. Removing +each member's reservoir from the ledger would be closer to "remove active spending +rights", but the ledger deliberately has no removal; emptying is the strongest +form available and is what the tests assert. + +## Benefits + +Conservation is exact because the ledger enforces it, not because a test checks a +sum. Every failure path leaves the world unchanged, so there is no partial +conversion to recover from. A conversion that drops a member fails and says which +one. Ages and the reserve distribution survive the move intact. The plan is a +value, so the sample can be inspected before anything is committed. + +## Costs + +A plan is bounded to 256 members, because that is the ledger's transaction limit +and one leg is needed per member; larger groups need several conversions, which +this ADR does not coordinate. The plan holds a copy of the cohort and of every +leg. Members are supplied by the caller as an explicit record rather than read +from any live representation, so something has to map a world onto them, and that +mapping is not written here. + +## Risks + +This is not persistence. The before-and-after property holds across a rejection +inside one process; a crash between the ledger transaction and the registry +install is not something an in-memory registry can be recovered from, and durable +conversion sequence numbers, escrow and replay are M7 and M8. The function cannot +tell whether the members it was given are all the members there were, so +completeness is a caller obligation and an honest gap. Emptying a reservoir is not +the same as withdrawing the right to use it: nothing prevents a later transfer +crediting that reservoir again, and only the cohort registry's single-ownership +rule limits what that could mean. Nothing here says a cohort may then advance, and +a collapsed cohort cannot yet be turned back into individuals, so this direction +is one-way until M4.4. + +## Consequences + +Test that a plan totals its members exactly, that classes carry the ages and +reserves the members had, and that a member's reserve is never redistributed. Test +that every ineligible state refuses the whole plan and names the member, that a +foreign habitat or genome, a duplicate identity, an unclassifiable age, an empty +group and a group beyond the transaction limit are each refused. Test that a +committed collapse leaves the ledger's conserved total unchanged, empties every +member reservoir, credits the destination with exactly the planned total and +installs the cohort. Test that a plan which is never committed changes nothing, +that a commit refused at the destination or on a stale balance changes nothing in +either the ledger or the registry, and that committing one plan twice is refused +without moving inventory a second time. Test that the plan is copy-only, since a +moved-from plan would keep its identities and lose its legs. No genome schema, +mutation catalog, archive, episode driver, ensemble, cohort record, renderer or +deployment changes. The ledger changes only by gaining defaulted comparisons on +two of its value types, which no behaviour depends on. diff --git a/docs/adr/README.md b/docs/adr/README.md index 0375fab..77d3f8f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -29,6 +29,7 @@ Each record has the eight required sections. 0034 adopts the permanent lineage archive and absence that is never extinction. 0035 derives strategies from genomes and measures them over a split-half gradient. 0036 defines the tier 2 cohort, its declared resolution and exclusive ownership. +0037 collapses individuals into a cohort as one sampled, ledger-exact transaction. Every dependency adoption records exact version/commit and integrity hash, transitive license obligations, maintenance/security review, owner and removal diff --git a/docs/biology/ECOLOGY_MODEL.md b/docs/biology/ECOLOGY_MODEL.md index c1967da..a975a08 100644 --- a/docs/biology/ECOLOGY_MODEL.md +++ b/docs/biology/ECOLOGY_MODEL.md @@ -157,3 +157,37 @@ Carrying a bound is not meeting one; M4.5 is where resolution equivalence is measured. Conservation between a cohort and the rest of the world is the ledger's property and is not asserted by this type, which holds an inventory without participating in any transfer. + +## Implemented M4.2 collapse + +[ADR-0037](../adr/0037-collapse-to-cohort.md) implements `PlanCollapse` and +`CommitCollapse` for a single habitat and genome in one process. It settles +nothing else: `AdvancePopulation`, `PlanMaterialize`, `CommitMaterialize` and +`TransferPopulation` remain contracts nothing implements, and the direction is +one-way until M4.4. + +Collapse is two phases over one sample, so recovery replays a committed sample and +never samples again: the plan is immutable, carries an already-validated cohort, +and commit derives nothing. Members that are controlled, suspended, dead or +unsettled are rejected as this document requires, and rejection refuses the whole +plan rather than dropping the member. That is what makes adversarial selection +visible: a conversion cannot quietly exclude the unhealthy and still look honest. +Age, and the per-class reserve distribution, are carried through unchanged; a +member whose age fits no declared class refuses the plan rather than being moved +into one. + +Exact inventory is totalled through the ledger, not alongside it. One atomic +transaction carries one leg per member, each moving that member's entire reserve, +so the conserved total is unchanged by construction and no remainder is left in a +second tier. The destination is proved available before anything moves, so a +refusal cannot strand biomass in a reservoir nothing owns, and every rejection +leaves both the ledger and the registry exactly as they were. + +Two gaps are explicit. This cannot establish that the members offered were all the +members there were; completeness is the caller's obligation. And "remove active +spending rights" is implemented as emptying, because the ledger has no reservoir +removal: nothing prevents a later transfer crediting an emptied reservoir, and +only the registry's single-ownership rule bounds what that would mean. Durable +conversion sequence numbers, escrow and crash recovery across a process boundary +are M7 and M8; the before-and-after property proved here holds across a rejection +inside one process. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index a89c5dc..7ef76ab 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -961,3 +961,69 @@ No existing contract changed. The proof golden `d61ad5bf0c928c76`, the ecosystem fingerprint `2cd4a15f9fbe9949`, the ensemble fingerprint `5ec59d390909b526` and the frozen genome fixture are unchanged. Linux validation is pending; no Gitea result is claimed since `b01a824`. + +## M4.2 collapse to cohort + +Executed on this Windows host (2026-09-24): Release configure, build and `ctest` +35/35; the analysis preset (clang-tidy 19, warnings as errors) built clean; the +ASan preset configured, built and ran 35/35; `clang-format` 19.1.5 reported no +violations. All four checks ran and passed on the committed tree. No Clang or GCC +compile happens on this host, so Linux CI remains the first such result. + +`evo-collapse-tests` covers seven properties: that a plan totals its members +exactly and moves each member's whole reserve, that ages and the per-class reserve +distribution survive the move without redistribution, that every ineligible state +and every malformed request refuses the whole plan by name, that a committed +collapse leaves the ledger's conserved total unchanged while emptying every member +reservoir and crediting the destination, that every rejection leaves both the +ledger and the registry exactly as they were, that one plan cannot be committed +twice, and that a moved-from plan is still whole. + +All ten guards were confirmed load-bearing by removing each in turn and rebuilding: +the ineligible, foreign, duplicate, self-destination, age classification, stale +sample, occupied destination, empty class and commit ordering guards, and the +copy-only declaration. Two needed a second pass. The first age mutation did not +compile, which is not evidence about the test, so it was rewritten to make the +class predicate always match, which places every member in the first class and is +detected at runtime. Removing the copy declarations fails to compile in Release +for the reason recorded for the cohort; with the static assertion also removed the +same mutation was rerun under ASan, where it exits 1, so the runtime assertions +are load-bearing independently of the compile-time proof. + +The commit ordering mutation is worth naming: moving the ledger transaction ahead +of the destination check is detected, because a rejected conversion then leaves +biomass in a reservoir nothing owns while the members are already empty. That is +the dual-representation failure this milestone is named after, and the ordering is +what prevents it rather than a comment saying it does not happen. + +One expectation of my own was wrong rather than the code. A replay of a committed +plan was expected to report `destination_occupied`, but the staleness check ran +first and reported `stale_plan`, which is equally true. Both are pure checks made +before anything moves, so safety was unaffected and only the diagnosis differed; +the destination check now runs first, because "this conversion already happened" +says more about a replay than "the world moved". The ordering rationale is +recorded beside it. + +`accounting::ReservoirId` and `accounting::Transfer` gained the defaulted +comparisons that every other value type in the project already carries, so a +plan's legs can be compared. This is additive, no behaviour depends on it, and +ADR-0037's status was corrected to say so rather than claim no M1 change. + +Coverage limits. Completeness of the offered member set is not checkable here and +is not checked: nothing establishes that the caller offered every member it had. +Emptying a reservoir is not withdrawing the right to use it, since the ledger has +no removal, so a later transfer could credit an emptied reservoir and no test +asserts otherwise. The before-and-after property is demonstrated across rejections +inside one process; there is no persistence, so a crash between the ledger +transaction and the registry install is outside what an in-memory registry can +show, and durable conversion sequences, escrow and replay stay M7 and M8. Plans +are bounded to 256 members by the ledger's transaction limit and nothing +coordinates several conversions. The ledger-failure and destination-unavailable +branches are reachable only past bounds the tests do not build, so they are +refused-by-construction rather than exercised. + +No existing behaviour changed. The proof golden `d61ad5bf0c928c76`, the ecosystem +fingerprint `2cd4a15f9fbe9949`, the ensemble fingerprint `5ec59d390909b526` and +the frozen genome fixture are unchanged, and the other 34 tests pass untouched. +No deployment manifest or image pin changed. Linux validation is pending; no Gitea +result is claimed since `b01a824`. diff --git a/include/evo/accounting/ledger.hpp b/include/evo/accounting/ledger.hpp index 2f0e778..18aa4b7 100644 --- a/include/evo/accounting/ledger.hpp +++ b/include/evo/accounting/ledger.hpp @@ -26,11 +26,13 @@ struct Inventory { }; struct ReservoirId { std::uint32_t value{}; + auto operator<=>(const ReservoirId&) const = default; }; struct Transfer { ReservoirId from; ReservoirId to; Inventory amount; + auto operator<=>(const Transfer&) const = default; }; enum class LedgerError : std::uint8_t { reservoir_limit, diff --git a/include/evo/ecology/collapse.hpp b/include/evo/ecology/collapse.hpp new file mode 100644 index 0000000..d18729f --- /dev/null +++ b/include/evo/ecology/collapse.hpp @@ -0,0 +1,127 @@ +#pragma once + +#include "evo/ecology/cohort.hpp" + +namespace evo::ecology { +// What a member is doing when a conversion reaches it. Only an active, settled +// member may be converted; every other state refuses the whole plan rather than +// being skipped, so a conversion cannot quietly leave out whoever was +// inconvenient and still look like an honest one. +enum class MemberState : std::uint8_t { + active, + controlled, // a player holds it; ECOLOGY_MODEL keeps these out of populations + suspended, // offline or parked, so its viability is not this tier's to decide + dead, // its inventory belongs to decomposition, not to a cohort + unsettled // has an obligation in flight and is not whole yet +}; + +// One identified individual offered to a conversion. This is an explicit record a +// caller fills in, not a view of any live representation: the ecology library +// stays independent of whatever is simulating individuals. +struct ActiveMember { + std::uint64_t identity{}; + std::uint64_t genome{}; + HabitatId habitat{}; + std::uint64_t age{}; // ticks; carried into a class, never reset + accounting::ReservoirId reservoir{}; + // What that reservoir holds. Checked against the ledger again at commit, so a + // sample that has gone stale is refused rather than applied. + accounting::Inventory reserve{}; + MemberState state{}; + auto operator<=>(const ActiveMember&) const = default; +}; + +// Half-open age class bounds, declared by the caller. This is the resolution +// decision ADR-0036 leaves to whoever builds the record. +struct AgeBound { + std::uint64_t low{}; + std::uint64_t high{}; + auto operator<=>(const AgeBound&) const = default; +}; + +struct CollapseRequest { + std::uint64_t conversion{}; + Owner owner{}; + HabitatId habitat{}; + std::uint64_t genome{}; + Tick tick{}; + std::uint64_t revision{}; + // Where the members' inventory is gathered. Must not be a member's own. + accounting::ReservoirId destination{}; + std::vector bounds; + ApproximationBound bound{}; +}; + +enum class CollapseError : std::uint8_t { + invalid_request, + invalid_bounds, + no_members, + too_many_members, + duplicate_member, + foreign_member, + ineligible_member, + unclassified_age, + overflow, + invalid_cohort, + stale_plan, + destination_occupied, + destination_unavailable, + ledger_failure +}; + +// The sample, taken once. ECOLOGY_MODEL requires that recovery replays a +// committed sample rather than sampling again, so this carries everything commit +// needs and commit derives nothing: the cohort is already built and validated, +// and the legs already say what each member is expected to hold. +class CollapsePlan { + public: + // Copy-only, for the reason ADR-0036 makes a cohort copy-only: a moved-from + // plan would keep its identities while losing its legs, and committing it + // would move nothing while appearing to convert everyone. + CollapsePlan(const CollapsePlan&) = default; + CollapsePlan& operator=(const CollapsePlan&) = default; + + [[nodiscard]] const Cohort& cohort() const noexcept { + return cohort_; + } + // One leg per member, in the order the members were offered. Each moves that + // member's whole reserve, so nothing is left behind in a second tier. + [[nodiscard]] std::span legs() const noexcept { + return legs_; + } + [[nodiscard]] std::span members() const noexcept { + return members_; + } + [[nodiscard]] accounting::Inventory total() const noexcept { + return total_; + } + [[nodiscard]] accounting::ReservoirId destination() const noexcept { + return destination_; + } + + auto operator<=>(const CollapsePlan&) const = default; + + private: + friend std::expected plan_collapse(std::span, + const CollapseRequest&); + // Taken by reference: a cohort is copy-only, so a by-value parameter would + // be one copy more and a move that does nothing. + explicit CollapsePlan(const Cohort& cohort) : cohort_{cohort} {} + Cohort cohort_; + std::vector legs_; + std::vector members_; + accounting::Inventory total_{}; + accounting::ReservoirId destination_{}; +}; + +// Reads the members once and decides everything. Pure: it touches no ledger and +// no registry, so a plan can be inspected before anything is committed. +[[nodiscard]] std::expected +plan_collapse(std::span members, const CollapseRequest& request); + +// Applies exactly that plan. The destination is proved available before anything +// moves, so no rejection can strand inventory in a reservoir nothing owns: every +// failure leaves the ledger and the registry as they were. +[[nodiscard]] std::expected +commit_collapse(accounting::Ledger& ledger, CohortRegistry& registry, const CollapsePlan& plan); +} // namespace evo::ecology diff --git a/src/ecology/collapse.cpp b/src/ecology/collapse.cpp new file mode 100644 index 0000000..f1dd364 --- /dev/null +++ b/src/ecology/collapse.cpp @@ -0,0 +1,174 @@ +#include "evo/ecology/collapse.hpp" + +#include +#include +#include + +namespace evo::ecology { +namespace { +constexpr auto maximum = std::numeric_limits::max(); + +[[nodiscard]] bool add(std::uint64_t& total, std::uint64_t amount) noexcept { + if (amount > maximum - total) { + return false; + } + total += amount; + return true; +} +[[nodiscard]] bool add(accounting::Inventory& total, const accounting::Inventory& amount) noexcept { + if (!add(total.energy.value, amount.energy.value)) { + return false; + } + for (std::size_t channel = 0; channel < total.matter.size(); ++channel) { + if (!add(total.matter[channel].value, amount.matter[channel].value)) { + return false; + } + } + return true; +} +} // namespace + +std::expected plan_collapse(std::span members, + const CollapseRequest& request) { + if (request.conversion == 0 || request.owner.worker == 0 || request.owner.epoch == 0 || + request.habitat.value == 0 || request.genome == 0 || request.revision == 0 || + request.destination.value == 0) { + return std::unexpected{CollapseError::invalid_request}; + } + if (request.bounds.empty() || request.bounds.size() > max_age_classes) { + return std::unexpected{CollapseError::invalid_bounds}; + } + for (std::size_t index = 0; index < request.bounds.size(); ++index) { + const auto& bound = request.bounds[index]; + if (bound.high <= bound.low) { + return std::unexpected{CollapseError::invalid_bounds}; + } + if (index > 0 && bound.low < request.bounds[index - 1].high) { + return std::unexpected{CollapseError::invalid_bounds}; + } + } + if (members.empty()) { + return std::unexpected{CollapseError::no_members}; + } + // One ledger leg per member, so the transaction limit is the group limit. + if (members.size() > accounting::max_transfers) { + return std::unexpected{CollapseError::too_many_members}; + } + + std::vector classes(request.bounds.size()); + for (std::size_t index = 0; index < request.bounds.size(); ++index) { + classes[index].age_low = request.bounds[index].low; + classes[index].age_high = request.bounds[index].high; + } + accounting::Inventory total{}; + std::vector seen; + seen.reserve(members.size()); + std::vector legs; + legs.reserve(members.size()); + for (const auto& member : members) { + if (member.identity == 0 || member.reservoir.value == 0) { + return std::unexpected{CollapseError::invalid_request}; + } + // An ineligible member refuses the whole plan. Skipping it would let a + // caller obtain a plan by omitting whoever was inconvenient, and the + // result would be indistinguishable from an honest conversion. + if (member.state != MemberState::active) { + return std::unexpected{CollapseError::ineligible_member}; + } + if (member.habitat != request.habitat || member.genome != request.genome) { + return std::unexpected{CollapseError::foreign_member}; + } + // Gathering a member's inventory into its own reservoir would convert + // nothing while reporting that it had. + if (member.reservoir == request.destination) { + return std::unexpected{CollapseError::invalid_request}; + } + if (std::ranges::find(seen, member.identity) != seen.end()) { + return std::unexpected{CollapseError::duplicate_member}; + } + seen.push_back(member.identity); + // Age is carried, never reset: a member with nowhere to go refuses the + // plan rather than being placed in a class it does not belong to. + const auto at = std::ranges::find_if(classes, [&](const AgeClass& age) { + return member.age >= age.age_low && member.age < age.age_high; + }); + if (at == classes.end()) { + return std::unexpected{CollapseError::unclassified_age}; + } + if (!add(at->count, 1) || !add(at->reserve, member.reserve) || + !add(total, member.reserve)) { + return std::unexpected{CollapseError::overflow}; + } + legs.push_back({member.reservoir, request.destination, member.reserve}); + } + + // A declared bound nobody fell into is a resolution the caller chose and this + // group did not need. ADR-0036 has no empty class, so it is simply not one. + std::erase_if(classes, [](const AgeClass& age) { return age.count == 0; }); + CohortDraft draft; + draft.representation_version = cohort_representation_version; + draft.habitat = request.habitat; + draft.genome = request.genome; + draft.owner = request.owner; + draft.last_tick = request.tick; + draft.revision = request.revision; + draft.conversion = request.conversion; + draft.classes = std::move(classes); + draft.bound = request.bound; + // Built and validated here, so commit cannot fail on the record's validity + // after the ledger has already moved. + auto cohort = Cohort::create(std::move(draft)); + if (!cohort) { + return std::unexpected{CollapseError::invalid_cohort}; + } + CollapsePlan plan{*cohort}; + plan.legs_ = std::move(legs); + plan.members_ = std::move(seen); + plan.total_ = total; + plan.destination_ = request.destination; + return plan; +} + +std::expected +commit_collapse(accounting::Ledger& ledger, CohortRegistry& registry, const CollapsePlan& plan) { + const auto balances = ledger.balances(); + if (plan.destination().value > balances.size()) { + return std::unexpected{CollapseError::destination_unavailable}; + } + // The destination is proved available before anything moves, so the install + // below cannot fail and no rejection can strand inventory in a reservoir + // nothing owns. It is also checked before the sample, which matters only for + // what a replay reports: committing one plan twice leaves the members empty, + // so both checks would refuse it, and "this conversion already happened" says + // more than "the world moved". Both are pure, so the order is a reporting + // choice and not a safety one. + const auto& cohort = plan.cohort(); + if (registry.find(cohort.habitat(), cohort.genome()).has_value()) { + return std::unexpected{CollapseError::destination_occupied}; + } + if (registry.size() >= max_cohorts) { + return std::unexpected{CollapseError::destination_unavailable}; + } + // The sample has to still be true. Holding anything other than exactly what + // was sampled means the world moved, and moving only the sampled part would + // leave a remainder behind: the same biomass in two tiers. + for (const auto& leg : plan.legs()) { + if (leg.from.value > balances.size()) { + return std::unexpected{CollapseError::stale_plan}; + } + if (balances[leg.from.value - 1] != leg.amount) { + return std::unexpected{CollapseError::stale_plan}; + } + } + if (ledger.last_action() == maximum) { + return std::unexpected{CollapseError::ledger_failure}; + } + if (!ledger.transfer(ledger.last_action() + 1, plan.legs())) { + return std::unexpected{CollapseError::ledger_failure}; + } + if (!registry.install(cohort)) { + return std::unexpected{CollapseError::destination_occupied}; + } + return cohort; +} +} // namespace evo::ecology diff --git a/tests/collapse_tests.cpp b/tests/collapse_tests.cpp new file mode 100644 index 0000000..24f45ce --- /dev/null +++ b/tests/collapse_tests.cpp @@ -0,0 +1,341 @@ +#include "evo/ecology/collapse.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace { +using namespace evo::ecology; +using namespace evo::accounting; +using evo::Tick; +void check(bool condition, std::source_location location = std::source_location::current()) { + if (!condition) { + throw std::runtime_error("collapse line " + std::to_string(location.line())); + } +} +// Variadic so a braced initializer containing a comma stays one argument. +#define CHECK(...) check(static_cast(__VA_ARGS__)) + +// Asserting on .error() alone is undefined when the call unexpectedly succeeded, +// which would let a broken guard pass quietly. This checks the failure first. +template +[[nodiscard]] bool refused(const std::expected& result, CollapseError expected) { + return !result.has_value() && result.error() == expected; +} + +Inventory held(std::uint64_t energy, std::uint64_t matter) { + return {{energy}, + {Femtograms{matter}, Femtograms{matter}, Femtograms{matter}, Femtograms{matter}}}; +} +// Reservoirs 1..3 are the members, 4 is the cohort, 5 is an unrelated elsewhere. +constexpr std::size_t reservoir_count = 5; +constexpr ReservoirId destination{4}; + +std::vector members() { + return {{101, 3, {7}, 10, {1}, held(10, 100), MemberState::active}, + {102, 3, {7}, 150, {2}, held(20, 200), MemberState::active}, + {103, 3, {7}, 160, {3}, held(30, 300), MemberState::active}}; +} +CollapseRequest request() { + CollapseRequest source; + source.conversion = 5; + source.owner = {11, 2}; + source.habitat = {7}; + source.genome = 3; + source.tick = Tick{900}; + source.revision = 1; + source.destination = destination; + source.bounds = {{0, 100}, {100, 200}, {200, 300}}; + source.bound = {2, held(1, 1)}; + return source; +} +Ledger world() { + std::array opening{}; + const auto offered = members(); + for (std::size_t index = 0; index < offered.size(); ++index) { + opening[index] = offered[index].reserve; + } + opening[4] = held(7, 7); // An unrelated reservoir, to prove nothing else moves. + auto ledger = Ledger::create(opening); + check(ledger.has_value()); + return std::move(*ledger); +} +CollapsePlan planned() { + const auto offered = members(); + auto plan = plan_collapse(offered, request()); + check(plan.has_value()); + return *plan; +} + +void a_plan_totals_its_members_exactly() { + const auto plan = planned(); + // Nothing is created or lost in the sample itself. + CHECK(plan.total() == held(60, 600)); + CHECK(plan.legs().size() == 3); + CHECK(plan.members().size() == 3); + CHECK(plan.destination() == destination); + const auto offered = members(); + for (std::size_t index = 0; index < offered.size(); ++index) { + // Each leg moves that member's whole reserve, so nothing stays behind. + CHECK(plan.legs()[index].from == offered[index].reservoir); + CHECK(plan.legs()[index].to == destination); + CHECK(plan.legs()[index].amount == offered[index].reserve); + CHECK(plan.members()[index] == offered[index].identity); + } + const auto& cohort = plan.cohort(); + CHECK(cohort.habitat() == HabitatId{7}); + CHECK(cohort.genome() == 3); + CHECK(cohort.owner() == Owner{11, 2}); + CHECK(cohort.last_tick() == Tick{900}); + CHECK(cohort.conversion() == 5); + CHECK(cohort.count() == 3); + CHECK(cohort.reserve() == plan.total()); +} + +void ages_and_the_distribution_survive_the_move() { + const auto plan = planned(); + const auto classes = plan.cohort().classes(); + // A bound nobody fell into is not carried, because there is no empty class. + CHECK(classes.size() == 2); + // The member aged 10 is alone in the first class with exactly its own reserve. + CHECK(classes[0].age_low == 0); + CHECK(classes[0].age_high == 100); + CHECK(classes[0].count == 1); + CHECK(classes[0].reserve == held(10, 100)); + // The two in the second class keep their combined reserve, not a share of the + // total: a redistribution would conserve mass and destroy the distribution. + CHECK(classes[1].age_low == 100); + CHECK(classes[1].age_high == 200); + CHECK(classes[1].count == 2); + CHECK(classes[1].reserve == held(50, 500)); + CHECK(classes[0].reserve != classes[1].reserve); + // Individuals are whole, so nothing is owed. + CHECK(classes[0].residual == 0); + CHECK(classes[1].residual == 0); + // Declaring one wide class is a resolution choice that produces the average + // this record exists to avoid; it is permitted and it is visibly coarser. + auto coarse = request(); + coarse.bounds = {{0, 300}}; + const auto offered = members(); + const auto flat = plan_collapse(offered, coarse); + CHECK(flat.has_value()); + CHECK(flat->cohort().classes().size() == 1); + CHECK(flat->cohort().reserve() == plan.cohort().reserve()); + CHECK(flat->cohort().count() == plan.cohort().count()); +} + +void an_ineligible_member_refuses_the_whole_plan() { + // Skipping one would let a caller obtain a plan by omitting whoever was + // inconvenient, and the result would look exactly like an honest conversion. + for (const auto state : {MemberState::controlled, MemberState::suspended, MemberState::dead, + MemberState::unsettled}) { + auto offered = members(); + offered[1].state = state; + CHECK(refused(plan_collapse(offered, request()), CollapseError::ineligible_member)); + } + // A member of another habitat or genome is not part of this group at all. + auto foreign_habitat = members(); + foreign_habitat[2].habitat = {8}; + CHECK(refused(plan_collapse(foreign_habitat, request()), CollapseError::foreign_member)); + auto foreign_genome = members(); + foreign_genome[2].genome = 4; + CHECK(refused(plan_collapse(foreign_genome, request()), CollapseError::foreign_member)); + // One member offered twice would be converted twice. + auto twice = members(); + twice.push_back(twice[0]); + twice.back().reservoir = {5}; + CHECK(refused(plan_collapse(twice, request()), CollapseError::duplicate_member)); + // An age outside every declared bound cannot be placed without resetting it. + auto unplaceable = members(); + unplaceable[2].age = 900; + CHECK(refused(plan_collapse(unplaceable, request()), CollapseError::unclassified_age)); + // Gathering into a member's own reservoir would convert nothing. + auto into_itself = request(); + into_itself.destination = {2}; + const auto offered = members(); + CHECK(refused(plan_collapse(offered, into_itself), CollapseError::invalid_request)); + CHECK(refused(plan_collapse({}, request()), CollapseError::no_members)); + std::vector crowd; + for (std::uint64_t index = 0; index <= max_transfers; ++index) { + crowd.push_back({index + 1, 3, {7}, 10, {1}, held(0, 0), MemberState::active}); + } + CHECK(refused(plan_collapse(crowd, request()), CollapseError::too_many_members)); + // Bounds are the same declared resolution ADR-0036 validates. + for (auto broken : {0U, 1U, 2U}) { + auto spoiled = request(); + if (broken == 0) { + spoiled.bounds.clear(); + } else if (broken == 1) { + spoiled.bounds[1].high = spoiled.bounds[1].low; + } else { + spoiled.bounds[1].low = spoiled.bounds[0].high - 1; + } + CHECK(refused(plan_collapse(offered, spoiled), CollapseError::invalid_bounds)); + } + for (auto missing : {0U, 1U, 2U, 3U, 4U, 5U, 6U}) { + auto blank = request(); + if (missing == 0) { + blank.conversion = 0; + } else if (missing == 1) { + blank.owner.worker = 0; + } else if (missing == 2) { + blank.owner.epoch = 0; + } else if (missing == 3) { + blank.habitat = {}; + } else if (missing == 4) { + blank.genome = 0; + } else if (missing == 5) { + blank.revision = 0; + } else { + blank.destination = {}; + } + CHECK(refused(plan_collapse(offered, blank), CollapseError::invalid_request)); + } +} + +void a_committed_collapse_conserves_and_empties_the_members() { + auto ledger = world(); + CohortRegistry registry; + const auto before = ledger.conserved_totals(); + const auto plan = planned(); + const auto installed = commit_collapse(ledger, registry, plan); + CHECK(installed.has_value()); + // Conservation is the ledger's property, not an assertion made beside it. + CHECK(ledger.conserved_totals() == before); + // Every member reservoir is empty: the same biomass is not in two tiers. + for (std::size_t index = 0; index < 3; ++index) { + CHECK(ledger.balances()[index] == Inventory{}); + } + CHECK(ledger.balances()[destination.value - 1] == plan.total()); + CHECK(ledger.balances()[4] == held(7, 7)); // Nothing unrelated moved. + CHECK(registry.size() == 1); + const auto found = registry.find(HabitatId{7}, 3); + CHECK(found.has_value()); + CHECK(*found == plan.cohort()); + CHECK(found->reserve() == plan.total()); + CHECK(*installed == plan.cohort()); +} + +void every_rejection_leaves_the_world_as_it_was() { + // A plan that is never committed changes nothing at all. + auto untouched = world(); + CohortRegistry idle; + const auto opening = + std::vector{untouched.balances().begin(), untouched.balances().end()}; + const auto action = untouched.last_action(); + const auto plan = planned(); + CHECK(std::vector(untouched.balances().begin(), untouched.balances().end()) == + opening); + CHECK(untouched.last_action() == action); + CHECK(idle.size() == 0); + + // A destination already holding this habitat and genome refuses before the + // ledger is touched, so nothing is stranded in a reservoir nobody owns. + auto ledger = world(); + CohortRegistry occupied; + auto sitting = request(); + sitting.revision = 9; + const auto other = plan_collapse(members(), sitting); + CHECK(other.has_value()); + CHECK(occupied.install(other->cohort()).has_value()); + CHECK(refused(commit_collapse(ledger, occupied, plan), CollapseError::destination_occupied)); + CHECK(std::vector(ledger.balances().begin(), ledger.balances().end()) == opening); + CHECK(ledger.last_action() == action); + CHECK(occupied.size() == 1); + + // A sample that has gone stale is refused rather than partly applied. Moving + // only the sampled part would leave a remainder in the member's reservoir. + auto drifted = world(); + CohortRegistry empty_registry; + const std::array leak{Transfer{{1}, {5}, held(1, 1)}}; + CHECK(drifted.transfer(drifted.last_action() + 1, leak).has_value()); + const auto after_leak = + std::vector{drifted.balances().begin(), drifted.balances().end()}; + const auto leaked_action = drifted.last_action(); + CHECK(refused(commit_collapse(drifted, empty_registry, plan), CollapseError::stale_plan)); + CHECK(std::vector(drifted.balances().begin(), drifted.balances().end()) == + after_leak); + CHECK(drifted.last_action() == leaked_action); + CHECK(empty_registry.size() == 0); + + // A member holding more than was sampled is equally stale: the surplus would + // stay behind as the same biomass in a second tier. + auto enriched = world(); + CohortRegistry spare; + const std::array gift{Transfer{{5}, {1}, held(1, 1)}}; + CHECK(enriched.transfer(enriched.last_action() + 1, gift).has_value()); + CHECK(refused(commit_collapse(enriched, spare, plan), CollapseError::stale_plan)); + CHECK(enriched.balances()[0] == held(11, 101)); + CHECK(spare.size() == 0); +} + +void one_plan_cannot_be_committed_twice() { + auto ledger = world(); + CohortRegistry registry; + const auto plan = planned(); + CHECK(commit_collapse(ledger, registry, plan).has_value()); + const auto settled = std::vector{ledger.balances().begin(), ledger.balances().end()}; + const auto action = ledger.last_action(); + // The destination is now occupied, so the replay is refused before the ledger + // is reached and inventory is not moved a second time. + CHECK(refused(commit_collapse(ledger, registry, plan), CollapseError::destination_occupied)); + CHECK(std::vector(ledger.balances().begin(), ledger.balances().end()) == settled); + CHECK(ledger.last_action() == action); + CHECK(registry.size() == 1); + CHECK(registry.find(HabitatId{7}, 3)->count() == 3); + // Even into a fresh registry the members are empty now, so the sample that + // said they held something is stale and the replay still moves nothing. + CohortRegistry fresh; + CHECK(refused(commit_collapse(ledger, fresh, plan), CollapseError::stale_plan)); + CHECK(std::vector(ledger.balances().begin(), ledger.balances().end()) == settled); + CHECK(fresh.size() == 0); +} + +void a_moved_from_plan_is_still_a_whole_plan() { + // A moved-from plan would keep its identities and lose its legs, and + // committing it would move nothing while reporting a conversion. + static_assert(std::is_copy_constructible_v); + static_assert(std::is_copy_assignable_v); + static_assert(!std::is_nothrow_move_constructible_v); + auto source = planned(); + const auto before = source; + // Both diagnostics are the point of the check: clang-tidy is right that no + // move happens here and wrong that it is a mistake. + // NOLINTNEXTLINE(performance-move-const-arg) + const auto moved = std::move(source); + // NOLINTNEXTLINE(bugprone-use-after-move): the point of the check. + CHECK(source == before); + // NOLINTNEXTLINE(bugprone-use-after-move) + CHECK(source.legs().size() == 3); + // NOLINTNEXTLINE(bugprone-use-after-move) + CHECK(source.cohort().count() == 3); + CHECK(moved == before); + // The supposedly moved-from plan still converts everyone it sampled. + auto ledger = world(); + CohortRegistry registry; + // NOLINTNEXTLINE(bugprone-use-after-move): the point of the check. + const auto installed = commit_collapse(ledger, registry, source); + CHECK(installed.has_value()); + CHECK(installed->count() == 3); + CHECK(ledger.balances()[destination.value - 1] == held(60, 600)); +} +} // namespace +int main() try { + a_plan_totals_its_members_exactly(); + ages_and_the_distribution_survive_the_move(); + an_ineligible_member_refuses_the_whole_plan(); + a_committed_collapse_conserves_and_empties_the_members(); + every_rejection_leaves_the_world_as_it_was(); + one_plan_cannot_be_committed_twice(); + a_moved_from_plan_is_still_a_whole_plan(); + std::cout << "PASS collapse sampling, exact conservation and unchanged-on-rejection\n"; + return 0; +} catch (...) { + return 1; +}