Implement M5.3 versioned deterministic abiotic generation
This commit is contained in:
+3
-1
@@ -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
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user