Initial commit: architecture docs and headless engineering proof

Aeternalis Evolution, a custom-engine persistent evolutionary MMO.

This first commit establishes the project skeleton:

- Architecture and design docs: project vision, system overview,
  engineering constitution, roadmap, 19 ADRs, and the simulation,
  world, network, persistence and infrastructure architectures.
- Headless engineering proof: deterministic synthetic particles,
  component lifecycle, explicit PRNG streams, canonical snapshots
  and restored execution.
- Build and tooling: CMake 3.28+ / Ninja presets, C++23 feature
  check, clang-format and clang-tidy config, format check script,
  Windows check script, and a Docker build context.
- Tests: unit tests, benchmarks, a snapshot fuzz target and CLI
  integration wiring.

No gameplay, renderer, network service or running deployment yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-09-14 15:44:41 -04:00
co-authored by Claude Opus 5
commit d5b4bd068e
63 changed files with 3531 additions and 0 deletions
+276
View File
@@ -0,0 +1,276 @@
#include "evo/simulation/world.hpp"
#include "evo/telemetry/sinks.hpp"
#include <array>
#include <charconv>
#include <exception>
#include <filesystem>
#include <fstream>
#include <iomanip>
#include <iostream>
#include <limits>
#include <optional>
#include <string_view>
#include <system_error>
#include <utility>
namespace {
struct Options {
std::uint64_t seed{123456};
std::uint64_t ticks{1000};
std::uint64_t entities{8};
std::filesystem::path load, save, output, metrics;
bool verify_replay{};
bool help{};
};
std::expected<std::uint64_t, evo::Error> number(std::string_view text) {
std::uint64_t value{};
const auto [end, error] = std::from_chars(text.data(), text.data() + text.size(), value);
if (error != std::errc{} || end != text.data() + text.size()) {
return std::unexpected{evo::Error::invalid_arguments};
}
return value;
}
std::expected<void, evo::Error> validate_paths(const Options& options) {
auto paths = std::array{options.load, options.save, options.output, options.metrics};
for (auto& path : paths) {
if (!path.empty()) {
std::error_code error;
path = std::filesystem::weakly_canonical(path, error);
if (error) {
return std::unexpected{evo::Error::io_failure};
}
}
}
for (std::size_t first = 0; first < paths.size(); ++first) {
for (std::size_t second = first + 1; second < paths.size(); ++second) {
if (paths[first].empty() || paths[second].empty()) {
continue;
}
if (paths[first] == paths[second]) {
return std::unexpected{evo::Error::invalid_arguments};
}
std::error_code error;
const auto first_exists = std::filesystem::exists(paths[first], error);
if (error) {
return std::unexpected{evo::Error::io_failure};
}
const auto second_exists = std::filesystem::exists(paths[second], error);
if (error) {
return std::unexpected{evo::Error::io_failure};
}
if (first_exists && second_exists) {
const auto same = std::filesystem::equivalent(paths[first], paths[second], error);
if (error) {
return std::unexpected{evo::Error::io_failure};
}
if (same) {
return std::unexpected{evo::Error::invalid_arguments};
}
}
}
}
return {};
}
std::expected<Options, evo::Error> parse(int argc, char** argv) {
Options options;
bool initial_state_option = false;
for (int index = 1; index < argc; ++index) {
const std::string_view key{argv[index]};
if (key == "--help") {
options.help = true;
continue;
}
if (key == "--verify-replay") {
options.verify_replay = true;
continue;
}
if (++index >= argc) {
return std::unexpected{evo::Error::invalid_arguments};
}
const std::string_view value{argv[index]};
if (key == "--seed" || key == "--ticks" || key == "--entities") {
const auto parsed = number(value);
if (!parsed) {
return std::unexpected{parsed.error()};
}
if (key == "--seed") {
options.seed = *parsed;
initial_state_option = true;
} else if (key == "--entities") {
options.entities = *parsed;
initial_state_option = true;
} else {
options.ticks = *parsed;
}
} else if (key == "--load") {
options.load = value;
} else if (key == "--save") {
options.save = value;
} else if (key == "--output") {
options.output = value;
} else if (key == "--metrics") {
options.metrics = value;
} else {
return std::unexpected{evo::Error::invalid_arguments};
}
}
if (options.entities > evo::max_entities || (!options.load.empty() && initial_state_option)) {
return std::unexpected{evo::Error::invalid_arguments};
}
if (const auto valid = validate_paths(options); !valid) {
return std::unexpected{valid.error()};
}
return options;
}
std::expected<evo::SimulationWorld, evo::Error> initial_world(const Options& options) {
if (options.load.empty()) {
evo::SimulationWorld world{options.seed};
for (std::uint64_t index = 0; index < options.entities; ++index) {
const auto created = world.create_entity();
if (!created) {
return std::unexpected{created.error()};
}
}
return world;
}
std::ifstream input{options.load, std::ios::binary | std::ios::ate};
const auto length = input.tellg();
if (!input || length < 0 || length > static_cast<std::streamoff>(evo::max_snapshot_bytes)) {
return std::unexpected{evo::Error::io_failure};
}
evo::Snapshot bytes(static_cast<std::size_t>(length));
input.seekg(0);
if (!bytes.empty()) {
input.read(reinterpret_cast<char*>(bytes.data()),
static_cast<std::streamsize>(bytes.size()));
}
if (!input) {
return std::unexpected{evo::Error::io_failure};
}
return evo::SimulationWorld::restore(bytes);
}
std::expected<void, evo::Error> advance(evo::SimulationWorld& world, std::uint64_t ticks) {
if (ticks > std::numeric_limits<std::uint64_t>::max() - world.current_tick().value) {
return std::unexpected{evo::Error::tick_exhausted};
}
for (std::uint64_t tick = 0; tick < ticks; ++tick) {
if (const auto result = world.tick(); !result) {
return result;
}
}
return {};
}
std::expected<void, evo::Error> run(const Options& options) {
auto loaded = initial_world(options);
if (!loaded) {
return std::unexpected{loaded.error()};
}
auto world = std::move(*loaded);
std::optional<evo::SimulationWorld> replay;
if (options.verify_replay) {
replay = world;
}
if (const auto result = advance(world, options.ticks); !result) {
return result;
}
if (replay) {
const auto half = options.ticks / 2;
if (const auto result = advance(*replay, half); !result) {
return result;
}
auto restored = evo::SimulationWorld::restore(replay->serialize());
if (!restored) {
return std::unexpected{restored.error()};
}
if (const auto result = advance(*restored, options.ticks - half); !result) {
return result;
}
if (restored->serialize() != world.serialize()) {
return std::unexpected{evo::Error::replay_mismatch};
}
}
if (!options.save.empty()) {
const auto bytes = world.serialize();
std::ofstream snapshot{options.save, std::ios::binary | std::ios::trunc};
snapshot.write(reinterpret_cast<const char*>(bytes.data()),
static_cast<std::streamsize>(bytes.size()));
snapshot.close();
if (!snapshot) {
return std::unexpected{evo::Error::io_failure};
}
}
if (!options.metrics.empty()) {
if (const auto valid = validate_paths(options); !valid) {
return valid;
}
std::ofstream metrics_file{options.metrics};
evo::PrometheusTextSink sink{metrics_file};
sink.observe({world.current_tick(), static_cast<std::uint64_t>(world.entities().size())});
metrics_file.close();
if (!metrics_file) {
return std::unexpected{evo::Error::io_failure};
}
}
std::ofstream output_file;
if (!options.output.empty()) {
if (const auto valid = validate_paths(options); !valid) {
return valid;
}
output_file.open(options.output);
if (!output_file) {
return std::unexpected{evo::Error::io_failure};
}
}
auto& output = options.output.empty() ? std::cout : output_file;
output << "{\"rules_version\":" << evo::rules_version
<< ",\"format_version\":" << evo::format_version << ",\"seed\":" << world.seed()
<< ",\"ticks\":" << world.current_tick().value
<< ",\"entities\":" << world.entities().size() << ",\"state_hash\":\"" << std::hex
<< std::setfill('0') << std::setw(16) << world.state_hash() << std::dec
<< "\",\"replay_verified\":" << (options.verify_replay ? "true" : "false") << "}\n";
output.flush();
if (!options.output.empty()) {
output_file.close();
}
if (!output) {
return std::unexpected{evo::Error::io_failure};
}
return {};
}
} // namespace
int main(int argc, char** argv) try {
try {
const auto options = parse(argc, argv);
if (!options) {
evo::log_error(std::cerr, options.error());
return 2;
}
if (options->help) {
std::cout
<< "evo-sim [--seed N --entities N | --load FILE] --ticks N\n"
" [--verify-replay] [--save FILE] [--output JSON] [--metrics FILE]\n"
"Synthetic proof. When loading, ticks are additional.\n";
return 0;
}
const auto result = run(*options);
if (!result) {
evo::log_error(std::cerr, result.error());
return 1;
}
return 0;
} catch (const std::exception&) {
evo::log_error(std::cerr, evo::Error::unhandled_exception);
return 1;
}
} catch (...) {
// Last-resort process boundary, including failure of error reporting itself.
return 1;
}