From 70cd2883278f31ffd808b077e1b2919125bc0bb1 Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 27 Sep 2026 09:15:21 -0400 Subject: [PATCH] Complete M6.4 atomic environmental transfers --- CMakeLists.txt | 7 +- README.md | 4 + docs/ROADMAP.md | 2 +- docs/STATUS.md | 16 +- .../0053-atomic-environmental-transfers.md | 77 ++++++ docs/adr/README.md | 1 + docs/architecture/WORLD_ARCHITECTURE.md | 9 + docs/biology/ENERGY_MODEL.md | 8 + docs/engineering/VALIDATION.md | 20 ++ docs/world/ENVIRONMENTAL_FIELDS.md | 4 + docs/world/ENVIRONMENTAL_TRANSFERS.md | 85 +++++++ docs/world/ENVIRONMENT_VIEWS.md | 4 + include/evo/world/environment.hpp | 1 + include/evo/world/fields.hpp | 1 + include/evo/world/transfers.hpp | 97 ++++++++ src/world/transfers.cpp | 184 ++++++++++++++ tests/environment_transfers_tests.cpp | 228 ++++++++++++++++++ 17 files changed, 744 insertions(+), 4 deletions(-) create mode 100644 docs/adr/0053-atomic-environmental-transfers.md create mode 100644 docs/world/ENVIRONMENTAL_TRANSFERS.md create mode 100644 include/evo/world/transfers.hpp create mode 100644 src/world/transfers.cpp create mode 100644 tests/environment_transfers_tests.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index c334d57..d2e2103 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -34,7 +34,7 @@ target_include_directories(evo_simulation PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/in target_compile_features(evo_simulation PUBLIC cxx_std_23) evo_owned_target(evo_simulation) -set(evo_world_sources src/world/coordinates.cpp src/world/generation.cpp src/world/chunks.cpp src/world/edits.cpp src/world/codec.cpp src/world/local_files.cpp src/world/environment_units.cpp src/world/fields.cpp src/world/environment.cpp) +set(evo_world_sources src/world/coordinates.cpp src/world/generation.cpp src/world/chunks.cpp src/world/edits.cpp src/world/codec.cpp src/world/local_files.cpp src/world/environment_units.cpp src/world/fields.cpp src/world/environment.cpp src/world/transfers.cpp) add_library(evo_world STATIC ${evo_world_sources}) add_library(evo::world ALIAS evo_world) target_include_directories(evo_world PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") @@ -72,6 +72,11 @@ evo_owned_target(evo-sim) include(CTest) if(BUILD_TESTING) + add_executable(evo-environment-transfers-tests tests/environment_transfers_tests.cpp) + target_link_libraries(evo-environment-transfers-tests PRIVATE evo::world) + evo_owned_target(evo-environment-transfers-tests) + add_test(NAME environment-transfers-contracts COMMAND evo-environment-transfers-tests) + set_tests_properties(environment-transfers-contracts PROPERTIES TIMEOUT 60) add_executable(evo-environment-views-tests tests/environment_views_tests.cpp) target_link_libraries(evo-environment-views-tests PRIVATE evo::world) evo_owned_target(evo-environment-views-tests) diff --git a/README.md b/README.md index b42d47d..4f1a25d 100644 --- a/README.md +++ b/README.md @@ -142,3 +142,7 @@ M4.6 reproduction, measurements and limits: [aggregate budget report](docs/engin M5.1 local voxel/address API and scope: [local voxel contract](docs/world/LOCAL_VOXEL_CONTRACT.md). M5.8 process restart proof and measured costs: [world proof](docs/engineering/WORLD_PROOF.md). + +M6.4: [atomic environmental transfers](docs/world/ENVIRONMENTAL_TRANSFERS.md) +own finite field and organism resource compartments together. Biology integration +is next (M6.5); coupled snapshot/recovery remains M6.8. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 8475fab..12cde25 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -318,7 +318,7 @@ terrain/biology persistence are not provided by this independent codec. Next: M6 M6.3 implements [read-only environment views](world/ENVIRONMENT_VIEWS.md) under ADR-0052: bounded canonical voxel footprints, exact typed derived values, explicit absence and tick/field/chunk freshness checks. No implicit terrain load or inventory -authorization occurs. Next: M6.4 atomic coordinated transfers. +authorization occurs in views alone. M6.4 now implements [coordinated transfers](world/ENVIRONMENTAL_TRANSFERS.md) under ADR-0053: tagged resource accounts, atomic staged batches, capacity and ownership checks, and bounded exact retries. Coupled persistence remains M6.8. Next: M6.5 producer/consumer biology adapters. ## M7 - Persistent region server diff --git a/docs/STATUS.md b/docs/STATUS.md index 03d6d93..2faf13e 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 52 ADRs. + diagrams, biological contracts, engineering constitution and 53 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 | M6.4 coordinated environmental transfers | Atomic organism/environment debits and credits, fresh-view checks and retry identity | +| 1 | M6.5 couple producer/consumer biology | Finite environmental supply, explicit conversions and lifecycle checks through the coupled owner | | Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report | | 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 | @@ -641,3 +641,15 @@ Freshness validation rejects wrong stores, changed tick/field state and stale ch tokens, including eviction/reload. No persistent format or simulation rule changed. Views grant no inventory reservation; coherent tick/store pairing remains a host responsibility. Next: M6.4 coordinated environmental transfers. + + +## M6.4 atomic environmental transfers (2026-09-27) + +Implemented the [transfer contract](world/ENVIRONMENTAL_TRANSFERS.md) and ADR-0053. +A single owner stages and publishes fields and tagged organism resource accounts +atomically, validates view freshness and ownership, rejects capacity/stock/budget +violations, and retains 64 exact request receipts. Tests cover contention, late-leg +rollback, changed retries, independent compartment balances and conservation. +This is in-memory ownership; no coupled recovery format or durable ACK is claimed. +No schema, simulation version, dependency or deployment changed. Next: M6.5 biology +adapters, including explicit conversion and active/alive validation. diff --git a/docs/adr/0053-atomic-environmental-transfers.md b/docs/adr/0053-atomic-environmental-transfers.md new file mode 100644 index 0000000..8c746f5 --- /dev/null +++ b/docs/adr/0053-atomic-environmental-transfers.md @@ -0,0 +1,77 @@ +# ADR-0053: Atomic local environment and organism resource transfers + +## Status +Accepted for M6.4 in-memory coupled ownership, not durable or distributed outcomes. + +## Context +Independent setters could spend the same supply twice or credit an organism after +an environmental debit fails. ADR-0024's Ledger transfers only within its own finite +opening balances; adding an external mint API would undermine that contract. Its +C/N/P/other totals also do not retain water versus organic compartment identity. + +## Decision +Add EnvironmentalTransfers in evo::world. It exclusively owns a FieldStore, a +ChunkStore and 1..64 fixed organism resource accounts, each with ten explicitly +tagged balances and capacities matching Field channels. Account IDs are nonzero, +unique and ordered. These are resource endpoints for later biology adapters, not +organism lifecycle/genome implementations. Read-only accounting::Inventory totals +are derived from tagged balances, never a second spendable ledger. + +Creation consumes unique ownership of both stores, including on failure. Callers +must discard mutable aliases. Bind the previously unbound terrain to the supplied +world/frame and require equality with fields, all 1..256 sites loaded, and terrain +material equal to declared substrate at each site. This is trusted host adoption, +not authentication of terrain provenance. No terrain mutation or standalone field +mutation is exposed while the coupled owner lives. Later terrain editing requires +a coordinated capacity/mapping contract, rather than bypassing this owner. + +Each batch has a fresh nonzero command, original logical tick and 1..32 ordered legs. +A leg moves a positive amount of one identical field compartment between one owned +site and one owned organism account in either direction. No reactions, heating, +retagging, cross-region transfers or implied biological permissions. Earlier staged +credits may fund later legs, but no intermediate overdraft is allowed. + +Require an M6.3 view from these exact stores at the request/current tick, current +field watermark and chunk tokens; each leg's site and field must be covered and +available. Validate organism and environmental supply/capacity and prepare all +replacement pages and accounts before nonthrowing publication. Advance the field +watermark and publish the receipt/history in that same single-owner phase. + +Retain the last 64 successful full batches, not hashes alone. A retained ID with +identical original tick and ordered legs returns its original receipt before +freshness checks; it never transfers again. Changed payload rejects. Older IDs +outside retention reject as stale. Failures consume neither IDs nor history. +Retry lookup requires a view belonging to this owner, but its tick/revisions may +be stale; copied results cannot introduce a foreign owner. + +Cap sites at 256 for this gate so fixed staging is bounded. Charge resident owner, +fixed history, both existing stores and fixed account storage; reserve 64 KiB for +staging and charge old plus all new field pages at prepare peak. FieldStore's own +budget must also cover replacements. Snapshot output, caller views and allocator +headers are excluded. Allocation exceptions propagate before publication. + +## Alternatives Considered +External credit/debit setters break conservation and expose partial transactions. +A persistent duplicate Ledger plus field balances creates two authorities. A +detached tagged candidate with a narrow friend boundary keeps one live copy and +preserves compartments without changing M2. Distributed escrow is unnecessary here. + +## Benefits +Unique local ownership, finite tagged resources, full-payload retry identity and +all-or-nothing multi-leg commit. Existing independent ledgers and formats remain valid. + +## Costs +Fixed small endpoint/site limits and conservative global field invalidation. A +two-way transfer is not a biological process; uptake/capture/decay rules remain M6.5+. +No persistence API for this owner until the combined-state gate. + +## Risks +Host aliases, false ticks or wrongly assigned endpoint identity violate the ownership +precondition. Do not persist only fields after a coupled transfer: accounts and +history must accompany them. Restart-safe exactly-once acknowledgement remains M6.8/M7. + +## Consequences +Test last-nutrient contention, exact/changed/expired retries, stale/foreign views, +uncovered endpoints, capacity, overflow, peak budgets, late-leg rollback and independent +per-channel conservation. No account may progress offline via this primitive: biology +adapters must validate active lifecycle and permitted actions before submission. diff --git a/docs/adr/README.md b/docs/adr/README.md index 905da7f..f3698e1 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -59,3 +59,4 @@ design. No unadopted candidate is a link dependency of the proof. - [ADR-0050: Environmental units and coupling](0050-environmental-units-and-coupling.md) - accepted for M6's bounded habitat/accounting contract; no field storage or terrain conversion yet. - [ADR-0051: Optional environmental fields](0051-optional-environmental-fields.md) - accepted for M6.2 finite sparse pages, local transfers and field snapshot v1. - [ADR-0052: Environment views](0052-read-only-environment-views.md) - accepted for M6.3 bounded read-only footprint queries and freshness validation. +- [ADR-0053: Atomic environmental transfers](0053-atomic-environmental-transfers.md) - accepted for M6.4 tagged resource ownership, atomic local batches and bounded exact retries. diff --git a/docs/architecture/WORLD_ARCHITECTURE.md b/docs/architecture/WORLD_ARCHITECTURE.md index bf7a878..b4f788f 100644 --- a/docs/architecture/WORLD_ARCHITECTURE.md +++ b/docs/architecture/WORLD_ARCHITECTURE.md @@ -183,3 +183,12 @@ and an explicit host tick. Queries never load chunks or mutate inventories. A separate validator rejects stale ticks, field watermarks, foreign store instances and stale sampled chunk tokens. Coherent store pairing and single-owner scheduling remain host obligations; M6.4 must validate and commit in one ownership phase. + +## M6.4 coordinated resource ownership + +[ADR-0053](../adr/0053-atomic-environmental-transfers.md) and the +[transfer contract](../world/ENVIRONMENTAL_TRANSFERS.md) define one owner of field +stocks, terrain binding and tagged organism resource accounts. Fresh views authorize +only staged transfers; both endpoints and the retry receipt publish together after +validation and allocation. Accounts are resource endpoints; biological lifecycle +integration follows in M6.5. Field-only snapshots cannot recover a coupled owner. diff --git a/docs/biology/ENERGY_MODEL.md b/docs/biology/ENERGY_MODEL.md index e04a74c..85b690d 100644 --- a/docs/biology/ENERGY_MODEL.md +++ b/docs/biology/ENERGY_MODEL.md @@ -303,3 +303,11 @@ dissolved N/P, organic matter/energy, incident-energy and heat inventories. Mate defaults provide capacity, never supply. Local transfers can only relocate the same channel; water cannot become organic other. Field snapshots preserve depletion. No rate source, biochemical conversion or transfer to organisms exists yet. + +## Environmental transfer boundary (M6.4) + +The [coupled owner](../world/ENVIRONMENTAL_TRANSFERS.md) retains ten resource tags +across environment and organism endpoints. Its Inventory is a derived report, not +another spendable ledger. Water cannot turn into organic matter, and incident energy +or heat cannot turn into usable energy through this adapter. M6.5 must supply explicit +biological conversion rules and lifecycle validation; M2 Ledger invariants remain intact. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 404620a..e25f676 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -1772,3 +1772,23 @@ ChunkStore does not yet bind a world identity, so coherent field/terrain pairing cannot be independently authenticated by this view. Combined ownership, reservation, atomic inventory transfer and retry outcomes remain M6.4. No deployment or World0 operation occurred. + +## M6.4 atomic environmental transfers - 2026-09-27 + +Executed on Windows x64 with the installed Visual Studio toolchain: + +- `tools/windows-check.ps1 -Preset release -Action check`: build and 52/52 CTests passed (NDEBUG). +- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy/warnings-as-errors build and 52/52 CTests passed. +- `tools/windows-check.ps1 -Preset asan -Action check`: AddressSanitizer build and 52/52 CTests passed. +- `tools/windows-check.ps1 -Preset release -Action format`: passed. + +New environment-transfers-contracts exercises last-stock contention, fresh versus +stale/foreign views, exact retries, changed-payload refusal, expired command IDs, +command exhaustion, late-leg rollback, account and water capacities, admission +overflow, separate owner/field allocation budgets, and 100 batches checked against +independent expected balances across all ten compartments. No golden changed. + +This evidence covers local in-memory atomicity. Coupled snapshots, allocation-failure +injection, process crash recovery and biological lifecycle integration are not claimed. +Linux/UBSan/TSan were not run locally; their existing Gitea jobs remain required CI +evidence. No cluster workload or World0 state was changed. diff --git a/docs/world/ENVIRONMENTAL_FIELDS.md b/docs/world/ENVIRONMENTAL_FIELDS.md index 3a1940a..345551e 100644 --- a/docs/world/ENVIRONMENTAL_FIELDS.md +++ b/docs/world/ENVIRONMENTAL_FIELDS.md @@ -88,3 +88,7 @@ pages use 17304. A single present channel serializes to 10756 bytes regardless o resident layout. These are owned-storage observations, not peak RSS or planetary capacity claims. Test assertions use relative page costs so ABI metadata differences do not falsely fail another supported platform. + +M6.4's [coupled owner](ENVIRONMENTAL_TRANSFERS.md) adopts this store exclusively. +Do not retain mutable aliases or use a field-only snapshot to recover coupled state; +organism accounts and retry history must be restored together in the future M6.8 codec. diff --git a/docs/world/ENVIRONMENTAL_TRANSFERS.md b/docs/world/ENVIRONMENTAL_TRANSFERS.md new file mode 100644 index 0000000..f9fc8b8 --- /dev/null +++ b/docs/world/ENVIRONMENTAL_TRANSFERS.md @@ -0,0 +1,85 @@ +# M6.4 atomic environmental transfers + +Authority: [ADR-0053](../adr/0053-atomic-environmental-transfers.md). +`EnvironmentalTransfers` owns both stores and fixed tagged organism resource accounts. +It accepts no arbitrary resource setters, endpoint insertion or mutable store access. +Creation consumes unique_ptr inputs even on failure; it is an initial admission step, +not a live migration. Never retain mutable aliases after transferring ownership. + +## Admission and units + +Require nonzero world/frame equal to FieldStore identity, 1..256 mapped field sites, +and 1..64 accounts in strictly increasing nonzero organism-ID order. Each account +has ten balances and capacities in Field enum order, fg for mass and pJ for energy. +Capacity is not inventory. Every balance must fit its capacity, and combined fields +plus accounts must fit u64 for each of energy/C/N/P/other. Water and organic other +remain distinct tags although both contribute to the derived other total. Whole +biomass is not another spendable account. Incident energy and heat retain their tags +even if moved to an account; they do not become usable organic energy. + +All mapped terrain chunks must already be loaded and each site's terrain material +must match its declared substrate. No volume/mass conversion or capacity inference +occurs. Terrain does not yet carry its own WorldIdentity; admission assigns it the +host-supplied identity, so host provenance remains a trusted precondition. The owner +exposes const fields/terrain for queries, and const account spans for inspection. +Neither substrate nor geometry can change through this owner in M6.4. + +## Batch contract + +```mermaid +sequenceDiagram + participant B as Biology adapter (later) + participant O as Coupled owner + participant P as Private candidate + B->>O: Batch ID, original tick, ordered legs, view + O->>O: Exact retained retry? return original receipt + O->>O: Validate owners, tick, revisions and footprint + O->>P: Stage balances and replacement pages + P->>P: Validate every ordered debit/credit and both budgets + O->>O: Publish fields + accounts + watermark + history + O-->>B: Receipt +``` + +One batch has 1..32 ordered positive legs, each naming voxel, organism ID, Field, +direction and amount. Only environment-to-account or account-to-environment transfers +are supported; each leg preserves the exact compartment. All sites/fields must be +covered by the supplied view and present. The caller's current tick and request tick +must equal the view tick for a fresh batch. Single-owner execution is mandatory +through validation and publication. No concurrent read/write guarantees are made. + +The field watermark versions both endpoints because accounts can change only with +fields in this owner. A successful batch invalidates earlier views. A rejected batch +preserves field bytes, every account, watermark and retry history. Earlier candidate +credits can fund later legs; a later failure discards the entire candidate. No clamp, +implicit partial fulfillment, or capacity overflow is allowed. + +Retain 64 full successful batches and receipts. Identical command/tick/ordered legs +returns the original receipt even with a stale view/current tick, without a second +transfer. A view still must belong to these exact stores. Changed retained payload +returns conflict. Command IDs at/below the watermark outside retention return stale. +Rejected IDs can be retried with a corrected plan. ID exhaustion never wraps. Host +IDs/authentication and lifecycle are not inferred from a numeric resource-account ID. + +## Memory and persistence boundary + +Account/history arrays are fixed members charged in sizeof(owner); owned field and +terrain accounted bytes are also charged. An additional 65536 bytes is reserved for +fixed staging (256*10 u64 quantities, 64 accounts, replacement metadata and request +copies). Before allocating replacement pages, both owner and field budgets must fit +all old plus new field pages, with their scratch reservations. Report this as +accounted bytes, not RSS; allocator metadata, query/serialization buffers and small +call-stack overhead are excluded. Creation also checks combined resident admission. + +`totals()` derives an accounting::Inventory from the authoritative stores/accounts. +It is reporting, not a mutable Ledger. M2's Ledger API and conservation remain +unchanged; the narrow FieldStore friend boundary exists only for this owning adapter. + +There is no coupled snapshot or durable acknowledgement in this gate. Existing M5/M6.2 +codecs are unchanged and insufficient to resume this owner after a coupled commit: +M6.8 must persist accounts, fields, terrain binding, watermark and exact retry window +together. M7 supplies durable publication. Never reload field-only bytes as recovered +coupled world state. Tests exercise in-memory atomicity, not crash recovery. + +M6.5 biology adapters must validate active/alive status, capabilities, source budgets +and biological costs. This resource endpoint abstraction neither implements metabolism +nor allows offline progression. Next: one producer/consumer fixture using this owner. diff --git a/docs/world/ENVIRONMENT_VIEWS.md b/docs/world/ENVIRONMENT_VIEWS.md index 0f8596f..f50eb0e 100644 --- a/docs/world/ENVIRONMENT_VIEWS.md +++ b/docs/world/ENVIRONMENT_VIEWS.md @@ -67,3 +67,7 @@ index or concurrency is justified at this gate. Existing geometry/field formats, versions and goldens are unchanged. Later combined snapshots must restore the stores first and reacquire views. Next: M6.4 coordinated environmental transfers, including inventory ownership and retry semantics. + +M6.4 implements the validation-and-publication ownership phase in +[EnvironmentalTransfers](ENVIRONMENTAL_TRANSFERS.md). A view alone never grants +mutation authority; the owner checks the request, both endpoints and capacity. diff --git a/include/evo/world/environment.hpp b/include/evo/world/environment.hpp index a0957cb..29d5c3a 100644 --- a/include/evo/world/environment.hpp +++ b/include/evo/world/environment.hpp @@ -79,6 +79,7 @@ class EnvironmentView { } private: + friend class EnvironmentalTransfers; friend std::expected query_environment(const FieldStore&, const ChunkStore&, std::uint64_t, std::span, std::uint32_t); diff --git a/include/evo/world/fields.hpp b/include/evo/world/fields.hpp index af36823..69942f5 100644 --- a/include/evo/world/fields.hpp +++ b/include/evo/world/fields.hpp @@ -93,6 +93,7 @@ class FieldStore { } private: + friend class EnvironmentalTransfers; using Page = std::array; struct Channel { bool present{}; diff --git a/include/evo/world/transfers.hpp b/include/evo/world/transfers.hpp new file mode 100644 index 0000000..ec6fdfd --- /dev/null +++ b/include/evo/world/transfers.hpp @@ -0,0 +1,97 @@ +#pragma once +#include "evo/world/environment.hpp" +#include +#include +#include +#include +#include +#include +#include + +namespace evo::world { +struct OrganismResourceId { + std::uint64_t value{}; + auto operator<=>(const OrganismResourceId&) const = default; +}; +// Tagged compartments in Field order; fg for mass, pJ for energy. No lifecycle state. +struct OrganismResources { + OrganismResourceId id; + std::array balances{}, capacities{}; + auto operator<=>(const OrganismResources&) const = default; +}; +enum class ResourceDirection : std::uint8_t { to_organism, to_environment }; +struct EnvironmentalLeg { + VoxelAddress voxel; + OrganismResourceId organism; + Field field; + ResourceDirection direction; + std::uint64_t amount{}; + auto operator<=>(const EnvironmentalLeg&) const = default; +}; +struct EnvironmentalBatch { + std::uint64_t command{}, tick{}; + std::span legs; +}; +struct EnvironmentalReceipt { + std::uint64_t command{}, tick{}; + std::size_t legs{}; + auto operator<=>(const EnvironmentalReceipt&) const = default; +}; +enum class TransferError : std::uint8_t { + config, + identity, + terrain_binding, + capacity, + overflow, + budget, + invalid_request, + wrong_owner, + stale_view, + uncovered, + missing, + unknown_organism, + insufficient, + conflict, + stale_command +}; +class EnvironmentalTransfers { + public: + static constexpr std::size_t max_sites = 256, max_organisms = 64, max_legs = 32; + static constexpr std::size_t retained_commands = 64, scratch_bytes = 65536; + // Consumes both stores on success or failure. Retaining mutable aliases is forbidden. + [[nodiscard]] static std::expected, TransferError> + create(WorldIdentity identity, std::unique_ptr fields, + std::unique_ptr terrain, std::span organisms, + std::size_t byte_budget); + EnvironmentalTransfers(const EnvironmentalTransfers&) = delete; + EnvironmentalTransfers& operator=(const EnvironmentalTransfers&) = delete; + EnvironmentalTransfers(EnvironmentalTransfers&&) = delete; + EnvironmentalTransfers& operator=(EnvironmentalTransfers&&) = delete; + [[nodiscard]] const FieldStore& fields() const noexcept { + return *fields_; + } + [[nodiscard]] const ChunkStore& terrain() const noexcept { + return *terrain_; + } + [[nodiscard]] std::span organisms() const noexcept { + return std::span{organisms_}.first(count_); + } + [[nodiscard]] accounting::Inventory totals() const noexcept; + [[nodiscard]] std::size_t accounted_bytes() const noexcept; + [[nodiscard]] std::expected + commit(const EnvironmentalBatch& batch, const EnvironmentView& view, + std::uint64_t current_tick); + + private: + struct History { + EnvironmentalReceipt receipt{}; + std::array legs{}; + }; + EnvironmentalTransfers() = default; + std::unique_ptr fields_; + std::unique_ptr terrain_; + std::array organisms_{}; + std::array history_{}; + std::size_t count_{}, budget_{}, next_history_{}; +}; +} // namespace evo::world diff --git a/src/world/transfers.cpp b/src/world/transfers.cpp new file mode 100644 index 0000000..aae879d --- /dev/null +++ b/src/world/transfers.cpp @@ -0,0 +1,184 @@ +#include "evo/world/transfers.hpp" +#include +#include +#include +#include + +namespace evo::world { +namespace { +constexpr auto ceiling = std::numeric_limits::max(); +constexpr std::array mass_channels{3, 1, 2, 0, 1, 2, 3}; +bool accumulate(accounting::Inventory& sum, std::size_t field, std::uint64_t amount) noexcept { + auto& value = field < 7 ? sum.matter[mass_channels[field]].value : sum.energy.value; + if (amount > ceiling - value) + return false; + value += amount; + return true; +} +} // namespace +std::expected, TransferError> +EnvironmentalTransfers::create(WorldIdentity identity, std::unique_ptr fields, + std::unique_ptr terrain, + std::span organisms, + std::size_t byte_budget) { + if (!fields || !terrain || organisms.empty() || organisms.size() > max_organisms || + fields->sites().size() > max_sites) + return std::unexpected{TransferError::config}; + if (identity.world == 0 || identity.frame == 0 || fields->identity() != identity) + return std::unexpected{TransferError::identity}; + const auto resident = + sizeof(EnvironmentalTransfers) + fields->accounted_bytes() + terrain->accounted_bytes(); + if (resident > byte_budget || scratch_bytes > byte_budget - resident) + return std::unexpected{TransferError::budget}; + accounting::Inventory sum{}; + for (std::size_t i = 0; i < fields->sites().size(); ++i) { + const auto& site = fields->sites()[i]; + const auto location = split(site.voxel, base_chunk_edge); + const auto view = terrain->view(location->chunk); + if (!view) + return std::unexpected{TransferError::terrain_binding}; + const auto cell = terrain->read(*view, location->local); + if (!cell || cell->material() != site.substrate) + return std::unexpected{TransferError::terrain_binding}; + for (std::size_t k = 0; k < field_count; ++k) { + const auto value = fields->read(i, static_cast(k)); + if (value && !accumulate(sum, k, *value)) + return std::unexpected{TransferError::overflow}; + } + } + for (std::size_t i = 0; i < organisms.size(); ++i) { + const auto& organism = organisms[i]; + if (organism.id.value == 0 || (i != 0 && organisms[i - 1].id >= organism.id)) + return std::unexpected{TransferError::config}; + for (std::size_t k = 0; k < field_count; ++k) { + if (organism.balances[k] > organism.capacities[k]) + return std::unexpected{TransferError::capacity}; + if (!accumulate(sum, k, organism.balances[k])) + return std::unexpected{TransferError::overflow}; + } + } + auto owner = std::unique_ptr(new EnvironmentalTransfers); + owner->fields_ = std::move(fields); + owner->terrain_ = std::move(terrain); + std::copy(organisms.begin(), organisms.end(), owner->organisms_.begin()); + owner->count_ = organisms.size(); + owner->budget_ = byte_budget; + return owner; +} +std::size_t EnvironmentalTransfers::accounted_bytes() const noexcept { + return sizeof(EnvironmentalTransfers) + fields_->accounted_bytes() + + terrain_->accounted_bytes(); +} +accounting::Inventory EnvironmentalTransfers::totals() const noexcept { + accounting::Inventory sum{}; + for (std::size_t k = 0; k < field_count; ++k) { + for (std::size_t i = 0; i < fields_->sites().size(); ++i) { + const auto value = fields_->read(i, static_cast(k)); + if (value) + (void)accumulate(sum, k, *value); + } + for (const auto& organism : organisms()) + (void)accumulate(sum, k, organism.balances[k]); + } + return sum; // Admission bounds totals; same-channel transfers preserve them. +} +std::expected +EnvironmentalTransfers::commit(const EnvironmentalBatch& batch, const EnvironmentView& view, + std::uint64_t current_tick) { + if (batch.command == 0 || batch.legs.empty() || batch.legs.size() > max_legs) + return std::unexpected{TransferError::invalid_request}; + if (view.fields_ != fields_.get() || view.terrain_ != terrain_.get() || view.samples_.empty()) + return std::unexpected{TransferError::wrong_owner}; + if (batch.command <= fields_->command_) { + for (const auto& h : history_) { + if (h.receipt.command != batch.command) + continue; + if (h.receipt.tick != batch.tick || h.receipt.legs != batch.legs.size() || + !std::equal(batch.legs.begin(), batch.legs.end(), h.legs.begin())) + return std::unexpected{TransferError::conflict}; + return h.receipt; + } + return std::unexpected{TransferError::stale_command}; + } + if (batch.tick != current_tick || + !validate_environment(view, *fields_, *terrain_, current_tick)) + return std::unexpected{TransferError::stale_view}; + std::array, field_count> staged{}; + std::array touched{}; + auto accounts = organisms_; + const auto sites = fields_->sites(); + for (const auto& leg : batch.legs) { + const auto k = static_cast(leg.field); + if (k >= field_count || leg.amount == 0 || + (leg.direction != ResourceDirection::to_organism && + leg.direction != ResourceDirection::to_environment)) + return std::unexpected{TransferError::invalid_request}; + const auto sample = std::lower_bound( + view.samples_.begin(), view.samples_.end(), leg.voxel, + [](const EnvironmentSample& s, VoxelAddress a) { return s.voxel < a; }); + if (sample == view.samples_.end() || sample->voxel != leg.voxel || + (view.mask_ & (1U << k)) == 0) + return std::unexpected{TransferError::uncovered}; + if (!sample->fields[k]) + return std::unexpected{TransferError::missing}; + const auto site = + std::lower_bound(sites.begin(), sites.end(), leg.voxel, + [](const FieldSite& s, VoxelAddress a) { return s.voxel < a; }); + const auto i = static_cast(site - sites.begin()); + const auto account = std::lower_bound( + accounts.begin(), accounts.begin() + static_cast(count_), leg.organism, + [](const OrganismResources& a, OrganismResourceId id) { return a.id < id; }); + if (account == accounts.begin() + static_cast(count_) || + account->id != leg.organism) + return std::unexpected{TransferError::unknown_organism}; + if (!touched[k]) { + for (std::size_t j = 0; j < sites.size(); ++j) + staged[k][j] = fields_->fields_[k].get(j); + touched[k] = true; + } + auto& environment = staged[k][i]; + auto& organism = account->balances[k]; + const bool uptake = leg.direction == ResourceDirection::to_organism; + auto& source = uptake ? environment : organism; + auto& destination = uptake ? organism : environment; + const auto capacity = + uptake ? account->capacities[k] + : (leg.field == Field::water ? fields_->water_capacity(i)->value : ceiling); + if (leg.amount > source) + return std::unexpected{TransferError::insufficient}; + if (leg.amount > ceiling - destination) + return std::unexpected{TransferError::overflow}; + if (destination + leg.amount > capacity) + return std::unexpected{TransferError::capacity}; + source -= leg.amount; + destination += leg.amount; + } + std::size_t new_bytes{}; + for (std::size_t k = 0; k < field_count; ++k) + if (touched[k]) + new_bytes += FieldStore::page_bytes(std::span{staged[k]}.first(sites.size())); + const auto resident = accounted_bytes(); + if (new_bytes > budget_ - resident - scratch_bytes || + new_bytes > fields_->budget_ - fields_->bytes_ - FieldStore::scratch_bytes) + return std::unexpected{TransferError::budget}; + std::array replacements; + for (std::size_t k = 0; k < field_count; ++k) + if (touched[k]) + replacements[k] = FieldStore::encode(std::span{staged[k]}.first(sites.size())); + static_assert(std::is_nothrow_move_assignable_v); + // All checks and allocations complete. Single-owner, nonthrowing publication. + for (std::size_t k = 0; k < field_count; ++k) + if (touched[k]) { + fields_->bytes_ -= fields_->fields_[k].bytes(); + fields_->bytes_ += replacements[k].bytes(); + fields_->fields_[k] = std::move(replacements[k]); + } + organisms_ = accounts; + fields_->command_ = batch.command; + auto& history = history_[next_history_]; + history.receipt = {batch.command, batch.tick, batch.legs.size()}; + std::copy(batch.legs.begin(), batch.legs.end(), history.legs.begin()); + next_history_ = (next_history_ + 1) % retained_commands; + return history.receipt; +} +} // namespace evo::world diff --git a/tests/environment_transfers_tests.cpp b/tests/environment_transfers_tests.cpp new file mode 100644 index 0000000..d7f753e --- /dev/null +++ b/tests/environment_transfers_tests.cpp @@ -0,0 +1,228 @@ +#include "evo/world/transfers.hpp" +#include +#include +#include +#include +#include +#include +#include +namespace { +using namespace evo::world; +constexpr WorldIdentity id{7, 9}; +constexpr std::array voxels{{{0, 0, -16000}, {1, 0, -16000}}}; +void check(bool ok, std::source_location at = std::source_location::current()) { + if (!ok) + throw std::runtime_error("transfers line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) +template bool refused(const std::expected& r, TransferError e) { + return !r && r.error() == e; +} +struct Parts { + std::unique_ptr fields; + std::unique_ptr terrain; + std::array accounts; +}; +Parts parts(bool loaded = true, bool all = true, std::size_t field_budget = 2000000) { + const std::array sites{{{voxels[0], {{0}, {0}, {0}, {10}, {20}, {3}}, {1}}, + {voxels[1], {{0}, {0}, {0}, {10}, {20}, {3}}, {1}}}}; + const std::uint64_t stock = 10; + std::array openings; + for (std::size_t k = 0; k < field_count; ++k) + openings[k] = {static_cast(k), {&stock, 1}}; + const FieldDefaults defaults{{evo::accounting::Femtograms{0}, evo::accounting::Femtograms{20}, + evo::accounting::Femtograms{20}}}; + auto f = FieldStore::create(id, 1, defaults, sites, + std::span{openings}.first(all ? field_count : 1), field_budget); + CHECK(f); + auto t = ChunkStore::create({}, 2, 2000000, {{VolumeUnits{100}, VolumeUnits{100}}}); + CHECK(t); + if (loaded) + CHECK((*t)->load({0, 0, -1000})); + Parts p{std::move(*f), std::move(*t), {}}; + for (std::size_t i = 0; i < 2; ++i) { + p.accounts[i].id = {i + 1}; + p.accounts[i].capacities.fill(100); + } + return p; +} +auto adopt(Parts p, std::size_t budget = 4000000, WorldIdentity identity = id) { + return EnvironmentalTransfers::create(identity, std::move(p.fields), std::move(p.terrain), + p.accounts, budget); +} +auto owner() { + auto r = adopt(parts()); + CHECK(r); + return std::move(*r); +} +EnvironmentView view(const EnvironmentalTransfers& o, std::uint64_t tick = 1, + std::uint32_t mask = 1023) { + auto v = query_environment(o.fields(), o.terrain(), tick, voxels, mask); + CHECK(v); + return std::move(*v); +} +EnvironmentalLeg leg(Field f = Field::nitrogen, std::uint64_t amount = 10) { + return {voxels[0], {1}, f, ResourceDirection::to_organism, amount}; +} +struct State { + WorldBytes fields; + std::vector accounts; + auto operator<=>(const State&) const = default; +}; +State state(const EnvironmentalTransfers& o) { + return {o.fields().snapshot(), {o.organisms().begin(), o.organisms().end()}}; +} +void atomicity() { + auto o = owner(); + auto v = view(*o); + auto a = leg(); + const auto total = o->totals(); + const auto receipt = o->commit({1, 1, {&a, 1}}, v, 1); + CHECK(receipt); + const auto committed = state(*o); + CHECK(o->organisms()[0].balances[1] == 10 && *o->fields().read(0, Field::nitrogen) == 0); + CHECK(o->totals() == total); + CHECK(o->commit({1, 1, {&a, 1}}, v, 999) == receipt); + CHECK(state(*o) == committed); + a.organism = {2}; + CHECK(refused(o->commit({1, 1, {&a, 1}}, v, 1), TransferError::conflict)); + CHECK(refused(o->commit({2, 1, {&a, 1}}, v, 1), TransferError::stale_view)); + auto fresh = view(*o); + CHECK(refused(o->commit({2, 1, {&a, 1}}, fresh, 1), TransferError::insufficient)); + CHECK(state(*o) == committed); + a = leg(Field::water, 3); + std::array batch{a, leg(Field::nitrogen, 1)}; + CHECK(refused(o->commit({2, 1, batch}, fresh, 1), TransferError::insufficient)); + CHECK(state(*o) == committed); + batch[1] = leg(Field::organic_other, 4); + CHECK(o->commit({2, 1, batch}, fresh, 1)); + CHECK(o->organisms()[0].balances[0] == 3 && o->organisms()[0].balances[6] == 4); + CHECK(o->totals() == total); + auto next = view(*o); + for (auto& b : batch) + b.direction = ResourceDirection::to_environment; + CHECK(o->commit({3, 1, batch}, next, 1)); + CHECK(o->organisms()[0].balances[0] == 0); + CHECK(o->totals() == total); +} +void rejection() { + auto o = owner(); + auto v = view(*o); + auto a = leg(); + const auto before = state(*o); + auto other = owner(); + auto alien = view(*other); + CHECK(refused(o->commit({1, 1, {&a, 1}}, alien, 1), TransferError::wrong_owner)); + CHECK(refused(o->commit({1, 2, {&a, 1}}, v, 2), TransferError::stale_view)); + CHECK(refused(o->commit({0, 1, {&a, 1}}, v, 1), TransferError::invalid_request)); + CHECK(refused(o->commit({1, 1, {}}, v, 1), TransferError::invalid_request)); + std::array many{}; + CHECK(refused(o->commit({1, 1, many}, v, 1), TransferError::invalid_request)); + a.organism = {3}; + CHECK(refused(o->commit({1, 1, {&a, 1}}, v, 1), TransferError::unknown_organism)); + a = leg(); + a.voxel.x = 3; + CHECK(refused(o->commit({1, 1, {&a, 1}}, v, 1), TransferError::uncovered)); + a = leg(); + auto limited = view(*o, 1, 1); + CHECK(refused(o->commit({1, 1, {&a, 1}}, limited, 1), TransferError::uncovered)); + a.amount = 0; + CHECK(refused(o->commit({1, 1, {&a, 1}}, v, 1), TransferError::invalid_request)); + CHECK(state(*o) == before); + auto missing = adopt(parts(true, false)); + CHECK(missing); + auto mv = view(**missing); + a = leg(); + CHECK(refused((*missing)->commit({1, 1, {&a, 1}}, mv, 1), TransferError::missing)); + auto p = parts(); + p.accounts[0].capacities[1] = 1; + auto small = adopt(std::move(p)); + CHECK(small); + auto sv = view(**small); + CHECK(refused((*small)->commit({1, 1, {&a, 1}}, sv, 1), TransferError::capacity)); + p = parts(); + p.accounts[0].balances[0] = 20; + auto water = adopt(std::move(p)); + CHECK(water); + auto wv = view(**water); + a = leg(Field::water, 11); + a.direction = ResourceDirection::to_environment; + const auto wb = state(**water); + CHECK(refused((*water)->commit({1, 1, {&a, 1}}, wv, 1), TransferError::capacity)); + CHECK(state(**water) == wb); +} +void admission_budget() { + CHECK(refused(adopt(parts(false)), TransferError::terrain_binding)); + CHECK(refused(adopt(parts(), 4000000, {8, 9}), TransferError::identity)); + auto p = parts(); + p.accounts[1].id = {1}; + CHECK(refused(adopt(std::move(p)), TransferError::config)); + p = parts(); + p.accounts[0].id = {0}; + CHECK(refused(adopt(std::move(p)), TransferError::config)); + p = parts(); + p.accounts[0].balances[0] = 101; + CHECK(refused(adopt(std::move(p)), TransferError::capacity)); + p = parts(); + p.accounts[0].balances[1] = std::numeric_limits::max(); + p.accounts[0].capacities[1] = p.accounts[0].balances[1]; + CHECK(refused(adopt(std::move(p)), TransferError::overflow)); + auto o = owner(); + const auto tight = o->accounted_bytes() + EnvironmentalTransfers::scratch_bytes; + auto bounded = adopt(parts(), tight); + CHECK(bounded); + auto v = view(**bounded); + auto a = leg(); + const auto before = state(**bounded); + CHECK(refused((*bounded)->commit({1, 1, {&a, 1}}, v, 1), TransferError::budget)); + CHECK(state(**bounded) == before); + p = parts(); + const auto fb = p.fields->accounted_bytes() + FieldStore::scratch_bytes; + bounded = adopt(parts(true, true, fb)); + CHECK(bounded); + v = view(**bounded); + CHECK(refused((*bounded)->commit({1, 1, {&a, 1}}, v, 1), TransferError::budget)); +} +void conservation_history() { + auto o = owner(); + const auto total = o->totals(); + for (std::uint64_t command = 1; command <= 100; ++command) { + auto v = view(*o, command); + std::array batch; + for (std::size_t k = 0; k < field_count; ++k) { + batch[k] = leg(static_cast(k), 1); + if (command % 2 == 0) + batch[k].direction = ResourceDirection::to_environment; + } + auto r = o->commit({command, command, batch}, v, command); + CHECK(r); + CHECK(o->totals() == total); + for (std::size_t k = 0; k < field_count; ++k) { + CHECK(o->organisms()[0].balances[k] == command % 2); + CHECK(*o->fields().read(0, static_cast(k)) == 10 - command % 2); + } + CHECK(o->commit({command, command, batch}, v, command + 1) == r); + batch[0].amount = 2; + CHECK(refused(o->commit({command, command, batch}, v, command), TransferError::conflict)); + } + auto v = view(*o, 101); + auto a = leg(Field::water, 1); + CHECK(refused(o->commit({1, 1, {&a, 1}}, v, 101), TransferError::stale_command)); + CHECK(o->commit({std::numeric_limits::max(), 101, {&a, 1}}, v, 101)); + CHECK(o->commit({std::numeric_limits::max(), 101, {&a, 1}}, v, 102)); +} +} // namespace +int main() { + try { + atomicity(); + rejection(); + admission_budget(); + conservation_history(); + return 0; + } catch (const std::exception& e) { + std::fprintf(stderr, "%s\n", e.what()); + return 1; + } catch (...) { + return 1; + } +}