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
@@ -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.