Complete M6.2 optional finite environmental fields
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user