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
@@ -0,0 +1,39 @@
# Engineering constitution
Authority: founding requirements → architecture → accepted/scoped ADRs → public
contracts → tests → implementation. A failing test never justifies changing a
locked requirement. Document a conflict and stop expanding affected code until
the contract is resolved. Proposed ADRs are not permission to ship a final game
rule. Every PR names its affected modules and decision scope.
| Topic | Rule |
|---|---|
| Language | C++23 subset, standard library `std::expected`; configure must verify support. No modules, reflection, unsupported library facilities or compiler extensions in public contracts. GCC 14 Linux CI target; MSVC 19.44+ Windows target; verify actual versions in validation report. |
| Build | Target-based CMake ≥3.28, out-of-source builds and checked-in presets. `evo::simulation` must compile without graphics, networking, database or Kubernetes. |
| Naming | Namespace `evo`; types `PascalCase`; functions/variables/files `snake_case`; private fields trailing `_`; constants `snake_case`. No deep biological inheritance. |
| Formatting | clang-format configuration is authoritative; pin formatter major in CI. Avoid hand-format debates. Headers self-contained; `#pragma once`; explicit includes. |
| Dependencies | Default none for the proof. New dependencies require purpose, pinned revision, license/security review, reproducible acquisition and an ADR when architectural. No unreviewed network fetch at configure time. Keep third-party warning policy separate. |
| Ownership | Values by default; RAII; `unique_ptr` for exclusive heap ownership. `shared_ptr` only with documented shared lifetime. Pointers/references/spans are non-owning; state lifetime/invalidation. No paired raw allocation/free. |
| Threading | A host owns threads. One writer owns simulation state. Workers receive immutable work and return deterministically merged results. No hidden threads, detached work or speculative lock-free structures. |
| Exceptions | Recoverable invalid commands/data return `expected<T, Error>`. Optional means legitimate absence, not hidden errors. Allocation/standard-library exceptions propagate to process boundaries, which log and exit/recover; never catch-and-continue a partially mutated tick. No exception-driven game flow. |
| Errors | Typed error enum now; later structured contextual error at adapters. Do not mix boolean failure/null/exception for the same contract. Check nodiscard returns. Partial construction must not publish invalid state. |
| Logging | Structured bounded records at app/I/O boundaries, UTC/monotonic timing there only. No secrets, raw session tickets or unbounded payloads. Deterministic kernel returns counters/errors; it never reads a clock or writes stdout. |
| Assertions | Internal programming invariants may assert; hostile or persisted input must use runtime validation in release builds. Tests never rely on `assert`, which disappears under NDEBUG. |
| Serialization | Explicit fields, endianness, length bounds, versions, canonical order. Never memcpy native object layouts onto disk/wire; no trust in a client struct. Validate before allocation and publication. |
| Coordinates | Proof: integer millimetres, periodic 2D local domain. Target: documented region-local right-handed coordinates, +Z up and stable global hierarchical address; spherical mapping is an open ADR. No absolute planet floats in hot entity state. |
| Units | Named unit wrappers; conversions explicit. Later quantities require dimensional interfaces (J, kg, mol, m, s) and documented fixed-point ranges or error budgets. Do not mistake toy integer movement for a physics decision. |
| Randomness | Explicit serialized PRNG state/seed. No `rand`, `random_device`, ambient generator or implementation-defined distributions in the kernel. Noncryptographic RNG never authenticates sessions. |
| Time | Integer tick identity; fixed quantum experiment 50ms. No wall-clock reads, variable dt or implicit offline progression in the kernel. Tick-rate change requires simulation-version review. |
| Floating point | Proof uses integer state. Future systems specify exact/tolerant/nondeterministic boundaries; no fast-math in authoritative code. Reject non-finite external values. Stable reductions and measured error budgets. |
| API stability | Internal versioned source contracts, no stable binary ABI promise yet. Public change updates architecture, tests and callers together. Do not expose future third-party ECS/client/codec types through kernel APIs. |
| Tests | Unit, deterministic golden, property-style seed ensembles, restore/codec validation and CLI integration now. Fuzz/sanitizer jobs and benchmarks provided. Add network/load/recovery/ecology gates when those contracts exist; do not pretend empty tests validate them. |
| Analysis | Owned code: strong warnings, CI warnings-as-errors, clang-tidy, format check. ASan+UBSan Linux together; TSan separately. Instrument libraries and executables. Never combine ASan and TSan. |
| Performance | Measure before optimizing; benchmark seed, entity count, ticks, compiler/build and hardware. Wall-time thresholds require a controlled runner. CI portable benchmarks report rather than gate noisy timing. |
| Documentation | State implemented versus planned. ADRs include context, decision, alternatives, benefits, costs, risks, consequences and status. Link evidence for dependency claims. Keep roadmap status and actual verification honest. |
| Security | Server authority, bounded parsing, least privilege, reviewed cryptographic protocols, redacted logs. No custom cryptography; no administrative credentials in game processes. No World0 deployment/destruction from a routine build. |
Before code: read relevant docs and ADRs, inspect public interfaces and tests,
state modules touched. Small increments must build and test. No placeholder
libraries, speculative services or invented gameplay to fill directory trees.
Repository licensing is a maintainer decision; do not apply an open-source
license to this game by assumption.
+35
View File
@@ -0,0 +1,35 @@
# Validation strategy
Tests defend contracts, not directory coverage. All checks remain active in
Release builds. Current proof has no actual network, biology or distributed
recovery, so those categories below are milestone gates rather than passing
test labels attached to empty targets.
| Category | Foundation evidence | Future gate |
|---|---|---|
| Unit | PRNG reference vectors, entity lifecycle, capacity/error boundaries | Genome development and energetic transfer rules |
| Deterministic regression | Frozen canonical fingerprint plus independent reference calculation; uninterrupted vs restored execution | Versioned ecosystem baseline ensembles |
| Property-style | Many explicit seeds and tick split points; coordinate and ID invariants | Conservation, nonnegative mass/population and phenotype prerequisites |
| Serialization | Exact byte round-trip, malformed lengths/versions/checksum/IDs/coordinates; validate before publication | Compatible migrations, verified object archive and replay range |
| Integration | CLI seed/ticks and replay verification; file save/load comparison | Durable death/reproduction acknowledgment and worker process kill |
| Fuzz | Optional libFuzzer snapshot decoder with bounded input and sanitizer instrumentation | Authenticated protocol/parser and migration fuzzing |
| Static/sanitizers | clang-format/tidy; ASan/UBSan and separate TSan configurations | TSan on real scheduler and I/O lifecycle |
| Benchmark/load | Seed/count/tick/time/compiler report for kernel; no noisy portable time threshold | 20+ clients, region load, interest bandwidth, recovery backlog |
| Biological regression | Absent until M2; do not call synthetic particles an ecosystem | Million-tick balances, predator/prey cycles, starvation, diversity and extinction |
| Disaster recovery | Absent until persistent services exist | Off-host verified backup restore; database/object consistency; old owner fencing |
Reference fixture, rules/format 1: seed 123456, create 8 particles at (0,0), then
1,000 ticks yields canonical payload FNV-1a `d61ad5bf0c928c76`. Expected positions
by ID: (49,10), (985,993), (39,33), (1008,0), (16,1), (7,3), (1004,1007),
(995,15). The initial value was computed independently in JavaScript with
explicit wrapping BigInt arithmetic, not copied from the C++ test result.
SplitMix64 seed-zero vectors begin `e220a8397b1dcdaf`, `6e789e6aa1b965f4`,
`06c45d188009454f`, `f88bb8a8724c81ec`.
Changing a golden requires a stated rule/format change, compatibility decision,
independent review and updated documentation. A new compiler or optimization
mode must reproduce existing integer fixtures. Floating-point biology later
needs error envelopes and ensemble comparisons in addition to exact fixtures.
Unexecuted configurations are not validation. Record exact tools, commands,
results and limitations in VALIDATION.md at the end of each foundation change.