75 lines
4.3 KiB
Markdown
75 lines
4.3 KiB
Markdown
[Reviewed]
|
|
# 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.
|