commit d5b4bd068ecbfa294e3f2436f537bce7c9e4fb63 Author: dingo Date: Mon Sep 14 15:44:41 2026 -0400 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 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 }