Complete M6.2 optional finite environmental fields

This commit is contained in:
dingo
2026-09-27 00:21:05 -04:00
parent 750afcd4d4
commit ab130b0fbb
15 changed files with 984 additions and 3 deletions
+88
View File
@@ -0,0 +1,88 @@
# M6.2 optional environmental fields
[ADR-0051](../adr/0051-optional-environmental-fields.md) scopes `FieldStore`.
Its public API is `include/evo/world/fields.hpp`; it has no I/O, threads or biology.
## Ownership and creation
The store owns 1..4096 fixed sites in strict voxel-address order. Site index is a
stable local ID. Sites have valid one-voxel HabitatBoxes and a substrate material
from M5's table v1. Distinct voxels ensure boxes cannot overlap within this store.
The host must prevent ownership overlap with other stores and bind world/frame.
Creating another store is an independent fixture branch, not additional live supply.
Opening ID is nonzero, immutable host provenance; it is not verified externally.
Water capacity defaults for materials 0/1/2 are supplied explicitly and stored.
Capacity is not water, pore geometry, density or an extraction grant. Water must
not exceed its site's capacity, including transfers and restore. Zero capacity
allows only zero stored water; moisture remains undefined there per M6.1.
Substrate declarations are immutable field metadata. M6.4 must establish a coupled
geometry revision before terrain edits can change habitat capacity or substrate.
Optional channels: water; dissolved N, P; organic C, N, P, other, chemical energy;
incident energy; heat. Scalar matter uses fg and energy uses pJ. Channel identity
preserves compartments. Water contributes to `other`, dissolved/organic components
to their named elements, and all energy compartments to energy. The sum of each
conserved channel must fit u64 at creation/restore. Organic mass and total biomass
are derived; there is no second biomass inventory. Missing channels return `missing`,
not zero. A present all-zero field stays present through encoding and restore.
Opening spans contain either one value repeated at all sites or exactly site-count
values. Channels must be supplied in increasing enum order without duplicates.
No default stock is generated from a material, absent page, restore or read.
No sites/fields can be added after creation in v1.
## Storage, operations and bounds
Each present channel uses site zero's scalar as baseline. A 64-site page allocates
64 u64 values only if any valid value differs; the last page's padding is zero.
No pages are allocated for a uniform field. Memory accounting is
`sizeof(FieldStore) + site_count*sizeof(FieldSite) + allocated_pages*512`.
An operation reserves an additional 32768-byte scalar scratch allowance and charges
old plus new channel pages during replacement; this is accounted memory, not RSS.
Caller input/output buffers, allocator headers and small stack metadata are excluded.
Restore additionally uses at most 327680 bytes of dense field staging, a second
`site_count*sizeof(FieldSite)` mapping array and at most ten opening-span records,
outside the resident budget. All counts are bounded before those allocations.
`read(site, channel)` returns the owned scalar in that channel's units; it grants
no consumption permission. M6.3 will add derived footprint/tick/revision views.
`transfer(action, channel, from, to, amount)` moves a positive quantity between
distinct sites within one present field. It checks source, overflow, water capacity,
fresh nonzero command and replacement budget before publishing. Rejection preserves
all quantities and watermark. Same/older commands reject, never execute again.
This storage primitive cannot feed an organism, convert compartments or create heat.
It transfers no terrain volume. M6.4 supplies coordinated biological transactions.
Empty input, bad material, invalid box, duplicate voxel/channel, mismatched span,
sum overflow and insufficient budgets fail explicitly. Allocation exceptions
propagate to the host; candidates are detached until success. Stores are noncopyable
and nonmovable; scalar reads return values and retain no lifetime-sensitive views.
## Persistence and compatibility
[Snapshot schema](../../schemas/world-fields-v1.md) encodes logical quantities
independently of pages. It includes world/frame, nonzero opening identity, material
defaults, mapping, channel presence and transfer watermark. Canonical decode/re-encode
must match exactly. Runtime byte budgets and pointers are not persisted.
No old/unknown version is migrated implicitly; checksums detect accidental corruption
only. Restoring a field snapshot never calls the terrain generator.
Snapshot buffers are not durable publication. M5 LocalWorldFiles does not save these
fields and must not be advertised as recovering a coupled environment. M6.8/M7 must
publish a version bundle and ownership boundary across terrain, fields and biology.
There are no configured rate sources in v1, so no fractional rate state exists to
restore. Introducing rates requires explicit serialized residual/interval state.
Tests measure uniform, sparse and fully varying resident footprints, exhaust a
finite source into another site, reject overspending without mutation, restore the
depleted state and continue deterministically. Codec tests cover truncation, checksum,
version, identity, shape, channel order, capacity and total-overflow rejection, and
bounded repaired-checksum mutation smoke. Next: M6.3 environment read views.
Measured Windows x64/MSVC 19.44 fixture (130 sites): uniform or absent fields use
15768 accounted resident bytes; one varying 64-site page uses 16280; three varying
pages use 17304. A single present channel serializes to 10756 bytes regardless of
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.
+5
View File
@@ -131,3 +131,8 @@ M6.2 introduces optional fields, explicit initial inventories and versioned pers
M6.3 read views; M6.4 coordinated ownership/transfer validation; M6.5-6.8 integrated
processes, source budgets and replay. Density/composition conversion, chemical
reactions, global atmosphere/hydrology and cross-region transfer remain unsupported.
M6.2 now implements [optional fields](ENVIRONMENTAL_FIELDS.md) and independent field
snapshots under ADR-0051. Incident energy is finite stock only; no configured rates
or fractional source state exist in field format v1. Enabling rates will require
explicit versioned residual/interval persistence before any integration can commit.