Files
aevolution/docs/world/BASE_GENERATION.md
T

72 lines
4.1 KiB
Markdown

# M5.3 abiotic base contract
Implemented in `evo::world`, public header `evo/world/generation.hpp`.
[ADR-0044](../adr/0044-abiotic-generation.md) freezes the exact v1 integer algorithm.
This is a bounded synthetic terrain fixture, not a geological planet model.
## Inputs and output
`BaseDescriptor` contains uint64 seed and explicit coordinate/generator/material
versions and edge. The supported tuple is (1,1,1,16); all seeds are valid. Versions
are independent of biological simulation and snapshot format versions. Raw descriptor
construction does not validate it. Each entry validates before address arithmetic or
allocation, in coordinate/generator/material/edge order.
- `base_sample(descriptor, VoxelAddress)` returns one validated `CellSample`.
- `generate_base_chunk(descriptor, ChunkAddress)` returns exactly 4096 samples in
X-fast, then Y, then Z order, equivalent to point queries at the chunk's cells.
- `material_name(table_version, MaterialId)` resolves only v1 keys 0/1/2 to immutable
static names void/rock/regolith. Unknown tables and keys return typed errors.
Coordinate bounds, cell pitch and fill retain ADR-0042 semantics. Invalid inputs
return `expected` errors with no partially returned state. Standard allocation failure
propagates to the host exception boundary. Functions perform no I/O, spawn no threads,
use no clocks/global RNG and retain no mutable state; independent callers may execute
concurrently. Every logical sample is void or fully filled inert material. There is no
organism, lineage, biomass, nutrient or biological soil creation. Material identity is
not an extractable resource inventory; M6 must define inventory accounting separately.
## Boundaries and ownership
```mermaid
flowchart LR
D[Seed + versions + chunk address] --> V[Validate request]
V --> G[Pure global-address sample rule]
G --> S[4096 logical staging samples]
S --> C[M5.4 compact owned chunk]
```
Neighbor agreement means the same global cell has the same value, including when
queried as a neighbor halo. Different neighboring cells need not match. The generator
has no chunk-local seed or iteration-dependent state, so it cannot add chunk-border
terrain discontinuities. Jagged per-column height changes are intentional v1 fixture
behavior, not a smooth meshing claim. Z is up; surface lies in [-8,7]; three regolith
cells lie below it, then rock. Cells at or above it are void.
Output is a temporary logical vector (4096 CellSample values), not compressed resident
storage. M5.4 must account for staging and convert into ADR-0043's uniform/palette/dense
layout. No world-wide cache or resident allocation grows here. The caller retains the
descriptor, world/frame identity and address; raw vectors carry no durable identity or
revision and must not be mistaken for authoritative stored chunks.
## Compatibility and verification
Persist the complete descriptor, frame/world identity and address in M5.6. Reject
unsupported versions without falling forward to current defaults. A future generator
must keep v1 dispatch available for referenced worlds, or perform an explicit reviewed
migration. Clones with the same descriptor/address intentionally regenerate the same
base. Geometry regeneration is not an authorized terrain edit or matter transfer.
`tools/world_generation_reference.py` independently computes 12 frozen fingerprints
for seeds 0, 123456 and UINT64_MAX and four signed chunks. Run it with Python 3; it
prints reference rows without modifying tests. Fingerprints hash material u16 LE then
fill u16 LE in X-fast order using FNV-1a. They are compatibility tests, not an adopted
codec, security hash or justification for replacing a golden after a failure.
CTest `world-generation-contracts` checks those goldens in reversed and forward query
orders, unrelated intervening generation, all 262144 samples in a 4x4x4 chunk volume,
all-axis origin seams, independently located strata, material membership, coordinate
corners/extremes and unsupported versions. Existing simulation goldens remain intact.
Cross-platform integer agreement is the required contract; local Windows success
alone is not evidence that Linux CI has run.