Files
aevolution/docs/engineering/ENGINEERING_CONSTITUTION.md
dingoandClaude Opus 5 d5b4bd068e 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>
2026-09-14 15:44:41 -04:00

5.9 KiB

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.