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