Files
aevolution/docs/adr/0053-atomic-environmental-transfers.md
T
2026-10-08 12:08:53 -04:00

4.8 KiB

[Reviewed]

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.

M6.5 amendment (2026-09-27): accepted ADR-0054 brings the coupled buffer codec forward to M6.5a. This supersedes the deferral above; rate/biology progress must join the aggregate before rate-driven execution in M6.5c. Durable publication stays M7.