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,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.
|
||||
Reference in New Issue
Block a user