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