95 lines
6.0 KiB
Markdown
95 lines
6.0 KiB
Markdown
# 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 adds [derived footprint/tick/revision views](ENVIRONMENT_VIEWS.md).
|
|
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](../../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.
|
|
|
|
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.
|