Files
aevolution/docs/world/ENVIRONMENTAL_FIELDS.md
T

6.0 KiB

M6.2 optional environmental fields

ADR-0051 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 adds derived footprint/tick/revision views. Read-only identity() and checked water_capacity(site) accessors support those queries without exposing writable metadata or changing field snapshot v1. 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 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.

M6.4's coupled owner 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.