Complete M6.4 atomic environmental transfers

This commit is contained in:
dingo
2026-09-27 09:15:21 -04:00
parent 965a33ca48
commit 70cd288327
17 changed files with 744 additions and 4 deletions
+6 -1
View File
@@ -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)
+4
View File
@@ -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.
+1 -1
View File
@@ -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
+14 -2
View File
@@ -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.
@@ -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.
+1
View File
@@ -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.
+9
View File
@@ -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.
+8
View File
@@ -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.
+20
View File
@@ -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.
+4
View File
@@ -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.
+85
View File
@@ -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.
+4
View File
@@ -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.
+1
View File
@@ -79,6 +79,7 @@ class EnvironmentView {
}
private:
friend class EnvironmentalTransfers;
friend std::expected<EnvironmentView, EnvironmentError>
query_environment(const FieldStore&, const ChunkStore&, std::uint64_t,
std::span<const VoxelAddress>, std::uint32_t);
+1
View File
@@ -93,6 +93,7 @@ class FieldStore {
}
private:
friend class EnvironmentalTransfers;
using Page = std::array<std::uint64_t, 64>;
struct Channel {
bool present{};
+97
View File
@@ -0,0 +1,97 @@
#pragma once
#include "evo/world/environment.hpp"
#include <array>
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <memory>
#include <span>
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<std::uint64_t, field_count> 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<const EnvironmentalLeg> 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<std::unique_ptr<EnvironmentalTransfers>, TransferError>
create(WorldIdentity identity, std::unique_ptr<FieldStore> fields,
std::unique_ptr<ChunkStore> terrain, std::span<const OrganismResources> 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<const OrganismResources> 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<EnvironmentalReceipt, TransferError>
commit(const EnvironmentalBatch& batch, const EnvironmentView& view,
std::uint64_t current_tick);
private:
struct History {
EnvironmentalReceipt receipt{};
std::array<EnvironmentalLeg, max_legs> legs{};
};
EnvironmentalTransfers() = default;
std::unique_ptr<FieldStore> fields_;
std::unique_ptr<ChunkStore> terrain_;
std::array<OrganismResources, max_organisms> organisms_{};
std::array<History, retained_commands> history_{};
std::size_t count_{}, budget_{}, next_history_{};
};
} // namespace evo::world
+184
View File
@@ -0,0 +1,184 @@
#include "evo/world/transfers.hpp"
#include <algorithm>
#include <limits>
#include <type_traits>
#include <utility>
namespace evo::world {
namespace {
constexpr auto ceiling = std::numeric_limits<std::uint64_t>::max();
constexpr std::array<std::size_t, 7> 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<std::unique_ptr<EnvironmentalTransfers>, TransferError>
EnvironmentalTransfers::create(WorldIdentity identity, std::unique_ptr<FieldStore> fields,
std::unique_ptr<ChunkStore> terrain,
std::span<const OrganismResources> 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<Field>(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<EnvironmentalTransfers>(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<Field>(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<EnvironmentalReceipt, TransferError>
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<std::array<std::uint64_t, max_sites>, field_count> staged{};
std::array<bool, field_count> touched{};
auto accounts = organisms_;
const auto sites = fields_->sites();
for (const auto& leg : batch.legs) {
const auto k = static_cast<std::size_t>(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<std::size_t>(site - sites.begin());
const auto account = std::lower_bound(
accounts.begin(), accounts.begin() + static_cast<std::ptrdiff_t>(count_), leg.organism,
[](const OrganismResources& a, OrganismResourceId id) { return a.id < id; });
if (account == accounts.begin() + static_cast<std::ptrdiff_t>(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<FieldStore::Channel, field_count> 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<FieldStore::Channel>);
// 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
+228
View File
@@ -0,0 +1,228 @@
#include "evo/world/transfers.hpp"
#include <array>
#include <cstdio>
#include <limits>
#include <source_location>
#include <stdexcept>
#include <string>
#include <vector>
namespace {
using namespace evo::world;
constexpr WorldIdentity id{7, 9};
constexpr std::array<VoxelAddress, 2> 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<bool>(__VA_ARGS__))
template <class T> bool refused(const std::expected<T, TransferError>& r, TransferError e) {
return !r && r.error() == e;
}
struct Parts {
std::unique_ptr<FieldStore> fields;
std::unique_ptr<ChunkStore> terrain;
std::array<OrganismResources, 2> accounts;
};
Parts parts(bool loaded = true, bool all = true, std::size_t field_budget = 2000000) {
const std::array<FieldSite, 2> 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<FieldOpening, field_count> openings;
for (std::size_t k = 0; k < field_count; ++k)
openings[k] = {static_cast<Field>(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<OrganismResources> 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<EnvironmentalLeg, 33> 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<std::uint64_t>::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<EnvironmentalLeg, field_count> batch;
for (std::size_t k = 0; k < field_count; ++k) {
batch[k] = leg(static_cast<Field>(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<Field>(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<std::uint64_t>::max(), 101, {&a, 1}}, v, 101));
CHECK(o->commit({std::numeric_limits<std::uint64_t>::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;
}
}