Files
aevolution/docs/adr/0051-optional-environmental-fields.md
T

74 lines
4.3 KiB
Markdown

# ADR-0051: Optional finite environmental field pages
## Status
Accepted for M6.2 bounded in-memory storage and binary-buffer persistence.
## Context
ADR-0050 defines units and one-voxel habitats. Terrain contains no extractable
nutrients. M6 needs finite stocks without allocating chemistry on every planet voxel.
The M5 codec cannot silently gain environmental state or promise atomic recovery of
independently saved geometry and biology.
## Decision
Add a separate `FieldStore` to evo::world. Creation fixes 1..4096 lexicographically
ordered habitat sites, one per voxel, each with an explicit local box and substrate
material ID. A nonzero opening ID records host provenance, not authentication.
World/frame, material defaults, mappings, field presence, quantities and command
watermark are serialized together. No site insertion, removal or regeneration API.
Three material water-capacity defaults (void/rock/regolith) are explicit nonnegative
fixture parameters. They supply no inventory or density. A site's substrate is a
field property, not a live terrain view; M6.4 must reconcile edits when binding stores.
Optional water, dissolved N/P, organic C/N/P/other/energy, incident energy and heat
channels own finite opening quantities. Missing differs from present zero. A field
opening supplies one uniform value or exactly one value per site; every repeated
uniform quantity is counted in global per-element/energy totals, checked against u64.
Compress each present channel with its first site's value as baseline, and allocate
64-value pages only where another site differs. Pages use stable site order, not
planet allocation. The bounded scalar layout is a scoped choice, not a claim of
optimal compression. Measure uniform and varying memory in tests.
Implement a same-channel, same-store transfer only: positive amount, distinct valid
sites, fresh nonzero action ID, sufficient balance, capacity and allocation budget.
Stage a replacement channel before atomic publication; success advances the persisted
watermark. Stale action IDs reject, including exact retries (ADR-0024 semantics).
There is no arbitrary setter, deletion, cross-compartment conversion or organism
credit. M6.4 still owns coordinated transactions and idempotent biological outcomes.
New field snapshot v1 uses canonical explicit little-endian logical values and an
FNV corruption checksum. Restore checks versions/identity/length/checksum and all
creation invariants into a detached store. It accepts no M5 snapshot as field state.
Host byte budgets exclude input/output buffers and allocator overhead; transient
channel replacement and bounded decode workspace are explicitly charged/documented.
Rate-driven sources are not supported: incident energy is only finite stock. Before
adding rates, persist rate identity, denominator, residual and interval watermark in
a new compatible format or explicit migration; never synthesize these on restore.
## Alternatives Considered
Dense chemistry per voxel violates sparse allocation goals. Derived material supply
would replenish after unloading. Piggybacking fields into M5 without a combined
transaction gives false durability. General adaptive grids and cross-store transfers
are unnecessary for the first storage contract. First-value baselines are simpler
than dictionaries, but an isolated change at site zero can allocate many pages.
## Benefits
Finite quantities, deterministic round trips, explicit absence and bounded sparse
allocation with no database or new dependency. Geometry formats remain unchanged.
## Costs
Logical wire arrays favor validation over compression. Fixed site membership caps
the proof; a changing baseline can increase replacement costs. Read access is scalar
by site/channel, not M6.3's tick/revision-tagged environment query.
## Risks
Host provenance and substrate declarations are trusted inputs. Restoring the same
snapshot twice does not fence process authority. Checksums do not authenticate data.
The snapshot is not automatically published by LocalWorldFiles or part of M5 recovery.
## Consequences
Document the byte schema and ownership boundary. Test absence/zero, uniform/varying
memory, exhaustion, rollback, global overflow, budgets, canonical continuation,
old/unknown versions and recomputed-checksum malformed inputs. Integrated persistent
region state remains M6.8/M7; no deployment or existing format/golden changes.