Implement M5.3 versioned deterministic abiotic generation

This commit is contained in:
dingo
2026-09-26 14:23:24 -04:00
parent 0798410dae
commit e2f99b780f
14 changed files with 520 additions and 5 deletions
+3 -1
View File
@@ -260,7 +260,9 @@ M5.1 is implemented under [ADR-0042](adr/0042-local-voxel-contract.md): see
negative seam examples and rejection rules. It does not allocate chunk storage.
M5.2 is complete: [ADR-0043](adr/0043-chunk-layout.md) selects 16-cube
uniform/palette/dense storage from the [comparison](engineering/CHUNK_LAYOUT_EVALUATION.md).
Next is 5.3: versioned deterministic abiotic generation.
M5.3 is complete under [ADR-0044](adr/0044-abiotic-generation.md):
[versioned abiotic generation](world/BASE_GENERATION.md) with frozen reference fixtures.
Next is 5.4: bounded sparse active chunk ownership and compact resident storage.
**Decisions still open:** final spherical layout, region dimensions, adaptive LOD,
field quantization beyond the initial experiment, hydrology and surface extraction.
+10 -2
View File
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
## Completed implementation
- Vision, architectural pillars, risks, open-question register, architecture
diagrams, biological contracts, engineering constitution and 43 ADRs.
diagrams, biological contracts, engineering constitution and 44 ADRs.
Proposed/deferred choices remain distinct from accepted proof decisions.
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
@@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic
| Priority | Work | Completion evidence |
|---|---|---|
| 1 | M5.3 deterministic abiotic base | Version seed/address/material generation; golden and seam tests; no implicit life |
| 1 | M5.4 sparse active chunk ownership | Bounded compact storage, regeneration, immutable revisioned views and dirty eviction refusal |
| Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report |
| 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it |
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
@@ -553,3 +553,11 @@ Compared three representations, four edges and five fixtures with seeded edit/or
checks. [Evaluation](engineering/CHUNK_LAYOUT_EVALUATION.md) records memory, costs,
encoding estimates and limits. ADR-0043 selects 16-cube uniform/palette/dense geometry.
No production container, generator, codec or deployment was added. Next: M5.3.
## M5.3 deterministic abiotic base
Added pure seed/address/version generation, a bounded inert material table and
16-cube logical output. [Contract](world/BASE_GENERATION.md) specifies rejection,
compatibility and storage boundaries. Twelve independent reference goldens and
signed seam/query-order tests freeze v1. No gameplay, persistence or deployment
was added. Next: M5.4 sparse active chunk ownership.
+58
View File
@@ -0,0 +1,58 @@
# 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.
+2
View File
@@ -45,3 +45,5 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0042: Local voxel contract](0042-local-voxel-contract.md) - accepted for M5.1; layout and planet mapping deferred.
- [ADR-0043: Bounded chunk layout](0043-chunk-layout.md) - accepted for M5; 16-cube uniform/palette/dense geometry.
- [ADR-0044: Abiotic generation](0044-abiotic-generation.md) - accepted for M5.3 synthetic integer base, version retention and material table.
+8
View File
@@ -116,3 +116,11 @@ No data allocation, terrain generation, material table, mass transfer, persisten
meshing or planet mapping is implemented by this contract. M5.2 measured storage; [ADR-0043](../adr/0043-chunk-layout.md) selects
16-cube uniform/palette/dense geometry for the bounded M5 implementation. Production
chunk ownership/allocation limits remain M5.4; optional chemistry pages remain M6.
## Implemented M5.3 generation boundary
[ADR-0044](../adr/0044-abiotic-generation.md) and the
[base generation contract](../world/BASE_GENERATION.md) add pure versioned point and
16-cube queries. Synthetic abiotic strata use global integer addresses and create no
life. Unsupported versions fail explicitly. Temporary logical output is not resident
storage; bounded chunk ownership/eviction is M5.4. There is no persistence or mesher.
+23
View File
@@ -1448,3 +1448,26 @@ Memory figures are owned capacities, not RSS or true allocation peaks; encoding
sizes are estimates, not a codec. See the report for excluded buffers and timing
limits. Native ASan does not cover UBSan. Linux CI, R730xd benchmarking and Kubernetes
execution were not run locally. No Argo/World0 deployment occurred. Next: M5.3.
## M5.3 deterministic abiotic generation - 2026-09-26
Implemented ADR-0044 in evo::world with a versioned inert material table and pure
point/chunk queries. The fixture creates no biological state. No existing simulation
version, golden or persistence codec changed.
Executed on Windows x64 / MSVC 19.44:
- `tools/windows-check.ps1 -Preset release -Action check`: 42/42 CTest passed.
- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy 19 build and
42/42 CTest passed.
- `tools/windows-check.ps1 -Preset asan -Action check`: 42/42 CTest passed.
- `tools/windows-check.ps1 -Preset release -Action format`: passed.
- `python tools/world_generation_reference.py`: computed the 12 frozen fixture
fingerprints independently before C++ execution; all match in CTest.
- `git diff --check`: passed.
New tests cover 262144 point/chunk comparisons across signed seams, query order,
stratigraphy, known/unknown materials, version/edge rejection and extreme addresses.
Fingerprint bytes are explicitly little endian logical fields. Linux CI and UBSan
were not run locally; no cross-platform execution result is claimed. No deployment
or World0 state change occurred. Next: M5.4 bounded sparse chunk ownership.
+71
View File
@@ -0,0 +1,71 @@
# 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.