Files
aevolution/docs/adr/0044-abiotic-generation.md
T

59 lines
3.1 KiB
Markdown

# ADR-0044: Versioned abiotic base generation
## Status
Accepted for the bounded M5.3 engineering fixture, not planetary geology.
## Context
Unmodified chunks must regenerate without query-order or worker dependence.
ADR-0042 defines coordinates; ADR-0043 selects edge 16. Unknown versions must
fail rather than silently generating new territory under different rules.
## Decision
Expose pure sample and chunk functions in evo::world. Inputs explicitly carry seed,
coordinate version, generator version, material version and edge. Only tuple
(1,1,1,16) is supported. Reject versions before addresses and allocation.
Return expected with typed errors. No mutable RNG, clocks, threads, I/O or life.
Generator v1 is a deliberately synthetic column fixture. Define M(u) with unsigned
64-bit wraparound: u=(u xor (u>>30))*0xbf58476d1ce4e5b9;
u=(u xor (u>>27))*0x94d049bb133111eb; return u xor (u>>31).
Let h=M(M(seed xor 0x4145564f47454e31) xor uint64(x));
h=M(h xor uint64(y)); surface=int64(h modulo 16)-8.
Signed conversion to unsigned uses modulo 2^64, not native byte hashing.
At z>=surface emit void; at surface-3<=z<surface emit regolith;
below that emit rock. Nonvoid fill is 65535, void fill zero.
Material table v1 is exactly 0 void, 1 rock, 2 regolith. Names describe inert
geometry only; no density, nutrient inventory, organisms or biological soil is implied.
Chunks contain 4096 X-fast logical samples, generated from global voxel addresses.
This temporary dense output is a conversion buffer, not resident storage; M5.4 must
convert to the selected uniform/palette/dense policy and budget staging capacity.
Caller owns world/frame identity; matching descriptors intentionally produce matching
content across world clones. Persist all descriptor fields and address in M5.6.
Keep v1 available while referenced; changing outputs requires a new generator version
and explicit migration, never overwriting a golden. No existing simulation version changes.
## Alternatives Considered
Sequential PRNG draws couple output to traversal. Platform noise/floating point adds
portability uncertainty. Real geological solvers or caves expand the gate needlessly.
Using chunk-local hashes creates artificial seams. Reusing the mutable simulation RNG
would couple generator compatibility to unrelated kernel changes.
## Benefits
Order-independent regeneration, bounded output and exact integer portability.
Point queries provide a common definition across chunk boundaries.
## Costs
Synthetic jagged columns are not realistic geology or smooth terrain. Temporary
logical vectors cost about 16 KiB plus overhead; no resident-world capacity claim.
## Risks
Treating material keys as unlimited resources would violate M6 accounting. Adjacent
cells need not have equal values: seam agreement means a shared global address gives
the same sample. No hydrology, atmosphere, meshing or planet topology is selected.
## Consequences
Freeze byte-wise logical fingerprints with a separate Python reference, test signed
boundaries, query order, all-axis seams, table membership and rejection under Release
and sanitizers. Production persistence/ownership remain later gates.