Complete M6.4 atomic environmental transfers
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user