From da39fc8095ff0880a697926d4d4a2d650bca54d9 Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 18 Oct 2026 13:57:52 -0400 Subject: [PATCH] M12.6: add bounded regional cellular census and lineage queries --- CMakeLists.txt | 6 + README.md | 5 + docs/STATUS.md | 16 ++ ...150-regional-cellular-census-projection.md | 63 +++++ docs/adr/README.md | 2 + docs/biology/ECOLOGICAL_IDENTITY_AND_TIME.md | 6 + docs/engineering/M12_DELIVERY_PLAN.md | 6 +- docs/engineering/M12_REMAINING_GATES.md | 10 +- docs/engineering/TEST_STRATEGY.md | 12 + docs/engineering/VALIDATION.md | 50 ++++ include/evo/biology/lineage.hpp | 5 + .../evo/server/lifecycle/cellular_census.hpp | 82 +++++++ .../ecology/regional-cellular-census-v1.md | 71 ++++++ src/server/lifecycle/cellular_census.cpp | 160 ++++++++++++ tests/cellular_census_tests.cpp | 231 ++++++++++++++++++ tests/cellular_migration_tests.cpp | 32 +++ tests/lineage_tests.cpp | 4 + 17 files changed, 757 insertions(+), 4 deletions(-) create mode 100644 docs/adr/0150-regional-cellular-census-projection.md create mode 100644 include/evo/server/lifecycle/cellular_census.hpp create mode 100644 schemas/ecology/regional-cellular-census-v1.md create mode 100644 src/server/lifecycle/cellular_census.cpp create mode 100644 tests/cellular_census_tests.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 4ba432c..0a18ff3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -89,6 +89,7 @@ add_library(evo_lifecycle STATIC src/server/lifecycle/primitive_lives.cpp src/server/lifecycle/primitive_batch.cpp src/server/lifecycle/cellular_lives.cpp src/server/lifecycle/cellular_migration.cpp src/server/lifecycle/cellular_migration_trace.cpp + src/server/lifecycle/cellular_census.cpp src/server/lifecycle/cellular_batch.cpp src/server/lifecycle/wildlife_controller.cpp src/server/lifecycle/cellular_play_summary.cpp src/server/lifecycle/cellular_population.cpp src/server/lifecycle/cellular_population_codec.cpp src/server/lifecycle/cellular_population_policy.cpp @@ -685,6 +686,11 @@ if(BUILD_TESTING) evo_owned_target(evo-cellular-population-tests) add_test(NAME cellular-population-transitions COMMAND evo-cellular-population-tests) set_tests_properties(cellular-population-transitions PROPERTIES TIMEOUT 180) + add_executable(evo-cellular-census-tests tests/cellular_census_tests.cpp) + target_link_libraries(evo-cellular-census-tests PRIVATE evo::lifecycle) + evo_owned_target(evo-cellular-census-tests) + add_test(NAME cellular-census-contract COMMAND evo-cellular-census-tests) + set_tests_properties(cellular-census-contract PROPERTIES TIMEOUT 180) add_test(NAME cellular-population-process-restart COMMAND "${CMAKE_COMMAND}" "-DPOPULATION_TEST=$" "-DTEST_DIR=${CMAKE_CURRENT_BINARY_DIR}/population-restart" diff --git a/README.md b/README.md index 5d5b70e..e862061 100644 --- a/README.md +++ b/README.md @@ -128,6 +128,11 @@ genome record, the deterministic development that derives a phenotype from it an the metabolic budgets that give capability a cost, and the seeded mutation catalog that proposes successors and the archive that keeps them. Synthetic process fixtures remain separate from organism biology. + +[Regional cellular census](schemas/ecology/regional-cellular-census-v1.md) provides +read-only local resident/presence/cohort and exact/descendant observations from +current cellular owners. Retained departed history is excluded from owned stock. +Durable world history, complete coverage and terminal extinction remain later gates. `apps/evo-sim` owns CLI/file I/O and reporting. `tests` holds contract, fuzz and measurement programs. `src/server/lifecycle` owns funded primitive diff --git a/docs/STATUS.md b/docs/STATUS.md index 06af653..92b59ed 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,5 +1,21 @@ # Project status and next steps +## M12.6a bounded regional census and history queries - 2026-10-18 + +The portable census now distinguishes resident individuals/cohorts and +active/lingering/suspended controlled lives, retaining exact body/reserve stock +and zero-carrier ancestry. Exact-genome and descendant queries use current carried +genomes. Retained departed history never counts as resident stock; migrations and +return trips retain that distinction without changing biology. + +Native Release passes **79/79**; GCC census/lineage/migration contracts, relevant +ASan/UBSan checks, Clang analysis and formatting pass. +[Evidence and limits](engineering/VALIDATION.md) retain durable atomic history +publication, commit/branch binding, complete world reconciliation and client +presentation as subsequent M12.6/12.7 work. This local projection grants no +terminal-extinction or ghost ownership authority. Linked ecology, maturation and +later integration/soak gates remain open; no deployment or World0 change. + ## M12.4l local migration storage failures - 2026-10-18 The private matrix now refuses preparation, staging or paired publication after diff --git a/docs/adr/0150-regional-cellular-census-projection.md b/docs/adr/0150-regional-cellular-census-projection.md new file mode 100644 index 0000000..67e5eac --- /dev/null +++ b/docs/adr/0150-regional-cellular-census-projection.md @@ -0,0 +1,63 @@ +# ADR-0150: Regional cellular census projection + +## Status + +Accepted for scoped M12.6a engineering implementation, 2026-10-18. This implements +a read-only local projection under ADR-0133, not durable population-history +publication, a complete world evidence envelope or terminal extinction. + +## Context and decision + +ADR-0144 retains departed organisms as known-alive archive records. Summing +`LineageArchive::living_carriers` across regions therefore duplicates migrants. +The exact population owner also contains both active and cohort members in one +store; counting that store and membership tags as separate organisms duplicates +stock. Suspended players remain living even when no organism is progressing. + +Add a bounded, detached `CellularCensus` projection of a valid rules-8 raw owner +(format 6/7) or exact population (envelope 1/2). Record world, region, frame, +completed tick and owner/rules/population versions. This observation has no lease, +commit digest or recovery-branch proof: observing an uncommitted candidate does +not grant it durable authority. A later adapter must bind a verified committed +payload and its exact history context before publishing evidence. + +Retain every locally archived genome in ascending ID order, including zero-carrier +ancestors, with its immutable parents and schema/development versions. Add a const +archive genome span for bounded enumeration; successful genome admission invalidates +that view. No removal or mutable archive access is added. + +Each row partitions resident living stock into five disjoint categories: individual +wildlife, exact cohort wildlife, active controlled, lingering controlled and +suspended controlled. Each category reports count, body and reserve in existing +pJ/C/N/P/other-fg units. Membership tags only classify the existing owned lives. +Corpses, food, nursery, heat and cumulative boundary flows are not living stock. +Retained nonresident archive records are a separate historical count without owned +inventory or current-viability meaning. Frozen source stock counts until paired +commit; an uncommitted destination ghost supplies no authoritative observation. + +Queries explicitly choose exact-genome carriers or the anchor's descendant +closure. Use the retained parent graph, bounded iterative traversal and checked +channel/count addition. Unknown anchor or unsupported versions fail; they do not +become zero. A zero result is a fact about this particular regional observation, +never world absence, species classification or terminal extinction. + +## Alternatives, costs and qualification + +Archive-only counting is invalid after migration; cohort-count addition violates +exclusive ownership. Scanning integer IDs up to an allocator high-water mark is +unbounded for sparse identities. Enumerate at most 4,096 retained genomes and +256 resident lives, retaining at most 65,536 historical nonresident records. +Build child adjacency once and visit each descendant at most once per query; +do not recurse on ancestry depth or inspect wall time. + +Require active/lingering/suspended separation, real funded wildlife, conversion +invariance, full restore reproducibility, mutation-current versus birth genomes, +zero-carrier ancestry retention, death exclusion, sparse identities and migration +ownership before/after/return. Compare resident counts and per-channel body/reserve +against direct individual observations. No biological rule, codec/golden, database, +network, renderer, foundation dependency, automatic selector or deployment changes. + +Durable append-only census/history with atomic commit binding, bounded backend +queries, branch/epoch/watermark reconciliation and client presentation remain +subsequent M12.6/12.7 work. Linked ecological resources and the rules-8 maturation +gap remain open independently of this observational primitive. diff --git a/docs/adr/README.md b/docs/adr/README.md index 5d543bf..42c63f7 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -1,5 +1,7 @@ # Architecture decision records +- [ADR-0150: Regional cellular census projection](0150-regional-cellular-census-projection.md) - bounded local resident/representation/presence census and exact/descendant queries; retained nonresident history never counts as owned stock or world extinction. + - [ADR-0149: Atomic paired biological migration publication](0149-atomic-cellular-migration-publication.md) - schema 49 binds both current fences, heads and exact candidates in one immutable receipt/transaction; recovery replays the pair and hosts verify the changed head before readiness. - [ADR-0148: Durable destination staging without activation](0148-durable-cellular-migration-staging.md) - schema 48 freezes the destination at its exact cut, retains a verified read-only ghost and replays it on recovery; source abort releases both pauses. diff --git a/docs/biology/ECOLOGICAL_IDENTITY_AND_TIME.md b/docs/biology/ECOLOGICAL_IDENTITY_AND_TIME.md index ef29f4a..779e39b 100644 --- a/docs/biology/ECOLOGICAL_IDENTITY_AND_TIME.md +++ b/docs/biology/ECOLOGICAL_IDENTITY_AND_TIME.md @@ -5,6 +5,12 @@ M12.1 defines evidence and explicit deferrals. The evidence contract is [identity-and-time-v1](../../schemas/ecology/identity-and-time-v1.md); it is not an implemented codec or world extinction service. +M12.6a implements [ADR-0150's bounded regional census](../adr/0150-regional-cellular-census-projection.md). +It reports local resident stock by current genome and exact/descendant scope, +including suspended players; retained nonresident records carry no owned stock. +This detached observation has no commit/branch binding or world coverage and +does not implement the global evidence envelope or terminal extinction below. + ## Identity and classification An organism has a permanent identity and terminal death. An immutable genome has diff --git a/docs/engineering/M12_DELIVERY_PLAN.md b/docs/engineering/M12_DELIVERY_PLAN.md index de61432..3cd1799 100644 --- a/docs/engineering/M12_DELIVERY_PLAN.md +++ b/docs/engineering/M12_DELIVERY_PLAN.md @@ -4,16 +4,16 @@ Requested scope: ecological identity, population qualification, durable automati tier transitions, unattended scheduling/migration and environmental coupling. Commit and push each validated scoped segment separately. -## Gate status (2026-10-17) +## Gate status (2026-10-18) | Subset | State | Evidence or condition for completion | |---|---|---| | 12.1 | Engineering evidence policy and explicit deferrals documented | ADR-0133, identity/time contract and worked histories; no new game rules or runtime versions. | | 12.2 | Exact local model selected and paired qualification implemented (12.2d); production cost gate open | ADR-0139, exact canonical equality across 196,608 paired ticks per platform. Regional approximation disabled; no compression claim. Deployment-host capacity and fuller interaction coverage remain open. | | 12.3 | Exact population profile/trace/store and opt-in host integration implemented (12.3b) | ADR-0142, schema 44; exact publication/recovery, mutation race guards, ambiguous replies and process kills. Executable/network population fault drills and target-host qualification remain open. | -| 12.4 | Unattended demand/pacing plus owned population interval admission/recovery implemented (12.4b) | ADR-0143/schema 45; bounded durable pending work, exact settlement, replacement-owner and uncertainty tests. Biological migration escrow and boundary/stock-in-transit evidence remain open. | +| 12.4 | Owned intervals and durable paired migration/fault qualification implemented in scoped segments through 12.4l | ADR-0143–0149/schema 49; bounded admitted work, source freeze, staged ghost, atomic pair and exact recovery, local TLS and storage faults. Multi-host/orchestrator, linked ecology and integrated stock audits remain open. | | 12.5 | Blocked on 12.2-12.4 | Finite M6 process fixtures do not qualify coupled persistent cellular/cohort atmosphere/water budgets. | -| 12.6 | Existing local archive retained; integrated population history open | World-level durable event/query/client path remains required. | +| 12.6 | Local archive plus regional resident/presence/cohort census and exact/descendant queries implemented (12.6a) | ADR-0150; local detached observations exclude departed history from stock. Commit/branch binding, atomic durable events and world-level query/client path remain required. | | 12.7 | Evidence policy defined; reconciler open | Complete durable world watermark and every viable/in-flight store remain required. | | 12.8 | Not qualified | Actual multi-day integrated ecology/restart/clone evidence remains required. | | 12.9 | Not accepted | Returning-player product evidence and expansion review remain required; World0 stays separately blocked. | diff --git a/docs/engineering/M12_REMAINING_GATES.md b/docs/engineering/M12_REMAINING_GATES.md index 2f4336e..fde123a 100644 --- a/docs/engineering/M12_REMAINING_GATES.md +++ b/docs/engineering/M12_REMAINING_GATES.md @@ -27,7 +27,7 @@ or authorize production enablement. | 12.3 | Dedicated population profile/trace/store/owning host; exact recovery and private PostgreSQL fault tests | Population-specific executable/network fault drills and target-host publication/capacity qualification. | | 12.4 | Owned intervals; exact transfer/accounting; durable atomic pair/recovery; independent loopback TLS path loss and owner expiry/replacement/heal; local object sync/read-failure matrix | Multi-host/kernel-network, storage-host and orchestrator drills, linked-boundary contracts and integrated ownership/stock audits at scale. | | 12.5 | Finite cellular contact feeding/decay and separate M6 producer/consumer resource owner | One jointly owned cellular/environment budget, explicit effective depth and source entitlements, versioned water/atmosphere species mapping and producer coefficients, plus closed/open and nutrient-exhaustion comparisons. | -| 12.6 | Retained genome/organism archive with ancestry and common-ancestor queries | Append-only population census/history events in the same durable commit, bounded world history queries/indexing and client presentation; no account power or invented precise statistical ancestry. | +| 12.6 | Retained archive plus bounded regional resident/presence/cohort census and exact/descendant queries (12.6a) | Append-only population census/history events in the same durable commit, bounded world history queries/indexing and client presentation; no account power or invented precise statistical ancestry. | | 12.7 | ADR-0133's viability/unknown semantics | Durable region-set/watermark reconciliation covering every owned representation, suspended/viable stock and migration escrow. Missing/stale regions must prevent terminal extinction. | | 12.8 | Deterministic seed/regime drivers and separate-process exact continuation | Reproducible integrated worlds running for actual days, real restarts/clone comparisons and retained accounting/diversity/cost audits. Accelerated tests cannot supply elapsed days. | | 12.9 | M11 feedback and current UI review retained | Returning-player samples on the integrated ecology and explicit product/3D readiness decision after soak evidence. No M12 product acceptance or World0 promotion is inferred. | @@ -94,6 +94,14 @@ Finite extra food alone does not close repeated wildlife generations. A versione growth contract and real multi-generation evidence remain necessary; transfer tests must not fabricate adult wildlife or silently change the rules to pass. +M12.6a's [regional census projection](../../schemas/ecology/regional-cellular-census-v1.md) +independently implements local current-genome and descendant-closure queries. +It keeps suspended stock and retained zero-carrier ancestry, separates exact cohort +tags from additional ownership, and excludes nonresident history from living stock. +It has no commit/branch/epoch binding or complete world coverage, so it cannot +publish authoritative world history or accept terminal extinction. Durable atomic +history publication and M12.7 reconciliation remain the next history boundaries. + Current expansion readiness: **no-go for M13 integration or World0 promotion** while these M12 integration/evidence gates remain open. This records the present engineering evidence, not a substitute for the later maintainer product review. diff --git a/docs/engineering/TEST_STRATEGY.md b/docs/engineering/TEST_STRATEGY.md index 644fdcd..8ab66bd 100644 --- a/docs/engineering/TEST_STRATEGY.md +++ b/docs/engineering/TEST_STRATEGY.md @@ -1,5 +1,17 @@ # Validation strategy +M12.6a's regional census tests compare per-category counts and body/reserve +inventories with direct individual observations. Cover active/lingering/suspended +controlled lives, real funded wildlife, exact cohort conversion/restoration, +permanent death and empty owners, all 256 resident slots, mutation-current versus +immutable birth genomes, zero-carrier ancestry and sparse IDs whose numeric order +differs from ancestry. Unknown anchor/scope and older biological rules must fail. +Existing migration tests additionally verify nonresident historical counts, +per-member migrant inventory, repeated return trips and imported cohort tags. +Full native regression and relevant ASan/UBSan/Clang checks qualify this portable +projection; durable commit-bound history, complete world coverage and client +queries remain separate M12.6/12.7 gates. No terminal-extinction outcome exists. + M12.4f's checkpoint contract exercises explicit portable bundle-9 to 10 upgrades for raw owners and a real nonempty cohort with retained policy/sequence. It requires complete candidate equality, canonical restore, continued batch-2 diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index c3df943..e9d7e5e 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -1,5 +1,55 @@ # Validation report +## 2026-10-18 - M12.6a bounded regional census and lineage queries + +ADR-0150 adds a detached rules-8 regional projection, with explicit presence and +representation categories, per-channel living body/reserve stock, exact/current +genome and descendant-closure queries, zero-carrier retained ancestry and separate +nonresident historical counts. A const archive genome span permits bounded sparse +enumeration without a scan to the largest ID. No archive removal/mutable access, +biological rule, persistent codec or database publication is added. See the +[projection contract](../../schemas/ecology/regional-cellular-census-v1.md). + +Executed locally: + +- Native MSVC Release full CTest **79/79 passed**, **13.97 s**, with NDEBUG. +- GCC 14 Release census, lineage and migration contracts **3/3 passed**, **2.45 s**, + including the final funded two-step mutation ancestry case and NDEBUG checks. +- Linux Clang 19 ASan/UBSan lineage, population, census and migration contracts + **4/4 passed**, **76.78 s**, without reports. After the final ancestry/sentinel + test addition, the census sanitizer test passed again, **21.66 s**. +- Explicit clang-tidy 19 on the implementation and census/lineage/migration tests + passed with no owned warnings; repository clang-format 19 and `git diff --check` + passed. No new warning suppression was added. + +Direct individual observations independently check category counts and every +body/reserve channel. Actual funded mutations distinguish immutable birth and +current genomes; the grandchild's sparse ID is numerically below its parent's. +Exact-genome zero retains its ancestor while a descendant query finds the living +successor. Active, lingering and suspended controlled stock stays distinct. +Real wildlife collapses/materializes without a second inventory; cohort restore +reproduces the same rows. Death leaves history but no living count. Empty worlds, +all 256 resident slots, unknown anchors/scopes and unsupported legacy rules are +covered. Migration tests audit departed historical records, exact individual +migrant inventories, 100 return transfers and imported envelope-2 cohort tags. + +Initial test setup incorrectly supplied zero capacity to the shared empty-opening +fixture; it now provisions positive capacity with no births. The first direct +analysis invocation lacked CMake-generated module scan maps. A separate scan-free +Clang compilation database resolves that tooling issue. An explicit named invalid +scope sentinel replaces the analyzer's rejected out-of-range literal test cast; +the API still rejects every scope other than exact or descendants. + +Limits: this is a portable in-memory observation, not a durable historical event, +committed evidence envelope, client query service or globally complete census. +No commit/epoch/branch/watermark binding or terminal-extinction outcome exists. +Archive capacities bound the algorithm; maximum-depth history performance on the +deployment host is not measured here. No new PostgreSQL, TSan, Docker or remote-CI +result is claimed; no thread or I/O path is introduced. Goldens and retained +biological formats are unchanged. Linked ecology/maturation, durable history, +world reconciliation and actual elapsed-day soak remain open. No deployment or +World0 action; unrelated `Build_Errors.txt` and `tash drop` remain untracked. + ## 2026-10-18 - M12.4l migration object sync/read failures Test-only qualification extends ADR-0147–0149 using the existing filesystem diff --git a/include/evo/biology/lineage.hpp b/include/evo/biology/lineage.hpp index 2b17969..b611756 100644 --- a/include/evo/biology/lineage.hpp +++ b/include/evo/biology/lineage.hpp @@ -118,6 +118,11 @@ class LineageArchive { [[nodiscard]] std::size_t archived() const noexcept { return genomes_.size(); } + // Ascending immutable IDs, including zero-carrier ancestors. Successful + // genome admission invalidates this view; no removal or spending rights. + [[nodiscard]] std::span genomes() const noexcept { + return genomes_; + } [[nodiscard]] std::uint32_t format_version() const noexcept { return format_version_; } diff --git a/include/evo/server/lifecycle/cellular_census.hpp b/include/evo/server/lifecycle/cellular_census.hpp new file mode 100644 index 0000000..018f032 --- /dev/null +++ b/include/evo/server/lifecycle/cellular_census.hpp @@ -0,0 +1,82 @@ +#pragma once + +#include "evo/server/lifecycle/cellular_population.hpp" + +#include +#include +#include +#include +#include +#include + +namespace evo::server { +inline constexpr std::uint32_t cellular_census_projection_version = 1; +enum class CellularCensusKind : std::uint8_t { + individual_wildlife, + cohort_wildlife, + active_controlled, + lingering_controlled, + suspended_controlled +}; +inline constexpr std::size_t cellular_census_kind_count = 5; +struct CellularCensusStock { + std::uint64_t count{}; + accounting::Inventory body{}, reserve{}; + bool operator==(const CellularCensusStock&) const = default; +}; +struct CellularCensusTotals { + std::array resident{}; + // Historical observations only: no owned inventory/current viability claim. + std::uint64_t retained_nonresident_records{}; + bool operator==(const CellularCensusTotals&) const = default; +}; +struct CellularCensusRow { + std::uint64_t genome{}; + std::uint32_t schema{}, development{}; + std::vector parents; + CellularCensusTotals totals; + bool operator==(const CellularCensusRow&) const = default; +}; +struct CellularCensusBoundary { + std::uint64_t world{}, region{}, frame{}, tick{}; + std::uint32_t owner_format{}, rules{}, population_format{}; // Zero: raw owner. + std::uint64_t quantum_microseconds{biology::cellular_motion_tick_microseconds}; + bool operator==(const CellularCensusBoundary&) const = default; +}; +enum class CellularCensusScope : std::uint8_t { exact_genome, descendants, invalid = 255 }; +enum class CellularCensusError : std::uint8_t { + unsupported, + history, + overflow, + unknown_genome, + invalid_scope +}; +// Detached bounded observation, NOT a committed/world-complete evidence record. +// It never owns inventory, changes biology or reports terminal extinction. +class CellularCensus { + public: + [[nodiscard]] static std::expected + observe(const CellularLives&); + [[nodiscard]] static std::expected + observe(const CellularPopulation&); + [[nodiscard]] const CellularCensusBoundary& boundary() const noexcept { + return boundary_; + } + // Ascending genome IDs. All retained ancestors remain, even with zero residents. + [[nodiscard]] std::span rows() const noexcept { + return rows_; + } + // Descendants includes the anchor. Unknown is an error, never a zero report. + [[nodiscard]] std::expected + query(std::uint64_t anchor, CellularCensusScope scope) const; + + private: + CellularCensus() = default; + [[nodiscard]] static std::expected + observe(const CellularLives&, std::span, std::uint32_t population); + [[nodiscard]] std::size_t locate(std::uint64_t genome) const; + CellularCensusBoundary boundary_; + std::vector rows_; + std::vector> children_; +}; +} // namespace evo::server diff --git a/schemas/ecology/regional-cellular-census-v1.md b/schemas/ecology/regional-cellular-census-v1.md new file mode 100644 index 0000000..3d18424 --- /dev/null +++ b/schemas/ecology/regional-cellular-census-v1.md @@ -0,0 +1,71 @@ +# Regional cellular census projection v1 + +Authority: [ADR-0150](../../docs/adr/0150-regional-cellular-census-projection.md), +under [ADR-0133](../../docs/adr/0133-ecological-identity-and-time-evidence.md). +Portable API: `evo::server::CellularCensus`. This is an in-memory observation +contract, not a persistent codec, network message or complete world evidence set. + +## Boundary and rows + +The boundary records exact world, region, frame, completed simulation tick, +50,000 µs quantum and owner/rules/population versions. Raw observation has +population format zero; exact populations retain envelope 1 or 2. Only rules 8, +owner 6/7 and those exact representations are supported. Unsupported sources fail. +The projection version is 1, separately from every biological/checkpoint format. + +Rows are unique and ascending by immutable genome ID. Each retains its genome +schema, development version and exact parent IDs, including ancestors with no +resident carriers. These links describe genome ancestry; they do not fabricate +organism parentage or a species classifier. Mutation counts use a resident's +current genome rather than its immutable birth genome. + +Each row contains five disjoint resident categories: + +| Category | Meaning | +|---|---| +| individual wildlife | Zero-account living resident without a cohort tag | +| cohort wildlife | The same owned resident store, classified by an exact membership tag | +| active controlled | Controlled living resident with active presence | +| lingering controlled | Frozen controlled life still lingering in its world slot | +| suspended controlled | Frozen controlled living stock outside active occupancy | + +Each category reports a whole-individual count, body inventory and reserve +inventory, in pJ and the four disjoint C/N/P/other fg channels. There are no +fractional organisms, statistical representatives or duplicate cohort inventory. +Counts and inventories exclude corpses, detritus, habitat food, nursery, heat and +cumulative boundary inflow/outflow. Those compartments still belong in a separate +whole-region conservation audit; they are not living or viable reproductive stock. + +`retained_nonresident_records` counts historical departed organisms by their +locally recorded genome. It carries no inventory or current presence/absence +meaning. A remote mutation or death need not be known by this historical source. +It is never added to resident stock. Returned residents cease being nonresident +under the existing migration contract. + +## Queries and authority limits + +`query(anchor, exact_genome)` selects only the named genome's current residents. +`query(anchor, descendants)` includes that anchor and all locally retained genome +descendants. Child adjacency and a visited set prevent repeated counting; +iterative traversal avoids native stack growth. Unknown anchors and invalid scope +are errors, not empty observations. Channel/count overflow refuses a result. + +The archive caps observation at 4,096 genomes and 65,536 historical organism +records; the owner caps resident lives at 256. Enumeration uses retained records, +never the numeric distance between sparse IDs. Building adjacency costs +O(G log G + E log G); querying descendant closure costs O(G + E), with E bounded by +the supported genome-parent limits. No database, clocks, threads or renderer are +involved. Returned rows and boundary remain detached from subsequent simulation. + +There is deliberately no terminal-extinction status. Zero carriers describes only +this exact regional observation; a missing row is not a zero for another region. +The API supplies no commit, owner epoch, history branch, region-set coverage, +pending-transfer status or proof of current authority. A detached candidate or +destination ghost can be observed for comparison but cannot be published as owned +world stock. Before paired migration commit, the frozen committed source owns +migrants; afterwards only the committed destination owns them. + +Durable M12.6 publication must derive this projection from a verified committed +payload, bind its manifest/digest and branch, and append evidence atomically with +the biological head. M12.7 must reconcile every required owner/store at a complete +watermark. Neither operation is implemented by this local projection. diff --git a/src/server/lifecycle/cellular_census.cpp b/src/server/lifecycle/cellular_census.cpp new file mode 100644 index 0000000..59035d1 --- /dev/null +++ b/src/server/lifecycle/cellular_census.cpp @@ -0,0 +1,160 @@ +#include "evo/server/lifecycle/cellular_census.hpp" + +#include +#include +#include + +namespace evo::server { +namespace { +bool add(std::uint64_t& target, std::uint64_t value) { + if (value > std::numeric_limits::max() - target) + return false; + target += value; + return true; +} +bool add(accounting::Inventory& target, const accounting::Inventory& value) { + if (!add(target.energy.value, value.energy.value)) + return false; + for (std::size_t channel = 0; channel < target.matter.size(); ++channel) + if (!add(target.matter[channel].value, value.matter[channel].value)) + return false; + return true; +} +bool add(CellularCensusTotals& target, const CellularCensusTotals& value) { + if (!add(target.retained_nonresident_records, value.retained_nonresident_records)) + return false; + for (std::size_t kind = 0; kind < target.resident.size(); ++kind) { + auto& stock = target.resident[kind]; + const auto& source = value.resident[kind]; + if (!add(stock.count, source.count) || !add(stock.body, source.body) || + !add(stock.reserve, source.reserve)) + return false; + } + return true; +} +} // namespace + +std::size_t CellularCensus::locate(std::uint64_t genome) const { + const auto found = std::ranges::lower_bound(rows_, genome, {}, &CellularCensusRow::genome); + return found != rows_.end() && found->genome == genome + ? static_cast(found - rows_.begin()) + : rows_.size(); +} +std::expected +CellularCensus::observe(const CellularLives& state) { + return observe(state, {}, 0); +} +std::expected +CellularCensus::observe(const CellularPopulation& population) { + return observe(population.state(), population.members(), population.format_version()); +} +std::expected +CellularCensus::observe(const CellularLives& state, std::span members, + std::uint32_t population) { + if (state.rules_version() != cellular_lives_foraging_rules || + (state.format_version() != cellular_lives_presence_format && + state.format_version() != cellular_lives_migration_format) || + (population != 0 && population != 1 && population != 2)) + return std::unexpected(CellularCensusError::unsupported); + CellularCensus result; + result.boundary_ = {state.world(), state.region(), state.frame(), state.tick(), + state.format_version(), state.rules_version(), population}; + const auto& archive = state.archive(); + result.rows_.reserve(archive.archived()); + for (const auto& genome : archive.genomes()) + result.rows_.push_back({genome.id(), + genome.schema_version(), + genome.development_version(), + {genome.parents().begin(), genome.parents().end()}, + {}}); + result.children_.resize(result.rows_.size()); + for (std::size_t child = 0; child < result.rows_.size(); ++child) + for (const auto parent : result.rows_[child].parents) { + const auto index = result.locate(parent); + if (index == result.rows_.size()) + return std::unexpected(CellularCensusError::history); + result.children_[index].push_back(child); + } + for (const auto& life : state.lives()) { + const auto row = result.locate(life.identity.genome); + if (row == result.rows_.size()) + return std::unexpected(CellularCensusError::history); + CellularCensusKind kind{}; + if (life.account == LifeAccount{}) { + const bool cohort = std::ranges::binary_search(members, life.identity.life, {}, + &CellularCohortMember::life); + kind = cohort ? CellularCensusKind::cohort_wildlife + : CellularCensusKind::individual_wildlife; + } else { + switch (life.presence) { + case CellularPresence::active: + kind = CellularCensusKind::active_controlled; + break; + case CellularPresence::lingering: + kind = CellularCensusKind::lingering_controlled; + break; + case CellularPresence::suspended: + kind = CellularCensusKind::suspended_controlled; + break; + } + } + auto& stock = result.rows_[row].totals.resident[static_cast(kind)]; + if (!add(stock.count, 1) || !add(stock.body, life.body) || + !add(stock.reserve, life.reserve)) + return std::unexpected(CellularCensusError::overflow); + } + const auto& nonresident = state.boundary_ledger().nonresident_organisms; + std::vector nonresident_genomes; + nonresident_genomes.reserve(nonresident.size()); + for (const auto organism : nonresident) { + const auto birth = archive.organism(organism); + if (!birth) + return std::unexpected(CellularCensusError::history); + nonresident_genomes.push_back(birth->genome); + } + // One bounded revision pass, rather than scanning every revision for every + // departed record. Archive admission guarantees canonical revision order. + for (const auto& revision : archive.revisions()) { + const auto found = std::ranges::lower_bound(nonresident, revision.organism); + if (found == nonresident.end() || *found != revision.organism) + continue; + auto& genome = nonresident_genomes[static_cast(found - nonresident.begin())]; + if (genome != revision.previous_genome) + return std::unexpected(CellularCensusError::history); + genome = revision.successor_genome; + } + for (const auto genome : nonresident_genomes) { + const auto row = result.locate(genome); + if (row == result.rows_.size()) + return std::unexpected(CellularCensusError::history); + if (!add(result.rows_[row].totals.retained_nonresident_records, 1)) + return std::unexpected(CellularCensusError::overflow); + } + return result; +} +std::expected +CellularCensus::query(std::uint64_t anchor, CellularCensusScope scope) const { + if (scope != CellularCensusScope::exact_genome && scope != CellularCensusScope::descendants) + return std::unexpected(CellularCensusError::invalid_scope); + const auto root = locate(anchor); + if (root == rows_.size()) + return std::unexpected(CellularCensusError::unknown_genome); + if (scope == CellularCensusScope::exact_genome) + return rows_[root].totals; + CellularCensusTotals result; + std::vector visited(rows_.size(), false); + std::vector pending{root}; + visited[root] = true; + for (std::size_t next = 0; next < pending.size(); ++next) { + const auto row = pending[next]; + if (!add(result, rows_[row].totals)) + return std::unexpected(CellularCensusError::overflow); + for (const auto child : children_[row]) + if (!visited[child]) { + visited[child] = true; + pending.push_back(child); + } + } + return result; +} +} // namespace evo::server diff --git a/tests/cellular_census_tests.cpp b/tests/cellular_census_tests.cpp new file mode 100644 index 0000000..fa7efb1 --- /dev/null +++ b/tests/cellular_census_tests.cpp @@ -0,0 +1,231 @@ +#include "evo/server/lifecycle/cellular_census.hpp" +#include "fixtures/cellular_ecology.hpp" + +#include + +namespace { +using namespace evo; +using namespace evo::server; +using namespace evo::fixture; +using Kind = CellularCensusKind; +using Scope = CellularCensusScope; +std::size_t index(Kind kind) { + return static_cast(kind); +} +Inventory sum(Inventory left, const Inventory& right) { + require(right.energy.value <= std::numeric_limits::max() - left.energy.value, + "oracle energy overflow"); + left.energy.value += right.energy.value; + for (std::size_t channel = 0; channel < left.matter.size(); ++channel) { + require(right.matter[channel].value <= + std::numeric_limits::max() - left.matter[channel].value, + "oracle matter overflow"); + left.matter[channel].value += right.matter[channel].value; + } + return left; +} +CellularCensusTotals direct(const CellularLives& state, std::uint64_t anchor, bool descendants, + const CellularPopulation* population = nullptr) { + CellularCensusTotals result; + for (const auto& life : state.lives()) { + const auto ancestry = + checked(state.archive().ancestry(life.identity.genome), "oracle ancestry"); + if (descendants ? std::ranges::find(ancestry, anchor) == ancestry.end() + : life.identity.genome != anchor) + continue; + std::size_t kind{}; + if (life.account == LifeAccount{}) + kind = population && population->in_cohort(life.identity.life) ? 1 : 0; + else + kind = 2 + static_cast(life.presence); + auto& stock = result.resident[kind]; + ++stock.count; + stock.body = sum(stock.body, life.body); + stock.reserve = sum(stock.reserve, life.reserve); + } + return result; +} +void verify(const CellularCensus& census, const CellularLives& state, + const CellularPopulation* population = nullptr) { + require(census.boundary() == + CellularCensusBoundary{state.world(), state.region(), state.frame(), state.tick(), + state.format_version(), state.rules_version(), + population ? population->format_version() : 0}, + "census lost its local/version/time boundary"); + require(census.rows().size() == state.archive().archived(), + "census discarded retained genomes"); + require(std::ranges::is_sorted(census.rows(), {}, &CellularCensusRow::genome), + "census genome order"); + for (const auto& row : census.rows()) { + const auto genome = checked(state.archive().find(row.genome), "census retained genome"); + require(row.schema == genome.schema_version() && + row.development == genome.development_version() && + std::ranges::equal(row.parents, genome.parents()), + "census rewrote genome provenance"); + require(checked(census.query(row.genome, Scope::exact_genome), "exact census query") == + direct(state, row.genome, false, population) && + checked(census.query(row.genome, Scope::descendants), "lineage census query") == + direct(state, row.genome, true, population), + "census differs from direct current-individual count/inventory"); + } +} +void step(CellularLives& state, bool freeze_first = false) { + std::vector intents; + for (const auto& life : state.lives()) { + CellularLifeIntent input{life.identity.life, {}}; + input.intent.frozen = freeze_first && life.identity.life == 100; + intents.push_back(input); + } + checked(state.advance_tick(intents), "census fixture tick"); +} +void presence_and_detachment() { + auto owner = opening(1, true); + const auto before = owner->snapshot(); + const auto initial = checked(CellularCensus::observe(*owner), "initial census"); + verify(initial, *owner); + require(owner->snapshot() == before, "observation changed biology"); + require(!initial.query(0, Scope::exact_genome) && + initial.query(0, Scope::exact_genome).error() == + CellularCensusError::unknown_genome && + !initial.query(100, Scope::invalid) && + initial.query(100, Scope::invalid).error() == CellularCensusError::invalid_scope, + "unknown genome/scope became a zero report"); + step(*owner, true); + auto lingering = checked(CellularCensus::observe(*owner), "lingering census"); + verify(lingering, *owner); + require(checked(lingering.query(100, Scope::exact_genome), "lingering founder") + .resident[index(Kind::lingering_controlled)] + .count == 1, + "lingering player disappeared from living stock"); + for (std::uint64_t ticks = 0; ticks <= cellular_linger_ticks; ++ticks) + step(*owner, true); + const auto suspended = checked(CellularCensus::observe(*owner), "suspended census"); + verify(suspended, *owner); + require(checked(suspended.query(100, Scope::exact_genome), "suspended founder") + .resident[index(Kind::suspended_controlled)] + .count == 1 && + checked(initial.query(100, Scope::exact_genome), "detached old founder") + .resident[index(Kind::active_controlled)] + .count == 1 && + initial.boundary().tick < suspended.boundary().tick, + "suspension lost viability or rewrote an earlier observation"); + const auto recovered = restore(*owner); + require( + std::ranges::equal(checked(CellularCensus::observe(*recovered), "restored census").rows(), + suspended.rows()), + "restore changed census"); +} +void mutation_and_retention() { + auto owner = opening(1, true, 1); + constexpr std::uint64_t first_successor = 9'000'000'000'000'000'000ULL; + // The grandchild ID precedes its parent in numeric order. Sparse IDs and + // ancestry depth must not become a numeric scan or a topological assumption. + for (const auto successor : {first_successor, first_successor - 1}) { + bool applied = false; + for (unsigned tick = 0; tick < 8192 && !applied; ++tick) { + const auto& life = owner->lives().front(); + std::vector choices; + if (life.mutation.offer) { + const auto& offer = *life.mutation.offer; + for (const auto& candidate : offer.candidates) { + const auto genome = + checked(owner->archive().find(life.identity.genome), "mutation genome"); + if (biology::fund_mutation(genome, offer.context, offer, candidate.operator_id, + successor, successor, life.reserve)) { + choices.push_back({life.identity.life, life.mutation.event_index, + life.mutation.offer_tick, successor, + candidate.operator_id}); + break; + } + } + } + const std::array intent{{{100, {}}}}; + const auto result = checked(owner->advance_tick_with_mutations(intent, choices), + "funded census mutation"); + applied = !result.mutations.empty() && + result.mutations.front().result == CellularMutationResult::applied; + } + require(applied, "census fixture never funded a mutation"); + } + const auto census = checked(CellularCensus::observe(*owner), "mutation census"); + verify(census, *owner); + require(census.rows().size() == 3 && census.rows().back().genome == first_successor && + checked(owner->archive().organism(100), "immutable birth").genome == 100 && + checked(census.query(100, Scope::exact_genome), "old exact carriers") == + CellularCensusTotals{} && + checked(census.query(first_successor, Scope::exact_genome), + "zero-carrier middle") == CellularCensusTotals{} && + checked(census.query(100, Scope::descendants), "mutated lineage") + .resident[index(Kind::active_controlled)] + .count == 1, + "current-genome observation used birth genome or dropped a zero-carrier ancestor"); +} +void cohorts_and_death() { + auto population = + checked(CellularPopulation::create(cellular_descendants()), "census population"); + const auto before = checked(CellularCensus::observe(*population), "individual wildlife census"); + verify(before, population->state(), population.get()); + const auto wildlife = std::ranges::find_if(population->state().lives(), [](const auto& life) { + return life.account == LifeAccount{}; + }); + require(wildlife != population->state().lives().end(), "census needs real wildlife"); + const auto genome = wildlife->identity.genome; + const auto biology = population->state().snapshot(); + const auto moved = checked(population->collapse(genome), "census collapse"); + const auto cohort = checked(CellularCensus::observe(*population), "cohort census"); + verify(cohort, population->state(), population.get()); + const auto stock = checked(cohort.query(genome, Scope::exact_genome), "cohort stock"); + require(moved > 0 && stock.resident[index(Kind::cohort_wildlife)].count == moved && + stock.resident[index(Kind::individual_wildlife)].count == 0 && + population->state().snapshot() == biology, + "membership tags counted a second spendable population"); + const auto& state = population->state(); + const auto recovered = + checked(CellularPopulation::restore(population->snapshot(), state.world(), state.region(), + state.frame(), state.tick()), + "cohort census restore"); + require(std::ranges::equal( + checked(CellularCensus::observe(*recovered), "restored cohort census").rows(), + cohort.rows()), + "restoring cohort tags changed census"); + checked(population->materialize(genome), "census materialize"); + require(std::ranges::equal( + checked(CellularCensus::observe(*population), "materialized census").rows(), + before.rows()), + "conversion oscillation changed observed biology"); + auto scarce = opening(7, false, 1); + for (unsigned tick = 0; tick < 8192 && !scarce->lives().empty(); ++tick) + step(*scarce); + require(scarce->lives().empty() && scarce->archive().recorded() > 0, + "death fixture never died"); + const auto dead = checked(CellularCensus::observe(*scarce), "dead census"); + verify(dead, *scarce); + require(dead.rows().size() == 1 && dead.rows().front().totals == CellularCensusTotals{}, + "corpse/detritus counted as a living or reproductive reserve"); + const auto empty = opening(1, true, 1, false); + require(checked(CellularCensus::observe(*empty), "empty census").rows().empty(), + "empty owner invented history"); + auto large = opening(1, true, 256); + verify(checked(CellularCensus::observe(*large), "capacity census"), *large); + auto legacy_primitive = + checked(PrimitiveLives::create({1, 1, 1, 1, {}, {{100, 100}}}), "legacy census opening"); + auto legacy_habitat = checked(biology::CellularHabitat::create({1, 1, 1, 1000, 1000, {}}), + "legacy census habitat"); + const auto legacy = checked(CellularLives::create(*legacy_primitive, std::move(legacy_habitat), + {{1000, 1000}, 0, 293150}), + "legacy census owner"); + const auto unsupported = CellularCensus::observe(*legacy); + require(!unsupported && unsupported.error() == CellularCensusError::unsupported, + "legacy rules silently reinterpreted by current census"); +} +} // namespace +int main() try { + presence_and_detachment(); + mutation_and_retention(); + cohorts_and_death(); + std::cout << "PASS local census presence, exact lineage queries, conversion and retention\n"; + return 0; +} catch (const std::exception& error) { + std::cerr << error.what() << '\n'; + return 1; +} diff --git a/tests/cellular_migration_tests.cpp b/tests/cellular_migration_tests.cpp index 5490616..7ea09f4 100644 --- a/tests/cellular_migration_tests.cpp +++ b/tests/cellular_migration_tests.cpp @@ -1,3 +1,4 @@ +#include "evo/server/lifecycle/cellular_census.hpp" #include "evo/server/lifecycle/cellular_migration.hpp" #include "evo/server/lifecycle/cellular_migration_trace.hpp" #include "evo/server/lifecycle/cellular_population_batch.hpp" @@ -411,6 +412,18 @@ void upgrade_and_move() { require(moved.source->archive().encode() == source->archive().encode() && moved.source->boundary_ledger().nonresident_organisms == moved.members, "departure erased history or recorded death"); + const auto departure = checked(CellularCensus::observe(*moved.source), "departure census"); + const auto arrival = checked(CellularCensus::observe(*moved.destination), "arrival census"); + const auto departed = + checked(departure.query(genome, CellularCensusScope::exact_genome), "departure carriers"); + const auto arrived = + checked(arrival.query(genome, CellularCensusScope::exact_genome), "arrival carriers"); + require(departed.retained_nonresident_records == moved.members.size() && + departed.resident[0] == CellularCensusStock{} && + arrived.retained_nonresident_records == 0 && + arrived.resident[0].count == moved.members.size(), + "regional census counted departed archive history as owned wildlife"); + Inventory migrant_bodies, migrant_reserves; for (const auto id : moved.members) { const auto before = std::ranges::find(source->lives(), id, [](const auto& life) { return life.identity.life; }); @@ -421,7 +434,12 @@ void upgrade_and_move() { "member was relabeled/healed/resampled"); require(moved.destination->archive().organism(id) == source->archive().organism(id), "birth history changed"); + migrant_bodies = plus(migrant_bodies, before->body); + migrant_reserves = plus(migrant_reserves, before->reserve); } + require(arrived.resident[0].body == migrant_bodies && + arrived.resident[0].reserve == migrant_reserves, + "census migrant inventory differs from exact individual stock"); require(moved.destination->next_bud_sequence() == target->next_bud_sequence(), "import consumed a local bud identity"); auto source_after = decode(*moved.source, moved.source->snapshot()); @@ -433,6 +451,12 @@ void upgrade_and_move() { checked(CellularMigration::prepare(back ? *target_after : *source_after, back ? *source_after : *target_after, genome), "migration return trip"); + const auto returning = checked(CellularCensus::observe(*next.destination), "return census"); + const auto returned = checked(returning.query(genome, CellularCensusScope::exact_genome), + "returned carriers"); + require(returned.retained_nonresident_records == 0 && + returned.resident[0].count == members.size(), + "returned stock was still classified as nonresident history"); if (back) { source_after = std::move(next.destination); target_after = std::move(next.source); @@ -512,6 +536,14 @@ void population_envelope() { peer->state().region(), peer->state().frame(), peer->state().tick()), "migrated cohort restore"); + const auto cohort_census = + checked(CellularCensus::observe(*restored), "imported cohort census"); + const auto cohort_stock = checked( + cohort_census.query(genome, CellularCensusScope::exact_genome), "imported cohort carriers"); + require(cohort_census.boundary().population_format == 2 && + cohort_stock.resident[0].count == 0 && + cohort_stock.resident[1].count == restored->members().size(), + "imported cohort census duplicated or lost exact members"); require(std::ranges::equal(restored->members(), next->members()), "cohort tags lost on restore"); checked(next->materialize(genome), "new envelope materialization"); diff --git a/tests/lineage_tests.cpp b/tests/lineage_tests.cpp index edafb2a..38a9903 100644 --- a/tests/lineage_tests.cpp +++ b/tests/lineage_tests.cpp @@ -73,6 +73,10 @@ void a_genome_outlives_every_organism_that_carried_it() { const auto first = archive.organism(100); CHECK(first && !first->alive && first->genome == 4); CHECK(first->born.value == 10 && first->died.value == 30); + // Read-only bounded enumeration includes records with no current carrier. + CHECK(archive.genomes().size() == archive.archived()); + CHECK(std::ranges::is_sorted(archive.genomes(), {}, &Genome::id)); + CHECK(std::ranges::find(archive.genomes(), 4, &Genome::id) != archive.genomes().end()); } void ancestry_and_descendants_resolve_through_a_dead_middle() {