Complete M6.4 atomic environmental transfers
This commit is contained in:
+1
-1
@@ -318,7 +318,7 @@ terrain/biology persistence are not provided by this independent codec. Next: M6
|
||||
M6.3 implements [read-only environment views](world/ENVIRONMENT_VIEWS.md) under
|
||||
ADR-0052: bounded canonical voxel footprints, exact typed derived values, explicit
|
||||
absence and tick/field/chunk freshness checks. No implicit terrain load or inventory
|
||||
authorization occurs. Next: M6.4 atomic coordinated transfers.
|
||||
authorization occurs in views alone. M6.4 now implements [coordinated transfers](world/ENVIRONMENTAL_TRANSFERS.md) under ADR-0053: tagged resource accounts, atomic staged batches, capacity and ownership checks, and bounded exact retries. Coupled persistence remains M6.8. Next: M6.5 producer/consumer biology adapters.
|
||||
|
||||
## M7 - Persistent region server
|
||||
|
||||
|
||||
+14
-2
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
|
||||
## Completed implementation
|
||||
|
||||
- Vision, architectural pillars, risks, open-question register, architecture
|
||||
diagrams, biological contracts, engineering constitution and 52 ADRs.
|
||||
diagrams, biological contracts, engineering constitution and 53 ADRs.
|
||||
Proposed/deferred choices remain distinct from accepted proof decisions.
|
||||
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
|
||||
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
|
||||
@@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic
|
||||
|
||||
| Priority | Work | Completion evidence |
|
||||
|---|---|---|
|
||||
| 1 | M6.4 coordinated environmental transfers | Atomic organism/environment debits and credits, fresh-view checks and retry identity |
|
||||
| 1 | M6.5 couple producer/consumer biology | Finite environmental supply, explicit conversions and lifecycle checks through the coupled owner |
|
||||
| Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report |
|
||||
| 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it |
|
||||
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
|
||||
@@ -641,3 +641,15 @@ Freshness validation rejects wrong stores, changed tick/field state and stale ch
|
||||
tokens, including eviction/reload. No persistent format or simulation rule changed.
|
||||
Views grant no inventory reservation; coherent tick/store pairing remains a host
|
||||
responsibility. Next: M6.4 coordinated environmental transfers.
|
||||
|
||||
|
||||
## M6.4 atomic environmental transfers (2026-09-27)
|
||||
|
||||
Implemented the [transfer contract](world/ENVIRONMENTAL_TRANSFERS.md) and ADR-0053.
|
||||
A single owner stages and publishes fields and tagged organism resource accounts
|
||||
atomically, validates view freshness and ownership, rejects capacity/stock/budget
|
||||
violations, and retains 64 exact request receipts. Tests cover contention, late-leg
|
||||
rollback, changed retries, independent compartment balances and conservation.
|
||||
This is in-memory ownership; no coupled recovery format or durable ACK is claimed.
|
||||
No schema, simulation version, dependency or deployment changed. Next: M6.5 biology
|
||||
adapters, including explicit conversion and active/alive validation.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -183,3 +183,12 @@ and an explicit host tick. Queries never load chunks or mutate inventories. A
|
||||
separate validator rejects stale ticks, field watermarks, foreign store instances
|
||||
and stale sampled chunk tokens. Coherent store pairing and single-owner scheduling
|
||||
remain host obligations; M6.4 must validate and commit in one ownership phase.
|
||||
|
||||
## M6.4 coordinated resource ownership
|
||||
|
||||
[ADR-0053](../adr/0053-atomic-environmental-transfers.md) and the
|
||||
[transfer contract](../world/ENVIRONMENTAL_TRANSFERS.md) define one owner of field
|
||||
stocks, terrain binding and tagged organism resource accounts. Fresh views authorize
|
||||
only staged transfers; both endpoints and the retry receipt publish together after
|
||||
validation and allocation. Accounts are resource endpoints; biological lifecycle
|
||||
integration follows in M6.5. Field-only snapshots cannot recover a coupled owner.
|
||||
|
||||
@@ -303,3 +303,11 @@ dissolved N/P, organic matter/energy, incident-energy and heat inventories. Mate
|
||||
defaults provide capacity, never supply. Local transfers can only relocate the same
|
||||
channel; water cannot become organic other. Field snapshots preserve depletion.
|
||||
No rate source, biochemical conversion or transfer to organisms exists yet.
|
||||
|
||||
## Environmental transfer boundary (M6.4)
|
||||
|
||||
The [coupled owner](../world/ENVIRONMENTAL_TRANSFERS.md) retains ten resource tags
|
||||
across environment and organism endpoints. Its Inventory is a derived report, not
|
||||
another spendable ledger. Water cannot turn into organic matter, and incident energy
|
||||
or heat cannot turn into usable energy through this adapter. M6.5 must supply explicit
|
||||
biological conversion rules and lifecycle validation; M2 Ledger invariants remain intact.
|
||||
|
||||
@@ -1772,3 +1772,23 @@ ChunkStore does not yet bind a world identity, so coherent field/terrain pairing
|
||||
cannot be independently authenticated by this view. Combined ownership, reservation,
|
||||
atomic inventory transfer and retry outcomes remain M6.4. No deployment or World0
|
||||
operation occurred.
|
||||
|
||||
## M6.4 atomic environmental transfers - 2026-09-27
|
||||
|
||||
Executed on Windows x64 with the installed Visual Studio toolchain:
|
||||
|
||||
- `tools/windows-check.ps1 -Preset release -Action check`: build and 52/52 CTests passed (NDEBUG).
|
||||
- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy/warnings-as-errors build and 52/52 CTests passed.
|
||||
- `tools/windows-check.ps1 -Preset asan -Action check`: AddressSanitizer build and 52/52 CTests passed.
|
||||
- `tools/windows-check.ps1 -Preset release -Action format`: passed.
|
||||
|
||||
New environment-transfers-contracts exercises last-stock contention, fresh versus
|
||||
stale/foreign views, exact retries, changed-payload refusal, expired command IDs,
|
||||
command exhaustion, late-leg rollback, account and water capacities, admission
|
||||
overflow, separate owner/field allocation budgets, and 100 batches checked against
|
||||
independent expected balances across all ten compartments. No golden changed.
|
||||
|
||||
This evidence covers local in-memory atomicity. Coupled snapshots, allocation-failure
|
||||
injection, process crash recovery and biological lifecycle integration are not claimed.
|
||||
Linux/UBSan/TSan were not run locally; their existing Gitea jobs remain required CI
|
||||
evidence. No cluster workload or World0 state was changed.
|
||||
|
||||
@@ -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