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:
@@ -0,0 +1,10 @@
|
||||
BasedOnStyle: LLVM
|
||||
IndentWidth: 4
|
||||
ColumnLimit: 100
|
||||
NamespaceIndentation: None
|
||||
AllowShortFunctionsOnASingleLine: Empty
|
||||
AllowShortIfStatementsOnASingleLine: Never
|
||||
AllowShortLoopsOnASingleLine: false
|
||||
BreakBeforeBraces: Attach
|
||||
PointerAlignment: Left
|
||||
SortIncludes: CaseSensitive
|
||||
@@ -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
|
||||
@@ -0,0 +1,8 @@
|
||||
.git
|
||||
build
|
||||
.vs
|
||||
.cache
|
||||
.env
|
||||
.env.*
|
||||
*.evo
|
||||
*.log
|
||||
@@ -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
@@ -0,0 +1,12 @@
|
||||
/build/
|
||||
/.cache/
|
||||
/.vs/
|
||||
/CMakeUserPresets.json
|
||||
/compile_commands.json
|
||||
*.evo
|
||||
*.profraw
|
||||
*.profdata
|
||||
*.log
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -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}}
|
||||
]
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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()
|
||||
@@ -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.
|
||||
@@ -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"]
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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/).
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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)
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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()
|
||||
@@ -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 }
|
||||
Reference in New Issue
Block a user