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 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-09-14 15:44:41 -04:00
co-authored by Claude Opus 5
commit d5b4bd068e
63 changed files with 3531 additions and 0 deletions
+10
View File
@@ -0,0 +1,10 @@
BasedOnStyle: LLVM
IndentWidth: 4
ColumnLimit: 100
NamespaceIndentation: None
AllowShortFunctionsOnASingleLine: Empty
AllowShortIfStatementsOnASingleLine: Never
AllowShortLoopsOnASingleLine: false
BreakBeforeBraces: Attach
PointerAlignment: Left
SortIncludes: CaseSensitive
+6
View File
@@ -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
+8
View File
@@ -0,0 +1,8 @@
.git
build
.vs
.cache
.env
.env.*
*.evo
*.log
+15
View File
@@ -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
+12
View File
@@ -0,0 +1,12 @@
/build/
/.cache/
/.vs/
/CMakeUserPresets.json
/compile_commands.json
*.evo
*.profraw
*.profdata
*.log
.env
.env.*
!.env.example
+24
View File
@@ -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.
+77
View File
@@ -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 <expected>
#if !defined(__cpp_lib_expected) || __cpp_lib_expected < 202202L
#error std::expected is required
#endif
int main() { std::expected<int, int> 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=$<TARGET_FILE:evo-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)
+26
View File
@@ -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}}
]
}
+85
View File
@@ -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.
+276
View File
@@ -0,0 +1,276 @@
#include "evo/simulation/world.hpp"
#include "evo/telemetry/sinks.hpp"
#include <array>
#include <charconv>
#include <exception>
#include <filesystem>
#include <fstream>
#include <iomanip>
#include <iostream>
#include <limits>
#include <optional>
#include <string_view>
#include <system_error>
#include <utility>
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<std::uint64_t, evo::Error> 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<void, evo::Error> 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<Options, evo::Error> 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<evo::SimulationWorld, evo::Error> 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<std::streamoff>(evo::max_snapshot_bytes)) {
return std::unexpected{evo::Error::io_failure};
}
evo::Snapshot bytes(static_cast<std::size_t>(length));
input.seekg(0);
if (!bytes.empty()) {
input.read(reinterpret_cast<char*>(bytes.data()),
static_cast<std::streamsize>(bytes.size()));
}
if (!input) {
return std::unexpected{evo::Error::io_failure};
}
return evo::SimulationWorld::restore(bytes);
}
std::expected<void, evo::Error> advance(evo::SimulationWorld& world, std::uint64_t ticks) {
if (ticks > std::numeric_limits<std::uint64_t>::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<void, evo::Error> run(const Options& options) {
auto loaded = initial_world(options);
if (!loaded) {
return std::unexpected{loaded.error()};
}
auto world = std::move(*loaded);
std::optional<evo::SimulationWorld> 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<const char*>(bytes.data()),
static_cast<std::streamsize>(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<std::uint64_t>(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;
}
+54
View File
@@ -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()
+36
View File
@@ -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.
+29
View File
@@ -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"]
+70
View File
@@ -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.
+90
View File
@@ -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.
+34
View File
@@ -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).
+34
View File
@@ -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).
+34
View File
@@ -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).
+34
View File
@@ -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).
+34
View File
@@ -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).
+34
View File
@@ -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.
+34
View File
@@ -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.
+34
View File
@@ -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).
+34
View File
@@ -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).
+34
View File
@@ -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<T, Error>. 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).
+34
View File
@@ -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.
+34
View File
@@ -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).
+34
View File
@@ -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).
+34
View File
@@ -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).
+34
View File
@@ -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).
@@ -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).
+34
View File
@@ -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/).
+34
View File
@@ -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).
@@ -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.
+26
View File
@@ -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.
+20
View File
@@ -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.
@@ -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.
+81
View File
@@ -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.
+50
View File
@@ -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.
@@ -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.
@@ -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<EntityId, Error>
auto result = world.tick(); // exactly one logical tick
auto bytes = world.serialize(); // canonical local snapshot
auto restored = SimulationWorld::restore(bytes); // expected<World, Error>
```
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.
+98
View File
@@ -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.
+105
View File
@@ -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.
+97
View File
@@ -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.
+88
View File
@@ -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.
+78
View File
@@ -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.
+80
View File
@@ -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.
@@ -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<T, Error>`. 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.
+35
View File
@@ -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.
+69
View File
@@ -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.
+33
View File
@@ -0,0 +1,33 @@
#pragma once
#include <cstdint>
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<std::uint32_t>(value % 3U);
}
[[nodiscard]] constexpr std::uint64_t state() const noexcept {
return state_;
}
private:
std::uint64_t state_;
};
} // namespace evo
+67
View File
@@ -0,0 +1,67 @@
#pragma once
#include <compare>
#include <cstdint>
#include <string_view>
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
+54
View File
@@ -0,0 +1,54 @@
#pragma once
#include "evo/core/random.hpp"
#include "evo/core/types.hpp"
#include <cstddef>
#include <cstdint>
#include <expected>
#include <span>
#include <vector>
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<std::uint8_t>;
class SimulationWorld {
public:
explicit SimulationWorld(std::uint64_t seed) noexcept : seed_{seed} {}
[[nodiscard]] std::expected<EntityId, Error> create_entity(Position2 position = {});
[[nodiscard]] std::expected<void, Error> remove_entity(EntityId id);
[[nodiscard]] std::expected<void, Error> tick() noexcept;
// Non-owning inspection; mutation can invalidate views and references.
[[nodiscard]] std::span<const EntityState> 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<SimulationWorld, Error>
restore(std::span<const std::uint8_t> bytes);
private:
std::uint64_t seed_;
Tick tick_{};
std::uint64_t next_id_{1};
std::vector<EntityState> entities_;
};
} // namespace evo
+35
View File
@@ -0,0 +1,35 @@
#pragma once
#include "evo/core/types.hpp"
#include <cstdint>
#include <ostream>
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
+10
View File
@@ -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.
+117
View File
@@ -0,0 +1,117 @@
#include "evo/simulation/world.hpp"
#include <algorithm>
#include <array>
namespace evo {
namespace {
constexpr std::array<std::uint8_t, 8> 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<const std::uint8_t> 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<std::uint8_t>(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<const std::uint8_t> 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<std::uint64_t>(bytes_[offset_++]) << (8U * index);
}
return value;
}
private:
std::span<const std::uint8_t> 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, Error>
SimulationWorld::restore(std::span<const std::uint8_t> 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<std::size_t>(count));
Reader rows{bytes.subspan(header_size, static_cast<std::size_t>(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<std::uint32_t>(x)},
Millimetres{static_cast<std::uint32_t>(y)}},
Random{random_state}});
previous_id = id;
}
return restored;
}
} // namespace evo
+47
View File
@@ -0,0 +1,47 @@
#include "evo/simulation/world.hpp"
#include <algorithm>
#include <limits>
namespace evo {
std::expected<EntityId, Error> 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<std::uint64_t>::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<void, Error> 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<void, Error> SimulationWorld::tick() noexcept {
if (tick_.value == std::numeric_limits<std::uint64_t>::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
+53
View File
@@ -0,0 +1,53 @@
#include "evo/simulation/world.hpp"
#include <chrono>
#include <exception>
#include <iostream>
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<double>(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;
}
+62
View File
@@ -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)
+29
View File
@@ -0,0 +1,29 @@
#include "evo/simulation/world.hpp"
#include <algorithm>
#include <cstddef>
#include <cstdint>
#include <cstdlib>
#include <span>
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;
}
+259
View File
@@ -0,0 +1,259 @@
#include "evo/simulation/world.hpp"
#include "evo/telemetry/sinks.hpp"
#include <array>
#include <exception>
#include <iostream>
#include <limits>
#include <source_location>
#include <sstream>
#include <stdexcept>
#include <string>
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<bool>(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<std::uint8_t>(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<std::uint64_t, 4> 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<std::array<std::uint32_t, 2>, 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<std::uint32_t>(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<std::uint64_t>::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<std::uint64_t>::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<std::uint64_t>(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;
}
+14
View File
@@ -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()
+44
View File
@@ -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 }