Files
aevolution/docs/world/ENVIRONMENTAL_TRANSFERS.md
T

5.3 KiB

M6.4 atomic environmental transfers

Authority: ADR-0053. 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

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.

M6.5a amendment: accepted ADR-0054 brings a coupled buffer codec forward. snapshot/restore now save terrain, fields, accounts and full retry history together. This supersedes the M6.8 resource-codec deferral above. No rate/biology state exists yet; the later fixture must include it before enabling source integration.