From e2f99b780fb3ea4c89f164c060782884824fa532 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 26 Sep 2026 14:23:24 -0400 Subject: [PATCH] Implement M5.3 versioned deterministic abiotic generation --- CMakeLists.txt | 8 +- README.md | 1 + docs/ROADMAP.md | 4 +- docs/STATUS.md | 12 +- docs/adr/0044-abiotic-generation.md | 58 ++++++++ docs/adr/README.md | 2 + docs/architecture/WORLD_ARCHITECTURE.md | 8 + docs/engineering/VALIDATION.md | 23 +++ docs/world/BASE_GENERATION.md | 71 +++++++++ include/evo/world/coordinates.hpp | 2 +- include/evo/world/generation.hpp | 40 +++++ src/world/generation.cpp | 79 ++++++++++ tests/world_generation_tests.cpp | 186 ++++++++++++++++++++++++ tools/world_generation_reference.py | 31 ++++ 14 files changed, 520 insertions(+), 5 deletions(-) create mode 100644 docs/adr/0044-abiotic-generation.md create mode 100644 docs/world/BASE_GENERATION.md create mode 100644 include/evo/world/generation.hpp create mode 100644 src/world/generation.cpp create mode 100644 tests/world_generation_tests.cpp create mode 100644 tools/world_generation_reference.py diff --git a/CMakeLists.txt b/CMakeLists.txt index dfd8491..6d5408d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -34,7 +34,7 @@ target_include_directories(evo_simulation PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/in target_compile_features(evo_simulation PUBLIC cxx_std_23) evo_owned_target(evo_simulation) -add_library(evo_world STATIC src/world/coordinates.cpp) +add_library(evo_world STATIC src/world/coordinates.cpp src/world/generation.cpp) add_library(evo::world ALIAS evo_world) target_include_directories(evo_world PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") target_compile_features(evo_world PUBLIC cxx_std_23) @@ -71,6 +71,12 @@ evo_owned_target(evo-sim) include(CTest) if(BUILD_TESTING) + add_executable(evo-world-generation-tests tests/world_generation_tests.cpp) + target_link_libraries(evo-world-generation-tests PRIVATE evo::world) + evo_owned_target(evo-world-generation-tests) + add_test(NAME world-generation-contracts COMMAND evo-world-generation-tests) + set_tests_properties(world-generation-contracts PROPERTIES TIMEOUT 60) + add_executable(evo-world-coordinate-tests tests/world_coordinates_tests.cpp) target_link_libraries(evo-world-coordinate-tests PRIVATE evo::world) evo_owned_target(evo-world-coordinate-tests) diff --git a/README.md b/README.md index ed9d1f0..7fed3b4 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ network service. Dev verification manifests are separate from the simulation. - [Architecture decisions and proposals](docs/adr/README.md) - [Actionable milestones 0–4 and later gates](docs/ROADMAP.md) - [Open design questions](docs/architecture/OPEN_QUESTIONS.md) +- [Versioned abiotic base generation](docs/world/BASE_GENERATION.md) - [Actual validation results](docs/engineering/VALIDATION.md) - [Current delivery status and next steps](docs/STATUS.md) - [Opt-in ECS evaluation and measurements](docs/engineering/ECS_EVALUATION.md) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 3d7d61a..2567bf1 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -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. diff --git a/docs/STATUS.md b/docs/STATUS.md index a7097a5..088d7de 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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. diff --git a/docs/adr/0044-abiotic-generation.md b/docs/adr/0044-abiotic-generation.md new file mode 100644 index 0000000..ff1dca3 --- /dev/null +++ b/docs/adr/0044-abiotic-generation.md @@ -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 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. diff --git a/include/evo/world/coordinates.hpp b/include/evo/world/coordinates.hpp index fff28f7..89f4963 100644 --- a/include/evo/world/coordinates.hpp +++ b/include/evo/world/coordinates.hpp @@ -50,7 +50,7 @@ enum class WorldError : std::uint8_t { invalid_cell }; -// Explicit edge candidate in {8,16,32,64}; no storage size has been adopted. +// Explicit edge candidate in {8,16,32,64}; coordinate API stays explicit; M5 storage selects 16. [[nodiscard]] std::expected split(VoxelAddress voxel, std::uint32_t edge) noexcept; [[nodiscard]] std::expected join(ChunkLocation location, diff --git a/include/evo/world/generation.hpp b/include/evo/world/generation.hpp new file mode 100644 index 0000000..c89e9fb --- /dev/null +++ b/include/evo/world/generation.hpp @@ -0,0 +1,40 @@ +#pragma once + +#include "evo/world/coordinates.hpp" + +#include +#include +#include +#include + +namespace evo::world { +inline constexpr std::uint32_t base_chunk_edge = 16; +inline constexpr std::uint32_t base_chunk_cells = 4096; +// Raw request, validated on every entry. No implicit upgrade to newer versions. +struct BaseDescriptor { + std::uint64_t seed{}; + std::uint32_t coordinate_version{1}; + std::uint32_t generator_version{1}; + std::uint32_t material_version{1}; + std::uint32_t edge{base_chunk_edge}; + auto operator<=>(const BaseDescriptor&) const = default; +}; +enum class GenerationError : std::uint8_t { + unsupported_coordinates, + unsupported_generator, + unsupported_materials, + unsupported_edge, + invalid_voxel, + invalid_chunk, + unknown_material +}; +// Names carry no biological/chemical inventory or density. +[[nodiscard]] std::expected +material_name(std::uint32_t table_version, MaterialId id) noexcept; +[[nodiscard]] std::expected base_sample(BaseDescriptor descriptor, + VoxelAddress address) noexcept; +// Bounded X-fast staging output, not resident chunk ownership or a wire record. +// Allocation exceptions propagate to the host boundary. No partial result escapes. +[[nodiscard]] std::expected, GenerationError> +generate_base_chunk(BaseDescriptor descriptor, ChunkAddress address); +} // namespace evo::world diff --git a/src/world/generation.cpp b/src/world/generation.cpp new file mode 100644 index 0000000..80fe222 --- /dev/null +++ b/src/world/generation.cpp @@ -0,0 +1,79 @@ +#include "evo/world/generation.hpp" + +namespace evo::world { +namespace { +std::expected validate(BaseDescriptor d) noexcept { + if (d.coordinate_version != coordinate_contract_version) { + return std::unexpected{GenerationError::unsupported_coordinates}; + } + if (d.generator_version != 1) { + return std::unexpected{GenerationError::unsupported_generator}; + } + if (d.material_version != 1) { + return std::unexpected{GenerationError::unsupported_materials}; + } + if (d.edge != base_chunk_edge) { + return std::unexpected{GenerationError::unsupported_edge}; + } + return {}; +} +std::uint64_t mix(std::uint64_t value) noexcept { + value = (value ^ (value >> 30U)) * 0xbf58476d1ce4e5b9ULL; + value = (value ^ (value >> 27U)) * 0x94d049bb133111ebULL; + return value ^ (value >> 31U); +} +CellSample sample(std::uint64_t seed, VoxelAddress a) noexcept { + auto hash = mix(mix(seed ^ 0x4145564f47454e31ULL) ^ static_cast(a.x)); + hash = mix(hash ^ static_cast(a.y)); + const auto surface = static_cast(hash % 16U) - 8; + const std::uint16_t material = a.z >= surface ? 0 : (a.z >= surface - 3 ? 2 : 1); + // All constructed pairs obey CellSample's invariant by construction. + return *CellSample::create({material}, material == 0 ? 0 : fill_scale); +} +} // namespace +std::expected material_name(std::uint32_t version, + MaterialId id) noexcept { + if (version != 1) { + return std::unexpected{GenerationError::unsupported_materials}; + } + switch (id.value) { + case 0: + return "void"; + case 1: + return "rock"; + case 2: + return "regolith"; + default: + return std::unexpected{GenerationError::unknown_material}; + } +} +std::expected base_sample(BaseDescriptor d, VoxelAddress a) noexcept { + if (const auto valid = validate(d); !valid) { + return std::unexpected{valid.error()}; + } + if (!lower_corner_mm(a)) { + return std::unexpected{GenerationError::invalid_voxel}; + } + return sample(d.seed, a); +} +std::expected, GenerationError> generate_base_chunk(BaseDescriptor d, + ChunkAddress a) { + if (const auto valid = validate(d); !valid) { + return std::unexpected{valid.error()}; + } + const auto origin = join({a, {}}, base_chunk_edge); + if (!origin) { + return std::unexpected{GenerationError::invalid_chunk}; + } + std::vector result; + result.reserve(base_chunk_cells); + for (std::int64_t z = 0; z < base_chunk_edge; ++z) { + for (std::int64_t y = 0; y < base_chunk_edge; ++y) { + for (std::int64_t x = 0; x < base_chunk_edge; ++x) { + result.push_back(sample(d.seed, {origin->x + x, origin->y + y, origin->z + z})); + } + } + } + return result; +} +} // namespace evo::world diff --git a/tests/world_generation_tests.cpp b/tests/world_generation_tests.cpp new file mode 100644 index 0000000..8d061c3 --- /dev/null +++ b/tests/world_generation_tests.cpp @@ -0,0 +1,186 @@ +#include "evo/world/generation.hpp" + +#include +#include +#include +#include +#include +#include + +namespace { +using namespace evo::world; +void check(bool condition, std::source_location at = std::source_location::current()) { + if (!condition) { + throw std::runtime_error("world generation line " + std::to_string(at.line())); + } +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) +template bool refused(const std::expected& r, GenerationError e) { + return !r && r.error() == e; +} +std::uint64_t fingerprint(const std::vector& cells) { + std::uint64_t result = 14695981039346656037ULL; + for (const auto cell : cells) { + for (const auto value : {cell.material().value, cell.fill()}) { + for (unsigned shift = 0; shift < 16; shift += 8) { + result = (result ^ ((value >> shift) & 255U)) * 1099511628211ULL; + } + } + } + return result; +} +struct Golden { + std::uint64_t seed; + ChunkAddress address; + std::uint64_t hash; +}; +// Frozen from the independent Python integer oracle, before running C++ generation. +constexpr std::array goldens{{ + {0ULL, {0, 0, 0}, 14125776257468910697ULL}, + {0ULL, {-1, -1, -1}, 7242967182163540465ULL}, + {0ULL, {-2, 3, 0}, 4316025128172914782ULL}, + {0ULL, {4, -3, -1}, 1854350054262447477ULL}, + {123456ULL, {0, 0, 0}, 448061536662205469ULL}, + {123456ULL, {-1, -1, -1}, 14519177808023994198ULL}, + {123456ULL, {-2, 3, 0}, 7503881715723395046ULL}, + {123456ULL, {4, -3, -1}, 10763600219040791926ULL}, + {18446744073709551615ULL, {0, 0, 0}, 9340024193566171638ULL}, + {18446744073709551615ULL, {-1, -1, -1}, 17378676633817032737ULL}, + {18446744073709551615ULL, {-2, 3, 0}, 521055241663119581ULL}, + {18446744073709551615ULL, {4, -3, -1}, 6558335077292188849ULL}, +}}; +void frozen_and_order_independent() { + for (std::size_t reverse = goldens.size(); reverse > 0; --reverse) { + const auto g = goldens[reverse - 1]; + const auto first = generate_base_chunk({g.seed}, g.address); + CHECK(first && first->size() == base_chunk_cells && fingerprint(*first) == g.hash); + const auto unrelated = generate_base_chunk({g.seed ^ 123U}, {9, -10, 2}); + CHECK(unrelated); + const auto again = generate_base_chunk({g.seed}, g.address); + CHECK(again && *again == *first); + } + for (const auto g : goldens) { + const auto result = generate_base_chunk({g.seed}, g.address); + CHECK(result && fingerprint(*result) == g.hash); + } +} +void samples_seams_and_materials() { + // Independent rectangular enumeration straddles negative and positive chunk + // faces on all axes. A halo sample from either side has one global definition. + for (std::int64_t cz = -2; cz <= 1; ++cz) { + for (std::int64_t cy = -2; cy <= 1; ++cy) { + for (std::int64_t cx = -2; cx <= 1; ++cx) { + const auto chunk = generate_base_chunk({73}, {cx, cy, cz}); + CHECK(chunk); + std::size_t index = 0; + for (std::int64_t z = 0; z < 16; ++z) { + for (std::int64_t y = 0; y < 16; ++y) { + for (std::int64_t x = 0; x < 16; ++x) { + const auto point = + base_sample({73}, {cx * 16 + x, cy * 16 + y, cz * 16 + z}); + CHECK(point && *point == (*chunk)[index++]); + CHECK(material_name(1, point->material())); + CHECK(point->fill() == (point->material().value == 0 ? 0 : fill_scale)); + } + } + } + } + } + } + // Test stratigraphy independently of hash implementation by locating the + // first void cell; exactly three regolith cells must lie immediately below. + for (std::int64_t x = -32; x <= 32; ++x) { + std::int64_t height = -12; + while (height <= 8) { + const auto at = base_sample({91}, {x, -x, height}); + CHECK(at); + if (at->material().value == 0) { + break; + } + ++height; + } + CHECK(height >= -8 && height <= 7); + for (std::int64_t z = -16; z <= 16; ++z) { + const auto at = base_sample({91}, {x, -x, z}); + CHECK(at && at->material().value == (z >= height ? 0 : (z >= height - 3 ? 2 : 1))); + } + } + CHECK(*material_name(1, {0}) == "void"); + CHECK(*material_name(1, {1}) == "rock"); + CHECK(*material_name(1, {2}) == "regolith"); +} +void rejection_and_extremes() { + using E = GenerationError; + constexpr auto lo = std::numeric_limits::min(); + constexpr auto hi = std::numeric_limits::max(); + for (const auto version : {0U, 2U, std::numeric_limits::max()}) { + for (unsigned field = 0; field < 4; ++field) { + BaseDescriptor d{}; + E error{}; + switch (field) { + case 0: + d.coordinate_version = version; + error = E::unsupported_coordinates; + break; + case 1: + d.generator_version = version; + error = E::unsupported_generator; + break; + case 2: + d.material_version = version; + error = E::unsupported_materials; + break; + default: + d.edge = version; + error = E::unsupported_edge; + break; + } + CHECK(refused(base_sample(d, {hi, lo, 0}), error)); + CHECK(refused(generate_base_chunk(d, {hi, lo, 0}), error)); + } + CHECK(refused(material_name(version, {0}), E::unsupported_materials)); + } + for (const auto edge : {8U, 32U, 64U}) { + BaseDescriptor d{}; + d.edge = edge; + CHECK(refused(generate_base_chunk(d, {}), E::unsupported_edge)); + } + for (const auto id : {3U, 65535U}) { + CHECK(refused(material_name(1, {static_cast(id)}), E::unknown_material)); + } + for (const auto bad : {lo, hi, -voxel_limit - 1, voxel_limit}) { + for (const auto a : + {VoxelAddress{bad, 0, 0}, VoxelAddress{0, bad, 0}, VoxelAddress{0, 0, bad}}) { + CHECK(refused(base_sample({}, a), E::invalid_voxel)); + } + } + constexpr auto limit = voxel_limit / 16; + for (const auto bad : {lo, hi, -limit - 1, limit}) { + for (const auto a : + {ChunkAddress{bad, 0, 0}, ChunkAddress{0, bad, 0}, ChunkAddress{0, 0, bad}}) { + CHECK(refused(generate_base_chunk({}, a), E::invalid_chunk)); + } + } + for (const auto x : {-limit, limit - 1}) { + for (const auto y : {-limit, limit - 1}) { + for (const auto z : {-limit, limit - 1}) { + const auto chunk = generate_base_chunk({}, {x, y, z}); + CHECK(chunk && chunk->size() == 4096); + CHECK((*chunk)[0] == *base_sample({}, {x * 16, y * 16, z * 16})); + CHECK((*chunk)[4095] == *base_sample({}, {x * 16 + 15, y * 16 + 15, z * 16 + 15})); + } + } + } +} +} // namespace +int main() try { + frozen_and_order_independent(); + samples_seams_and_materials(); + rejection_and_extremes(); + return 0; +} catch (const std::exception& e) { + std::fprintf(stderr, "%s\n", e.what()); + return 1; +} catch (...) { + return 1; +} diff --git a/tools/world_generation_reference.py b/tools/world_generation_reference.py new file mode 100644 index 0000000..8c888cd --- /dev/null +++ b/tools/world_generation_reference.py @@ -0,0 +1,31 @@ +"""Independent ADR-0044 v1 oracle; prints frozen C++ fixture rows, no file edits. +Fingerprint: FNV-1a over X-fast samples, material u16 LE then fill u16 LE. +Not a cryptographic digest or production serialization format. +""" +MASK = (1 << 64) - 1 + + +def mix(n): + n = ((n ^ (n >> 30)) * 0xbf58476d1ce4e5b9) & MASK + n = ((n ^ (n >> 27)) * 0x94d049bb133111eb) & MASK + return n ^ (n >> 31) + + +def fingerprint(seed, chunk): + digest = 14695981039346656037 + for z in range(chunk[2] * 16, (chunk[2] + 1) * 16): + for y in range(chunk[1] * 16, (chunk[1] + 1) * 16): + for x in range(chunk[0] * 16, (chunk[0] + 1) * 16): + column = mix(mix(mix(seed ^ 0x4145564f47454e31) ^ (x & MASK)) ^ (y & MASK)) + height = column % 16 - 8 + material = 0 if z >= height else (2 if z >= height - 3 else 1) + fill = 65535 if material else 0 + for byte in material.to_bytes(2, 'little') + fill.to_bytes(2, 'little'): + digest = ((digest ^ byte) * 1099511628211) & MASK + return digest + + +if __name__ == '__main__': + for seed in [0, 123456, MASK]: + for chunk in [(0, 0, 0), (-1, -1, -1), (-2, 3, 0), (4, -3, -1)]: + print(f'{{{seed}ULL, {{{chunk[0]}, {chunk[1]}, {chunk[2]}}}, {fingerprint(seed, chunk)}ULL}},')