4.3 KiB
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.