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
+4
View File
@@ -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.
+85
View File
@@ -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.
+4
View File
@@ -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.