From d5b4bd068ecbfa294e3f2436f537bce7c9e4fb63 Mon Sep 17 00:00:00 2001 From: dingo Date: Mon, 14 Sep 2026 15:44:41 -0400 Subject: [PATCH] Initial commit: architecture docs and headless engineering proof Aeternalis Evolution, a custom-engine persistent evolutionary MMO. This first commit establishes the project skeleton: - Architecture and design docs: project vision, system overview, engineering constitution, roadmap, 19 ADRs, and the simulation, world, network, persistence and infrastructure architectures. - Headless engineering proof: deterministic synthetic particles, component lifecycle, explicit PRNG streams, canonical snapshots and restored execution. - Build and tooling: CMake 3.28+ / Ninja presets, C++23 feature check, clang-format and clang-tidy config, format check script, Windows check script, and a Docker build context. - Tests: unit tests, benchmarks, a snapshot fuzz target and CLI integration wiring. No gameplay, renderer, network service or running deployment yet. Co-Authored-By: Claude Opus 5 --- .clang-format | 10 + .clang-tidy | 6 + .dockerignore | 8 + .editorconfig | 15 + .gitignore | 12 + AGENTS.md | 24 ++ CMakeLists.txt | 77 +++++ CMakePresets.json | 26 ++ README.md | 85 ++++++ apps/evo-sim/main.cpp | 276 ++++++++++++++++++ cmake/ProjectOptions.cmake | 54 ++++ deploy/README.md | 36 +++ deploy/docker/Dockerfile | 29 ++ docs/PROJECT_VISION.md | 70 +++++ docs/ROADMAP.md | 90 ++++++ docs/adr/0001-language-toolchain.md | 34 +++ docs/adr/0002-build-system.md | 34 +++ docs/adr/0003-dependencies.md | 34 +++ docs/adr/0004-test-benchmark-framework.md | 34 +++ docs/adr/0005-ecs-strategy.md | 34 +++ docs/adr/0006-tick-model.md | 34 +++ docs/adr/0007-prng.md | 34 +++ docs/adr/0008-serialization.md | 34 +++ docs/adr/0009-units-coordinates.md | 34 +++ docs/adr/0010-error-handling.md | 34 +++ docs/adr/0011-thread-ownership.md | 34 +++ docs/adr/0012-logging.md | 34 +++ docs/adr/0013-postgresql-client.md | 34 +++ docs/adr/0014-message-bus.md | 34 +++ docs/adr/0015-observability.md | 34 +++ .../0016-persistence-and-region-ownership.md | 34 +++ docs/adr/0017-network-security.md | 34 +++ docs/adr/0018-infrastructure-services.md | 34 +++ docs/adr/0019-voxel-storage-and-meshing.md | 54 ++++ docs/adr/DEPENDENCY_EVALUATION.md | 26 ++ docs/adr/README.md | 20 ++ .../INFRASTRUCTURE_ARCHITECTURE.md | 104 +++++++ docs/architecture/NETWORK_ARCHITECTURE.md | 81 +++++ docs/architecture/OPEN_QUESTIONS.md | 50 ++++ docs/architecture/PERSISTENCE_ARCHITECTURE.md | 144 +++++++++ docs/architecture/SIMULATION_ARCHITECTURE.md | 109 +++++++ docs/architecture/SYSTEM_OVERVIEW.md | 98 +++++++ docs/architecture/WORLD_ARCHITECTURE.md | 105 +++++++ docs/biology/ECOLOGY_MODEL.md | 97 ++++++ docs/biology/ENERGY_MODEL.md | 88 ++++++ docs/biology/GENOME_MODEL.md | 78 +++++ docs/biology/REPRODUCTION_MODEL.md | 80 +++++ docs/engineering/ENGINEERING_CONSTITUTION.md | 39 +++ docs/engineering/TEST_STRATEGY.md | 35 +++ docs/infrastructure/OPERATIONS.md | 69 +++++ include/evo/core/random.hpp | 33 +++ include/evo/core/types.hpp | 67 +++++ include/evo/simulation/world.hpp | 54 ++++ include/evo/telemetry/sinks.hpp | 35 +++ schemas/proof-snapshot.md | 10 + src/simulation/snapshot.cpp | 117 ++++++++ src/simulation/world.cpp | 47 +++ tests/benchmarks/simulation_benchmark.cpp | 53 ++++ tests/cli_integration.cmake | 62 ++++ tests/fuzz/snapshot_fuzz.cpp | 29 ++ tests/simulation_tests.cpp | 259 ++++++++++++++++ tools/check-format.cmake | 14 + tools/windows-check.ps1 | 44 +++ 63 files changed, 3531 insertions(+) create mode 100644 .clang-format create mode 100644 .clang-tidy create mode 100644 .dockerignore create mode 100644 .editorconfig create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 CMakeLists.txt create mode 100644 CMakePresets.json create mode 100644 README.md create mode 100644 apps/evo-sim/main.cpp create mode 100644 cmake/ProjectOptions.cmake create mode 100644 deploy/README.md create mode 100644 deploy/docker/Dockerfile create mode 100644 docs/PROJECT_VISION.md create mode 100644 docs/ROADMAP.md create mode 100644 docs/adr/0001-language-toolchain.md create mode 100644 docs/adr/0002-build-system.md create mode 100644 docs/adr/0003-dependencies.md create mode 100644 docs/adr/0004-test-benchmark-framework.md create mode 100644 docs/adr/0005-ecs-strategy.md create mode 100644 docs/adr/0006-tick-model.md create mode 100644 docs/adr/0007-prng.md create mode 100644 docs/adr/0008-serialization.md create mode 100644 docs/adr/0009-units-coordinates.md create mode 100644 docs/adr/0010-error-handling.md create mode 100644 docs/adr/0011-thread-ownership.md create mode 100644 docs/adr/0012-logging.md create mode 100644 docs/adr/0013-postgresql-client.md create mode 100644 docs/adr/0014-message-bus.md create mode 100644 docs/adr/0015-observability.md create mode 100644 docs/adr/0016-persistence-and-region-ownership.md create mode 100644 docs/adr/0017-network-security.md create mode 100644 docs/adr/0018-infrastructure-services.md create mode 100644 docs/adr/0019-voxel-storage-and-meshing.md create mode 100644 docs/adr/DEPENDENCY_EVALUATION.md create mode 100644 docs/adr/README.md create mode 100644 docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md create mode 100644 docs/architecture/NETWORK_ARCHITECTURE.md create mode 100644 docs/architecture/OPEN_QUESTIONS.md create mode 100644 docs/architecture/PERSISTENCE_ARCHITECTURE.md create mode 100644 docs/architecture/SIMULATION_ARCHITECTURE.md create mode 100644 docs/architecture/SYSTEM_OVERVIEW.md create mode 100644 docs/architecture/WORLD_ARCHITECTURE.md create mode 100644 docs/biology/ECOLOGY_MODEL.md create mode 100644 docs/biology/ENERGY_MODEL.md create mode 100644 docs/biology/GENOME_MODEL.md create mode 100644 docs/biology/REPRODUCTION_MODEL.md create mode 100644 docs/engineering/ENGINEERING_CONSTITUTION.md create mode 100644 docs/engineering/TEST_STRATEGY.md create mode 100644 docs/infrastructure/OPERATIONS.md create mode 100644 include/evo/core/random.hpp create mode 100644 include/evo/core/types.hpp create mode 100644 include/evo/simulation/world.hpp create mode 100644 include/evo/telemetry/sinks.hpp create mode 100644 schemas/proof-snapshot.md create mode 100644 src/simulation/snapshot.cpp create mode 100644 src/simulation/world.cpp create mode 100644 tests/benchmarks/simulation_benchmark.cpp create mode 100644 tests/cli_integration.cmake create mode 100644 tests/fuzz/snapshot_fuzz.cpp create mode 100644 tests/simulation_tests.cpp create mode 100644 tools/check-format.cmake create mode 100644 tools/windows-check.ps1 diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000..0a4e3cc --- /dev/null +++ b/.clang-format @@ -0,0 +1,10 @@ +BasedOnStyle: LLVM +IndentWidth: 4 +ColumnLimit: 100 +NamespaceIndentation: None +AllowShortFunctionsOnASingleLine: Empty +AllowShortIfStatementsOnASingleLine: Never +AllowShortLoopsOnASingleLine: false +BreakBeforeBraces: Attach +PointerAlignment: Left +SortIncludes: CaseSensitive diff --git a/.clang-tidy b/.clang-tidy new file mode 100644 index 0000000..93915be --- /dev/null +++ b/.clang-tidy @@ -0,0 +1,6 @@ +Checks: '-*,clang-analyzer-*,bugprone-*,performance-*,portability-*,-bugprone-easily-swappable-parameters' +WarningsAsErrors: '*' +HeaderFilterRegex: '(include[\\/]evo|src)[\\/].*' +FormatStyle: file +CheckOptions: + bugprone-narrowing-conversions.WarnOnIntegerToFloatingPointNarrowingConversion: true diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..9ecb0b2 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,8 @@ +.git +build +.vs +.cache +.env +.env.* +*.evo +*.log diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..836b94c --- /dev/null +++ b/.editorconfig @@ -0,0 +1,15 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 4 + +[*.{json,yml,yaml,cmake}] +indent_size = 2 + +[CMakeLists.txt] +indent_size = 2 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d81497d --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +/build/ +/.cache/ +/.vs/ +/CMakeUserPresets.json +/compile_commands.json +*.evo +*.profraw +*.profdata +*.log +.env +.env.* +!.env.example diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..820793b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,24 @@ +# Agent working agreement + +Read docs/PROJECT_VISION.md, docs/engineering/ENGINEERING_CONSTITUTION.md, +relevant docs/architecture files and docs/adr records before code changes. +Inspect public headers and related tests. State affected modules before editing. + +Authority: founding brief → architecture → scoped accepted ADRs → public +contracts → tests → implementation. Recommendations and experiments must not +silently become locked game rules. Stop expanding affected implementation if +you discover an architectural conflict; document it and propose a resolution. + +Keep the headless library independent of graphics, Steam, network, database and +Kubernetes. No gameplay, server or renderer is part of the foundation proof. +Do not add placeholder services or arbitrary third-party dependencies. +Dependencies need version/license/maintenance evidence and appropriate ADRs. + +Public API changes update docs/tests/callers together. Use CMake presets, CTest, +clang-format, clang-tidy and relevant sanitizer checks. Read README.md for exact +commands. Tests must work under NDEBUG. Do not replace a golden merely to make a +test pass; explain the simulation-version change and compatibility implications. + +Never deploy, reset or prune World0 from routine development. Never commit +secrets. Do not claim checks passed unless they actually ran; record environmental +limits in docs/engineering/VALIDATION.md. Preserve uncommitted work by others. diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..9096e0a --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,77 @@ +cmake_minimum_required(VERSION 3.28) +project(AeternalisEvolution VERSION 0.1.0 LANGUAGES CXX) + +if(CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR) + message(FATAL_ERROR "Use an out-of-source build, e.g. cmake --preset debug") +endif() +set(CMAKE_CXX_STANDARD 23) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_EXTENSIONS OFF) +set(CMAKE_EXPORT_COMPILE_COMMANDS ON) +include(CheckCXXSourceCompiles) +check_cxx_source_compiles("#include +#if !defined(__cpp_lib_expected) || __cpp_lib_expected < 202202L +#error std::expected is required +#endif +int main() { std::expected result{42}; return *result == 42 ? 0 : 1; }" + EVO_HAS_EXPECTED) +if(NOT EVO_HAS_EXPECTED) + message(FATAL_ERROR "This compiler/standard-library pair lacks the required C++23 std::expected") +endif() + +option(EVO_WARNINGS_AS_ERRORS "Treat owned-code warnings as errors" ON) +option(EVO_ENABLE_TIDY "Run clang-tidy during compilation" OFF) +option(EVO_BUILD_FUZZER "Build the Clang libFuzzer snapshot target" OFF) +set(EVO_SANITIZER "none" CACHE STRING "none, address (ASan/UBSan), or thread") +set_property(CACHE EVO_SANITIZER PROPERTY STRINGS none address thread) +include(cmake/ProjectOptions.cmake) + +set(evo_simulation_sources src/simulation/world.cpp src/simulation/snapshot.cpp) +add_library(evo_simulation STATIC ${evo_simulation_sources}) +add_library(evo::simulation ALIAS evo_simulation) +target_include_directories(evo_simulation PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") +target_compile_features(evo_simulation PUBLIC cxx_std_23) +evo_owned_target(evo_simulation) + +add_executable(evo-sim apps/evo-sim/main.cpp) +target_link_libraries(evo-sim PRIVATE evo::simulation) +evo_owned_target(evo-sim) + +include(CTest) +if(BUILD_TESTING) + add_executable(evo-tests tests/simulation_tests.cpp) + target_link_libraries(evo-tests PRIVATE evo::simulation) + evo_owned_target(evo-tests) + add_test(NAME simulation-contracts COMMAND evo-tests) + add_test(NAME test-harness-failure COMMAND evo-tests --self-test-failure) + set_tests_properties(test-harness-failure PROPERTIES WILL_FAIL TRUE) + add_test(NAME cli-replay COMMAND evo-sim --seed 123456 --ticks 1000 --entities 8 --verify-replay) + set_tests_properties(cli-replay PROPERTIES PASS_REGULAR_EXPRESSION "d61ad5bf0c928c76") + add_test(NAME cli-invalid-number COMMAND evo-sim --ticks -1) + set_tests_properties(cli-invalid-number PROPERTIES WILL_FAIL TRUE) + add_test(NAME cli-file-integration COMMAND "${CMAKE_COMMAND}" + "-DEVO_SIM=$" "-DTEST_DIR=${CMAKE_CURRENT_BINARY_DIR}/cli-integration" + -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/cli_integration.cmake") + set_tests_properties(simulation-contracts cli-replay cli-file-integration PROPERTIES TIMEOUT 60) +endif() + +add_executable(evo-benchmark tests/benchmarks/simulation_benchmark.cpp) +target_link_libraries(evo-benchmark PRIVATE evo::simulation) +evo_owned_target(evo-benchmark) + +if(EVO_BUILD_FUZZER) + if(NOT CMAKE_CXX_COMPILER_ID STREQUAL "Clang" OR MSVC OR EVO_SANITIZER STREQUAL "thread") + message(FATAL_ERROR "Fuzzing requires Linux Clang and is incompatible with TSan") + endif() + # Compile the kernel itself with coverage and sanitizer instrumentation. + add_executable(evo-snapshot-fuzz tests/fuzz/snapshot_fuzz.cpp ${evo_simulation_sources}) + target_include_directories(evo-snapshot-fuzz PRIVATE include) + evo_owned_target(evo-snapshot-fuzz) + target_compile_options(evo-snapshot-fuzz PRIVATE -fsanitize=fuzzer,address,undefined -fno-omit-frame-pointer) + target_link_options(evo-snapshot-fuzz PRIVATE -fsanitize=fuzzer,address,undefined) +endif() + +find_program(EVO_CLANG_FORMAT NAMES clang-format-19 clang-format) +add_custom_target(format-check COMMAND "${CMAKE_COMMAND}" + "-DFORMATTER=${EVO_CLANG_FORMAT}" "-DSOURCE_ROOT=${CMAKE_CURRENT_SOURCE_DIR}" + -P "${CMAKE_CURRENT_SOURCE_DIR}/tools/check-format.cmake" VERBATIM) diff --git a/CMakePresets.json b/CMakePresets.json new file mode 100644 index 0000000..5e374fd --- /dev/null +++ b/CMakePresets.json @@ -0,0 +1,26 @@ +{ + "version": 6, + "cmakeMinimumRequired": {"major": 3, "minor": 28, "patch": 0}, + "configurePresets": [ + {"name": "base", "hidden": true, "generator": "Ninja", "binaryDir": "${sourceDir}/build/${presetName}", "cacheVariables": {"BUILD_TESTING": "ON", "EVO_WARNINGS_AS_ERRORS": "ON"}}, + {"name": "debug", "inherits": "base", "cacheVariables": {"CMAKE_BUILD_TYPE": "Debug"}}, + {"name": "release", "inherits": "base", "cacheVariables": {"CMAKE_BUILD_TYPE": "Release"}}, + {"name": "analysis", "inherits": "debug", "cacheVariables": {"EVO_ENABLE_TIDY": "ON"}}, + {"name": "asan", "inherits": "debug", "cacheVariables": {"EVO_SANITIZER": "address"}}, + {"name": "tsan", "inherits": "debug", "cacheVariables": {"EVO_SANITIZER": "thread"}} + ], + "buildPresets": [ + {"name": "debug", "configurePreset": "debug"}, + {"name": "release", "configurePreset": "release"}, + {"name": "analysis", "configurePreset": "analysis"}, + {"name": "asan", "configurePreset": "asan"}, + {"name": "tsan", "configurePreset": "tsan"} + ], + "testPresets": [ + {"name": "debug", "configurePreset": "debug", "output": {"outputOnFailure": true}}, + {"name": "release", "configurePreset": "release", "output": {"outputOnFailure": true}}, + {"name": "analysis", "configurePreset": "analysis", "output": {"outputOnFailure": true}}, + {"name": "asan", "configurePreset": "asan", "output": {"outputOnFailure": true}}, + {"name": "tsan", "configurePreset": "tsan", "output": {"outputOnFailure": true}} + ] +} diff --git a/README.md b/README.md new file mode 100644 index 0000000..631304f --- /dev/null +++ b/README.md @@ -0,0 +1,85 @@ +# Aeternalis Evolution + +A custom-engine persistent evolutionary MMO. The world retains its biological +history; each player life begins as a primitive cell and ends permanently. + +This repository starts with architecture and a headless engineering proof: +deterministic synthetic particles, component lifecycle, explicit PRNG streams, +canonical snapshots and restored execution. It contains no gameplay, renderer, +network service or running Kubernetes deployment. + +## Start here + +- [Project vision and locked requirements](docs/PROJECT_VISION.md) +- [System overview and module boundaries](docs/architecture/SYSTEM_OVERVIEW.md) +- [Engineering constitution](docs/engineering/ENGINEERING_CONSTITUTION.md) +- [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) +- [Actual validation results](docs/engineering/VALIDATION.md) + +Read [AGENTS.md](AGENTS.md) before changing code. Architecture and contracts are +authoritative over implementation. No external runtime library is needed for +the initial proof. C++23 support is checked during configuration. + +## Build and run + +Requires CMake 3.28+, Ninja and a C++23 compiler/standard library supporting +`std::expected`. GCC 14 is the initial Linux CI target; MSVC 19.44 or newer is +the Windows target. Detailed verified tool versions are in the validation report. + +```sh +cmake --preset debug +cmake --build --preset debug +ctest --preset debug +./build/debug/evo-sim --seed 123456 --entities 8 --ticks 1000 --verify-replay +``` + +On Windows use a Visual Studio x64 developer shell, or the repository's +`tools/windows-check.ps1` helper. Executables have `.exe` suffix on Windows. + +```sh +./build/debug/evo-sim --seed 123456 --entities 8 --ticks 500 --save state.evo +./build/debug/evo-sim --load state.evo --ticks 500 --output results.json +``` + +The second command continues saved PRNG/component state. `--verify-replay` +compares an uninterrupted run to a midpoint serialization/restore run. JSON +reports the seed, ticks, active entities and canonical state hash. Snapshots +are bounded local test files; they are not crash-consistent production storage. + +## Checks and measurements + +```sh +cmake --build --preset debug --target format-check +cmake --preset analysis +cmake --build --preset analysis +cmake --preset asan +cmake --build --preset asan +ctest --preset asan +cmake --preset release +cmake --build --preset release +ctest --preset release +./build/release/evo-benchmark +``` + +ASan uses UBSan too on supported Linux compilers. TSan has a separate `tsan` +preset and is never combined with ASan. clang-format/tidy major 19 is the initial +analysis baseline. The optional Clang libFuzzer target exercises snapshot +restore. See [testing strategy](docs/engineering/TEST_STRATEGY.md) and +[deployment scaffold](deploy/README.md) for scope and commands. + +## Repository boundaries + +`include/evo` exposes core values and the headless simulation API. +`src/simulation` implements component state, tick ordering and local snapshot +codec. `apps/evo-sim` owns CLI/file I/O and reporting. `tests` holds contract, +fuzz and measurement programs. Future biology, world, networking and persistence +modules are documented boundaries; they are added when they have real behavior. + +World0 is persistent state. No normal configure, build, test or CI job may create, +reset, deploy to or delete it. Kubernetes and GitOps are designed here; deployment +requires actual cluster inventory, credentials, storage and backup decisions. + +The project license has not been selected. Do not infer an open-source license +from a public dependency's license. diff --git a/apps/evo-sim/main.cpp b/apps/evo-sim/main.cpp new file mode 100644 index 0000000..9f8f1b9 --- /dev/null +++ b/apps/evo-sim/main.cpp @@ -0,0 +1,276 @@ +#include "evo/simulation/world.hpp" +#include "evo/telemetry/sinks.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace { +struct Options { + std::uint64_t seed{123456}; + std::uint64_t ticks{1000}; + std::uint64_t entities{8}; + std::filesystem::path load, save, output, metrics; + bool verify_replay{}; + bool help{}; +}; + +std::expected number(std::string_view text) { + std::uint64_t value{}; + const auto [end, error] = std::from_chars(text.data(), text.data() + text.size(), value); + if (error != std::errc{} || end != text.data() + text.size()) { + return std::unexpected{evo::Error::invalid_arguments}; + } + return value; +} + +std::expected validate_paths(const Options& options) { + auto paths = std::array{options.load, options.save, options.output, options.metrics}; + for (auto& path : paths) { + if (!path.empty()) { + std::error_code error; + path = std::filesystem::weakly_canonical(path, error); + if (error) { + return std::unexpected{evo::Error::io_failure}; + } + } + } + for (std::size_t first = 0; first < paths.size(); ++first) { + for (std::size_t second = first + 1; second < paths.size(); ++second) { + if (paths[first].empty() || paths[second].empty()) { + continue; + } + if (paths[first] == paths[second]) { + return std::unexpected{evo::Error::invalid_arguments}; + } + std::error_code error; + const auto first_exists = std::filesystem::exists(paths[first], error); + if (error) { + return std::unexpected{evo::Error::io_failure}; + } + const auto second_exists = std::filesystem::exists(paths[second], error); + if (error) { + return std::unexpected{evo::Error::io_failure}; + } + if (first_exists && second_exists) { + const auto same = std::filesystem::equivalent(paths[first], paths[second], error); + if (error) { + return std::unexpected{evo::Error::io_failure}; + } + if (same) { + return std::unexpected{evo::Error::invalid_arguments}; + } + } + } + } + return {}; +} + +std::expected parse(int argc, char** argv) { + Options options; + bool initial_state_option = false; + for (int index = 1; index < argc; ++index) { + const std::string_view key{argv[index]}; + if (key == "--help") { + options.help = true; + continue; + } + if (key == "--verify-replay") { + options.verify_replay = true; + continue; + } + if (++index >= argc) { + return std::unexpected{evo::Error::invalid_arguments}; + } + const std::string_view value{argv[index]}; + if (key == "--seed" || key == "--ticks" || key == "--entities") { + const auto parsed = number(value); + if (!parsed) { + return std::unexpected{parsed.error()}; + } + if (key == "--seed") { + options.seed = *parsed; + initial_state_option = true; + } else if (key == "--entities") { + options.entities = *parsed; + initial_state_option = true; + } else { + options.ticks = *parsed; + } + } else if (key == "--load") { + options.load = value; + } else if (key == "--save") { + options.save = value; + } else if (key == "--output") { + options.output = value; + } else if (key == "--metrics") { + options.metrics = value; + } else { + return std::unexpected{evo::Error::invalid_arguments}; + } + } + if (options.entities > evo::max_entities || (!options.load.empty() && initial_state_option)) { + return std::unexpected{evo::Error::invalid_arguments}; + } + if (const auto valid = validate_paths(options); !valid) { + return std::unexpected{valid.error()}; + } + return options; +} + +std::expected initial_world(const Options& options) { + if (options.load.empty()) { + evo::SimulationWorld world{options.seed}; + for (std::uint64_t index = 0; index < options.entities; ++index) { + const auto created = world.create_entity(); + if (!created) { + return std::unexpected{created.error()}; + } + } + return world; + } + std::ifstream input{options.load, std::ios::binary | std::ios::ate}; + const auto length = input.tellg(); + if (!input || length < 0 || length > static_cast(evo::max_snapshot_bytes)) { + return std::unexpected{evo::Error::io_failure}; + } + evo::Snapshot bytes(static_cast(length)); + input.seekg(0); + if (!bytes.empty()) { + input.read(reinterpret_cast(bytes.data()), + static_cast(bytes.size())); + } + if (!input) { + return std::unexpected{evo::Error::io_failure}; + } + return evo::SimulationWorld::restore(bytes); +} + +std::expected advance(evo::SimulationWorld& world, std::uint64_t ticks) { + if (ticks > std::numeric_limits::max() - world.current_tick().value) { + return std::unexpected{evo::Error::tick_exhausted}; + } + for (std::uint64_t tick = 0; tick < ticks; ++tick) { + if (const auto result = world.tick(); !result) { + return result; + } + } + return {}; +} + +std::expected run(const Options& options) { + auto loaded = initial_world(options); + if (!loaded) { + return std::unexpected{loaded.error()}; + } + auto world = std::move(*loaded); + std::optional replay; + if (options.verify_replay) { + replay = world; + } + if (const auto result = advance(world, options.ticks); !result) { + return result; + } + if (replay) { + const auto half = options.ticks / 2; + if (const auto result = advance(*replay, half); !result) { + return result; + } + auto restored = evo::SimulationWorld::restore(replay->serialize()); + if (!restored) { + return std::unexpected{restored.error()}; + } + if (const auto result = advance(*restored, options.ticks - half); !result) { + return result; + } + if (restored->serialize() != world.serialize()) { + return std::unexpected{evo::Error::replay_mismatch}; + } + } + if (!options.save.empty()) { + const auto bytes = world.serialize(); + std::ofstream snapshot{options.save, std::ios::binary | std::ios::trunc}; + snapshot.write(reinterpret_cast(bytes.data()), + static_cast(bytes.size())); + snapshot.close(); + if (!snapshot) { + return std::unexpected{evo::Error::io_failure}; + } + } + if (!options.metrics.empty()) { + if (const auto valid = validate_paths(options); !valid) { + return valid; + } + std::ofstream metrics_file{options.metrics}; + evo::PrometheusTextSink sink{metrics_file}; + sink.observe({world.current_tick(), static_cast(world.entities().size())}); + metrics_file.close(); + if (!metrics_file) { + return std::unexpected{evo::Error::io_failure}; + } + } + std::ofstream output_file; + if (!options.output.empty()) { + if (const auto valid = validate_paths(options); !valid) { + return valid; + } + output_file.open(options.output); + if (!output_file) { + return std::unexpected{evo::Error::io_failure}; + } + } + auto& output = options.output.empty() ? std::cout : output_file; + output << "{\"rules_version\":" << evo::rules_version + << ",\"format_version\":" << evo::format_version << ",\"seed\":" << world.seed() + << ",\"ticks\":" << world.current_tick().value + << ",\"entities\":" << world.entities().size() << ",\"state_hash\":\"" << std::hex + << std::setfill('0') << std::setw(16) << world.state_hash() << std::dec + << "\",\"replay_verified\":" << (options.verify_replay ? "true" : "false") << "}\n"; + output.flush(); + if (!options.output.empty()) { + output_file.close(); + } + if (!output) { + return std::unexpected{evo::Error::io_failure}; + } + return {}; +} +} // namespace + +int main(int argc, char** argv) try { + try { + const auto options = parse(argc, argv); + if (!options) { + evo::log_error(std::cerr, options.error()); + return 2; + } + if (options->help) { + std::cout + << "evo-sim [--seed N --entities N | --load FILE] --ticks N\n" + " [--verify-replay] [--save FILE] [--output JSON] [--metrics FILE]\n" + "Synthetic proof. When loading, ticks are additional.\n"; + return 0; + } + const auto result = run(*options); + if (!result) { + evo::log_error(std::cerr, result.error()); + return 1; + } + return 0; + } catch (const std::exception&) { + evo::log_error(std::cerr, evo::Error::unhandled_exception); + return 1; + } +} catch (...) { + // Last-resort process boundary, including failure of error reporting itself. + return 1; +} diff --git a/cmake/ProjectOptions.cmake b/cmake/ProjectOptions.cmake new file mode 100644 index 0000000..f6210d0 --- /dev/null +++ b/cmake/ProjectOptions.cmake @@ -0,0 +1,54 @@ +if(NOT EVO_SANITIZER MATCHES "^(none|address|thread)$") + message(FATAL_ERROR "Unsupported EVO_SANITIZER=${EVO_SANITIZER}") +endif() +if(EVO_ENABLE_TIDY) + if(NOT CMAKE_GENERATOR MATCHES "Ninja|Makefiles") + message(FATAL_ERROR "Use Ninja or Makefiles for clang-tidy compilation") + endif() + find_program(EVO_CLANG_TIDY NAMES clang-tidy-19 clang-tidy REQUIRED) + execute_process(COMMAND "${EVO_CLANG_TIDY}" --version OUTPUT_VARIABLE tidy_version) + if(NOT tidy_version MATCHES "version 19\\.") + message(FATAL_ERROR "Analysis baseline requires clang-tidy major 19") + endif() +endif() +if(MSVC AND EVO_SANITIZER STREQUAL "address") + # MSVC runtime checks are incompatible with AddressSanitizer. + string(REPLACE "/RTC1" "" CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG}") +endif() +if(MSVC AND EVO_SANITIZER STREQUAL "thread") + message(FATAL_ERROR "MSVC does not provide TSan; use the dedicated Linux preset/job") +endif() + +function(evo_owned_target target) + if(MSVC) + target_compile_options(${target} PRIVATE /W4 /permissive- /Zc:__cplusplus /utf-8 /fp:strict) + if(EVO_WARNINGS_AS_ERRORS) + target_compile_options(${target} PRIVATE /WX) + endif() + if(EVO_SANITIZER STREQUAL "address") + target_compile_options(${target} PRIVATE /fsanitize=address) + target_link_options(${target} PRIVATE /INCREMENTAL:NO) + endif() + elseif(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang") + target_compile_options(${target} PRIVATE -Wall -Wextra -Wpedantic -Wconversion -Wshadow -fno-fast-math) + if(EVO_WARNINGS_AS_ERRORS) + target_compile_options(${target} PRIVATE -Werror) + endif() + if(EVO_SANITIZER STREQUAL "address") + target_compile_options(${target} PRIVATE -fsanitize=address,undefined -fno-omit-frame-pointer -fno-sanitize-recover=all) + target_link_options(${target} PRIVATE -fsanitize=address,undefined -fno-sanitize-recover=all) + elseif(EVO_SANITIZER STREQUAL "thread") + target_compile_options(${target} PRIVATE -fsanitize=thread -fno-omit-frame-pointer) + target_link_options(${target} PRIVATE -fsanitize=thread) + endif() + else() + message(FATAL_ERROR "Unsupported compiler; add a documented/tested toolchain") + endif() + if(EVO_ENABLE_TIDY) + set(tidy_command "${EVO_CLANG_TIDY};--warnings-as-errors=*") + if(MSVC) + list(APPEND tidy_command "--extra-arg=/EHsc") + endif() + set_property(TARGET ${target} PROPERTY CXX_CLANG_TIDY "${tidy_command}") + endif() +endfunction() diff --git a/deploy/README.md b/deploy/README.md new file mode 100644 index 0000000..061aedc --- /dev/null +++ b/deploy/README.md @@ -0,0 +1,36 @@ +# Container and delivery foundation + +M0 builds/tests evo-sim. It deploys no Kubernetes resources, publishes no image, +connects no database and supplies no persistent region server. + +```sh +docker build --file deploy/docker/Dockerfile --tag aeternalis-evo:dev . +docker run --rm --network none --read-only --cap-drop ALL \ + --security-opt no-new-privileges aeternalis-evo:dev \ + --seed 123456 --ticks 1000 --verify-replay +``` + +The GCC14 build stage runs CTest before producing the non-root UID/GID10001 runtime. +It includes the executable and system runtime libraries. Builder package versions +are recorded at /usr/share/evo/build-packages.txt. Output is stdout; file outputs +require an explicitly mounted writable destination. + +CI covers GCC14 Debug/Release, MSVC, LLVM19 format/tidy, ASan/UBSan, separate TSan, +bounded seeded libFuzzer and image build/smoke. TSan validates its configuration +on the current sequential kernel, not a future scheduler. Runtime/runner failures +must be diagnosed, never marked passing. Retain useful fuzz reproducers and add +longer campaigns when decoder complexity warrants them. + +Scaffold limits: hosted runners, Ubuntu tag and distro security packages move. +Before publishing, review/pass UBUNTU_IMAGE as an immutable digest, retain package +manifests/results, produce an SBOM, scan/sign and promote the final digest through +reviewed GitOps. The pinned checkout action also needs normal security updates. +[GCC14 package](https://packages.ubuntu.com/noble/g%2B%2B-14), +[LLVM packages](https://packages.ubuntu.com/clang), +[checkout v4.2.2 commit](https://github.com/actions/checkout/commit/11bd71901bbe5b1630ceea73d27597364c9af683). + +Harbor, Argo CD, Argo Workflows and Kubernetes follow +[infrastructure architecture](../docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md) +and [operations gates](../docs/infrastructure/OPERATIONS.md). World0 promotion is +manual; state is protected from routine cleanup. No fake endpoints/credentials or +unvalidated storage-class manifests are supplied. diff --git a/deploy/docker/Dockerfile b/deploy/docker/Dockerfile new file mode 100644 index 0000000..a2bd49a --- /dev/null +++ b/deploy/docker/Dockerfile @@ -0,0 +1,29 @@ +# Development bootstrap tag. Promotion requires an approved immutable digest. +ARG UBUNTU_IMAGE=ubuntu:24.04 +FROM ${UBUNTU_IMAGE} AS build +ENV DEBIAN_FRONTEND=noninteractive +RUN apt-get update \ + && apt-get install -y --no-install-recommends ca-certificates cmake ninja-build g++-14 \ + && rm -rf /var/lib/apt/lists/* +WORKDIR /source +COPY . . +RUN cmake --preset release -B build/container \ + -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=/opt/evo/bin \ + && cmake --build build/container --parallel 2 \ + && ctest --test-dir build/container --output-on-failure --no-tests=error --timeout 120 +RUN dpkg-query -W > /opt/evo/build-packages.txt + +FROM ${UBUNTU_IMAGE} AS runtime +ENV DEBIAN_FRONTEND=noninteractive +RUN apt-get update \ + && apt-get install -y --no-install-recommends libstdc++6 libgcc-s1 \ + && rm -rf /var/lib/apt/lists/* \ + && groupadd --gid 10001 evo \ + && useradd --uid 10001 --gid 10001 --no-create-home \ + --home-dir /nonexistent --shell /usr/sbin/nologin evo +COPY --from=build /opt/evo/bin/evo-sim /usr/local/bin/evo-sim +COPY --from=build /opt/evo/build-packages.txt /usr/share/evo/build-packages.txt +USER 10001:10001 +WORKDIR /tmp +ENTRYPOINT ["/usr/local/bin/evo-sim"] +CMD ["--seed", "123456", "--ticks", "1000"] diff --git a/docs/PROJECT_VISION.md b/docs/PROJECT_VISION.md new file mode 100644 index 0000000..8d43d44 --- /dev/null +++ b/docs/PROJECT_VISION.md @@ -0,0 +1,70 @@ +# Aeternalis Evolution + +## Purpose and first product + +The persistent protagonist is a planet's evolutionary history. Each player life +starts as a primitive cell, develops an ecological strategy, can seed autonomous +descendants, and ends permanently. The first product is a compelling persistent +cellular MMO ecosystem. Multicellularity and a modifiable three-dimensional voxel +planet follow only after that loop works. + +This document translates the founding brief; it does not supersede its locked +requirements. See [the architecture](architecture/SYSTEM_OVERVIEW.md), +[decision records](adr/README.md), and [roadmap](ROADMAP.md). + +## Locked requirements + +| Pillar | Contract | +|---|---| +| Absolute permadeath | Dead organisms never resume. A new life is a primitive cell with no account-age biological advantage. Historical knowledge may persist. | +| Persistent ancestry | Descendants are independent wildlife, survive the player's logout/death, and fail through ecological pressure. Extinct genomes remain in history. | +| Player-origin biology | A world can start with geology and chemistry but no life. Every lineage must ultimately reference a player-influenced founder. Do not silently seed prebuilt wildlife. | +| Ecological progression | No classes, mandatory intelligence endgame, linear mutation tree, or cell-to-human ladder. Mixed and unfamiliar strategies are valid. | +| Biological costs | Traits change physical/developmental parameters. Energy, matter, nutrients and environmental constraints determine consequences. | +| Offline fairness | An offline player organism cannot move, feed, reproduce, mutate, grow, or progress passively. Logout safety treatment is unresolved. NPC descendants continue independently. | +| Shared presentation | Perceivable biological state follows the same rules for NPCs and players. No arbitrary player/NPC/level/ownership labels. Friend recognition is a separate design question. | +| Scale separation | Cellular 2D and macroscopic 3D domains exchange ecology and conserved resources, not literal cross-scale collision physics. | +| Custom engine | Modern C++, no Unity or Unreal. Simulation is graphics independent. Specialized dependencies require justification. | +| Authority and durability | Clients submit intentions. Server owns outcomes. Disposable workers recover from durable state and uniquely fenced region ownership. No database writes per simulation tick. | +| Sparse world | Deterministic procedural base plus persisted changes; sparse, adaptive voxel detail. No planet-sized dense voxel allocation. | +| Delivery | Testable increments, documented decisions, explicit simulation versions, restore exercises and human promotion of World 0. No renderer in the foundation. | + +## Recommendations versus experiments + +RECOMMENDATION: one repository, one modular backend initially, independent region +worker processes, PostgreSQL metadata/durability and S3-compatible payload +storage behind adapters. Split deployments when scaling or failure isolation +requires it. Kubernetes scheduling capacity must grow with added nodes. + +EXPERIMENT: the initial proof uses a 50 ms tick quantum, integer positions in a +small periodic test domain, a bounded component store and a simple explicit +PRNG. This is an engineering fixture, not a selected game movement, physics, +ecology, world size or timing model. Its format is deliberately not World 0's +storage format. + +## Assumptions requiring validation + +- Linux x86-64 is the first dedicated-server target; Windows is a developer and + eventual client target. Actual R730xd CPU, storage, network and Kubernetes + versions have not been inspected. +- Approximately 128 GB is physical RAM, not a promised simulation budget. + Co-located storage/database failures are shared hardware failures. +- Steam distribution comes later through an identity-provider boundary. +- The founding brief is the product authority. Architectural recommendations + may be revised by ADR; gameplay questions are not silently resolved by code. + +## Principal risks and evidence needed + +| Risk | Why it threatens the vision | Mitigation / decision evidence | +|---|---|---| +| Unfun repeated cellular lives | Correct infrastructure cannot rescue the first product | Instrument controlled playtests at M11; measure session variety and causes of death | +| Ecological collapse or monopoly | One strategy could erase meaningful choices | Seeded ensemble experiments, energetic budgets, diversity and extinction histories; no automatic despawning disguised as selection | +| Resolution exploit | Entity/population conversion could manufacture resources or immortality | Conservation ledger, exclusive representation ownership, adversarial round-trip tests | +| Lost or duplicated authority | Death/reproduction could reverse or duplicate after failure | Fencing epochs, durable outcome acknowledgments, idempotent recovery and handoff fault tests | +| Upgrade changes physical laws | Persistent ecology can be destroyed by a valid software deployment | Clone, migrate, accelerate, compare, approve, then world-wide compatible upgrade | +| Morphology/animation scope | Arbitrary bodies may be computationally or artistically infeasible | Isolated later R&D with exit criteria; no dependency from cellular milestones | +| One-host loss | Kubernetes replicas do not survive a chassis failure together | Separate backup failure domain and verified restore; explicitly limited initial availability | +| AI architectural drift | Implementation can accidentally invent game rules or bypass authority | Constitution → ADR → contract → tests → code review; small independently reviewable changes | + +All 38 founding open questions are tracked in +[OPEN_QUESTIONS.md](architecture/OPEN_QUESTIONS.md), with owners and decision gates. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..843890d --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,90 @@ +# Engineering roadmap + +Initial delivery: architecture, engineering standards, toolchain scaffold and a +small deterministic state/restore proof. This is M0 plus a bounded M1 experiment; +it is not a playable game or a completed universal kernel. Validation evidence +belongs in [VALIDATION.md](engineering/VALIDATION.md). Tasks below are sized as +independent reviews; dependent tasks begin after their contracts are settled. + +## M0 — Engineering foundation + +| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk | +|---|---|---|---|---|---| +| 0.1 Preserve vision and constraints | docs/PROJECT_VISION.md, architecture/* | Founding brief | Locked vs proposed explicit; all open questions indexed | Requirement-to-document review | Silent game-rule invention | +| 0.2 Select scoped toolchain and practices | docs/adr/*, engineering/*, AGENTS.md | 0.1 | Dependency/ownership/error/determinism contracts agreed for proof | C++23 expected feature probe | Library support differs by compiler | +| 0.3 Build minimal library and CLI | CMakeLists.txt, cmake/, include/evo/, apps/evo-sim/ | 0.2 | Out-of-source configure/build on available toolchain; kernel dependency-free | Debug + Release configure/build | Accidental platform coupling | +| 0.4 Add owned-code checks | .clang-format, .clang-tidy, CMake presets | 0.3 | Format and static analysis runnable; warnings-as-errors scoped | Run format/tidy and record tool versions | Noisy analysis can cause ignored warnings | +| 0.5 Add test and measurement harness | tests/, benchmarks/, core/telemetry | 0.3 | Release-safe checks, CTest, benchmark metadata and bounded structured logs | Deliberate invalid data fails; benchmark completes | Home-grown harness grows into framework | +| 0.6 Add sanitizers and fuzz entry | CMake options, tests/fuzz/ | 0.4–0.5 | ASan/UBSan, separate TSan configs, bounded codec fuzz target | Instrumented test jobs; fuzz smoke where toolchain supports it | Platform sanitizer gaps | +| 0.7 Container and CI skeleton | deploy/docker/, .github/workflows/, tools/ | 0.3–0.6 | Build/test/analyze/container workflow; no implicit cluster deployment | Local checks; container job when daemon available | Unpinned images, CI mistaken for executed validation | +| 0.8 Close foundation increment | README.md, engineering/VALIDATION.md | 0.1–0.7 | Exact tested/untested status, commands and next task recorded | Reproduce from clean build | Claiming production readiness prematurely | + +## M1 — Universal simulation kernel + +| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk | +|---|---|---|---|---|---| +| 1.1 Implement fixed tick + PRNG proof | core/random.hpp, simulation/world.* | 0.2–0.5 | Tick count and per-entity streams explicit; no wall clock | Golden vectors, same-seed equality, different-seed divergence | Draw-order drift | +| 1.2 Implement minimal component lifecycle | simulation/world.* | 1.1, ADR-0005 | Stable IDs, bounded creation/removal, read-only views | Duplicate/stale ID, capacity and ordering tests | ID reuse or reference invalidation | +| 1.3 Canonical local snapshot and restore | simulation/snapshot.cpp, schemas/proof-snapshot.md | 1.2, ADR-0008 | Bounded versioned byte format; validate before publish | Round trip, corruption, overflow, truncation, version rejection | Unsafe parsing, native padding | +| 1.4 Freeze deterministic reference result | tests/simulation_tests.cpp | 1.3 | Continuous and restored runs match agreed fingerprint | Golden fingerprint and seeded property ensembles | Test only comparing same broken implementation | +| 1.5 Evaluate mature ECS adoption | prototype branch, ADR-0005 | 1.2, biological component workload sketch | Measured iteration/lifecycle/serialization cost and justified choice | Benchmark with representative sparse compositions | Premature general framework | +| 1.6 Establish scheduler and input phases | simulation/scheduler/, core/time/ | 1.4–1.5 | Explicit phase DAG, one writer, immutable jobs and stable merge | Reordered completion gives equal state; command ordering tests | Hidden concurrency nondeterminism | +| 1.7 Add spatial contract | simulation/spatial/, units ADR | 1.5–1.6 | Local coordinates and bounded neighborhood queries | Boundary/wrap/precision properties and brute-force comparison | Planet precision leaking into local physics | + +The first increment implements 1.1–1.4 as a proof. 1.5–1.7 remain separate work; +no scheduler or generic ECS placeholder is counted as completion. + +## M2 — Minimal energy ecosystem + +| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk | +|---|---|---|---|---|---| +| 2.1 Ratify accounting units and ledger | biology/energy, world/resources, ENERGY_MODEL | M1, units ADR | Energy/matter/nutrient units, transfer APIs, overflow/error budget explicit | Dimensional compile checks and conservation properties | Rounding creates resources | +| 2.2 Add abiotic source and producer | biology/metabolism, world/resources | 2.1 | Energy enters only through named source; uptake bounded by resources | Closed-box balance plus external source accounting | Arbitrary growth subsidies | +| 2.3 Add consumer intentions and ingestion | biology/digestion, simulation/spatial | 2.2, 1.7 | Shared validated action path transfers matter/energy | Predator/prey transfer and dead-action rejection | Consuming twice in same tick | +| 2.4 Death and decomposition | biology/lifecycle, ecology | 2.3 | Active capability ends; corpse pool transfers conserved nutrients | Death terminality, decomposition limits, ledger audit | Nutrients double counted | +| 2.5 Reproduction and wildlife identity | biology/reproduction, genome identity | 2.4, reproduction contract | Sufficient resources required; child consumes parent budget | Insufficient investment, unique ID and ancestry tests | Free offspring or implicit player ownership | +| 2.6 Long-run ecosystem fixture | apps/evo-sim, tests/ecosystem, metrics | 2.2–2.5 | Producer→consumer→death→nutrients cycle; report over million ticks | Many seeds, nonnegative balances, measured extinction/diversity | Passing invariants despite uninteresting ecology | + +M2 founder fixtures explicitly identify synthetic test-player origins; they do +not introduce unrelated wildlife into persistent worlds. Morphology is absent. + +## M3 — Genome v0.1 + +| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk | +|---|---|---|---|---|---| +| 3.1 Immutable genome schema and ancestry | biology/genome, schemas, docs/biology | M2, genome/heredity decisions | Versioned developmental capability data; immutable parent references | Canonical encoding, invalid graph and range tests | Literal-DNA scope or class tree | +| 3.2 Development pipeline | biology/development, phenotype | 3.1 | Genome + environment develops explicit physical parameters | Same input yields same phenotype; material/capability prerequisites | Genome confused with runtime damage | +| 3.3 Derive energetic components | metabolism/movement/membrane adapters | 3.2, M2 | Size/membrane/movement tradeoffs affect several budgets | Thicker structure costs matter and maintenance | RPG modifiers reintroduced | +| 3.4 Seeded mutation candidates | biology/mutation | 3.1–3.3, design decision | Bounded reproducible candidates conditioned by legitimate context | Prerequisite, cost, invalid-choice, fixed-seed tests | Hidden deterministic best build or biased adaptation | +| 3.5 Heredity/divergence history | reproduction/genome/history contract | 3.4, NPC-mutation decision | Reproduction persists parent/child links; genome identity survives death | Branching lineage fixtures and terminal organism tests | Deleting extinct genomes | +| 3.6 Genome ecology ensembles | tests/ecosystem, tools/reports | 3.5 | Compare strategies under resource/temperature gradients | Statistical distributions, conservation, diversity report | Tuning one seed overfits | + +## M4 — Population abstraction + +| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk | +|---|---|---|---|---|---| +| 4.1 Define cohort state and ownership | biology/ecology, schemas/population | M3, ECOLOGY_MODEL | Genome/lineage, counts, age, reserves, residuals and ownership explicit | Invalid cohort/negative reserve rejection | Population averages hide viable outliers | +| 4.2 Collapse active individuals | ecology/conversion | 4.1 | Transfer IDs/reserves to one aggregate representation atomically | Exact ledger conservation and crash-before/after commit tests | Dual representation | +| 4.3 Advance local cohorts | ecology/population | 4.2 | Conservative birth/death/predation/migration accounting per interval | Nonnegative counts, energy bounds, seeded ensembles | Numerical instability / false extinctions | +| 4.4 Materialize representatives | ecology/materialization | 4.3 | Withdraw exact shares and residuals; preserve genome identity | Repeated round trips, scarcity and adversarial oscillation | Re-materialization becomes free healing | +| 4.5 Validate resolution equivalence | tests/ecosystem, benchmarks | 4.4 | 100 individuals → aggregate → 10,000 ticks → representatives | Conservation exactly; ecological distributions within documented tolerance | Claiming identical trajectories at different resolution | +| 4.6 Budget and review aggregate model | docs/adr, simulation metrics | 4.5 | CPU/memory and error bounds justify tier policy | Active/aggregate benchmark and ecological sensitivity report | Premature world-scale claims | + +## Later gates + +| Milestone | Deliverable and acceptance gate | +|---|---| +| M5 Basic voxel world | Sparse small-volume generation + modifications + restore; deterministic base and bounded delta tests; mesher remains an experiment | +| M6 Environmental resources | Light/moisture/limited nutrients connected through conserved transfers; no full chemistry simulation | +| M7 Persistent region | Unique fenced authority, durable outcomes, snapshots/replay, health/metrics, process-kill recovery; migrations before real data | +| M8 Kubernetes World0 | Inventory actual host, provision dev/stage/world0 with guarded promotion and backups; delete worker pod and restore automatically; restore on independent storage verified | +| M9 Custom 2D client | ADRs for SDL3, renderer and audio; usable window/input/camera, biological presentation, no NPC labels | +| M10 Realtime multiplayer | Authenticated intentions, reliable outcomes, prediction/reconciliation/interpolation and interest; 20+ bot clients then measured scaling/fault tests | +| M11 Cellular gameplay | Movement, feeding, predation, mutation, reproduction, descendants, total restart; playtest FUN and repeated-life variety | +| M12 Persistent ecology | Days-long unattended worlds, genealogy, extinction evidence, player absence and diverse strategies; analyze collapse/runaway lineages | +| M13 3D R&D | Isolated smooth meshing, body graph, procedural skin/physics/locomotion comparisons with measured exit criteria | +| M14 Multicellular transition | Ratified biological transition and first cell→multicellular→3D slice with conserved ecological coupling | + +No date or production capacity is promised without staffing and benchmark data. +Every release records simulation/world/network versions; biological upgrades use +production snapshot → clone → migrate → accelerated comparison → approval. diff --git a/docs/adr/0001-language-toolchain.md b/docs/adr/0001-language-toolchain.md new file mode 100644 index 0000000..db6d70e --- /dev/null +++ b/docs/adr/0001-language-toolchain.md @@ -0,0 +1,34 @@ +# ADR-0001: C++23 subset and toolchain + +## Status + +Adopted for proof. GCC14/Linux is the planned CI reference; local MSVC19.44, CMake3.31.6 and LLVM19.1.5 are available. + +## Context + +Language mode does not guarantee standard-library feature support. The kernel needs portable values and explicit errors. + +## Decision + +Use C++23 without extensions and compile-probe std::expected. Exclude modules, reflection and newer experimental facilities. Verify each compiler/library pair. + +## Alternatives Considered + +C++20 plus expected polyfill adds dependency/migration work; unrestricted latest language weakens reproducibility. + +## Benefits + +Modern error/value vocabulary and explicit agent-reviewable code. + +## Costs + +Feature probes and multiple compiler lanes. + +## Risks + +Toolchain drift and compiler/library mismatch; successful builds do not prove floating-point equivalence. + +## Consequences + +Record tool versions; fail missing features clearly. Replay-test upgrades and pin release build images before promotion. Sources: [GCC conformance](https://gcc.gnu.org/projects/cxx-status.html), [MSVC conformance](https://learn.microsoft.com/en-us/cpp/overview/visual-cpp-language-conformance). + diff --git a/docs/adr/0002-build-system.md b/docs/adr/0002-build-system.md new file mode 100644 index 0000000..2e73233 --- /dev/null +++ b/docs/adr/0002-build-system.md @@ -0,0 +1,34 @@ +# ADR-0002: CMake target-oriented builds + +## Status + +Adopted for proof. + +## Context + +One kernel must build for Windows/Linux servers, CLI, tests and a later native client. + +## Decision + +CMake 3.28+, Ninja, checked-in configure/build/test presets. Target evo_simulation alias evo::simulation exports includes and C++ requirements. Scope warnings/analysis to owned targets. + +## Alternatives Considered + +Meson is concise but another ecosystem; Bazel remote execution does not yet justify machinery; platform project files duplicate contracts. + +## Benefits + +One graph, standard IDE integration and CTest. + +## Costs + +Requires disciplined target/cache management. + +## Risks + +Global flags infect dependencies; missing optional tools can falsely appear successful. + +## Consequences + +Requested analysis/sanitizers fail when unsupported. Out-of-source builds and no proof configure-time downloads. [CMake presets](https://cmake.org/cmake/help/v3.28/manual/cmake-presets.7.html). + diff --git a/docs/adr/0003-dependencies.md b/docs/adr/0003-dependencies.md new file mode 100644 index 0000000..239ba00 --- /dev/null +++ b/docs/adr/0003-dependencies.md @@ -0,0 +1,34 @@ +# ADR-0003: Dependency adoption and package management + +## Status + +Dependency-free proof adopted; vcpkg manifest proposed at first dependency gate. + +## Context + +Cross-platform reproducibility must not require assembling unrelated frameworks. + +## Decision + +Standard library only initially. Compare vcpkg exact registry baseline/overrides with Conan2 lockfiles using one compiled dependency; measure cold/warm/offline builds, binary size, transitive licenses and update workflow. + +## Alternatives Considered + +Conan provides profiles/revision locks with recipe maintenance; vcpkg fits CMake/Windows but baseline/features need care; FetchContent is not full transitive governance. + +## Benefits + +No-download proof; real workload supplies manager evidence. + +## Costs + +Measured integration gate before adoption. + +## Risks + +Mutable tags, ranges, stale caches, transitive licenses and fictitious generated APIs. + +## Consequences + +Record revision/hash, owner, license, build options and removal boundary; mirror release artifacts. No empty manifests/fake pins. [vcpkg](https://learn.microsoft.com/en-us/vcpkg/concepts/manifest-mode), [Conan](https://docs.conan.io/2/tutorial/versioning/lockfiles.html). + diff --git a/docs/adr/0004-test-benchmark-framework.md b/docs/adr/0004-test-benchmark-framework.md new file mode 100644 index 0000000..5645276 --- /dev/null +++ b/docs/adr/0004-test-benchmark-framework.md @@ -0,0 +1,34 @@ +# ADR-0004: Bounded test and benchmark harness + +## Status + +Owned CTest/chrono harness adopted for proof only; Catch2/Google Benchmark proposed before M2 expansion. + +## Context + +The small proof needs real deterministic, restore and malformed-input checks without dependency bootstrap. + +## Decision + +Release-active checks, named failures, nonzero exit, CTest and a steady-clock benchmark outside simulation. Record seed/count/ticks/compiler/build. Report shared-runner timings without pass thresholds. + +## Alternatives Considered + +Catch2 (BSL-1.0) offers expression diagnostics/fixtures; Google Benchmark (Apache-2.0) offers dedicated measurement; GoogleTest is viable without a present required advantage. + +## Benefits + +Immediate verification and a small review surface. + +## Costs + +Limited diagnostics, no shrinking/statistical measurement framework. + +## Risks + +Homemade harness becomes a maintenance project or hides failure. + +## Consequences + +Do not grow a custom DSL/mock/statistics framework. Pin/evaluate frameworks before M2. Seed ensembles are sampled invariants, not exhaustive proof. [Catch2](https://github.com/catchorg/Catch2), [Google Benchmark](https://github.com/google/benchmark). + diff --git a/docs/adr/0005-ecs-strategy.md b/docs/adr/0005-ecs-strategy.md new file mode 100644 index 0000000..5785246 --- /dev/null +++ b/docs/adr/0005-ecs-strategy.md @@ -0,0 +1,34 @@ +# ADR-0005: Component storage before a general ECS + +## Status + +Adopted for proof as bounded experiment; production ECS deferred to M1 measurements. + +## Context + +Composition is locked; taxonomy inheritance is prohibited. The proof needs identity/state, not dynamic queries. + +## Decision + +Use sorted component-composed rows with monotonic non-reused u64 IDs, capped at100,000. Public values expose no third-party handles. lower_bound lookup is O(log n); erase is O(n). + +## Alternatives Considered + +EnTT is MIT, header-only C++ with documented uses. Flecs offers C/C++, relationships, queries/scheduling under MIT. Relative workload performance is unmeasured. + +## Benefits + +Small lifecycle/replay surface, stable order, easy diagnostics. + +## Costs + +Less flexible than archetypes or independent pools; erase moves rows. + +## Risks + +Prototype grows into homemade ECS, ID exhaustion, view invalidation, structural-order drift. + +## Consequences + +Compare churn/query/memory/order/diagnostics on sparse/dense workloads before adoption. Defer structural edits to stable phases. Reject exhausted/stale IDs; generational reuse needs separate design. [EnTT](https://github.com/skypjack/entt), [Flecs](https://github.com/SanderMertens/flecs). + diff --git a/docs/adr/0006-tick-model.md b/docs/adr/0006-tick-model.md new file mode 100644 index 0000000..bfc8be7 --- /dev/null +++ b/docs/adr/0006-tick-model.md @@ -0,0 +1,34 @@ +# ADR-0006: Fixed logical ticks + +## Status + +Logical ticks adopted for proof; 50,000 microseconds is experimental. + +## Context + +Replay needs a clock independent of machine speed; accelerated simulation must not sleep. + +## Decision + +Explicit whole ticks; serialize tick/quantum. Host pacing uses bounded catch-up without increasing dt. Future ecology uses integer cadence and declared transfer boundaries. + +## Alternatives Considered + +Variable dt couples results to scheduling; one rate across every scale wastes work; physical substeps need fixed versioned schedules. + +## Benefits + +Repeatable ordering, accelerated tests and clear recovery point. + +## Costs + +Overload/input-cutoff policy and possible substeps. + +## Risks + +Catch-up loops, counter overflow, reduction order, accidental offline progression. + +## Consequences + +Reject tick overflow. Clocks and metric timing never drive biological decisions. Compare 10/20/30/60Hz at client/network gates. Rate changes require version review; no offline controlled-organism catch-up. + diff --git a/docs/adr/0007-prng.md b/docs/adr/0007-prng.md new file mode 100644 index 0000000..3062701 --- /dev/null +++ b/docs/adr/0007-prng.md @@ -0,0 +1,34 @@ +# ADR-0007: Explicit deterministic random streams + +## Status + +SplitMix64 and unbiased ternary mapping adopted for synthetic proof; production stream strategy deferred. + +## Context + +A seed is insufficient when draw order or distribution mapping is unspecified. + +## Decision + +Serialize per-entity u64 state. next adds 0x9e3779b97f4a7c15 modulo2^64; z=(z xor(z>>30))*0xbf58476d1ce4e5b9; z=(z xor(z>>27))*0x94d049bb133111eb; return z xor(z>>31). Seed each entity from next() of seed XOR (id*0xd1b54a32d192ed03 modulo2^64). For ternary, reject output zero, then modulo3: the remaining 2^64-1 outputs divide evenly into three bins. Two accepted draws per tick drive x/y; rejected draws still advance state. + +## Alternatives Considered + +PCG/xoshiro/counter-based generators have different state/stream tradeoffs. Standard engines with unspecified distributions do not define our byte contract. + +## Benefits + +Auditable algorithm, compact entity-local state, reference vectors. + +## Costs + +Explicit draw-order versioning and bounded-mapping review. + +## Risks + +Nearby seeds do not establish statistical stream independence at planetary scale. + +## Consequences + +Golden-test seed expansion/restoration/order. Later biology requires named subsystem streams and distribution evidence. Never use this RNG for authentication, secrets or anti-replay nonces. [Reference](https://prng.di.unimi.it/splitmix64.c). Initial draft's raw modulo mapping was corrected before implementation to avoid bias; the frozen fixture and kernel use rejection. + diff --git a/docs/adr/0008-serialization.md b/docs/adr/0008-serialization.md new file mode 100644 index 0000000..ecd0162 --- /dev/null +++ b/docs/adr/0008-serialization.md @@ -0,0 +1,34 @@ +# ADR-0008: Canonical proof snapshots and future codecs + +## Status + +Local proof format adopted; durable-world and network formats deferred. + +## Context + +Restore must reproduce state while bounded parsing rejects malformed/incompatible input. + +## Decision + +Explicit LE AEVOPRF0 header, u32 format/rules, u64 quantum/seed/tick/nextID, u32 count; sorted rows id/u32x/u32y/u64rng; trailing FNV1a. Validate size/count before allocation, versions/ranges/IDs before publication. Exact format in SIMULATION_ARCHITECTURE. FNV is accidental-corruption detection only. + +## Alternatives Considered + +Protobuf fits backend schemas; FlatBuffers provides direct buffer access; Cap'n Proto includes serialization/RPC machinery. All require codegen/runtime governance and measured comparison. Protobuf deterministic encoding is explicitly not canonical. + +## Benefits + +Exact portable bytes and bounded dependency-free surface. + +## Costs + +Owned codec/fuzzing with no schema-evolution tooling. + +## Risks + +Overflow/allocation amplification/omitted state/checksum confusion or accidental production use. + +## Consequences + +Semantic hash order remains explicit whichever codec is selected. Test malformed/corrupt input and restore-continuation. Production needs stronger integrity, migration manifests and authenticated transport. Never serialize padding/pointers/client structs. [Protobuf canonicality](https://protobuf.dev/programming-guides/serialization-not-canonical/), [FlatBuffers](https://github.com/google/flatbuffers), [Cap'n Proto](https://github.com/capnproto/capnproto). + diff --git a/docs/adr/0009-units-coordinates.md b/docs/adr/0009-units-coordinates.md new file mode 100644 index 0000000..7fdbe9c --- /dev/null +++ b/docs/adr/0009-units-coordinates.md @@ -0,0 +1,34 @@ +# ADR-0009: Units and spatial frames + +## Status + +Minimal proof units adopted; dimensional library and planet mapping deferred. + +## Context + +Microscopic and planetary scales cannot share unqualified float positions. + +## Decision + +Named millimetre/tick/ID values and explicit conversions. Proof domain1024mm and quantum50000us are synthetic fixtures. Target local frames right-handed +Z up, tied to stable region addresses; microdomains have separate frames/ecological coupling. + +## Alternatives Considered + +Aliases cannot distinguish quantities; mp-units provides compile-time dimensional safety under MIT; homemade units algebra duplicates specialized work. + +## Benefits + +Visible dimensions/ranges and bounded local precision. + +## Costs + +Explicit conversions and frame transforms. + +## Risks + +Wrapper proliferation, overflow, confusing proof torus with planet geometry. + +## Consequences + +Evaluate mp-units compiler support/diagnostics/compile time before biology. Specify J/kg/mol/m/s ranges and residuals. Prototype seams/poles/depth before global mapping. [mp-units](https://github.com/mpusz/mp-units). + diff --git a/docs/adr/0010-error-handling.md b/docs/adr/0010-error-handling.md new file mode 100644 index 0000000..62909bc --- /dev/null +++ b/docs/adr/0010-error-handling.md @@ -0,0 +1,34 @@ +# ADR-0010: Explicit recoverable errors + +## Status + +Adopted for proof. + +## Context + +Mixed boolean/null/exception failure conventions hide invalid state and complicate generated code review. + +## Decision + +Recoverable validation/I/O failures return nodiscard std::expected. Optional means legitimate absence. Release checks validate persisted/hostile input; internal invariants may assert. Allocation/library exceptions reach process boundaries, which stop or recover committed state. + +## Alternatives Considered + +Exceptions everywhere obscure routine flow; error out-parameters invite partial output; disabling exceptions globally conflicts with libraries. + +## Benefits + +Visible contracts, RAII and no nullable success ambiguity. + +## Costs + +Propagation and adapter translation boilerplate. + +## Risks + +Unchecked results, allocation during mutation, catching/continuing partially advanced ticks. + +## Consequences + +Validate before publication; do not promise unproven exception guarantees. Never continue authoritative state after unexpected mid-tick exceptions. Translate library conventions at adapters; test unchanged state after rejection. [expected proposal](https://wg21.link/P0323R12). + diff --git a/docs/adr/0011-thread-ownership.md b/docs/adr/0011-thread-ownership.md new file mode 100644 index 0000000..06cd0b3 --- /dev/null +++ b/docs/adr/0011-thread-ownership.md @@ -0,0 +1,34 @@ +# ADR-0011: Explicit thread ownership + +## Status + +One simulation owner adopted; parallel scheduler deferred. + +## Context + +Concurrent mutation threatens replay and authority before it improves throughput. + +## Decision + +Application owns threads; one writer per SimulationWorld. No component thread creation. Future I/O queues bounded immutable commands admitted at ordered tick boundaries; jobs read immutable inputs and merge stably. Other executors cannot mutate simulation. + +## Alternatives Considered + +Locks around arbitrary components do not define order; work stealing can exist behind deterministic commits; lock-free needs evidence. + +## Benefits + +Simple race/ordering model. + +## Costs + +Initial single-core throughput and future queue design. + +## Risks + +Unbounded queues, blocking ticks, completion nondeterminism and teardown races. + +## Consequences + +Profile first. Every executor specifies owner/bounds/overload/cancel/join/failure. No detached threads or speculative lock-free code. Separate TSan job; sequential proof does not validate future concurrency. + diff --git a/docs/adr/0012-logging.md b/docs/adr/0012-logging.md new file mode 100644 index 0000000..1d58725 --- /dev/null +++ b/docs/adr/0012-logging.md @@ -0,0 +1,34 @@ +# ADR-0012: Structured application logging + +## Status + +Small standard-library sink adopted; spdlog proposed at server sink gate. + +## Context + +Diagnostics cannot inject I/O/time into simulation. + +## Decision + +Applications emit bounded structured severity/event records. Kernel returns values/errors. Proof uses typed static event names; future external strings require escaping/redaction. Timestamps stay separate from simulation identity. + +## Alternatives Considered + +spdlog provides compiled/header-only/async sinks under MIT with fmt obligations. Standard streams suffice initially; custom async logging duplicates mature work. + +## Benefits + +Immediate diagnostics behind replaceable boundary. + +## Costs + +Limited sink management and future escaping tests. + +## Risks + +Blocking output, secret leakage, unbounded payloads and logs mistaken for durable history. + +## Consequences + +At M7 measure bounded queue/drop/flush policies, allocations, tail latency, binary size and portability before pinning spdlog. Best-effort logs never establish recovery truth. [spdlog](https://github.com/gabime/spdlog). + diff --git a/docs/adr/0013-postgresql-client.md b/docs/adr/0013-postgresql-client.md new file mode 100644 index 0000000..146c7a9 --- /dev/null +++ b/docs/adr/0013-postgresql-client.md @@ -0,0 +1,34 @@ +# ADR-0013: PostgreSQL client boundary + +## Status + +Proposed for M7; no database dependency in proof. PostgreSQL preference follows brief. + +## Context + +Persistence needs transactions, fencing, migrations and outbox; ticks must not call the database. + +## Decision + +Recommend libpqxx inside persistence adapters, I/O-executor connection ownership and typed errors. Prototype rollback, parameterized SQL, deadlines, ambiguous reconnect and bounded pools. + +## Alternatives Considered + +Direct libpq offers C ABI/async control with more RAII/result conversion. ORM introduces unneeded mapping. libpqxx adds C++ transaction ergonomics and exception translation. + +## Benefits + +Transactional concerns isolated from biology. + +## Costs + +Client/runtime deployment, pinning, pooling and integration tests. + +## Risks + +Ambiguous commit, blocked requests, injection, retry duplication and schema mismatch. + +## Consequences + +Parameterized SQL; unique constraints/idempotency for retries. Timeout does not prove rollback. Inject failure after commit before ACK. Pin supported PostgreSQL/libpqxx pair and measure throughput/size. [libpqxx BSD-3-Clause](https://github.com/jtv/libpqxx), [libpq](https://www.postgresql.org/docs/current/libpq.html). + diff --git a/docs/adr/0014-message-bus.md b/docs/adr/0014-message-bus.md new file mode 100644 index 0000000..07ec825 --- /dev/null +++ b/docs/adr/0014-message-bus.md @@ -0,0 +1,34 @@ +# ADR-0014: Evaluate NATS JetStream + +## Status + +Proposed for M7–M8 asynchronous integration; no broker in proof. + +## Context + +History/region notifications may need durable fan-out; modular backend can start with direct calls/PostgreSQL. + +## Decision + +Evaluate JetStream first. Publish committed outbox IDs; consumers deduplicate transactionally and ACK after commit. Treat delivery as at least once at application boundary. + +## Alternatives Considered + +PostgreSQL outbox polling avoids service; NATS adds buffering/fan-out; Kafka partition/operations work lacks present evidence; Core NATS alone lacks durable replay. + +## Benefits + +Independent background consumers and backpressure. + +## Costs + +Retention/disk/broker upgrades/credentials/lag operations. + +## Risks + +Duplicate/reordered events, poison records, disk exhaustion, broker-as-truth and same-host replica loss. + +## Consequences + +Test restart/replay/redelivery/retention/poison handling. Required history stays in source of truth. Broker never grants ownership; DB fencing governs writes. Adopt only for measured need. [JetStream](https://docs.nats.io/concepts/jetstream), [server](https://github.com/nats-io/nats-server), [C client](https://github.com/nats-io/nats.c). + diff --git a/docs/adr/0015-observability.md b/docs/adr/0015-observability.md new file mode 100644 index 0000000..3c713c8 --- /dev/null +++ b/docs/adr/0015-observability.md @@ -0,0 +1,34 @@ +# ADR-0015: Metrics outside authoritative state + +## Status + +Small proof boundary adopted; Prometheus/Grafana/Loki/Otel adapters proposed for M7–M8. + +## Context + +Need tick/entity/recovery evidence without observer effects on decisions. + +## Decision + +Kernel exposes deterministic values; host measures monotonic duration and exports separately. Proof text sink reports tick/entity gauges and benchmark runtime; no HTTP needed. No entity/genome/account metric labels. + +## Alternatives Considered + +prometheus-cpp (MIT) provides client APIs; Otel C++ (Apache-2.0) adds metrics/logs/traces/exporter dependencies. Tiny direct exposition needs format tests. + +## Benefits + +Replay-safe instrumentation and replaceable exporter. + +## Costs + +Host aggregation, retention and cardinality budgets. + +## Risks + +Blocking observers, high-cardinality exhaustion and wall-time/logical-time confusion. + +## Consequences + +M7 adds tick histograms, checkpoint age, fencing/recovery/queue/persistence metrics. Biology flows when implemented. Compare binary/allocations/tail latency/drop behavior/portability; no noisy timing gates. [prometheus-cpp](https://github.com/jupp0r/prometheus-cpp), [Otel C++](https://github.com/open-telemetry/opentelemetry-cpp). + diff --git a/docs/adr/0016-persistence-and-region-ownership.md b/docs/adr/0016-persistence-and-region-ownership.md new file mode 100644 index 0000000..7f1a0f2 --- /dev/null +++ b/docs/adr/0016-persistence-and-region-ownership.md @@ -0,0 +1,34 @@ +# ADR-0016: Persistence and region ownership + +## Status + +Proposed; no persistent services in M0. + +## Context + +Semantic history alone cannot recover physical state; timeout-only ownership permits stale writes. + +## Decision + +PostgreSQL fenced epochs and expected heads, immutable recovery segments, snapshots, transactional decisions/history/outbox, distinct simulated/committed ticks. Same command ID with different request digest fails. + +## Alternatives Considered + +Per-tick DB, universal scalar event sourcing, snapshots alone and broker/Redis/Kubernetes leases alone do not satisfy complete replay/fencing requirements. + +## Benefits + +Inspectable authority and idempotent irreversible biology. + +## Costs + +Commit latency, complete replay verification, gateway epoch registration and orphan GC. + +## Risks + +Incomplete recovery, stale gateway output, partitions and host disaster loss. + +## Consequences + +Fault-test every upload/commit/ACK/handoff boundary before M7. Same lease-row lock guards acquire/renew/commit/release. PostgreSQL time decides expiry; local deadlines fail conservatively. Resolve independent disaster durability before World0. [PostgreSQL locks](https://www.postgresql.org/docs/current/explicit-locking.html). + diff --git a/docs/adr/0017-network-security.md b/docs/adr/0017-network-security.md new file mode 100644 index 0000000..23737c1 --- /dev/null +++ b/docs/adr/0017-network-security.md @@ -0,0 +1,34 @@ +# ADR-0017: Network transport and security + +## Status + +Transport proposed; server authority/no custom cryptography locked. + +## Context + +Superseding state and durable decisions need distinct delivery and trust contracts. + +## Decision + +Keep application semantics transport-neutral; compare QUIC streams+DATAGRAM with DTLS-protected UDP plus mature reliability. Own replication/perception/application logic; use maintained crypto implementations. + +## Alternatives Considered + +TCP/TLS all traffic is simple but head-of-line behavior needs measurement; early Steam-specific coupling limits portability; homemade encrypted transport rejected. + +## Benefits + +Established security with perception-aware replication and independent identity provider. + +## Costs + +Reconnect/channel/window/rate/epoch tests and dependency review. + +## Risks + +Replay/parser abuse, hidden-information leakage, obsolete crypto and compromised workers. + +## Consequences + +Measure loss/latency/MTU/NAT/platforms/binary size/license/maintenance, then pin. Fuzz and adversarial tests gate multiplayer. Worker compromise requires scoped durable constraints/audit, not only client authority. [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html), [DATAGRAM](https://www.rfc-editor.org/info/rfc9221/), [DTLS1.3](https://www.rfc-editor.org/info/rfc9147/). + diff --git a/docs/adr/0018-infrastructure-services.md b/docs/adr/0018-infrastructure-services.md new file mode 100644 index 0000000..d25caae --- /dev/null +++ b/docs/adr/0018-infrastructure-services.md @@ -0,0 +1,34 @@ +# ADR-0018: Initial infrastructure services + +## Status + +Proposed; M0 deploys no services. + +## Context + +One host constrains resource/operations budgets; adding nodes must increase capacity without game redesign. + +## Decision + +Modular backend plus disposable region workers, preferred PostgreSQL, S3 adapter, conditional JetStream, no Redis initially. Separate dev/stage/world0 identities, credentials and guarded promotion. + +## Alternatives Considered + +DB outbox polling can suffice; Kafka needs demonstrated scale; distributed storage requires actual hardware/operational evidence; noun-per-service rejected. + +## Benefits + +Fewer failure modes, separable adapters and scale by workload. + +## Costs + +Explicit retention, resource budgets, restore, consumer deduplication and guard tests. + +## Risks + +Shared-host loss, logs/queue growth, stale storage ownership and accidental deletion. + +## Consequences + +Pin release digests/licenses; test restoration and limits before M8. JetStream is not DB exactly-once side effects. Official MinIO repo archived April25 2026/no longer maintained: do not adopt archived distribution by default; evaluate maintained S3 backend. [MinIO](https://github.com/minio/minio), [JetStream](https://docs.nats.io/concepts/jetstream). + diff --git a/docs/adr/0019-voxel-storage-and-meshing.md b/docs/adr/0019-voxel-storage-and-meshing.md new file mode 100644 index 0000000..30509ee --- /dev/null +++ b/docs/adr/0019-voxel-storage-and-meshing.md @@ -0,0 +1,54 @@ +# ADR-0019: Sparse voxel storage and deferred meshing + +## Status + +Proposed. Sparse procedural base plus modifications is locked; actual layout, +planet topology and mesher need experiments. No meshing dependency in M0. + +## Context + +Deep/core modification, smooth surfaces and chemistry cannot use dense whole +planet allocation or dozens of floats per voxel. Rendering cannot own inventories. + +## Decision + +Recommend versioned sparse chunk interfaces, deterministic base, persisted edits +and compaction. Separate geometry/material from optional channels; compare palette +IDs, quantized fields, uniform values, sparse pages and coarser grids. Mesh caches +key source/neighbor revisions, mesher version and LOD. M5 proves local storage; +later identical fixtures compare Marching Cubes, Surface Nets and Dual Contouring. + +## Alternatives Considered + +Dense planet and surface-only heightfields violate requirements. Uniform chunk +fields provide a baseline but waste cold data; fully adaptive per-field trees +complicate coupled updates. Sparse optional channels trade indexing for bounded +resident work. Marching Cubes is a scalar triangulation baseline with ambiguity/ +seam obligations. Surface Nets variants differ in smoothing/topology behavior. +Dual Contouring uses Hermite data/QEFs with robustness and gradient obligations. +[Marching Cubes](https://www.cs.toronto.edu/~jacobson/seminar/lorenson-and-cline-1987.pdf), +[Dual Contouring](https://people.eecs.berkeley.edu/~jrs/meshpapers/JuLosassoSchaeferWarren.pdf). + +## Benefits + +Simulation remains graphics independent; untouched territory regenerates; all +meshers share field views and fixtures. Chemistry survives visual redesign. + +## Costs + +Retain generator versions, channel metadata/residuals, halos and compaction. +Heavily modified territory still grows. Conservative mapping between grids costs. + +## Risks + +Cracks/stale collision exploits, slow compressed updates, unbounded refinement, +duplicated resources, and surface indexing that fails at the core. Paper access +does not license arbitrary implementation code. + +## Consequences + +Compare sphere, cavity, thin wall, tunnel, edits, chunk seams and mixed LOD. +Measure generation/edit/remesh p50/p95/p99, peak/resident memory, snapshot size, +topology/collision correctness and visible error. Test environmental conservation +independently. Adoption records exact version, license, maintenance, portability, +binary size and debugging complexity. A small volume proves no planet capacity. diff --git a/docs/adr/DEPENDENCY_EVALUATION.md b/docs/adr/DEPENDENCY_EVALUATION.md new file mode 100644 index 0000000..8ecd99b --- /dev/null +++ b/docs/adr/DEPENDENCY_EVALUATION.md @@ -0,0 +1,26 @@ +# Dependency evaluation + +Initial primary-source evidence is linked in ADRs. No third-party runtime library +is adopted by the proof. Recheck exact release/transitive licenses at adoption. +Maintenance statements are shortlist evidence, not measured suitability. + +| Candidate | Maintenance / portability / agent review | Performance, size and complexity hypothesis | License / disposition | +|---|---|---|---| +| CMake | Published presets/CTest; native Windows/Linux; explicit graph | Build tool, no runtime footprint | BSD-3-Clause tool; adopted | +| vcpkg / Conan2 | Documented baselines/locks; CMake+MSVC fit vs Python profiles | Measure cold/warm/offline/cache correctness | MIT tools; vcpkg proposed | +| Catch2 / Google Benchmark | Upstream fixtures/releases/build docs; explicit familiar APIs | More test compile time/size; no game runtime dependency | BSL-1.0 / Apache-2.0; gate before M2 | +| EnTT / Flecs | Production/query docs; templates vs C/C++ DSL diagnostics | Measure sparse/dense/churn/memory/build cost; no winner yet | MIT; M1 experiment | +| Protobuf / FlatBuffers / Cap'n Proto | Documented codegen/schema runtimes; generated API pins needed | Allocation vs direct access, payload size/time and codegen work | BSD-3-Clause / Apache-2.0 / MIT; deferred | +| spdlog | Maintained sink/build APIs; owned adapter | Async queues/format allocations/flush and binary cost | MIT plus fmt obligations; deferred | +| libpqxx / libpq | C++ RAII transactions vs C ownership; official DB docs | Batch throughput/latency; never tick-path I/O | BSD-3-Clause / PostgreSQL License; libpqxx proposed | +| NATS JetStream | Upstream streams/consumer docs; C-client boundary | Service RAM/disk/fan-out must justify broker | Audit server/client release licenses; proposed | +| prometheus-cpp / Otel C++ | Client vs broad SDK; upstream stability docs | Export overhead/cardinality/size/failure measurement | MIT / Apache-2.0; deferred | +| mp-units | Modern dimensional APIs; test compiler diagnostics | Compile time/binary footprint and conversion clarity | MIT; deferred | +| SplitMix64 algorithm | Author's published fixed transition; explicit state | Small constant work, 8-byte state; noncryptographic | Reference attribution in ADR0007; proof only | + +Every experiment records version/hash, compiler/OS, representative workload, +cold/warm build time, release binary size, allocations, peak/resident memory, +median/tail runtime and failure behavior. Require both supported OS/compiler +builds and sanitizers. Reject speed gains that obscure ownership/determinism, +lose maintenance support or expand security/operations beyond demonstrated value. +Neither library popularity nor a paper grants a license for the game itself. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..2409201 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,20 @@ +# Architecture decision records + +Locked requirements outrank these records. Review architecture, ADRs, public +contracts, tests, then implementation. Stop expanding implementation on conflict. + +**Adopted for proof** applies only to the bounded initial headless slice. +**Proposed** recommends without adopting a dependency. **Deferred** requires a +named experiment. Later **Accepted** and **Superseded** preserve rationale. +Proof choices do not silently settle gameplay or production infrastructure. + +Records 0001–0015 cover language, build, dependencies, tests/benchmarks, ECS, +ticks, randomness, serialization, units, errors, threads, logging, PostgreSQL, +messaging and metrics. 0016–0019 cover durability/ownership, networking/security, +infrastructure and voxels. Each record has the eight required sections. + +Every dependency adoption records exact version/commit and integrity hash, +transitive license obligations, maintenance/security review, owner and removal +boundary. Candidate performance and binary-size comparisons are hypotheses until +benchmarked. Primary sources were reviewed during the initial September 2026 +design. No unadopted candidate is a link dependency of the proof. diff --git a/docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md b/docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md new file mode 100644 index 0000000..82413dc --- /dev/null +++ b/docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md @@ -0,0 +1,104 @@ +# Infrastructure and Kubernetes topology + +Status: production-shaped proposal, not deployed workloads. Initial hardware is +one R730xd with approximately 128GB RAM. Kubernetes is available per brief; actual +CPU/storage/CNI/CSI/backup/network details remain uninspected. Replicas on one +physical host do not create an independent failure domain. + +```mermaid +flowchart TB + Registry[Harbor immutable images] --> Git[Reviewed deployment Git revision] + Git --> Argo[Argo CD environment applications] + CI[Build / tests / analysis / sanitizers] --> Registry + Workflows[Argo Workflows soak / clone / migration] --> Git + subgraph Cluster[Kubernetes cluster initially one physical node] + subgraph Dev[evolution-dev] + D[Isolated development workloads / quotas] + end + subgraph Stage[evolution-stage] + S[Cloned world / validation / quotas] + end + subgraph World[evolution-world0] + API[Modular backend and director] + R[Disposable region workers] + B[Background ecology / terrain jobs when needed] + PG[(PostgreSQL and durable volumes)] + OBJ[(S3-compatible payload storage)] + N[JetStream if adopted] + API --> PG + R --> PG + R --> OBJ + B --> PG + PG --> N + end + Obs[Prometheus / Grafana / Loki; Otel where justified] + end + PG --> Off[Independent backup/replication failure domain] + OBJ --> Off +``` + +Deploy one modular backend initially: accounts/identity adapters, history/genome +queries and director modules. Region processes scale separately for latency and +failure isolation. Background workers split only for measurable workload/lifecycle +needs. No Redis unless transient caching/session/routing measurements justify it; +no Kafka by default. Evaluate JetStream before adding a bus. + +## Scheduling, storage and security + +| Concern | Required shape | +|---|---| +| Region pods | Stateless image; memory state recovered through fenced ownership; requests/limits, bounded queues, startup/readiness/liveness probes | +| Stateful stores | Supported operator or reviewed StatefulSet strategy; persistent volumes, retention/reclaim safeguards, backup/restore tests | +| Future nodes | Labels for realtime, biosimulation, storage/database and optional GPU; affinity/taints and topology spread; no required separation that makes one-node dev unschedulable | +| Network | Default-deny namespace policies with explicit DNS/service flows; protected DB/storage/metrics; external realtime UDP exposure chosen with CNI/LB measurement | +| Identity | Dedicated service accounts; disable unnecessary token mounts; narrowly scoped RBAC and storage/DB grants | +| Pod security | Non-root, read-only rootfs, dropped capabilities, seccomp, bounded writable scratch and resource quotas | +| Secrets | External/cluster secret management chosen by operator; no plaintext repo secrets or credentials in images/logs | +| Termination | Stop admission, freeze/drain, commit recoverable state and release lease; grace budget measured; crash recovery remains necessary | + +CPU throttling can miss ticks; measure requests/limits rather than copying web +service settings. Autoscaling uses tick debt/latency and safe region moves, not +unbounded replica creation. Pod disruption budgets help planned maintenance but +cannot protect against chassis loss. Local volumes constrain scheduling; adding +compute nodes does not automatically make stateful storage portable. + +128GB is a capacity envelope, not all available simulation memory. Inventory OS/ +Kubernetes overhead, DB cache, object storage, observability, dev/stage and recovery +headroom before region budgets. Start measured namespace quotas and leave explicit +recovery/compaction headroom. No unverified entity/player-per-node promises. + +## Delivery and upgrades + +Commit → configure/build/warnings → format/tidy → unit/property/determinism/codec +checks → ASan/UBSan and separate TSan → applicable integration/ecology/load checks +→ measured benchmark report → container build/scan/SBOM/signature → Harbor digest +→ reviewed dev GitOps change → soak → staging clone/migration → manual World0 +promotion. Argo Workflows is the planned orchestrator for clone/accelerated/soak +jobs; Argo CD reconciles reviewed manifests. CI skeleton does not imply checks +or deployments already ran. + +World0 uses separate application/project permissions, disabled automatic prune/ +self-heal for destructive state transitions, retained PVCs and explicit promotion. +Routine developer jobs cannot delete namespace/data or change world versions. +World-law upgrades use a consistent world barrier, not adjacent different-rule +canaries. Keep infra/environment values separable so later repository extraction +does not require rewriting simulation. + +## Observability and adoption gates + +Prometheus/Grafana: tick histograms, worst-region debt, entities/players, bandwidth, +queues, checkpoint age, fencing/restore failures; add biomass/energy/nutrients, +birth/death/diversity metrics with biology. Loki: bounded structured logs. Otel +traces at request/I/O boundaries when useful. Avoid IDs as unbounded metric labels. +Alert on unavailable recovery paths, disk capacity/latency, missing backups, +restarts, packet loss and prolonged tick debt; test alerts through fault exercises. + +S3 is the storage API boundary; backend selection remains open. MinIO's official +repository is archived/no longer maintained, so do not assume it is an acceptable +new production default. Evaluate maintained alternatives for license, operations, +S3 semantics, durability and independent restore. [Official MinIO repository](https://github.com/minio/minio). + +Before M8: validate inventory, storage class/reclaim behavior, DNS/TLS/ingress, +Harbor/Argo integration, least privilege, resource budgets and off-host recovery. +Then kill a region pod and demonstrate automatic fenced restore. No manifests +with fabricated endpoints, secrets or storage classes are deployed in M0. diff --git a/docs/architecture/NETWORK_ARCHITECTURE.md b/docs/architecture/NETWORK_ARCHITECTURE.md new file mode 100644 index 0000000..1b51954 --- /dev/null +++ b/docs/architecture/NETWORK_ARCHITECTURE.md @@ -0,0 +1,81 @@ +# Authoritative network architecture + +Status: locked server authority and untrusted clients; transport/reliability are +proposals for M10. M0 has no networking. Steam distribution follows later through +an identity-provider adapter; core account IDs are independent of Steam IDs. + +```mermaid +flowchart LR + S[Steam identity provider] --> A[Identity adapter / backend] + C[Custom desktop client] <-->|HTTPS identity / world / history| A + A -->|short-lived region-scoped session grant| C + C -->|authenticated bounded intentions| R[Region network host] + R -->|ordered commands| W[Simulation owner] + W -->|views / outcomes| R + R -->|perceived deltas / ACKs / durable events| C +``` + +## Channel contracts + +| Channel | Information | Delivery contract | +|---|---|---| +| Realtime | Movement/orientation intentions and superseding snapshots | Prefer datagrams; sequence/drop obsolete state; bounded loss recovery | +| Reliable gameplay | Mutation choice, reproduction, death, region transfer | Idempotent action/event IDs; retry; outcome ACK after durable commit | +| Backend | Identity, world selection, friends, lineage/history/admin | HTTPS or justified gRPC; provider validation and least-privilege API scopes | + +InputFrame includes protocol/session/region epoch, sequence, intended tick, +bounded movement/orientation, action flags and validated interaction reference. +Clients cannot author position, damage, energy, resources, genome, reproduction +or death. Validate lengths, numeric ranges/non-finite values, sequence window, +target relevance, session ownership, action prerequisites, rates and expiry +before admitting bounded commands. Reject unsupported required protocol versions. +Do not deserialize directly into trusted native structs. + +Snapshot includes region/epoch, server tick, acknowledged simulated input sequence, +baseline ID, perception-filtered state and events. Recovery also exposes the +durable commit watermark. Receipt ACK means bytes accepted; simulated ACK means +input applied; final biological outcome means durable. These are not aliases. + +## Prediction and interest boundaries + +Client predicts only approved local motion using shared versioned rules. It keeps +bounded unacknowledged intentions. On authoritative snapshot, restore local state +at ACK, discard acknowledged inputs, replay remaining ones, and visually smooth +correction. Remote entities interpolate buffered snapshots with bounded +extrapolation; loss requests a fresh baseline. Death/mutation/reproduction remain +server decisions. Bound retained baselines, input buffers and packet work. + +Proposed interface: `PerceptionView(observer, tick)` → perceptible entity/field +facts; `InterestPolicy(session, view, budget)` → replication set and granularity. +Do spatial coarse filtering before biological perception. Poor vision cannot +receive hidden exact transforms; scent may expose a directional field, echolocation +a derived acoustic result. Rendering receives no arbitrary player/NPC/level labels. +Social friend identification is a separate authorized policy. Implement simple +spatial interest first; M0 does not implement sensory networking. + +## Reliability and security experiments + +Compare established authenticated datagram/reliable transports (including a +library-backed UDP security channel and QUIC options) against an owned selective +reliability layer. Measure loss/reorder/duplication, head-of-line delay, MTU/ +fragmentation, congestion, NAT routing, CPU, bandwidth and platform support. +Do not choose raw unauthenticated UDP or invent cryptography. The final protocol +ADR must name the maintained implementation, exact version, license, cipher +configuration and threat review. Custom replication/game protocol does not +require custom TLS, encryption, key exchange or random nonces. + +Use short-lived world/region/account-scoped grants, authenticated key establishment, +replay windows, rate/byte/work caps, server input scheduling windows and timeouts. +Reconnect cannot duplicate control grants. Secrets never enter logs or gameplay +snapshots. Network identities map to current ownership epoch; stale region +responses/handoff tickets fail. Administrative APIs and storage credentials are +separate from client sessions. Game workers have only region-scoped operations; +a compromised process remains a threat requiring isolation and audit, not merely +client validation. + +Required tests before M10 acceptance: fabricated/oversized/truncated packets, +NaN/overflow, replayed actions, sequence wrap/old baselines, duplicate/reordered +reliable messages, speed/mutation/resource cheats, flooded sessions, dropped ACKs, +lease/handoff races, reconnect uniqueness, sensory information leaks and bounded +queue overload. Demonstrate 20+ simulated clients, then measure higher load with +latency/loss and authoritative-state divergence reports. diff --git a/docs/architecture/OPEN_QUESTIONS.md b/docs/architecture/OPEN_QUESTIONS.md new file mode 100644 index 0000000..34c3e6a --- /dev/null +++ b/docs/architecture/OPEN_QUESTIONS.md @@ -0,0 +1,50 @@ +# Design decision register + +All recommendations below are reviewable, not silent product decisions. Owner +means the engineering/design role accountable at the gate, not an assigned +person. ADR indexes distinguish scoped proof choices from production proposals. + +| # | Open question | Current position / experiment | Owner; gate | +|---|---|---|---| +| 1 | Tick frequency | 20Hz proof only; measure latency, CPU, stiff biology | Simulation/network; before M7/M10 | +| 2 | Fixed/variable boundaries | Fixed authoritative ticks, host wall-clock pacing; ecology integer multiples | Simulation; M1 | +| 3 | ECS | Bounded component store proof; compare EnTT/Flecs realistic iteration | Engine; M1 | +| 4 | Dependency manager | Evaluate vcpkg manifest vs Conan; no runtime dependency for proof | Build; first dependency | +| 5 | Units library | Minimal explicit integer wrappers now; evaluate dimensional library before biology | Simulation; M2 | +| 6 | Determinism | Exact integer proof; physics separately scoped | Simulation; each system ADR | +| 7 | Mutation generation | Seeded context-conditioned candidates with validated prerequisites | Biology/design; M3/M11 | +| 8 | Genome representation | Immutable versioned developmental capabilities, not DNA | Biology; M3 | +| 9 | Developmental body | Typed body graph proposal | Biology/engine; M13 | +| 10 | Heredity/reproductive mutation | Preserve ancestry, define mutation budget and costs | Biology/design; M3/M11 | +| 11 | NPC mutation | Undecided; no silent autonomous divergence | Biology/design; M12 | +| 12 | Species/speciation | Derived classifications; no class mechanics | Biology/design; M12 | +| 13 | Lineage extinction | Need world-wide no-living/no-viable-reserve evidence | Ecology; M4/M12 | +| 14 | Offline state | Park without any progression; disconnect fairness unresolved | Design/security; before player persistence | +| 15 | Multicellular transition | Physiological and ecological criteria unresolved | Design/biology; M14 | +| 16 | Population abstraction | Conservative cohort ledger + distributions, ensemble validation | Ecology; M4 | +| 17 | Region dimensions | Benchmark against interest, entities and migration overhead | Engine/platform; M7 | +| 18 | Planet coordinates | Hierarchical global address + local coordinates proposal | World; M5/M13 | +| 19 | Spherical voxels | Prototype cubed sphere versus alternatives; no fixed topology yet | World; M13 | +| 20 | Voxel LOD | Sparse procedural base, aggregate fields, active chunks | World; M5/M13 | +| 21 | Surface meshing | Marching Cubes / Surface Nets / Dual Contouring comparison | Render/world; M13 | +| 22 | Hydrology | Conserved regional reservoirs/flux before full flow physics | World; M6/later R&D | +| 23 | Atmosphere | Aggregate mass and species budgets; no global CFD promise | Ecology/world; M12 | +| 24 | Cross-region ownership | Fenced leases + explicit handoff state machine | Distributed systems; M7/M10 | +| 25 | Reliability layer | Evaluate secure datagram/reliable transports before bespoke reliability | Network/security; M10 | +| 26 | Serialization | Local bounded binary proof; production schemas undecided | Engine/platform; M7/M10 | +| 27 | Snapshot/events | Snapshot + deterministic replay batches + durable semantic history | Persistence; M7 | +| 28 | Recovery | Committed contiguous replay range and unique epoch | Persistence; M7/M8 | +| 29 | Cross-version migration | Clone, migrate, accelerated comparison, approved world barrier | Simulation/platform; M7+ | +| 30 | Steam identity | Provider subject → internal account boundary | Backend/security; before Steam | +| 31 | Friend recognition | Separate social channel, no player/NPC labels | Design; M11 | +| 32 | Anti-cheat | Authoritative outcomes plus authenticated bounded intentions | Security; M10 | +| 33 | AI behavior | Shared intention interface; bounded deterministic controller | Simulation; M2/M11 | +| 34 | Evolvable behavior | Undecided; intelligence not mandatory | Biology/design; M12/R&D | +| 35 | Morphology limits | Development graph validates material, attachment and capability | Biology/design; M13 | +| 36 | Procedural animation | Isolated locomotion prototypes; no authored animation dependence | Engine; M13 | +| 37 | Retention | Permanent genome ancestry; tiered replay/snapshots/backups | Platform/design; M7/M8 | +| 38 | DR objectives | Propose measurable RPO/RTO, validate on actual storage/off-host target | Platform; before World0 | + +Additional blockers: actual host inventory, domain/TLS, registry and Git provider, +storage class/backup destination, resource budgets, project licensing and World0 +promotion approvers. None blocks a local dependency-free simulation proof. diff --git a/docs/architecture/PERSISTENCE_ARCHITECTURE.md b/docs/architecture/PERSISTENCE_ARCHITECTURE.md new file mode 100644 index 0000000..dcc5fde --- /dev/null +++ b/docs/architecture/PERSISTENCE_ARCHITECTURE.md @@ -0,0 +1,144 @@ +# Persistence and region authority + +Status: proposed production contract; source-of-truth PostgreSQL and disposable +workers follow locked requirements. M0 implements only an in-memory local proof +snapshot. It has no durable journal, database, lease or crash-consistent file writer. + +## Data ownership and recovery + +| Data | Proposed owner and retention | +|---|---| +| Accounts/provider subjects, worlds, regions | Versioned PostgreSQL relational metadata | +| Immutable genomes and ancestry/history | PostgreSQL metadata/events; never discard extinct genomes | +| Active simulation | Region worker memory, recoverable from committed checkpoint/replay | +| Snapshot/chunk payloads | Immutable S3-compatible objects, strong content digest | +| Snapshot manifests and committed replay ranges | PostgreSQL transactions; references verified objects | +| Notifications/projections | Transactional outbox; optional JetStream, idempotent consumers | +| Ephemeral routing/cache | In-process first; Redis only with measured need, never sole durable state | + +Proposed durable keys: world_id, region_id, epoch, simulation_version, +world_format_version, codec_version, generator_version, snapshot_id, tick, +covered_sequence, content_digest. Organism, genome and runtime entity identities +remain distinct. All cross-world keys include world identity. Migration SQL is +versioned when introduced at M7; do not create unused tables in M0. + +Recovery is not semantic events alone: deaths/births do not reconstruct intervening +movement, external inputs or random decisions. Persist contiguous deterministic +replay batches containing ordered admitted commands, exogenous inputs, tick range, +versions and resulting state hash. Preserve required RNG/state/checkpoint data. +Use strict append-only domain history for irreversible ancestry/lifecycle outcomes; +use snapshots plus replay for mutable region state, not event sourcing every scalar. +Batch transactions; no PostgreSQL write per simulation tick. + +```mermaid +sequenceDiagram + participant W as Worker + participant O as Object store + participant D as PostgreSQL + participant C as Client + W->>W: Simulate ordered ticks into pending batch + W->>O: Upload immutable replay payload if externalized / verify + W->>D: Fenced transaction: replay range + domain outcomes + outbox + D-->>W: Durable commit or ambiguous failure + W-->>C: Final outcome only after confirmed/reconciled commit + W->>O: Upload checkpoint bytes / verify digest + W->>D: Fenced publish manifest with covered sequence + Note over W,D: On recovery: manifest + complete replay range, verify hash before serving +``` + +Input receipt, simulated-input acknowledgment and durable gameplay acknowledgment +are distinct. Never present an uncommitted permanent death or reproductive success +as final. Acknowledged death/reproduction must reconstruct after worker loss. +Ordinary speculative movement may roll back within an explicit bounded replay +window; that window and batching latency are M7 experiments. Database failure +withholds irreversible outcomes, limits pending memory and pauses before budgets +or lease safety expire. A disconnected commit may have succeeded: reconcile its +idempotency key before retrying. + +Decision IDs store canonical request digests: retry with changed contents is +rejected. Track simulated_tick separately from committed_tick. Pending irreversible +decisions cannot enable dependent actions; pending death cannot bypass logout. +For initial M7, pause the entire region at an irreversible-outcome boundary until +commit. A future nonblocking alternative must prove deterministic isolation of +every affected interaction; freezing only a dying organism is insufficient. +CommitRegionBatch requires the current lease and expected predecessor head. +Segments identify contiguous ticks, predecessor digest, exact rules/binary/RNG +versions, resolved exchanges and required nondeterministic outputs. If initial M7 +cannot capture complete replay, evaluate full checkpoint batches explicitly rather +than claiming incomplete event replay is recovery. + +## Fenced region lease + +```mermaid +stateDiagram-v2 + Unassigned --> Acquiring: director assignment hint + Acquiring --> Recovering: transactional epoch increment / lease + Recovering --> Active: checkpoint + replay + validation complete + Active --> Draining: handoff or shutdown + Active --> Fenced: renewal failure / deadline safety margin + Draining --> Released: final committed checkpoint / release + Fenced --> Acquiring: new valid ownership acquisition +``` + +The director suggests assignment; PostgreSQL arbitrates. Proposed row: +`RegionLease(world, region, holder, epoch, expires_at)`. Acquisition locks the row, +requires release/expiry using database time, increments a never-reused epoch and +records holder/deadline. Renewal compares holder+epoch and unexpired authority. +Every durable region mutation transaction locks/checks that same lease row and +epoch; DB privileges prevent workers bypassing the guarded interface. The lock +serializes ownership acquisition against commits. A process cannot become +authoritative merely because it has a Pod identity or receives a NATS message. + +Workers fence themselves before their conservative local safety deadline; a +pause/resume cannot renew a stale epoch. Incoming commands, routing grants, +snapshots and transfer operations carry epoch/revision. Gateways/clients reject +stale-authority output under the routing/session protocol. Two processes may +hold stale routing views too: require bounded-validity authority registration +and fail-closed forwarding on uncertainty. Begin with one admission gateway per +region; partition/clock tests gate multiple gateways. Carrying an epoch alone +does not fence a gateway unaware of a newer epoch. Two processes may +retain memory, but cannot both commit authority. Recovery readiness requires +validated replay and a valid current lease; liveness is not proof of ownership. +Test long pauses, stale renewals, overlapping acquisition and delayed packets. + +## Entity handoff across regions + +1. Destination holds a valid compatible region lease and read-only ghost. +2. Source freezes the authoritative organism at a tick boundary and durably + prepares final state under a transfer ID. Ghost cannot spend/act/reproduce. +3. Destination validates and durably stages the exact transferred state. +4. One transaction checks both epochs and changes the organism ownership mapping + from source to destination, recording commit and state reference. +5. Destination activates only after observing commit and its current lease; + source tombstones its authority. Client reroutes with a fresh grant. + +Abort is a durable state transition permitted before commit; source resumes only +after observing that abort. Timeout alone does not authorize a second copy. +Retries return the recorded transfer outcome. Crash at each arrow must yield one +owner or a temporarily unavailable organism, never duplication/loss. Epochs and +the organism ownership mapping must be enforced inside persistence transactions. + +## Snapshots, migrations and retention + +Snapshots capture coherent committed state: snapshot.tick <= committed_tick with +a matching committed replay watermark. They never publish speculative outcomes. +Compression and I/O run outside the simulation writer on immutable buffers. +Upload immutable bytes, verify length/digest, then +publish metadata and replay coverage transactionally under the current fence. +Failed publication leaves an orphan, not a checkpoint. Compaction/GC retains all +objects reachable from live manifests, clones, backups and retained replay. Never +delete source replay until a verified recoverable replacement and backup exist. + +Version biology rules, world format and wire protocol independently. Unknown +required formats/rules fail closed. Upgrade: quiesce/capture consistent world +barrier → clone into isolated identity/subjects → migrate → accelerate → compare +ecological distributions and histories → explicit approval → compatible world +barrier deployment. Do not run adjacent regions under different physical laws. +Migration failure reverts code/state before new writes; downgrade after new writes +requires a designed reverse migration, not a blind database restore. + +Backup/DR is detailed in OPERATIONS. A replica on the same host does not survive +host loss. Exact guarantees for acknowledged outcomes require an explicitly +verified durable failure domain containing the complete causal recovery chain +and referenced payloads before acknowledgment; restoring an older backup cannot silently undo +permadeath. That admission/DR requirement is a World0 launch gate. diff --git a/docs/architecture/SIMULATION_ARCHITECTURE.md b/docs/architecture/SIMULATION_ARCHITECTURE.md new file mode 100644 index 0000000..c5b0bd4 --- /dev/null +++ b/docs/architecture/SIMULATION_ARCHITECTURE.md @@ -0,0 +1,109 @@ +# Simulation architecture + +## Contract and scope + +LOCKED: headless, composition-based simulation; explicit ticks and seeded +randomness; stable agreed replay; no graphics or infrastructure dependency. +RECOMMENDATION: one authoritative mutation owner per region. Systems execute in +a documented order; later jobs operate on immutable inputs and merge in stable +order. No component starts threads. + +```mermaid +flowchart TB + Planet[Tier 3: regional / planetary ecology] <-->|versioned conserved transfers| Population[Tier 2: lineage populations / distributions] + Population <-->|exclusive representation conversion| Entity[Tier 1: active individuals] + Micro[2D cellular domain] <-->|energy / nutrients / biomass ledgers| Macro[3D macroscopic domain] + Entity --> Micro + Entity --> Macro +``` + +Each represented organism belongs to exactly one active or aggregate population +record. Conversions preserve genotype identity, resource totals and residuals; +they do not manufacture newly sampled energy. Biological time advances from +world ticks. Offline player records do not participate in any progressing tier. + +## Initial proof interface + +The foundation uses **synthetic particles**, not organisms. `SimulationWorld` +stores a bounded sorted sequence of entity IDs, `Position2` components and +per-entity `Random` components. This is a minimal composition-store experiment, +not a general ECS framework. Maximum 100,000 active proof entities, monotonic +64-bit IDs with no reuse, read-only inspection by span. Mutation can invalidate +views; callers cannot hold references across mutation. Erasing an ID permanently +invalidates it. Entity exhaustion is an explicit error. + +```cpp +// Contract sketch; include/evo/simulation/world.hpp is the concrete API. +SimulationWorld world{seed}; +auto id = world.create_entity(Position2{}); // expected +auto result = world.tick(); // exactly one logical tick +auto bytes = world.serialize(); // canonical local snapshot +auto restored = SimulationWorld::restore(bytes); // expected +``` + +One proof tick is provisionally 50,000 microseconds. Every particle independently +draws two bounded values and moves -1, 0 or +1 integer millimetres per axis on a +1,024 mm periodic test domain. Movement is deliberately synthetic; no velocity, +biological energy, mutation, feeding or player input exists yet. Tick count +overflow is rejected before mutation. Entity ordering is ascending ID and RNG +state belongs to each entity, so unrelated entity removal cannot shift another +entity's random stream. + +## Determinism boundary + +Exact guarantee for proof version 1: same initial bytes or seed + entity creation +order, same API operations and tick count produce byte-identical canonical +snapshots. Integer unsigned operations are specified; no standard-library random +distributions, floating-point operations, addresses, wall clocks, hash-table +iteration or thread scheduling enter the state. Tests include algorithm golden +vectors and a frozen snapshot fingerprint, replay and mid-run recovery. + +This does **not** promise that future third-party physics will be bit-exact +across platforms. Such systems require their own versioned determinism scope, +tolerance envelopes and canonical-server target. Fast-math is forbidden in +authoritative deterministic code. Random streams for later systems will use +stable entity/system identifiers and explicit counters; changing draw order is a +simulation rules change. + +## Scheduling and pacing + +The kernel accepts no `deltaTime` argument. The executable advances an exact +requested number of ticks. A future realtime host converts monotonic wall time +into tick debt; it must cap catch-up work, emit overload metrics and shed region +load or pause under an explicit policy. It must not enlarge biological timesteps +to conceal overload. Slow ecology rates are integer multiples of base world +ticks; cross-tier transfers use committed tick intervals. + +## Snapshot proof format v1 + +All fields are encoded explicitly little endian with no padding. Header: +8-byte ASCII `AEVOPRF0`, u32 format version=1, u32 rules version=1, u64 tick +quantum in microseconds=50000, u64 world seed, u64 current tick, u64 next entity +ID, u32 entity count. Rows: u64 ID, u32 x, u32 y, u64 PRNG state. Trailer: u64 +FNV-1a of every preceding byte (offset 14695981039346656037, prime +1099511628211, wrapping u64). Header is 52 bytes; total is 60 + 24*count. + +Restore checks bounded input length/count **before allocation**, exact length, +magic, versions, tick quantum, checksum, sorted unique nonzero IDs below next ID, +and bounded coordinates. Unknown versions fail without partial state publication. +The fingerprint detects accidental damage and regressions; it is not an +authentication or security primitive. Snapshot allocation may throw at the host +boundary. There is no durable-file or crash-consistent storage claim here. + +Production storage will wrap independently versioned simulation/world/codec +identities with immutable object checksums and committed metadata; this local +format cannot be used for World 0 without a migration ADR. + +## Extension seams and failure tests + +Future commands carry tick, entity identity, sequence and validated intention; +duplicate/reordered input handling belongs to the host protocol boundary. +Biology introduces separate immutable genomes, development and phenotypes before +adding energetic systems. Entity lifecycle mutations occur at stable phase +boundaries. Metrics sinks see counters after ticks; they cannot mutate state. + +Tests must reject truncated, corrupt, oversized, unknown-version, duplicate-ID, +out-of-order and invalid-coordinate snapshots; compare continuous versus +restored execution; exercise removal, capacity and tick exhaustion; and check +that two entities' RNG streams remain independent of population order changes. +See ADRs 0005–0011 before extending this module. diff --git a/docs/architecture/SYSTEM_OVERVIEW.md b/docs/architecture/SYSTEM_OVERVIEW.md new file mode 100644 index 0000000..b5a4291 --- /dev/null +++ b/docs/architecture/SYSTEM_OVERVIEW.md @@ -0,0 +1,98 @@ +# System overview + +Status: architecture recommendation; locked product constraints are in +[PROJECT_VISION](../PROJECT_VISION.md). Only the local proof described in +[SIMULATION_ARCHITECTURE](SIMULATION_ARCHITECTURE.md) is implemented initially. + +## System context + +```mermaid +flowchart LR + Player[Player / Steam desktop client] -->|intentions| Game[Aeternalis world services] + Steam[Steam identity provider] -->|validated identity| Game + Operator[Operator] -->|approved GitOps release| Game + Game -->|perceived state / outcomes / history| Player + Game --> History[(Persistent world and phylogeny)] + Game --> Telemetry[Metrics / logs / traces] + Backups[Independent backup failure domain] <-->|verified archives / restore| History +``` + +## Component and dependency boundaries + +```mermaid +flowchart TD + Client[Custom desktop client] --> Protocol[Protocol / prediction adapter] + Region[Region process] --> Network[Transport / validation / interest] + Region --> Persist[Persistence adapter] + Region --> Sim[libevo simulation] + Sim --> Biology[Genome / development / phenotype / ecology] + Sim --> Environment[World / resources / sparse terrain interfaces] + Sim --> Core[IDs / units / ticks / PRNG] + Biology --> Core + Environment --> Core + Protocol --> Core + CLI[evo-sim / tests / benchmarks] --> Sim + Backend[Modular backend: identity / history / director] --> Persist + Persist --> Stores[PostgreSQL / object store] + Network --> Protocol +``` + +The renderer may consume phenotype and terrain views. Biology never consumes a +mesh, graphics device, network session or database connection. Public simulation +headers expose values and bounded commands, not third-party ECS/storage types. +No Steam ID, socket, Kubernetes API, logger clock or storage handle belongs in +the simulation state. Durable account references live in orchestration mapping. + +| Boundary | Owns | Must not own | +|---|---|---| +| core | Value types, deterministic algorithms, explicit version constants | Global state, threads, I/O | +| simulation (`evo_simulation`, alias `evo::simulation`) | State, stable tick ordering, component lifecycle, pure restore validation | Wall clock, transport, database or rendering | +| biology | Genotype → development → phenotype; energetic transfers | Account rewards, player/NPC subclasses | +| world | Procedural base identity, spatial/environmental fields | Dense planet allocation, gameplay authority | +| persistence | Durable metadata, snapshots, replay batches, migration | Per-tick simulation decisions | +| network | Input validation, authentication boundary, bounded codecs and relevance | Trust in client-provided positions or biology | +| backend | Identity adapters, account/world metadata, history queries, directory/lease coordination | Every noun deployed as a service | +| app / server | Tick pacing, I/O ownership, durable outcome barrier, metrics export | Alternative biological implementation | + +Only core, simulation, local snapshot codec and `evo-sim` are source modules in +the proof. Future rows are boundaries, not empty directories or dummy services. +Split a library when a real independently tested contract exists. + +## Runtime topology and data flow (target) + +```mermaid +flowchart LR + Client[Client] -->|HTTPS identity / world selection| API[Backend API] + API -->|session and routing grant| Client + Client -->|authenticated input channel| Worker[Region worker] + Director[Director] -->|assignment hint| Worker + Worker -->|fenced lease / commit| PG[(PostgreSQL)] + Worker -->|immutable snapshots| S3[(Object store)] + Worker -->|tick-boundary commands| Sim[In-memory simulation] + Sim -->|events and views| Worker + Worker -->|perception-filtered snapshots / durable outcomes| Client + PG -->|transactional outbox| Bus[Optional JetStream] + Bus -->|idempotent projections| History[History queries / ecology jobs] +``` + +Simulation reads an immutable ordered command batch at a tick boundary. It emits +state and domain outcomes. The host stages durable records and marks an outcome +committed only after the durable barrier. Projection notifications are not the +source of authority. Simulation metrics are deterministic counters; timing and +tracing are measured outside the simulation. + +## Failure containment + +- Worker crash: recover a consistent snapshot plus complete committed replay + range under a new lease epoch. Never accept an old worker's writes. +- Database unavailable: stop durable decisions and eventually pause simulation; + do not continue granting irreversible uncommitted outcomes. +- Object storage unavailable: retain/retry bounded pending snapshots; enforce + journal/storage budgets rather than silently dropping recovery data. +- Backend unavailable: availability degrades separately from existing regions, + within session and lease policies. This does not grant workers perpetual + authority. +- Shared-host outage: all initial workloads can stop. Off-host recovery is an + explicit operations requirement, not a benefit Kubernetes provides by itself. + +See persistence, network and infrastructure architecture for detailed contracts. diff --git a/docs/architecture/WORLD_ARCHITECTURE.md b/docs/architecture/WORLD_ARCHITECTURE.md new file mode 100644 index 0000000..5b8fe7a --- /dev/null +++ b/docs/architecture/WORLD_ARCHITECTURE.md @@ -0,0 +1,105 @@ +# World architecture + +Status: locked sparse, persistent, editable-world requirements; recommended +contracts below; planetary topology, resolution and solvers remain experiments. +These are future boundaries, not implemented environmental systems in M0. + +```mermaid +flowchart TD + P[Planet seed and generation version] --> C[Planetary aggregate cells] + C --> R[Regions with leased authority] + R --> M[2D microscopic habitats] + R --> V[Sparse 3D environmental chunks] + V --> F[Derived fine detail and mesh caches] + M <--> L[Conservative ecological transfer ledger] + V <--> L + B[Immutable procedural base] --> V + D[Persisted modifications and snapshots] --> V +``` + +Region, terrain-chunk and ecological-cell boundaries need not coincide. A world +mapping contract resolves them; assigning another process never changes durable +addresses. Every lineage ultimately refers to a player-influenced founder; base +generation supplies geology, chemistry and energy, never implicit wildlife. + +## Coordinates and contracts + +Recommend a planet-centered right-handed reference frame for interchange, +bounded region-local right-handed frames (+Z up) for active simulation and stable +integer chunk addresses. Persist frame transforms, resolution, origin, units and +versions. A microscopic habitat defines two metric axes and effective depth; +2D area never implicitly becomes 3D biomass. Render origin shifts do not move +authoritative state. Use coarse addresses plus local offsets, not global hot +entity floats. Final spherical indexing, radius, region/chunk sizes and precision +remain open. M5 starts with a small local test volume. + +| Logical contract | Inputs / outputs and invariant | +|---|---| +| GenerateBaseChunk | seed, generator/material versions, address → deterministic samples; no I/O clock | +| ReadEnvironment | footprint, requested fields, view → units, resolution, valid tick and error bound | +| ProposeEnvironmentalTransfer | action ID, owners, quantities → reserved inventory or insufficiency | +| CommitEnvironmentalTransfer | reservation, epoch → exactly one debit/credit; retry returns prior outcome | +| ApplyTerrainEdit | command ID, expected revision, geometry, matter destinations → new chunk revision | +| BuildSurface | immutable samples, neighbor revisions, mesher/LOD versions → disposable mesh/collision cache | + +## Representation and storage + +See ADR-0019. Evaluate palette material IDs, quantized geometry, constant uniform +channels, sparse varying field pages and coarser chemistry grids. Material tables +hold shared coefficients. Allocate only relevant changing fields. Concentration +derives from inventory/volume; temperature derives from thermal energy and heat +capacity. A material ID does not imply unlimited extractable nutrients. + +Quantization defines units, range, rounding and residuals. Refinement partitions +existing inventory; coarsening sums extensive quantities before deriving intensive +ones. Fine detail cannot contribute consumable matter without a parent budget. +Benchmarks include geometry, fields, indexes, halos, dirty journals and caches; +stress uniform, heterogeneous and heavily excavated worlds, including deep edits. + +```mermaid +sequenceDiagram + participant W as Worker + participant G as Versioned generator + participant S as Object store + participant J as Durable manifest and journal + W->>J: Read committed manifest / covered sequence + W->>S: Read verified compacted payload if present + W->>G: Otherwise generate exact recorded base version + W->>J: Read complete committed edits after covered sequence + W->>W: Replay edits and validate inventory + W->>S: Upload immutable compacted candidate and verify + W->>J: Atomically publish new manifest / covered sequence +``` + +Keep generator versions required by existing territory. Never regenerate old +chunks under new geology implicitly. Compaction records base/version/address, +revision, covered sequence and digest. Upload alone is not a commit; deletion +waits for clone/backup references and retention. Neighbor halos are read-only, +revision-tagged state. Stale mesh work is discarded. Collision revision gating +requires a later gameplay ADR; visually completed edits cannot bypass physics. + +## Ecological coupling and fidelity + +2D organisms/cohorts debit biomass through a transfer ledger to 3D plankton +density. Corpses debit organic matter to decomposition/nutrient reservoirs. +Domains do not share literal physics. Each inventory has exactly one owner; +active detail reserves a disjoint share of its aggregate. Transfers record ID, +source/destination, epochs, logical interval, composition, amount and causal event. + +Across regions, durably escrow the source before idempotent destination credit. +Recovery retries or cancels using durable transfer state; elapsed time cannot +authorize another credit. In-transit inventory remains in conservation totals. +Edits displace mass to soil, carried resources, debris/fluid or an explicit sink. +Excavation cannot simply delete matter. + +Solver intervals are explicit integer multiples of world ticks. Use committed +boundary views and apply integrated fluxes once. Catch-up is bounded and measured; +never silently drop intervals. Hydrology, atmospheric chemistry, erosion, +boundary conditions and acceptable numerical residuals remain experiments. M6 +uses light, moisture and one or two nutrients, not global CFD. + +Required tests: address round trips and seams; generator golden versions; +duplicate edit idempotency; crash at every compaction boundary; oscillating LOD +without resource gain; stale halo invalidation; stalled transfer escrow; corrupt +objects/full disk rejection. No planet topology or smooth mesher is accepted +until its comparison demonstrates precision, seam correctness and bounded cost. diff --git a/docs/biology/ECOLOGY_MODEL.md b/docs/biology/ECOLOGY_MODEL.md new file mode 100644 index 0000000..a1db968 --- /dev/null +++ b/docs/biology/ECOLOGY_MODEL.md @@ -0,0 +1,97 @@ +# Ecology and simulation fidelity + +Locked: scalable tiers and independent persistent descendants. Contracts below +are recommended; population math, lineage/species classifications are experiments. + +| Tier | Owned state | +|---|---| +| 1 active | Identified individuals, position, phenotype, reserve, lifecycle and interactions | +| 2 local | Genome/cohort, counts, demographic distributions, matter/composition/reserve | +| 3 regional | Genome/lineage density distributions, inventories and environmental coupling | + +No inventory is spendable in two tiers. Representatives are either debited cohort +shares or read-only noninteractive visuals. Never average distinct genomes into +one genome. Controlled organisms cannot collapse into progressing populations; +offline state is separate. Carry uncertainty and approximation error explicitly. + +```mermaid +flowchart LR + I[Individuals] -->|freeze / reserve| T[Conversion transaction] + T -->|commit inventory| P[Population] + P <-->|conservative allocation| E[Regional ecology] + P -->|reserve feasible share| T + T -->|install identities| I + S[Suspended inventory] --- A[World accounting] + T --> A + P --> A + I --> A +``` + +PopulationRecord proposes habitat/genome/lineage identity, representation version, +owner epoch, last simulated tick, demographic bins, count semantics, material/ +element inventory, reserve, spatial support, uncertainty and conversion sequence. +Preserve reproductive state or exclude it until conversion is valid. Expected +fractional density differs from an available individual; integer materialization +uses a seeded rule/residual and remains bounded by funded biomass/energy. + +| Contract | Invariant | +|---|---| +| PlanCollapse | Reject controlled/suspended/dead/unsettled members; group compatible states and total exact inventory | +| CommitCollapse | Remove active spending rights and install cohort once under current epoch | +| AdvancePopulation | Bounded flux proposals over a declared interval and environment view | +| PlanMaterialize | Reserve feasible count, composition, reserve and demographics | +| CommitMaterialize | Debit cohort/install active identities while retaining provenance | +| TransferPopulation | Source escrow, idempotent destination credit and durable settlement | + +Prefer local deterministic transactions. At a tick boundary freeze the old +representation, reserve under conversion ID/epoch, validate conservation and +destination, commit source removal/destination installation recoverably, then +expose. Recovery replays the committed sample, never samples again. A timeout +cannot release remote reservations. Cross-worker bus delivery is not exactly-once +authority. Count escrow in global totals. + +Keep IDs in initial fixtures. Later statistical representation needs an ADR for +retained individuals versus cohort representatives; never invent precise parentage +from statistical ancestry. Adversarial conversion cannot select only healthy/high +energy members or reset age/injury/fertility/incubation. Unsupported states stay +explicit until a valid conversion exists. + +## Population math and timing experiments + +`N_next = N + births - deaths + immigration - emigration`. + +`B_next = B + assimilated_growth + immigrant_biomass - mortality_biomass - +predation_biomass - emigrant_biomass`. + +Births redistribute funded investment, not independently created biomass. +Predation changes counts and transfers biomass once; death returns detritus. +Compare bounded flux, seeded stochastic cohort and deterministic expected-density +models. Reject/subdivide unstable intervals; never hide negative populations with +clamps. Operational capacity limits backpressure rather than ecologically cull. +Shared bounded perception/intention controllers are the initial AI proposal; +evolving behavior/learning and universal species definitions remain open. + +Advance whole declared intervals and record last committed tick. One owner +integrates each interval; late transfers are not new production. Expose catch-up +backlog/freshness. Whole-world outage wall-time catch-up is an explicit later +policy, while offline controlled biology remains frozen either way. Exact seeded +repeatability does not imply exact fidelity to individual ecology: compare matched +ensembles and publish population/biomass/diversity error envelopes. + +## Extinction and acceptance + +Distinguish no active observation, ecological absence and terminal extinction. +Require a globally reconciled watermark covering active individuals, cohorts, +eggs/spores, in-flight transfers and every viable store. Suspended members make +absence differ from recoverable viability: extinction stays provisional until +policy acceptance. Rounding a density to zero cannot declare irreversible +extinction. Preserve genome/ancestry/origin/extinction evidence permanently; +census series may be summarized at declared resolution. Clones have isolated +IDs/event destinations and cannot publish into World0. + +M4: collapse 100 funded compatible individuals, simulate 10,000 ticks, materialize +feasible representatives. Test conservation including flux/residual/escrow, genome +identity, deterministic replay, crashes at every conversion boundary, interval +uniqueness, mixed-genome diversity, repeated conversion attacks, extreme rates, +late migrations/censuses and suspended viability. Compare explicit individuals: +passing conservation alone is insufficient ecological evidence. diff --git a/docs/biology/ENERGY_MODEL.md b/docs/biology/ENERGY_MODEL.md new file mode 100644 index 0000000..7e4abd9 --- /dev/null +++ b/docs/biology/ENERGY_MODEL.md @@ -0,0 +1,88 @@ +# Energy and matter accounting + +Locked: explicit biological costs and conservation. Ledger structure is +recommended; coefficients/solvers are experiments, not claims of biochemical +accuracy. M0 particles do not implement this model. + +| Quantity | Convention | +|---|---| +| Usable/source/work/heat energy | J inventories; W reported rates; explicit fixed-point quantum if adopted | +| Material | kg or scaled mass; validated element composition | +| Elements/nutrients | kg of specified element; mol requires explicit identity and conversion | +| Temperature | K; intensive state, not conserved inventory | +| Population | Nonnegative integer individuals or separately typed expected count | + +Material and its element composition are two views of the same matter, not +additive inventories. Conserve an explicit 'other' component if the chemical +basis is simplified. Reserve and structural chemical energy must not double +count ingestible energy. Work may immediately become heat in a simplified model; +it then cannot also remain available as mechanical energy. + +For each closed accounting interval: + +`E_end = E_start + external_input - exported_energy - unmodeled_heat_loss`. + +If heat is modeled, include its reservoir in E_end instead of that loss term. +For every element k: `M_end[k] = M_start[k] + imported[k] - exported[k]`. +Totals include environment, organisms, eggs/spores/cohorts, corpses, transfer +escrow and suspended organisms. Death/reproduction/conversion are transfers. +Atmospheric release is a transfer when atmosphere is modeled, otherwise an +explicit boundary export. Light/geothermal flux is finite per area/interval; +chemosynthesis consumes finite potential or recorded geological replenishment. + +`reserve_next = reserve + assimilation + capture - maintenance - locomotion - +construction - reproduction - exported_reserve`. + +Every term has a counterpart. Unmet costs trigger the defined starvation policy, +never a negative reserve or implicit loan. Overflow/excess follows named outputs. + +```mermaid +sequenceDiagram + participant B as Biology + participant L as Tick ledger + participant R as Inventory owners + B->>L: Propose(action ID, debits, credits, costs) + L->>L: Validate dimensions, composition, bounds and phase + L->>R: Reserve balances in stable order + alt Sufficient resources + L->>R: Commit balanced transfer exactly once + L-->>B: Outcome and phenotype/lifecycle changes + else Insufficient or stale + L-->>B: Reject or explicitly quantified partial consumption + end +``` + +The ledger is an in-process deterministic buffer, not a remote service or +database write per transfer. Initial canonical entity/action allocation order +introduces priority bias: measure against fair-share alternatives before tuning. +Randomized fairness requires a purpose-specific recorded stream. Costs and +outputs commit together; retries cannot double-spend. Partial ingestion is a +declared quantity, not partially published offspring. + +Checked integer arithmetic carries division residuals. Floating-point solvers +require finite checks, fixed reduction order and declared absolute/relative error +budgets. Never conceal failed conservation by clamping balances. A density field +is a view of owned finite inventory; consumers contend for that inventory. + +| Process | Debit → credit / limitation | +|---|---| +| Capture | finite flux + substrate → reserve/production + loss; area/efficiency bound | +| Feeding | prey/resource matter + reserve → assimilation + waste + heat; ingestion bound | +| Maintenance/movement | reserve → work/heat; phenotype demand and fixed interval | +| Growth | material + reserve → structure + heat; developmental plan | +| Reproduction | funded parent/environment inventory → offspring investment + heat | +| Death | live compartments → corpse/detritus exactly once | +| Decomposition | detritus + reactants → nutrients/chemical outputs/heat; rate/reactant bound | + +M2 uses explicitly synthetic founder fixtures, not unrelated wildlife in a +persistent world. A simplified decomposition basis must balance completely; +scalar biomass-to-nutrients is not full elemental chemistry. Expose source +inputs, inventory/sink totals, unmet maintenance, failed transfers and per-element +residuals. Distinguish cumulative quantities/rates; IDs are not metric labels. + +Tests: closed-box conservation, finite-source exhaustion, predation with waste, +starvation nonnegativity, reproduction rollback, exactly-once death/decomposition, +competing consumers, long-run rounding, overflow/NaN rejection, cross-tier escrow +and independently recomputed seeded totals. Baseline metabolism, efficiencies, +light attenuation, stoichiometry, heat fidelity and starvation rules remain open. +Conservation alone does not guarantee a stable or enjoyable ecosystem. diff --git a/docs/biology/GENOME_MODEL.md b/docs/biology/GENOME_MODEL.md new file mode 100644 index 0000000..041c4fa --- /dev/null +++ b/docs/biology/GENOME_MODEL.md @@ -0,0 +1,78 @@ +# Genome, development and phenotype + +Status: locked separation and evolutionary intent; recommended schema; mutation +and morphology are experiments. No biology is implemented in the M0 proof. + +```mermaid +flowchart LR + G[Immutable developmental genome] --> D[Versioned development] + E[Environment / resources / growth history] --> D + D --> P[Phenotype revision] + P --> C[Physical and biological components] + C --> S[Simulation] + S --> H[Reproduction / survival / history] +``` + +Genomes encode evolvable developmental capabilities, not literal DNA or an +Animal/Plant/Fungus inheritance hierarchy. Classification is derived. Capability +is distinct from realized structure: permitted armor still requires material and +energy. Reconstructible phenotype caches require retained developmental inputs, +including growth and damage history. Fitness is an outcome, not a power score. + +| Proposed genome field | Invariant | +|---|---| +| genome_id | Immutable world-scoped identity, distinct from runtime entity ID | +| schema and development-rule versions | Explicit interpretation and migration boundaries | +| parents | Zero only for documented founder; one initially; possible multiple parents later | +| origin_event_id | Explains founder, mutation or reproduction origin | +| capabilities and parameters | Canonical typed records with units, ranges and prerequisites | +| content_digest | Integrity/deduplication aid; never merges distinct historical origins | + +Founder admission is a world event with inventory debited from a documented +environmental or external genesis budget. Genome v0.1 covers energy conversion, +membrane, movement, ingestion, reproduction, target size and tolerances only. + +| Contract | Required behavior | +|---|---| +| ValidateGenome | Reject unknown required capability, invalid range/dependency and cyclic development | +| PlanDevelopment | Return bounded construction plan and resource requirements from genome/growth/environment | +| ApplyDevelopment | Reserve resources; commit phenotype revision and matching transfers, or make no change | +| DerivePhenotype | Produce dimensioned mass, geometry, maintenance and enabled component descriptions | +| GenerateMutationCandidates | Genome + bounded recorded context + explicit stream/version → canonical candidates | +| SelectMutation | Revalidate candidate, organism/genome revision and current context before immutable successor | + +A displayed candidate does not reserve resources. Changed context must reject or +revalidate; never silently substitute a different mutation. Thicker membrane first +changes thickness/composition; development derives construction mass, +permeability/protection, movement and thermal consequences. Omitted physics is a +documented model limitation, not an unrelated percentage modifier. + +## Candidate-generation experiment + +Propose a constrained catalog of mutation operators over capability/parameter +records. Filter by prerequisites, sort stable operator IDs, then sample bounded +integer weights from recorded genome/context. This is an internal rule catalog, +not a visible linear progression tree. Environment-conditioned offerings are a +game-design proposal, not a claim that biological mutation anticipates needs. + +Record seed, organism, eligible event index, context digest, rules and stream ID. +Unrelated entity additions cannot change candidates. No wall clock, std::hash or +implementation-defined distribution enters sampling. Store bounded context +statistics; retries cannot obtain free rerolls. Candidate count, context window, +costs, inherited/acquired expression, NPC mutation and recombination remain open +before M3 mutation acceptance. No implementation silently settles these rules. + +## Later morphology and history + +Evaluate typed body graphs with tissue/segment/organ nodes and distinct attachment, +joint, vascular, neural and developmental edges. Independent consumers derive +meshes, collisions, mass, maintenance and locomotion. Validate work/graph bounds, +structural connectivity and resource feasibility. Development dependencies are +acyclic or explicitly bounded; vascular cycles can be valid. Mesh validity alone +does not prove biological viability. Intelligence remains one costly strategy. + +Keep extinct genomes and ancestry indefinitely. Rule migrations preserve original +records/provenance and are tested on cloned worlds. Unknown required capabilities +fail closed. Tests cover canonical round trips, prerequisites, resource-limited +development, deterministic candidates, stream independence, retry stability, +bounded graph expansion, ancestry-preserving migration and material tradeoffs. diff --git a/docs/biology/REPRODUCTION_MODEL.md b/docs/biology/REPRODUCTION_MODEL.md new file mode 100644 index 0000000..98940fc --- /dev/null +++ b/docs/biology/REPRODUCTION_MODEL.md @@ -0,0 +1,80 @@ +# Reproduction, life ownership and permadeath + +Locked: irreversible death, independent descendants and no offline progression. +Strategy/heredity/logout fairness are proposals requiring explicit acceptance +before gameplay. Separate account, controlled organism, genome and lineage IDs. +Historical creator references grant neither wildlife ownership nor visual labels. + +```mermaid +flowchart TD + A[Account] -->|current control grant| P[Living organism] + A --> H[History without biological bonuses] + P -->|funded reproduction| D[Independent wildlife descendants] + P -->|permanent death| X[Historical dead organism] + X --> H + A -->|new life| N[Primitive founder] +``` + +No resurrection, retained power, checkpoint or special corpse-retrieval mechanic. +Corpse biomass follows ordinary ecology, not an account recovery entitlement. + +## Reproduction and death contracts + +Proposed intention: `Reproduce(action_id, parent_id, expected_revision, strategy, +candidate_id?)`. Server resolves life/control state, prerequisites, costs, +environment, offspring allocation and genomic change. Client supplies no +authoritative child genome/count/cost. Parent costs, ancestry/genome records, +offspring inventory/allocation and event form one recoverable logical operation. +Durable acknowledgment requires recoverability; duplicate IDs return prior outcome. + +Binary fission proposes one autonomous descendant, with parent continuity/control +and splitting still open. Eggs/live birth use bounded young or cohorts with +explicit investment/gestation/mortality. Broadcast/spores use funded statistical +cohorts; theoretical fecundity never requests unbounded AI allocation. Capacity +backpressures, rejects or aggregates; it cannot grant free offspring or silently +delete committed lineages. NPC mutation/heredity/juvenile viability remain open. + +Alive→Dead is terminal for the organism ID. Remove actions before later phases; +transfer inventory to corpse/detritus exactly once. Proposed ordering resolves +lethal damage/maintenance before reproduction; changing this needs a decision and +fixtures. Descendants receive no arbitrary mortality modifier because a player +died: inherited demands/tolerances interact with ecology independently. + +Committed death must survive snapshot replay before recovered state is exposed. +Unavailable durability withholds final outcome acknowledgment and quarantines +pending irreversible changes. A new life follows the same primitive founder rule +for every account, with initial matter/energy provenance. No growth/reserve or +capability bonus transfers from history. + +## Offline experiment: suspended inventory + +Propose durable suspension outside progressing tiers. Freeze position reference, +genome, age/growth, energy/matter, disease, gestation and every biological timer. +Inventory stays in global accounting but cannot interact. Wildlife continues. + +```mermaid +stateDiagram-v2 + Active --> SuspendPending: logout or detected disconnect / freeze + SuspendPending --> Suspended: durable ownership transfer + Suspended --> Active: validated unique resume grant + Active --> Dead: committed death + SuspendPending --> Dead: lethal outcome determined before freeze +``` + +SuspendPending already has no biological advancement at the authoritative freeze +boundary. Servers can react only to detectable disconnects; heartbeat/detection +bounds need a logout ADR. Clients cannot backdate freeze time. Resume performs no +elapsed-time biology and first replays committed death. Changed habitat, blocked +spawn, duplicate login and danger need a policy without free travel/duplication. + +Suspension may evade predation or hoard biomass. A combat delay that advances +offline biology violates the brief. Evaluate in-session eligibility/admission +restrictions without progressing suspended organisms. Indefinite retention and +matter disposition also remain open; no proposal is shipped as a settled rule. + +Tests: dead IDs never act/resume; death/corpse exactly once; reproduction balanced +and atomic despite insufficient nutrients with abundant energy; retries stable; +descendants independent of parent death/logout; arbitrarily long suspension +preserves every timer; same-tick death/reproduction ordering; huge spore requests; +all suspend/resume crash points; changed habitat; unique control grants and +death committed after snapshot. Extinction includes suspended viability. diff --git a/docs/engineering/ENGINEERING_CONSTITUTION.md b/docs/engineering/ENGINEERING_CONSTITUTION.md new file mode 100644 index 0000000..fb78c4e --- /dev/null +++ b/docs/engineering/ENGINEERING_CONSTITUTION.md @@ -0,0 +1,39 @@ +# Engineering constitution + +Authority: founding requirements → architecture → accepted/scoped ADRs → public +contracts → tests → implementation. A failing test never justifies changing a +locked requirement. Document a conflict and stop expanding affected code until +the contract is resolved. Proposed ADRs are not permission to ship a final game +rule. Every PR names its affected modules and decision scope. + +| Topic | Rule | +|---|---| +| Language | C++23 subset, standard library `std::expected`; configure must verify support. No modules, reflection, unsupported library facilities or compiler extensions in public contracts. GCC 14 Linux CI target; MSVC 19.44+ Windows target; verify actual versions in validation report. | +| Build | Target-based CMake ≥3.28, out-of-source builds and checked-in presets. `evo::simulation` must compile without graphics, networking, database or Kubernetes. | +| Naming | Namespace `evo`; types `PascalCase`; functions/variables/files `snake_case`; private fields trailing `_`; constants `snake_case`. No deep biological inheritance. | +| Formatting | clang-format configuration is authoritative; pin formatter major in CI. Avoid hand-format debates. Headers self-contained; `#pragma once`; explicit includes. | +| Dependencies | Default none for the proof. New dependencies require purpose, pinned revision, license/security review, reproducible acquisition and an ADR when architectural. No unreviewed network fetch at configure time. Keep third-party warning policy separate. | +| Ownership | Values by default; RAII; `unique_ptr` for exclusive heap ownership. `shared_ptr` only with documented shared lifetime. Pointers/references/spans are non-owning; state lifetime/invalidation. No paired raw allocation/free. | +| Threading | A host owns threads. One writer owns simulation state. Workers receive immutable work and return deterministically merged results. No hidden threads, detached work or speculative lock-free structures. | +| Exceptions | Recoverable invalid commands/data return `expected`. Optional means legitimate absence, not hidden errors. Allocation/standard-library exceptions propagate to process boundaries, which log and exit/recover; never catch-and-continue a partially mutated tick. No exception-driven game flow. | +| Errors | Typed error enum now; later structured contextual error at adapters. Do not mix boolean failure/null/exception for the same contract. Check nodiscard returns. Partial construction must not publish invalid state. | +| Logging | Structured bounded records at app/I/O boundaries, UTC/monotonic timing there only. No secrets, raw session tickets or unbounded payloads. Deterministic kernel returns counters/errors; it never reads a clock or writes stdout. | +| Assertions | Internal programming invariants may assert; hostile or persisted input must use runtime validation in release builds. Tests never rely on `assert`, which disappears under NDEBUG. | +| Serialization | Explicit fields, endianness, length bounds, versions, canonical order. Never memcpy native object layouts onto disk/wire; no trust in a client struct. Validate before allocation and publication. | +| Coordinates | Proof: integer millimetres, periodic 2D local domain. Target: documented region-local right-handed coordinates, +Z up and stable global hierarchical address; spherical mapping is an open ADR. No absolute planet floats in hot entity state. | +| Units | Named unit wrappers; conversions explicit. Later quantities require dimensional interfaces (J, kg, mol, m, s) and documented fixed-point ranges or error budgets. Do not mistake toy integer movement for a physics decision. | +| Randomness | Explicit serialized PRNG state/seed. No `rand`, `random_device`, ambient generator or implementation-defined distributions in the kernel. Noncryptographic RNG never authenticates sessions. | +| Time | Integer tick identity; fixed quantum experiment 50ms. No wall-clock reads, variable dt or implicit offline progression in the kernel. Tick-rate change requires simulation-version review. | +| Floating point | Proof uses integer state. Future systems specify exact/tolerant/nondeterministic boundaries; no fast-math in authoritative code. Reject non-finite external values. Stable reductions and measured error budgets. | +| API stability | Internal versioned source contracts, no stable binary ABI promise yet. Public change updates architecture, tests and callers together. Do not expose future third-party ECS/client/codec types through kernel APIs. | +| Tests | Unit, deterministic golden, property-style seed ensembles, restore/codec validation and CLI integration now. Fuzz/sanitizer jobs and benchmarks provided. Add network/load/recovery/ecology gates when those contracts exist; do not pretend empty tests validate them. | +| Analysis | Owned code: strong warnings, CI warnings-as-errors, clang-tidy, format check. ASan+UBSan Linux together; TSan separately. Instrument libraries and executables. Never combine ASan and TSan. | +| Performance | Measure before optimizing; benchmark seed, entity count, ticks, compiler/build and hardware. Wall-time thresholds require a controlled runner. CI portable benchmarks report rather than gate noisy timing. | +| Documentation | State implemented versus planned. ADRs include context, decision, alternatives, benefits, costs, risks, consequences and status. Link evidence for dependency claims. Keep roadmap status and actual verification honest. | +| Security | Server authority, bounded parsing, least privilege, reviewed cryptographic protocols, redacted logs. No custom cryptography; no administrative credentials in game processes. No World0 deployment/destruction from a routine build. | + +Before code: read relevant docs and ADRs, inspect public interfaces and tests, +state modules touched. Small increments must build and test. No placeholder +libraries, speculative services or invented gameplay to fill directory trees. +Repository licensing is a maintainer decision; do not apply an open-source +license to this game by assumption. diff --git a/docs/engineering/TEST_STRATEGY.md b/docs/engineering/TEST_STRATEGY.md new file mode 100644 index 0000000..4de4029 --- /dev/null +++ b/docs/engineering/TEST_STRATEGY.md @@ -0,0 +1,35 @@ +# Validation strategy + +Tests defend contracts, not directory coverage. All checks remain active in +Release builds. Current proof has no actual network, biology or distributed +recovery, so those categories below are milestone gates rather than passing +test labels attached to empty targets. + +| Category | Foundation evidence | Future gate | +|---|---|---| +| Unit | PRNG reference vectors, entity lifecycle, capacity/error boundaries | Genome development and energetic transfer rules | +| Deterministic regression | Frozen canonical fingerprint plus independent reference calculation; uninterrupted vs restored execution | Versioned ecosystem baseline ensembles | +| Property-style | Many explicit seeds and tick split points; coordinate and ID invariants | Conservation, nonnegative mass/population and phenotype prerequisites | +| Serialization | Exact byte round-trip, malformed lengths/versions/checksum/IDs/coordinates; validate before publication | Compatible migrations, verified object archive and replay range | +| Integration | CLI seed/ticks and replay verification; file save/load comparison | Durable death/reproduction acknowledgment and worker process kill | +| Fuzz | Optional libFuzzer snapshot decoder with bounded input and sanitizer instrumentation | Authenticated protocol/parser and migration fuzzing | +| Static/sanitizers | clang-format/tidy; ASan/UBSan and separate TSan configurations | TSan on real scheduler and I/O lifecycle | +| Benchmark/load | Seed/count/tick/time/compiler report for kernel; no noisy portable time threshold | 20+ clients, region load, interest bandwidth, recovery backlog | +| Biological regression | Absent until M2; do not call synthetic particles an ecosystem | Million-tick balances, predator/prey cycles, starvation, diversity and extinction | +| Disaster recovery | Absent until persistent services exist | Off-host verified backup restore; database/object consistency; old owner fencing | + +Reference fixture, rules/format 1: seed 123456, create 8 particles at (0,0), then +1,000 ticks yields canonical payload FNV-1a `d61ad5bf0c928c76`. Expected positions +by ID: (49,10), (985,993), (39,33), (1008,0), (16,1), (7,3), (1004,1007), +(995,15). The initial value was computed independently in JavaScript with +explicit wrapping BigInt arithmetic, not copied from the C++ test result. +SplitMix64 seed-zero vectors begin `e220a8397b1dcdaf`, `6e789e6aa1b965f4`, +`06c45d188009454f`, `f88bb8a8724c81ec`. + +Changing a golden requires a stated rule/format change, compatibility decision, +independent review and updated documentation. A new compiler or optimization +mode must reproduce existing integer fixtures. Floating-point biology later +needs error envelopes and ensemble comparisons in addition to exact fixtures. + +Unexecuted configurations are not validation. Record exact tools, commands, +results and limitations in VALIDATION.md at the end of each foundation change. diff --git a/docs/infrastructure/OPERATIONS.md b/docs/infrastructure/OPERATIONS.md new file mode 100644 index 0000000..b46e239 --- /dev/null +++ b/docs/infrastructure/OPERATIONS.md @@ -0,0 +1,69 @@ +# Operations and disaster recovery + +Status: proposal requiring measured acceptance before World0. No deployment, +backup or distributed restore has been exercised in this foundation. + +| Failure | Proposed objective / gate | +|---|---| +| Worker lost, stores healthy | Zero lost committed decisions; fixture ready within 60 seconds | +| Uncommitted motion | Experiment with at most one second rollback; stop admission before backlog exceeds budget | +| Corrupt/missing state | Fail readiness; restore verified chain or quarantine, never initialize an empty replacement | +| Host destruction | RTO experiment 24 hours once independent storage/hardware exists; RPO gate below | + +Targets are not observed results. One host cannot promise availability or zero +data loss after its destruction. A proposed 15-minute backup RPO for mutable +world state cannot guarantee every acknowledged death/birth/ancestry record. +Permanent lifecycle/history requires an independent durable copy of the complete +causal recovery chain and referenced payloads before ACK for +host-loss RPO0. That replication/acknowledgment contract and its latency are a +World0 launch gate. Overlaying isolated lifecycle records on older resource state +can duplicate biomass or lose offspring. Restoring an older world must not +resurrect organisms or erase history; if the required causal state cannot be +reconciled, keep the world unavailable. + +## Backup and clone protocol + +Back up PostgreSQL base data plus continuous WAL. Preserve every immutable object +referenced by each recovery point. A database backup without those objects is not +a world backup. Manifest fields: world identity, simulation/generator/world/codec +versions, DB recovery target, region watermarks, object inventory/strong digests, +and binaries/container artifacts needed for replay. Encrypt off-host copies, +separate credentials and test recovery-key access. +[PostgreSQL continuous archiving](https://www.postgresql.org/docs/17/continuous-archiving.html). + +Retention experiment: 30 daily, 12 weekly, 12 monthly verified manifests plus +pre-upgrade checkpoints, subject to capacity evidence. Genome/ancestry/lifecycle +history does not expire with backup retention. GC respects all clone/backup pins +and complete replay chains. + +1. First implementation uses a coordinated admission/transfer barrier, avoiding + an unfinished distributed-snapshot algorithm. +2. Commit region boundaries; seal DB recovery point, referenced objects, ongoing + transfer state, region watermarks and versions into the manifest. +3. Verify/copy objects, restore isolated PostgreSQL at the compatible point. +4. Assign isolated world/runtime identities while preserving source provenance; + replace credentials, buckets and subjects; disable production integrations. +5. Replay and verify unique ownership, conservation, terminal deaths, ancestry + and hashes before readiness. Measure duration and missing-object behavior. +6. Record actual restore evidence. Upload success or a scheduled job is not a + restore test; alerts and recovery credentials must also work. + +Actual recovery fences old database/cluster writers before routing cutover and +prevents the old environment returning as competing authority. Resolve ambiguous +commits by command ID/request digest; timeout is not rollback. Retain old +simulation binaries and generators needed by historical state. + +## World0 protection and drills + +Separate Argo permissions/environment credentials; Retain reclaim policy where +supported; protected PVC and namespace/data deletion via RBAC/admission. Test +pruning and parent-app deletion separately. One prune flag is not a full safeguard. +[Kubernetes volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/), +[Argo sync options](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/). + +CI has no World0 data credentials. Cleanup requires exact dev/clone identity and +rejects World0. Drill worker termination in clones first: upload failure, +commit-before-ACK crash, stale owner resume, missing object, disk full, broker +redelivery and each handoff stage. Verify one owner, no duplicated outcomes, +permanent history and measured recovery. Never substitute namespace deletion for +a worker recovery test. diff --git a/include/evo/core/random.hpp b/include/evo/core/random.hpp new file mode 100644 index 0000000..f6f9edd --- /dev/null +++ b/include/evo/core/random.hpp @@ -0,0 +1,33 @@ +#pragma once + +#include + +namespace evo { +// SplitMix64; explicit unsigned wraparound. Reference and scope: ADR-0007. +// This algorithm is never a security primitive. +class Random { + public: + explicit constexpr Random(std::uint64_t state) noexcept : state_{state} {} + [[nodiscard]] constexpr std::uint64_t next() noexcept { + state_ += 0x9e3779b97f4a7c15ULL; + auto value = state_; + value = (value ^ (value >> 30U)) * 0xbf58476d1ce4e5b9ULL; + value = (value ^ (value >> 27U)) * 0x94d049bb133111ebULL; + return value ^ (value >> 31U); + } + // The 2^64-1 accepted outputs divide equally among three bins. + [[nodiscard]] constexpr std::uint32_t ternary() noexcept { + auto value = next(); + while (value == 0) { + value = next(); + } + return static_cast(value % 3U); + } + [[nodiscard]] constexpr std::uint64_t state() const noexcept { + return state_; + } + + private: + std::uint64_t state_; +}; +} // namespace evo diff --git a/include/evo/core/types.hpp b/include/evo/core/types.hpp new file mode 100644 index 0000000..481eb3a --- /dev/null +++ b/include/evo/core/types.hpp @@ -0,0 +1,67 @@ +#pragma once + +#include +#include +#include + +namespace evo { +struct EntityId { + std::uint64_t value{}; + auto operator<=>(const EntityId&) const = default; +}; +struct Millimetres { + std::uint32_t value{}; + auto operator<=>(const Millimetres&) const = default; +}; +struct Tick { + std::uint64_t value{}; + auto operator<=>(const Tick&) const = default; +}; +struct Position2 { + Millimetres x{}; + Millimetres y{}; + auto operator<=>(const Position2&) const = default; +}; + +enum class Error : std::uint8_t { + invalid_position, + entity_limit, + id_exhausted, + entity_not_found, + tick_exhausted, + invalid_snapshot, + unsupported_version, + invalid_arguments, + io_failure, + replay_mismatch, + unhandled_exception +}; + +[[nodiscard]] constexpr std::string_view error_name(Error error) noexcept { + switch (error) { + case Error::invalid_position: + return "invalid_position"; + case Error::entity_limit: + return "entity_limit"; + case Error::id_exhausted: + return "id_exhausted"; + case Error::entity_not_found: + return "entity_not_found"; + case Error::tick_exhausted: + return "tick_exhausted"; + case Error::invalid_snapshot: + return "invalid_snapshot"; + case Error::unsupported_version: + return "unsupported_version"; + case Error::invalid_arguments: + return "invalid_arguments"; + case Error::io_failure: + return "io_failure"; + case Error::replay_mismatch: + return "replay_mismatch"; + case Error::unhandled_exception: + return "unhandled_exception"; + } + return "unknown_error"; +} +} // namespace evo diff --git a/include/evo/simulation/world.hpp b/include/evo/simulation/world.hpp new file mode 100644 index 0000000..90b6a1e --- /dev/null +++ b/include/evo/simulation/world.hpp @@ -0,0 +1,54 @@ +#pragma once + +#include "evo/core/random.hpp" +#include "evo/core/types.hpp" + +#include +#include +#include +#include +#include + +namespace evo { +inline constexpr std::uint32_t format_version = 1; +inline constexpr std::uint32_t rules_version = 1; +inline constexpr std::uint64_t tick_quantum_us = 50'000; +inline constexpr std::uint32_t domain_extent_mm = 1'024; +inline constexpr std::uint32_t max_entities = 100'000; +inline constexpr std::size_t max_snapshot_bytes = 60 + 24 * max_entities; + +struct EntityState { + EntityId id; + Position2 position; + Random random; +}; +using Snapshot = std::vector; + +class SimulationWorld { + public: + explicit SimulationWorld(std::uint64_t seed) noexcept : seed_{seed} {} + [[nodiscard]] std::expected create_entity(Position2 position = {}); + [[nodiscard]] std::expected remove_entity(EntityId id); + [[nodiscard]] std::expected tick() noexcept; + // Non-owning inspection; mutation can invalidate views and references. + [[nodiscard]] std::span entities() const noexcept { + return entities_; + } + [[nodiscard]] Tick current_tick() const noexcept { + return tick_; + } + [[nodiscard]] std::uint64_t seed() const noexcept { + return seed_; + } + [[nodiscard]] Snapshot serialize() const; + [[nodiscard]] std::uint64_t state_hash() const; + [[nodiscard]] static std::expected + restore(std::span bytes); + + private: + std::uint64_t seed_; + Tick tick_{}; + std::uint64_t next_id_{1}; + std::vector entities_; +}; +} // namespace evo diff --git a/include/evo/telemetry/sinks.hpp b/include/evo/telemetry/sinks.hpp new file mode 100644 index 0000000..c1f3c30 --- /dev/null +++ b/include/evo/telemetry/sinks.hpp @@ -0,0 +1,35 @@ +#pragma once + +#include "evo/core/types.hpp" + +#include +#include + +namespace evo { +struct SimulationMetrics { + Tick tick; + std::uint64_t active_entities; +}; +// Host-owned observers; no kernel calls to I/O, exporters or clocks. +class MetricsSink { + public: + virtual ~MetricsSink() = default; + virtual void observe(SimulationMetrics metrics) = 0; +}; +class PrometheusTextSink final : public MetricsSink { + public: + explicit PrometheusTextSink(std::ostream& output) : output_{output} {} + void observe(SimulationMetrics metrics) override { + output_ << "# TYPE evo_simulation_tick gauge\nevo_simulation_tick " << metrics.tick.value + << "\n# TYPE evo_active_entities gauge\nevo_active_entities " + << metrics.active_entities << '\n'; + } + + private: + std::ostream& output_; +}; +// Typed static names keep these records bounded without arbitrary-string escaping. +inline void log_error(std::ostream& output, Error error) { + output << "{\"level\":\"error\",\"event\":\"" << error_name(error) << "\"}\n"; +} +} // namespace evo diff --git a/schemas/proof-snapshot.md b/schemas/proof-snapshot.md new file mode 100644 index 0000000..b585112 --- /dev/null +++ b/schemas/proof-snapshot.md @@ -0,0 +1,10 @@ +# Local proof snapshot + +The byte-level contract is in +[SIMULATION_ARCHITECTURE.md](../docs/architecture/SIMULATION_ARCHITECTURE.md). +Its concrete encoder/decoder is `src/simulation/snapshot.cpp`. + +Scope: local deterministic regression fixture only, format 1 / rules 1. +Not a network protocol, authenticated archive, event journal, production world +format or a durable storage implementation. A future format must preserve or +explicitly migrate supported historical versions; unknown versions fail closed. diff --git a/src/simulation/snapshot.cpp b/src/simulation/snapshot.cpp new file mode 100644 index 0000000..428504a --- /dev/null +++ b/src/simulation/snapshot.cpp @@ -0,0 +1,117 @@ +#include "evo/simulation/world.hpp" + +#include +#include + +namespace evo { +namespace { +constexpr std::array magic{'A', 'E', 'V', 'O', 'P', 'R', 'F', '0'}; +constexpr std::size_t header_size = 52; +constexpr std::size_t row_size = 24; +constexpr std::size_t checksum_size = 8; + +std::uint64_t checksum(std::span bytes) noexcept { + std::uint64_t hash = 14695981039346656037ULL; + for (const auto byte : bytes) { + hash = (hash ^ byte) * 1099511628211ULL; + } + return hash; +} +void append(Snapshot& bytes, std::uint64_t value, std::size_t width) { + for (std::size_t index = 0; index < width; ++index) { + bytes.push_back(static_cast(value & 0xffU)); + value >>= 8U; + } +} +// Private reader: callers validate the whole fixed header or bounded row region +// before reading. Widths below are constants, not input-controlled values. +class Reader { + public: + explicit Reader(std::span bytes) noexcept : bytes_{bytes} {} + std::uint64_t read(std::size_t width) noexcept { + std::uint64_t value{}; + for (std::size_t index = 0; index < width; ++index) { + value |= static_cast(bytes_[offset_++]) << (8U * index); + } + return value; + } + + private: + std::span bytes_; + std::size_t offset_{}; +}; +} // namespace + +Snapshot SimulationWorld::serialize() const { + Snapshot bytes; + bytes.reserve(header_size + row_size * entities_.size() + checksum_size); + bytes.insert(bytes.end(), magic.begin(), magic.end()); + append(bytes, format_version, 4); + append(bytes, rules_version, 4); + append(bytes, tick_quantum_us, 8); + append(bytes, seed_, 8); + append(bytes, tick_.value, 8); + append(bytes, next_id_, 8); + append(bytes, entities_.size(), 4); + for (const auto& entity : entities_) { + append(bytes, entity.id.value, 8); + append(bytes, entity.position.x.value, 4); + append(bytes, entity.position.y.value, 4); + append(bytes, entity.random.state(), 8); + } + append(bytes, checksum(bytes), checksum_size); + return bytes; +} +std::uint64_t SimulationWorld::state_hash() const { + const auto bytes = serialize(); + return checksum(std::span{bytes}.first(bytes.size() - checksum_size)); +} + +std::expected +SimulationWorld::restore(std::span bytes) { + if (bytes.size() < header_size + checksum_size || bytes.size() > max_snapshot_bytes || + !std::ranges::equal(bytes.first(magic.size()), magic)) { + return std::unexpected{Error::invalid_snapshot}; + } + Reader header{bytes.subspan(magic.size())}; + const auto format = header.read(4); + const auto rules = header.read(4); + if (format != format_version || rules != rules_version || header.read(8) != tick_quantum_us) { + return std::unexpected{Error::unsupported_version}; + } + const auto seed = header.read(8); + const auto tick = header.read(8); + const auto next_id = header.read(8); + const auto count = header.read(4); + if (count > max_entities || next_id == 0 || + bytes.size() != header_size + row_size * count + checksum_size) { + return std::unexpected{Error::invalid_snapshot}; + } + Reader trailer{bytes.last(checksum_size)}; + if (trailer.read(8) != checksum(bytes.first(bytes.size() - checksum_size))) { + return std::unexpected{Error::invalid_snapshot}; + } + SimulationWorld restored{seed}; + restored.tick_ = Tick{tick}; + restored.next_id_ = next_id; + restored.entities_.reserve(static_cast(count)); + Reader rows{bytes.subspan(header_size, static_cast(row_size * count))}; + std::uint64_t previous_id{}; + for (std::uint64_t index = 0; index < count; ++index) { + const auto id = rows.read(8); + const auto x = rows.read(4); + const auto y = rows.read(4); + const auto random_state = rows.read(8); + if (id <= previous_id || id >= next_id || x >= domain_extent_mm || y >= domain_extent_mm) { + return std::unexpected{Error::invalid_snapshot}; + } + restored.entities_.push_back( + EntityState{EntityId{id}, + Position2{Millimetres{static_cast(x)}, + Millimetres{static_cast(y)}}, + Random{random_state}}); + previous_id = id; + } + return restored; +} +} // namespace evo diff --git a/src/simulation/world.cpp b/src/simulation/world.cpp new file mode 100644 index 0000000..bd09481 --- /dev/null +++ b/src/simulation/world.cpp @@ -0,0 +1,47 @@ +#include "evo/simulation/world.hpp" + +#include +#include + +namespace evo { +std::expected SimulationWorld::create_entity(Position2 position) { + if (position.x.value >= domain_extent_mm || position.y.value >= domain_extent_mm) { + return std::unexpected{Error::invalid_position}; + } + if (entities_.size() >= max_entities) { + return std::unexpected{Error::entity_limit}; + } + if (next_id_ == std::numeric_limits::max()) { + return std::unexpected{Error::id_exhausted}; + } + const EntityId id{next_id_}; + Random derivation{seed_ ^ (id.value * 0xd1b54a32d192ed03ULL)}; + entities_.push_back(EntityState{id, position, Random{derivation.next()}}); + ++next_id_; // Publish only after successful allocation/construction. + return id; +} + +std::expected SimulationWorld::remove_entity(EntityId id) { + const auto found = std::ranges::lower_bound(entities_, id, {}, &EntityState::id); + if (found == entities_.end() || found->id != id) { + return std::unexpected{Error::entity_not_found}; + } + entities_.erase(found); + return {}; +} + +std::expected SimulationWorld::tick() noexcept { + if (tick_.value == std::numeric_limits::max()) { + return std::unexpected{Error::tick_exhausted}; + } + for (auto& entity : entities_) { + auto& position = entity.position; + position.x.value = + (position.x.value + entity.random.ternary() + domain_extent_mm - 1U) % domain_extent_mm; + position.y.value = + (position.y.value + entity.random.ternary() + domain_extent_mm - 1U) % domain_extent_mm; + } + ++tick_.value; + return {}; +} +} // namespace evo diff --git a/tests/benchmarks/simulation_benchmark.cpp b/tests/benchmarks/simulation_benchmark.cpp new file mode 100644 index 0000000..0909666 --- /dev/null +++ b/tests/benchmarks/simulation_benchmark.cpp @@ -0,0 +1,53 @@ +#include "evo/simulation/world.hpp" + +#include +#include +#include + +int main() try { + try { + constexpr std::uint64_t seed = 123456; + constexpr std::uint32_t count = 10'000; + constexpr std::uint64_t ticks = 1'000; + evo::SimulationWorld world{seed}; + for (std::uint32_t index = 0; index < count; ++index) { + if (!world.create_entity()) { + return 1; + } + } + const auto start = std::chrono::steady_clock::now(); + for (std::uint64_t tick = 0; tick < ticks; ++tick) { + if (!world.tick()) { + return 1; + } + } + const auto elapsed = + std::chrono::duration(std::chrono::steady_clock::now() - start); + std::cout << "{\"benchmark\":\"synthetic_tick\",\"seed\":" << seed + << ",\"entities\":" << count << ",\"ticks\":" << ticks + << ",\"seconds\":" << elapsed.count() << ",\"state_hash\":\"" << std::hex + << world.state_hash() << "\",\"compiler\":\"" +#if defined(__clang__) + << "Clang " << __clang_version__ +#elif defined(_MSC_VER) + << "MSVC " << _MSC_VER +#elif defined(__GNUC__) + << "GCC " << __VERSION__ +#else + << "unknown" +#endif + << "\",\"build\":\"" +#if defined(NDEBUG) + << "release" +#else + << "debug" +#endif + << "\"}\n"; + return 0; + } catch (const std::exception& error) { + std::cerr << error.what() << '\n'; + return 1; + } +} catch (...) { + return 1; +} diff --git a/tests/cli_integration.cmake b/tests/cli_integration.cmake new file mode 100644 index 0000000..1490a03 --- /dev/null +++ b/tests/cli_integration.cmake @@ -0,0 +1,62 @@ +if(NOT DEFINED EVO_SIM OR NOT DEFINED TEST_DIR) + message(FATAL_ERROR "EVO_SIM and TEST_DIR are required") +endif() +# Fresh build-local files each run; no recursive deletion or source-tree writes. +string(RANDOM LENGTH 16 ALPHABET 0123456789abcdef run_id) +set(run_dir "${TEST_DIR}/${run_id}") +file(MAKE_DIRECTORY "${run_dir}") + +function(expect_success) + execute_process(COMMAND "${EVO_SIM}" ${ARGN} + RESULT_VARIABLE result OUTPUT_VARIABLE output ERROR_VARIABLE error) + if(NOT result EQUAL 0) + message(FATAL_ERROR "CLI failed (${result}): ${error}") + endif() +endfunction() +function(expect_failure) + execute_process(COMMAND "${EVO_SIM}" ${ARGN} + RESULT_VARIABLE result OUTPUT_VARIABLE output ERROR_VARIABLE error) + if(NOT result MATCHES "^[1-9][0-9]*$") + message(FATAL_ERROR "Expected normal nonzero CLI exit, got ${result}: ${output} ${error}") + endif() +endfunction() + +expect_success(--seed 123456 --entities 8 --ticks 500 --save "${run_dir}/half.evo") +expect_success(--load "${run_dir}/half.evo" --ticks 500 --save "${run_dir}/resumed.evo" + --output "${run_dir}/report.json" --metrics "${run_dir}/metrics.prom") +expect_success(--seed 123456 --entities 8 --ticks 1000 --verify-replay + --save "${run_dir}/full.evo") +file(SHA256 "${run_dir}/resumed.evo" resumed_digest) +file(SHA256 "${run_dir}/full.evo" full_digest) +if(NOT resumed_digest STREQUAL full_digest) + message(FATAL_ERROR "CLI continuation differs from uninterrupted simulation") +endif() +file(READ "${run_dir}/report.json" report) +string(JSON state_hash GET "${report}" state_hash) +string(JSON tick GET "${report}" ticks) +if(NOT state_hash STREQUAL "d61ad5bf0c928c76" OR NOT tick EQUAL 1000) + message(FATAL_ERROR "CLI report does not match independent frozen fixture") +endif() +file(READ "${run_dir}/metrics.prom" metrics) +if(NOT metrics MATCHES "evo_active_entities 8" OR NOT metrics MATCHES "evo_simulation_tick 1000") + message(FATAL_ERROR "Missing or wrong metrics") +endif() + +file(WRITE "${run_dir}/sentinel" "preserve this file") +execute_process(COMMAND "${CMAKE_COMMAND}" -E create_hardlink + "${run_dir}/sentinel" "${run_dir}/alias" RESULT_VARIABLE linked) +if(NOT linked EQUAL 0) + message(FATAL_ERROR "Hard-link regression fixture could not be created") +endif() +expect_failure(--ticks 0 --save "${run_dir}/sentinel" --output "${run_dir}/alias") +expect_failure(--load "${run_dir}/sentinel" --output "${run_dir}/alias") +file(READ "${run_dir}/sentinel" preserved) +if(NOT preserved STREQUAL "preserve this file") + message(FATAL_ERROR "CLI overwrote an aliased input/output") +endif() +expect_failure(--load "${run_dir}/half.evo" --seed 123) +expect_failure(--entities 100001) +expect_failure(--ticks 18446744073709551616) +expect_failure(--unknown value) +expect_failure(--load "${run_dir}/missing") +expect_success(--entities 0 --ticks 2 --verify-replay) diff --git a/tests/fuzz/snapshot_fuzz.cpp b/tests/fuzz/snapshot_fuzz.cpp new file mode 100644 index 0000000..fb5b4b7 --- /dev/null +++ b/tests/fuzz/snapshot_fuzz.cpp @@ -0,0 +1,29 @@ +#include "evo/simulation/world.hpp" + +#include +#include +#include +#include +#include + +extern "C" int LLVMFuzzerTestOneInput(const std::uint8_t* data, std::size_t size) { + if (size > evo::max_snapshot_bytes) { + return 0; + } + const auto input = std::span{data, size}; + auto restored = evo::SimulationWorld::restore(input); + if (restored) { + const auto canonical = restored->serialize(); + if (!std::equal(canonical.begin(), canonical.end(), input.begin(), input.end())) { + std::abort(); + } + const auto ticked = restored->tick(); + if (!ticked && ticked.error() != evo::Error::tick_exhausted) { + std::abort(); + } + if (!evo::SimulationWorld::restore(restored->serialize())) { + std::abort(); + } + } + return 0; +} diff --git a/tests/simulation_tests.cpp b/tests/simulation_tests.cpp new file mode 100644 index 0000000..18b9773 --- /dev/null +++ b/tests/simulation_tests.cpp @@ -0,0 +1,259 @@ +#include "evo/simulation/world.hpp" +#include "evo/telemetry/sinks.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace { +void check(bool condition, const char* expression, + std::source_location location = std::source_location::current()) { + if (!condition) { + throw std::runtime_error(std::string{location.file_name()} + ":" + + std::to_string(location.line()) + " " + expression); + } +} +#define CHECK(expression) check(static_cast(expression), #expression) + +void advance(evo::SimulationWorld& world, std::uint64_t ticks) { + for (std::uint64_t tick = 0; tick < ticks; ++tick) { + CHECK(world.tick()); + } +} +evo::SimulationWorld fixture(std::uint64_t seed, std::uint32_t count) { + evo::SimulationWorld world{seed}; + for (std::uint32_t index = 0; index < count; ++index) { + CHECK(world.create_entity()); + } + return world; +} +void put(evo::Snapshot& bytes, std::size_t offset, std::uint64_t value, std::size_t width) { + for (std::size_t index = 0; index < width; ++index) { + bytes.at(offset + index) = static_cast(value & 0xffU); + value >>= 8U; + } +} +void resign(evo::Snapshot& bytes) { + std::uint64_t hash = 14695981039346656037ULL; + for (std::size_t index = 0; index < bytes.size() - 8; ++index) { + hash = (hash ^ bytes[index]) * 1099511628211ULL; + } + put(bytes, bytes.size() - 8, hash, 8); +} + +void random_vectors() { + evo::Random random{0}; + constexpr std::array expected{0xe220a8397b1dcdafULL, 0x6e789e6aa1b965f4ULL, + 0x06c45d188009454fULL, 0xf88bb8a8724c81ecULL}; + for (const auto value : expected) { + CHECK(random.next() == value); + } + evo::Random resumed{random.state()}; + CHECK(resumed.next() == random.next()); + evo::Random zero_first{0x61c8864680b583ebULL}; + CHECK(zero_first.ternary() == 1); + CHECK(zero_first.state() == 0x9e3779b97f4a7c15ULL); + for (int index = 0; index < 10'000; ++index) { + CHECK(random.ternary() < 3); + } +} +void entity_lifecycle() { + evo::SimulationWorld world{42}; + CHECK(world.entities().empty()); + const auto first = world.create_entity(); + const auto second = world.create_entity({evo::Millimetres{1023}, evo::Millimetres{0}}); + CHECK(first && second); + CHECK(first->value == 1 && second->value == 2); + const auto before = world.serialize(); + const auto invalid = world.create_entity({evo::Millimetres{1024}, evo::Millimetres{0}}); + CHECK(!invalid && invalid.error() == evo::Error::invalid_position); + CHECK(world.serialize() == before); + CHECK(world.remove_entity(*first)); + const auto stale = world.remove_entity(*first); + CHECK(!stale && stale.error() == evo::Error::entity_not_found); + const auto third = world.create_entity(); + CHECK(third && third->value == 3); + CHECK(world.entities()[0].id == *second); + CHECK(world.entities()[1].id == *third); + CHECK(!world.remove_entity(evo::EntityId{0})); +} +void golden_simulation() { + auto world = fixture(123456, 8); + advance(world, 1000); + CHECK(world.state_hash() == 0xd61ad5bf0c928c76ULL); + constexpr std::array, 8> positions{ + {{49, 10}, {985, 993}, {39, 33}, {1008, 0}, {16, 1}, {7, 3}, {1004, 1007}, {995, 15}}}; + for (std::size_t index = 0; index < positions.size(); ++index) { + CHECK(world.entities()[index].position.x.value == positions[index][0]); + CHECK(world.entities()[index].position.y.value == positions[index][1]); + } + auto other = fixture(123457, 8); + advance(other, 1000); + CHECK(other.state_hash() != world.state_hash()); +} +void replay_properties() { + for (std::uint64_t seed = 0; seed < 64; ++seed) { + auto full = fixture(seed, static_cast(seed % 17)); + auto partial = full; + const auto total = 2 * seed + 1; + advance(full, total); + advance(partial, seed); + const auto bytes = partial.serialize(); + auto restored = evo::SimulationWorld::restore(bytes); + CHECK(restored); + CHECK(restored->serialize() == bytes); + advance(*restored, total - seed); + CHECK(restored->serialize() == full.serialize()); + CHECK(restored->current_tick().value == total); + for (const auto& entity : restored->entities()) { + CHECK(entity.position.x.value < evo::domain_extent_mm); + CHECK(entity.position.y.value < evo::domain_extent_mm); + } + } +} +void stream_independence() { + auto full = fixture(91, 2); + auto reduced = full; + CHECK(reduced.remove_entity(evo::EntityId{1})); + advance(full, 500); + advance(reduced, 500); + CHECK(full.entities()[1].position == reduced.entities()[0].position); + CHECK(full.entities()[1].random.state() == reduced.entities()[0].random.state()); +} +void malformed_snapshots() { + const auto bytes = fixture(77, 2).serialize(); + for (std::size_t length = 0; length < bytes.size(); ++length) { + CHECK(!evo::SimulationWorld::restore(std::span{bytes}.first(length))); + } + for (std::size_t index = 0; index < bytes.size(); ++index) { + auto corrupted = bytes; + corrupted[index] ^= 0x80U; + CHECK(!evo::SimulationWorld::restore(corrupted)); + } + auto extra = bytes; + extra.push_back(0); + CHECK(!evo::SimulationWorld::restore(extra)); + CHECK(!evo::SimulationWorld::restore(evo::Snapshot(evo::max_snapshot_bytes + 1))); + struct Field { + std::size_t offset; + std::uint64_t value; + std::size_t width; + }; + const std::array fields{Field{40, 0, 8}, + Field{40, 2, 8}, // invalid next ID + Field{48, evo::max_entities + 1, 4}, + Field{48, 1, 4}, // count/length + Field{52, 0, 8}, + Field{52, 2, 8}, + Field{76, 1, 8}, // zero/duplicate/order + Field{60, evo::domain_extent_mm, 4}, + Field{64, evo::domain_extent_mm, 4}}; + for (const auto field : fields) { + auto invalid = bytes; + put(invalid, field.offset, field.value, field.width); + resign(invalid); // Reach semantic checks beyond checksum rejection. + CHECK(!evo::SimulationWorld::restore(invalid)); + } + for (const auto offset : {8U, 12U, 16U}) { + auto unsupported = bytes; + put(unsupported, offset, 999, 4); + resign(unsupported); + const auto restored = evo::SimulationWorld::restore(unsupported); + CHECK(!restored && restored.error() == evo::Error::unsupported_version); + } +} +void exhaustion_is_atomic() { + auto bytes = fixture(17, 1).serialize(); + put(bytes, 32, std::numeric_limits::max(), 8); + resign(bytes); + auto full_tick = evo::SimulationWorld::restore(bytes); + CHECK(full_tick); + const auto result = full_tick->tick(); + CHECK(!result && result.error() == evo::Error::tick_exhausted); + CHECK(full_tick->serialize() == bytes); + bytes = fixture(17, 1).serialize(); + put(bytes, 40, std::numeric_limits::max(), 8); + resign(bytes); + auto full_id = evo::SimulationWorld::restore(bytes); + CHECK(full_id); + const auto created = full_id->create_entity(); + CHECK(!created && created.error() == evo::Error::id_exhausted); + CHECK(full_id->serialize() == bytes); +} +void capacity_boundary() { + auto world = fixture(31, evo::max_entities); + const auto before = world.state_hash(); + const auto result = world.create_entity(); + CHECK(!result && result.error() == evo::Error::entity_limit); + CHECK(world.state_hash() == before); + const auto restored = evo::SimulationWorld::restore(world.serialize()); + CHECK(restored && restored->entities().size() == evo::max_entities); +} +void wire_layout_and_empty_state() { + evo::SimulationWorld world{0x1122334455667788ULL}; + const auto bytes = world.serialize(); + CHECK(bytes.size() == 60); + CHECK(bytes[8] == 1 && bytes[9] == 0); + CHECK(bytes[24] == 0x88 && bytes[31] == 0x11); + auto restored = evo::SimulationWorld::restore(bytes); + CHECK(restored && restored->serialize() == bytes); + const auto created = restored->create_entity(); + CHECK(created && created->value == 1); +} +void telemetry_is_host_owned() { + const auto world = fixture(4, 3); + const auto before = world.serialize(); + std::ostringstream text; + evo::PrometheusTextSink sink{text}; + sink.observe({world.current_tick(), static_cast(world.entities().size())}); + CHECK(text.str().find("evo_active_entities 3\n") != std::string::npos); + CHECK(world.serialize() == before); + std::ostringstream log; + evo::log_error(log, evo::Error::invalid_snapshot); + CHECK(log.str() == "{\"level\":\"error\",\"event\":\"invalid_snapshot\"}\n"); +} +} // namespace + +int main(int argc, char**) try { + // Dedicated CTest WILL_FAIL entry checks that this harness fails in Release. + if (argc > 1) { + try { + CHECK(false); + } catch (const std::exception&) { + return 1; + } + return 0; + } + struct Test { + const char* name; + void (*run)(); + }; + const std::array tests{Test{"random reference vectors", random_vectors}, + Test{"entity lifecycle", entity_lifecycle}, + Test{"frozen simulation fixture", golden_simulation}, + Test{"seeded replay properties", replay_properties}, + Test{"independent streams", stream_independence}, + Test{"bounded snapshots", malformed_snapshots}, + Test{"atomic exhaustion", exhaustion_is_atomic}, + Test{"capacity", capacity_boundary}, + Test{"canonical empty state", wire_layout_and_empty_state}, + Test{"host telemetry", telemetry_is_host_owned}}; + int failures = 0; + for (const auto& test : tests) { + try { + test.run(); + std::cout << "PASS " << test.name << '\n'; + } catch (const std::exception& error) { + ++failures; + std::cerr << "FAIL " << test.name << ": " << error.what() << '\n'; + } + } + return failures == 0 ? 0 : 1; +} catch (...) { + return 1; +} diff --git a/tools/check-format.cmake b/tools/check-format.cmake new file mode 100644 index 0000000..3e8556b --- /dev/null +++ b/tools/check-format.cmake @@ -0,0 +1,14 @@ +if(NOT FORMATTER OR NOT EXISTS "${FORMATTER}") + message(FATAL_ERROR "clang-format major 19 is required for format-check") +endif() +execute_process(COMMAND "${FORMATTER}" --version OUTPUT_VARIABLE version RESULT_VARIABLE result) +if(NOT result EQUAL 0 OR NOT version MATCHES "version 19\\.") + message(FATAL_ERROR "Expected clang-format major 19, got ${version}") +endif() +file(GLOB_RECURSE sources + "${SOURCE_ROOT}/include/*.hpp" "${SOURCE_ROOT}/src/*.cpp" + "${SOURCE_ROOT}/apps/*.cpp" "${SOURCE_ROOT}/tests/*.cpp") +execute_process(COMMAND "${FORMATTER}" --dry-run --Werror ${sources} RESULT_VARIABLE result) +if(NOT result EQUAL 0) + message(FATAL_ERROR "Formatting check failed") +endif() diff --git a/tools/windows-check.ps1 b/tools/windows-check.ps1 new file mode 100644 index 0000000..5d8ac3d --- /dev/null +++ b/tools/windows-check.ps1 @@ -0,0 +1,44 @@ +param( + [ValidateSet('debug', 'release', 'analysis', 'asan', 'tsan')] + [string]$Preset = 'debug', + [ValidateSet('configure', 'build', 'test', 'format', 'check')] + [string]$Action = 'check' +) +$ErrorActionPreference = 'Stop' +$repositoryRoot = Split-Path -Parent $PSScriptRoot +$vswherePath = Join-Path ${env:ProgramFiles(x86)} 'Microsoft Visual Studio\Installer\vswhere.exe' +if (!(Test-Path -LiteralPath $vswherePath)) { throw 'Visual Studio Installer/vswhere is required' } +$visualStudioRoot = & $vswherePath -latest -version '[17.0,18.0)' -products '*' -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath +if (!$visualStudioRoot) { throw 'Visual Studio 2022 C++ build tools are required' } +$developerScript = Join-Path $visualStudioRoot 'Common7\Tools\VsDevCmd.bat' +# cmd only initializes compiler environment; all filesystem work stays in PowerShell/CMake. +$environmentCommand = 'call "{0}" -no_logo -arch=x64 -host_arch=x64 && set' -f $developerScript +$environmentLines = & $env:ComSpec /d /c $environmentCommand +if ($LASTEXITCODE -ne 0) { throw 'Visual Studio environment initialization failed' } +foreach ($line in $environmentLines) { + if ($line -match '^([^=]+)=(.*)$') { + [Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process') + } +} +$cmakeRoot = Join-Path $visualStudioRoot 'Common7\IDE\CommonExtensions\Microsoft\CMake' +$llvmRoot = Join-Path $visualStudioRoot 'VC\Tools\Llvm\x64\bin' +$env:Path = "$cmakeRoot\CMake\bin;$cmakeRoot\Ninja;$llvmRoot;$env:Path" +Push-Location -LiteralPath $repositoryRoot +try { + if ($Action -in @('configure', 'check')) { + & cmake --preset $Preset + if ($LASTEXITCODE -ne 0) { throw 'CMake configure failed' } + } + if ($Action -in @('build', 'check')) { + & cmake --build --preset $Preset + if ($LASTEXITCODE -ne 0) { throw 'Build failed' } + } + if ($Action -in @('test', 'check')) { + & ctest --preset $Preset + if ($LASTEXITCODE -ne 0) { throw 'Tests failed' } + } + if ($Action -eq 'format') { + & cmake --build --preset $Preset --target format-check + if ($LASTEXITCODE -ne 0) { throw 'Formatting check failed' } + } +} finally { Pop-Location }