diff --git a/docs/INITIAL_BRIEF.md b/docs/INITIAL_BRIEF.md new file mode 100644 index 0000000..536e59e --- /dev/null +++ b/docs/INITIAL_BRIEF.md @@ -0,0 +1,2606 @@ +AETERNALIS EVOLUTION + +Master Engineering, Architecture, Infrastructure, and Game-System Brief + +You are acting as a principal software architect, senior C++ engineer, distributed-systems engineer, simulation engineer, game-engine engineer, DevOps/platform engineer, and technical project planner for a new persistent online evolutionary simulation game. + +Your immediate responsibility is not to blindly generate the entire game. + +Your responsibility is to: + +1. Understand and preserve the design vision below. +2. Turn it into rigorous technical architecture. +3. Identify unknowns and risks. +4. Produce Architecture Decision Records (ADRs). +5. Establish engineering standards. +6. Design repository/module boundaries. +7. Design the simulation model. +8. Design the networking model. +9. Design persistent-world infrastructure. +10. Design Kubernetes deployment architecture. +11. Produce an incremental milestone roadmap. +12. Scaffold the repository. +13. Create tests and development tooling. +14. Begin implementing the smallest foundational vertical slice. +15. Never compromise the long-term architecture merely to produce a quick demonstration. + +The project is intended to evolve from a development deployment on a single Dell PowerEdge R730xd Kubernetes host with approximately 128 GB RAM into a horizontally scalable production deployment by adding physical servers, processors, RAM, storage, and eventually additional Kubernetes clusters. + +Production scale is not required immediately. + +Production-shaped architecture is required immediately. + +⸻ + +1. CORE GAME CONCEPT + +This is a persistent MMO evolution game. + +Players begin each life as a primitive single-celled organism. + +The earliest gameplay is a 2D microscopic environment. + +The player must: + +* move, +* find energy/resources, +* consume matter or other organisms, +* avoid predators, +* reproduce, +* select evolutionary mutations, +* adapt to changing environmental conditions, +* and eventually potentially become multicellular. + +Evolution is the central character-development mechanic. + +There are no conventional RPG classes. + +There should not be a conventional linear skill tree. + +There should not be a predetermined progression such as: + +Cell → Fish → Reptile → Mammal → Human. + +Evolution must branch organically. + +Possible evolutionary strategies include, but are not limited to: + +* predation, +* scavenging, +* photosynthesis, +* chemosynthesis, +* parasitism, +* symbiosis, +* decomposition, +* sessile organisms, +* plants or plant-like organisms, +* fungi or fungus-like organisms, +* motile animal-like organisms, +* colonial organisms, +* enormous multicellular organisms, +* highly intelligent organisms, +* minimally intelligent but extremely successful organisms. + +“Animal,” “plant,” and “fungus” should preferably be emergent classifications, not hard-coded character classes. + +The simulation should allow organisms that do not fit real-world classifications cleanly. + +Examples: + +* photosynthetic mobile organisms, +* carnivorous plants, +* colonial superorganisms, +* mineral-consuming organisms, +* organisms using exotic but internally consistent metabolic strategies. + +⸻ + +2. PERMADEATH + +Permadeath is absolute. + +When the player-controlled organism dies: + +that organism is permanently dead. + +The player begins again as a new primitive single-celled organism. + +There are: + +* no resurrection mechanics, +* no corpse retrieval, +* no retained stat bonuses, +* no inherited power, +* no level checkpoints, +* no skipping the cellular stage merely because the player has reached later stages previously. + +Death should matter. + +The player may retain account-level historical information such as discoveries, statistics, lineage history, or a codex, but nothing that makes the next organism biologically stronger simply because the account is old. + +The world persists. + +The character does not. + +⸻ + +3. PERSISTENT LINEAGES + +Player-created organisms can reproduce. + +Reproduction creates descendants. + +A fundamental design under consideration is: + +Every player reproduction can seed one or more autonomous NPC descendants derived from the player’s current genome. + +The exact offspring count may eventually depend on reproductive strategy. + +Examples: + +Binary fission: + +* one descendant per reproductive event. + +Egg production: + +* potentially many offspring, +* high juvenile mortality, +* substantial energetic investment. + +Live birth: + +* fewer offspring, +* higher investment per offspring. + +Spore/broadcast reproduction: + +* potentially huge theoretical offspring counts, +* mostly represented statistically rather than instantiated as individual AI entities. + +NPC descendants are not owned by the player. + +They are wildlife. + +They continue existing after the player logs out or dies. + +The player may later encounter descendants from an earlier life. + +A later lineage created by the same player may even compete against or drive an older lineage extinct. + +⸻ + +4. OFFLINE PLAYERS + +Offline player-controlled organisms MUST NOT continue progressing. + +Logging out must not allow: + +* movement, +* feeding, +* reproduction, +* mutation, +* growth, +* passive progression. + +The exact logout treatment still requires design. + +Potential approaches include: + +* safely removing the player-controlled organism from active simulation, +* placing it in a non-progressing dormant state, +* another mechanism that preserves fairness. + +NPC descendants remain part of the ecosystem independently. + +⸻ + +5. NO PLAYER/NPC VISUAL DISTINCTION + +The game should not show arbitrary UI labels identifying: + +* player, +* NPC, +* level, +* species ownership. + +Players and NPC descendants should visually obey the same biological rules. + +Friends may be identifiable through a separate social mechanism. + +An organism’s behavior may make a human-controlled organism seem unusually intelligent, but there should not be a floating: + +PLAYER + +or: + +NPC + +tag above organisms. + +⸻ + +6. EVOLUTIONARY FAILURE AND NATURAL SELECTION + +When a player dies, existing descendants do not simply disappear. + +The cause of death demonstrates weaknesses in the player’s current evolutionary strategy. + +Examples: + +A high-metabolism lineage dies of starvation. + +Its descendants continue possessing that high metabolic demand and are therefore statistically more vulnerable to starvation. + +A lineage with poor toxin resistance dies from poison. + +Its descendants remain vulnerable unless mutation/divergence has occurred. + +A predator kills the player. + +That predator should also be capable of preying upon genetically similar descendants. + +Lineages should disappear because ecological pressures make them unsuccessful, not because the system arbitrarily removes them. + +⸻ + +7. THE WORLD SHOULD BEGIN BIOLOGICALLY EMPTY + +A new world/server may begin as a lifeless planet containing: + +* water, +* minerals, +* atmosphere, +* geological structures, +* energy sources, +* sunlight/starlight, +* chemistry, +* temperature gradients, +* hydrothermal or chemical energy sources. + +There need not initially be: + +* grass, +* trees, +* fish, +* plankton, +* deer, +* arbitrary NPC life. + +The long-term goal is: + +Every living lineage in the persistent world can ultimately trace its ancestry to organisms originally influenced or created by players. + +A forest existing years after server creation may descend from a lineage originally created by a player during the world’s earliest history. + +The game’s persistent “character” is effectively the world’s evolutionary history. + +⸻ + +8. ENERGY IS THE FUNDAMENTAL ECONOMY + +Avoid arbitrary RPG balancing wherever possible. + +Evolutionary advantages should cost something physically or biologically. + +Examples: + +More muscle: + +* increased force, +* greater resource consumption, +* increased oxygen requirement, +* increased mass. + +Armor: + +* increased protection, +* added mass, +* construction cost, +* possibly decreased mobility. + +Large brain: + +* increased behavioral capability, +* major metabolic cost. + +Flight: + +* mobility, +* escape advantages, +* enormous structural and energy requirements. + +Venom: + +* offensive benefit, +* biochemical production cost. + +Large body: + +* durability and predation advantages, +* major food requirements, +* slower reproduction. + +The biological economy should be dominated by: + +* energy, +* matter, +* nutrients, +* environmental constraints. + +The goal is for a large creature to be powerful only if the ecosystem can actually support it. + +⸻ + +9. 2D AND 3D SIMULATION DOMAINS + +The microscopic cellular phase will likely use a 2D simulation. + +The macroscopic multicellular phase will use a 3D simulation. + +These domains should NOT attempt to maintain direct physical one-to-one interaction across radically different scales. + +Instead, connect them ecologically. + +Example: + +Millions of microscopic photosynthetic organisms: + +micro-simulation population +→ aggregated plankton biomass +→ represented as food/resource density in the 3D ocean. + +A massive 3D organism dies: + +corpse biomass +→ decomposition/nutrients +→ affects microbial population models in the microscopic simulation. + +Thus: + +2D and 3D do not share literal physics. + +They share: + +* energy, +* nutrients, +* biomass, +* atmosphere, +* hydrology, +* ecology. + +The exact multicellular transition rules must be designed. + +⸻ + +10. VOXEL PLANET + +The macroscopic world should use a voxel-based planetary structure. + +The voxel system should ultimately allow the planet to be physically modified deep beneath the surface and potentially to its core. + +The intent is NOT a simplistic Minecraft cube aesthetic. + +Voxels are primarily the data representation. + +Visible terrain should eventually be reconstructed as smooth geometry using an appropriate surface extraction system such as: + +* Marching Cubes, +* Surface Nets, +* Dual Contouring, +* another justified algorithm. + +Do not commit to one algorithm without an ADR and prototype comparison. + +The world should be sparse and multi-resolution. + +Never allocate every voxel of the entire planet explicitly. + +Potential hierarchy: + +Planet +→ planetary cells +→ regions +→ chunks +→ active voxel data. + +Potential detail hierarchy: + +planetary simulation: +kilometer-scale aggregate cells + +regional simulation: +tens-of-meters scale + +active terrain: +meter-scale voxels + +fine interaction: +sub-meter generated/derived detail where necessary. + +Resolution should follow simulation relevance. + +⸻ + +11. PROCEDURAL BASE WORLD + PERSISTED MODIFICATIONS + +The world should have a deterministic procedural base. + +Example: + +Planet seed ++ +geological generation rules + +base terrain. + +Unmodified regions/chunks should be reproducible. + +Persistent storage should primarily contain: + +* world seed, +* geological state where required, +* modified chunks, +* voxel deltas, +* ecological/environmental changes, +* compacted snapshots. + +Conceptually: + +base generated chunk ++ +modification journal + +current chunk. + +Modification journals should periodically compact into new snapshots. + +⸻ + +12. VOXELS ARE ENVIRONMENTAL DATA + +A voxel should eventually be capable of representing more than “stone” or “dirt.” + +Potential properties include: + +* material identifier, +* density, +* temperature, +* moisture, +* water saturation, +* oxygen, +* carbon, +* nitrogen, +* phosphorus, +* salinity, +* organic matter, +* hardness, +* thermal conductivity, +* specific heat, +* chemical composition. + +DO NOT naïvely store dozens of 32-bit floats per voxel across the entire planet. + +Design data-oriented compact representations. + +Different voxel/material types may have different relevant fields. + +Far-away regions should use aggregate values rather than explicit high-resolution chemistry. + +⸻ + +13. BIOLOGY ↔ TERRAIN INTERACTION + +The environment must participate in biological simulation. + +Examples: + +Plants: + +* roots extract water/nutrients, +* photosynthetic surfaces capture light, +* canopies shade competitors, +* growth changes physical terrain. + +Burrowing organisms: + +* remove/displace matter, +* aerate soil, +* form caves/tunnels. + +Dead organisms: + +* become biomass, +* decompose, +* feed scavengers, +* return nutrients. + +Large herds: + +* consume vegetation, +* compact terrain, +* distribute nutrients. + +Long-lived ecosystems can gradually alter: + +* soil, +* atmosphere, +* water chemistry, +* erosion, +* sedimentation. + +The goal is eventually to allow biology to affect geology and geology to affect biology. + +⸻ + +14. GENOTYPE, DEVELOPMENT, PHENOTYPE + +These MUST be separate concepts. + +Pipeline: + +GENOTYPE +→ DEVELOPMENT +→ PHENOTYPE +→ PHYSICAL/BIOLOGICAL SIMULATION +→ FITNESS/REPRODUCTIVE SUCCESS. + +The genome describes developmental capabilities and parameters. + +Do not simulate literal real DNA. + +Instead implement an evolvable developmental genome suitable for gameplay. + +Possible categories: + +* metabolism, +* cellular structures, +* membrane, +* tissues, +* reproduction, +* digestion, +* sensory systems, +* locomotion, +* nervous systems, +* structural systems, +* immune/defensive systems, +* environmental tolerances, +* photosynthesis/chemosynthesis, +* morphology, +* growth, +* symmetry, +* organs. + +⸻ + +15. TRAITS MUST ALTER PHYSICAL/BIOLOGICAL PARAMETERS + +Avoid conventional effects like: + ++25 HP ++10% damage + +whenever possible. + +Prefer effects such as: + +skin thickness +2mm +muscle cross-sectional area increases +membrane rigidity changes +oxygen affinity changes +metabolic efficiency changes +enzyme temperature optimum changes. + +Derived systems then determine gameplay consequences. + +One mutation should potentially affect many systems. + +Example: + +Thicker armor: +→ added mass +→ increased protection +→ increased developmental material cost +→ increased movement cost +→ heat retention changes. + +This creates meaningful evolutionary tradeoffs. + +⸻ + +16. MUTATION GENERATION + +Mutation options should not be a static visible RPG tree. + +Candidate mutations may depend on: + +* current genome, +* phenotype, +* previous mutations, +* environmental conditions, +* player behavior, +* consumed resources, +* ecological pressures, +* developmental prerequisites. + +Concept: + +Current Genome ++ +Behavior ++ +Environmental Pressure ++ +Available Developmental Paths + +Candidate Mutations. + +Players should learn biological principles, not memorize a single guaranteed build order. + +The mutation system must remain deterministic/testable enough that it can be debugged. + +Randomness should use explicit seeded random generators. + +⸻ + +17. MULTICELLULAR MORPHOLOGY + +The eventual 3D creature creator should be conceptually similar to the freedom of Spore’s creature creator, but constrained by evolved biology. + +Players do not receive arbitrary body parts. + +They may manipulate structures their genome can actually develop. + +The underlying representation should probably be a body/development graph rather than just a mesh. + +Possible model: + +BodyGraph + +* nodes: + * tissue structures, + * body segments, + * organs, + * limbs, + * sensory structures, + * roots, + * leaves, + * reproductive organs. +* edges: + * anatomical attachment, + * joints, + * vascular connections, + * neural connections, + * developmental dependencies. + +The rendering system derives meshes from the phenotype. + +The physics system derives collision/mass structures. + +The locomotion system derives possible movement. + +The metabolic system derives maintenance costs. + +The damage system derives vulnerable structures. + +⸻ + +18. PROCEDURAL ANIMATION + +Because arbitrary evolved morphologies cannot rely on hand-authored animations, procedural locomotion must eventually exist. + +Possible systems: + +* inverse kinematics, +* procedural gait generation, +* center-of-mass control, +* foot placement, +* limb phase calculation, +* swimming propulsion, +* crawling, +* slithering, +* flying. + +A creature losing a limb should potentially cause its procedural movement system to compensate rather than merely playing a pre-authored animation. + +This is a later-stage R&D system and should NOT block the early cellular simulator. + +⸻ + +19. CUSTOM ENGINE REQUIREMENT + +DO NOT use: + +* Unreal Engine, +* Unity. + +The project will use a custom game/simulation engine. + +Do not build every low-level primitive unnecessarily. + +Using specialized libraries is allowed and encouraged where they provide clear value. + +Candidate technologies must be evaluated via ADRs. + +Primary implementation language: + +C++ + +Prefer a modern C++ standard supported consistently by our toolchain. + +Candidates should include C++23 where toolchain compatibility permits. + +Possible low-level dependencies to evaluate: + +Window/input: + +* SDL3 + +Graphics: + +* Vulkan directly + or +* another thin abstraction if strongly justified. + +Physics: + +* evaluate Jolt Physics or custom/specialized physics where appropriate. + +Audio: + +* lightweight library such as miniaudio. + +Developer UI: + +* Dear ImGui is acceptable for engineering/debug tooling. +* It is not automatically the final player UI. + +Serialization: +evaluate: + +* FlatBuffers, +* Protocol Buffers, +* Cap’n Proto, +* custom binary structures where justified. + +Do not introduce dependencies without documenting the reason. + +⸻ + +20. HEADLESS-FIRST SIMULATION ENGINE + +The most important software component is NOT the renderer. + +Create a graphics-independent simulation library. + +Potential name: + +libevo + +or an equivalent better project name. + +It must be usable by: + +* authoritative game server, +* headless ecosystem simulator, +* automated tests, +* benchmarking tools, +* client prediction where appropriate, +* offline development tools. + +Graphics must never be required to execute the biological simulation. + +Example conceptual API: + +SimulationWorld world; +world.tick(deltaTime); + +The headless simulation should eventually support commands like: + +evo-sim \ + --seed 123456 \ + --ticks 1000000 \ + --output simulation-results.json + +⸻ + +21. ECS / DATA-ORIENTED ARCHITECTURE + +The simulation should use a data-oriented Entity Component System or equivalent composition-based architecture. + +Do NOT construct a deep inheritance hierarchy such as: + +Animal +→ Mammal +→ Canine +→ Wolf. + +An organism should instead compose capabilities. + +Example entity: + +Entity + +* Transform +* Mass +* EnergyStorage +* Metabolism +* Genome +* Phenotype +* Locomotion +* Digestion +* SensorySystem +* ReproductiveSystem +* Health +* AIController. + +Photosynthetic organism: + +* Transform +* Mass +* EnergyStorage +* Genome +* Photosynthesis +* RootNetwork +* Reproduction +* ChemicalDefense. + +The engine should not require “Plant” and “Animal” base classes. + +Evaluate whether to: + +* build a minimal internal ECS, + or +* use a mature C++ ECS library. + +Create an ADR before deciding. + +⸻ + +22. SIMULATION DETERMINISM + +Deterministic behavior is highly valuable for: + +* debugging, +* regression tests, +* replay, +* server recovery, +* AI-written code validation, +* ecosystem comparison. + +Architect for deterministic simulation where practical. + +Requirements: + +* seeded PRNGs, +* no hidden use of global randomness, +* stable update ordering where necessary, +* explicit tick model, +* deterministic serialization where practical. + +Cross-platform floating-point exact determinism may not always be possible or desirable. + +Codex must document: + +* what is deterministic, +* what is approximately deterministic, +* what is intentionally nondeterministic. + +Create automated deterministic simulation regression tests. + +Example: + +same: + +* seed, +* initial state, +* simulation version, +* input stream + +should produce the same agreed result/hash where required. + +⸻ + +23. SIMULATION RESOLUTION / LEVEL OF DETAIL + +The MMO cannot simulate every organism at full fidelity globally. + +Implement conceptual simulation tiers. + +Tier 1 — Active entities + +Near players or otherwise important. + +Simulate: + +* position, +* velocity, +* physics, +* attacks, +* damage, +* perception, +* energy, +* individual reproduction, +* AI, +* interactions. + +Tier 2 — Local population simulation + +No longer maintain every individual. + +Represent: + +* genome/lineage, +* population, +* age distribution, +* biomass, +* average energy, +* reproduction, +* mortality, +* predation, +* migration. + +Tier 3 — Regional/planetary ecology + +Highly aggregated. + +Represent: + +* population density, +* biomass, +* resource consumption, +* nutrient flows, +* predator/prey relationships, +* environmental fitness, +* migration, +* atmosphere/environment contributions. + +Entities must be capable of: + +full entity +→ aggregate population + +and later: + +aggregate population +→ representative entities + +without changing the underlying genome identity. + +Design this carefully. + +⸻ + +24. SERVER AUTHORITATIVE NETWORK MODEL + +The server is authoritative. + +Clients may never authoritatively decide: + +* position, +* damage, +* energy, +* mutation, +* reproduction, +* genome state, +* resource collection, +* death. + +The client sends intentions/input. + +Example: + +InputFrame: + +* sequence, +* movement vector, +* orientation, +* action flags, +* interaction request. + +The server simulates the result. + +Client-side prediction may be used for responsiveness. + +The server sends: + +* snapshots, +* entity deltas, +* events, +* acknowledged input sequence. + +Implement: + +* prediction, +* reconciliation, +* interpolation, +* interest management. + +Do not make the client trusted. + +⸻ + +25. CUSTOM NETWORK STACK + +It is acceptable and likely expected to implement a custom real-time network backend. + +Separate concerns. + +Real-time simulation channel + +Likely UDP-based. + +Appropriate for: + +* movement, +* orientation, +* rapidly superseded entity state. + +Reliable gameplay channel + +Either: + +* reliable layer implemented over UDP, + or +* another justified mechanism. + +Used for: + +* mutation selection, +* reproduction events, +* death, +* region transitions, +* persistent biological decisions. + +Backend/API channel + +HTTPS and/or gRPC for: + +* Steam identity validation, +* account services, +* world selection, +* friends, +* lineage/history, +* administrative functions. + +Do not invent cryptography. + +Use established cryptographic libraries/protocols. + +Security design requires an ADR. + +⸻ + +26. NETWORK INTEREST MANAGEMENT + +Clients should only receive information they can meaningfully perceive. + +Evolutionary sensory abilities may eventually affect network relevance. + +Examples: + +Poor visual system: + +* no detailed distant visual entity state. + +Strong olfactory system: + +* receive directional scent field information rather than precise entity transforms. + +Echolocation: + +* receive derived acoustic perception information. + +This means the biological perception system and network interest-management system should eventually cooperate. + +Do not implement this complexity in Milestone 0. + +Design interfaces that will permit it later. + +⸻ + +27. WORLD PARTITIONING + +The planet must be partitioned into simulation regions. + +A region is owned at runtime by a simulation worker/server. + +Workers must NOT permanently own the persistent world state. + +Concept: + +World Director +→ assigns region +→ Region Server acquires lease +→ Region Server loads state +→ Region Server simulates +→ snapshots/events persisted. + +If the region process dies: + +lease expires +→ another worker acquires ownership +→ loads latest state +→ recovers +→ resumes. + +Kubernetes pods must be disposable. + +⸻ + +28. SEAMLESS REGION TRANSITION + +Eventually players must cross region boundaries without a traditional loading screen. + +Design for handoff: + +Region A owns organism. + +As boundary approaches: + +Region B receives ghost/shadow state. + +Then: + +authority transfers from A to B. + +Transition must avoid: + +* duplication, +* loss, +* two authoritative copies, +* exploit opportunities. + +This is not necessarily Milestone 0 implementation but architecture must account for it. + +⸻ + +29. PERSISTENCE MODEL + +Do NOT update PostgreSQL every simulation tick. + +Active simulation state lives primarily in process memory. + +Persistent world state should use combinations of: + +* snapshots, +* journals, +* durable events, +* checkpoints. + +Concept: + +snapshot ++ +events since snapshot + +current state. + +Region server crash recovery: + +load snapshot +→ replay persistent changes/events +→ resume. + +Determine where strict event sourcing is useful versus unnecessary complexity. + +Evolutionary history is particularly well-suited to durable event records. + +Potential events: + +* WORLD_CREATED +* GENOME_CREATED +* GENOME_MUTATED +* ORGANISM_REPRODUCED +* ORGANISM_DIED +* LINEAGE_CREATED +* SPECIATION_OCCURRED +* POPULATION_CHANGED +* LINEAGE_EXTINCT +* REGION_SNAPSHOT_CREATED. + +⸻ + +30. PHYLOGENETIC HISTORY + +Never permanently discard extinct genomes. + +The world should preserve its evolutionary history. + +The system should eventually support reconstructing: + +* parent genomes, +* child genomes, +* species/lineage divergence, +* population history, +* extinction events, +* common ancestors. + +Conceptually: + +Genome A +├─ Genome B +│ └─ Genome D +└─ Genome C +├─ Genome E +└─ Genome F + +This can power an in-game Tree of Life and historical tooling. + +⸻ + +31. INFRASTRUCTURE BASELINE + +Initial deployment environment: + +* Dell PowerEdge R730xd +* Kubernetes already available +* approximately 128 GB RAM +* additional hardware can be added later. + +The system must scale horizontally by adding physical Kubernetes nodes. + +Initial Kubernetes deployment may host most services on this one physical machine. + +Potential namespaces: + +* evolution-dev +* evolution-stage +* evolution-world0 + +world0 should be treated as persistent production-like state even when only developers/testers use it. + +Do not casually delete World 0. + +⸻ + +32. KUBERNETES SERVICE ARCHITECTURE + +Initial conceptual workloads: + +Platform/backend: + +* gateway/API +* account service +* identity integration +* genome service +* lineage service +* world director. + +Simulation: + +* active region servers, +* ecology workers, +* terrain/world workers, +* population workers. + +Infrastructure: + +* PostgreSQL, +* NATS JetStream, +* Redis if actually justified, +* object/blob storage, +* metrics, +* logging. + +Do NOT automatically create a microservice for every noun. + +Service boundaries should follow: + +* independent scaling requirements, +* failure domains, +* ownership/lifecycle differences, +* workload characteristics. + +A modular monolith is acceptable for early backend code where appropriate. + +Avoid distributed-systems complexity until there is a real benefit. + +⸻ + +33. MESSAGE BUS + +For early development, prefer evaluating: + +NATS JetStream + +before introducing Kafka. + +Potential events/topics: + +* world.region.assigned +* world.region.released +* organism.died +* organism.reproduced +* genome.created +* genome.extinct +* population.changed +* snapshot.completed. + +Kafka is not prohibited, but must not be introduced merely because this is an MMO. + +⸻ + +34. DATABASE + +PostgreSQL is the preferred initial relational source of truth. + +Potential persistent domains: + +* accounts, +* worlds, +* regions, +* genome metadata, +* lineages, +* evolutionary history, +* snapshot metadata, +* simulation versions, +* administrative records. + +Large chunk/snapshot binary payloads may belong in object storage rather than relational tables. + +Schema design must be versioned via migrations. + +⸻ + +35. OBJECT STORAGE + +Evaluate an S3-compatible system for: + +* voxel chunk snapshots, +* world snapshots, +* historical archives, +* simulation outputs, +* telemetry archives, +* large generated data. + +On the development cluster, MinIO or another suitable implementation may be evaluated. + +Do not store arbitrary huge binary blobs in PostgreSQL without justification. + +⸻ + +36. REDIS + +Redis is optional. + +Use it only for appropriate ephemeral workloads such as: + +* sessions, +* transient caches, +* routing hints, +* distributed short-lived state. + +Redis must not become the only durable copy of important world state. + +⸻ + +37. OBSERVABILITY + +Observability is mandatory from early development. + +Evaluate/use: + +* Prometheus, +* Grafana, +* Loki, +* OpenTelemetry where appropriate. + +Potential world metrics: + +* current players, +* active regions, +* active entities, +* known genomes, +* living lineages, +* extinct lineages, +* total biomass, +* photosynthetic energy capture, +* atmospheric oxygen, +* atmospheric carbon dioxide, +* decomposition rate, +* birth/death rates. + +Simulation metrics: + +* tick duration, +* worst region tick, +* entity count, +* ECS system timings, +* ecology worker backlog, +* chunk generation latency, +* network bandwidth. + +Infrastructure metrics: + +* CPU, +* memory, +* disk latency, +* storage capacity, +* packet loss, +* pod restarts, +* database performance. + +Instrumentation must be treated as part of engineering, not an afterthought. + +⸻ + +38. NODE SPECIALIZATION + +The initial server may run everything. + +The architecture must later permit Kubernetes node labels/affinities such as: + +* realtime simulation, +* background biosimulation, +* storage, +* database, +* GPU/compute if ever justified. + +Adding another physical server should increase available scheduling capacity without requiring game architecture changes. + +⸻ + +39. CI/CD + +Design a production-quality pipeline. + +Likely conceptual pipeline: + +Git commit +→ configure/build +→ compiler warnings +→ formatting validation +→ static analysis +→ unit tests +→ property tests +→ deterministic simulation tests +→ sanitizers +→ integration tests +→ ecosystem regression tests +→ benchmarks +→ container build +→ registry +→ development deployment +→ soak tests +→ staging +→ manual promotion to World 0/production. + +The project’s existing infrastructure experience favors: + +* container registry such as Harbor, +* Argo CD, +* Argo Workflows, +* GitOps deployment. + +Design with these technologies unless there is a strong documented reason not to. + +⸻ + +40. AI-ASSISTED DEVELOPMENT + +Most C++ implementation may be generated with AI systems such as Codex and Claude. + +Therefore repository structure and engineering rules must explicitly defend against AI-generated architectural drift. + +The authoritative order should be: + +1. architecture documentation, +2. ADRs, +3. public interfaces/contracts, +4. tests, +5. implementation. + +Never allow generated implementation to silently redefine architecture. + +⸻ + +41. ENGINEERING CONSTITUTION + +Create: + +docs/engineering/ENGINEERING_CONSTITUTION.md + +It must define at minimum: + +* supported C++ version, +* naming conventions, +* formatting, +* dependency policy, +* ownership model, +* pointer rules, +* threading policy, +* exception policy, +* error handling, +* logging, +* assertions, +* serialization rules, +* coordinate systems, +* units, +* deterministic randomness, +* simulation tick rules, +* floating-point expectations, +* API stability, +* testing requirements, +* documentation requirements, +* security expectations. + +Suggested ownership rules to evaluate: + +* values by default, +* std::unique_ptr for exclusive ownership, +* avoid std::shared_ptr unless shared lifetime is actually necessary, +* raw pointers/references only as non-owning observers. + +Use RAII. + +Avoid manually paired allocation/free operations. + +⸻ + +42. ERROR HANDLING + +Do not allow random inconsistency between: + +* exceptions, +* return bool, +* nullable values, +* error codes. + +Establish explicit rules. + +Consider std::expected for normal recoverable failures. + +Reserve exceptions for appropriate boundaries. + +Create an ADR. + +⸻ + +43. THREADING + +Threading rules must be defined BEFORE implementing complicated concurrency. + +Do not permit arbitrary components to spawn threads. + +Create explicit scheduler/thread ownership. + +Potential categories: + +* simulation thread(s), +* job system, +* networking IO, +* persistence/background IO, +* rendering. + +Avoid lock-free cleverness without proven need. + +AI-generated lock-free code must be considered high-risk. + +Use profilers before introducing complexity. + +⸻ + +44. TESTING REQUIREMENTS + +Testing is mandatory because large amounts of code may be AI-generated. + +Required categories: + +* unit tests, +* integration tests, +* property-based tests, +* fuzz tests where suitable, +* deterministic simulation tests, +* serialization round-trip tests, +* network protocol tests, +* load tests, +* crash recovery tests, +* benchmarks. + +Biological invariants should be testable. + +Examples: + +* energy cannot spontaneously appear except through defined external sources, +* mass cannot be negative, +* population cannot be negative, +* reproduction requires sufficient matter/energy, +* mutation prerequisites must be satisfied, +* dead organisms cannot perform active actions, +* ownership of an entity must be unique, +* region authoritative ownership cannot exist simultaneously in two servers. + +⸻ + +45. SANITIZERS / STATIC ANALYSIS + +Development and CI should use: + +* AddressSanitizer, +* UndefinedBehaviorSanitizer, +* ThreadSanitizer in dedicated jobs, +* clang-tidy, +* clang-format. + +Use strong warnings such as: + +* Wall, +* Wextra, +* Wpedantic. + +Decide carefully whether warnings-as-errors applies universally or only CI/owned code due to third-party dependency warnings. + +⸻ + +46. PERFORMANCE + +Performance matters but premature optimization is prohibited. + +Every serious optimization should ideally follow profiling. + +Create benchmark suites early. + +Likely hot areas later: + +* ECS iteration, +* spatial indexing, +* active entity simulation, +* voxel access, +* terrain meshing, +* network serialization, +* ecology calculations, +* procedural generation. + +Data layout must be considered from the beginning. + +⸻ + +47. SIMULATION VERSIONING + +The persistent world must know which simulation rules generated its state. + +Store an explicit simulation version. + +Example: + +biology-engine: 0.4.0 +world-format: 0.2.0 +network-protocol: 0.3.0. + +Changing biological rules can catastrophically alter the persistent ecosystem. + +Therefore production simulation upgrades require: + +production snapshot +→ clone +→ migrate +→ run accelerated simulation +→ compare ecology +→ approve +→ production migration. + +Do not casually canary different physical laws between adjacent regions of the same live world. + +⸻ + +48. WORLD CLONING + +The architecture should support cloning a persistent world snapshot into: + +* staging, +* development, +* simulation experiments. + +This will be used for: + +* biological algorithm changes, +* schema migrations, +* ecosystem regression testing, +* disaster recovery exercises. + +⸻ + +49. BACKUPS / DISASTER RECOVERY + +Design from the beginning for: + +* PostgreSQL backup, +* object-storage backup, +* world snapshots, +* snapshot verification, +* restore testing, +* retention, +* corruption detection. + +A power outage or Kubernetes restart must not reset world history. + +Region pods must recover automatically. + +⸻ + +50. STEAM + +The final client will be distributed through Steam. + +This is NOT a browser game. + +Steam integration is not part of Milestone 0. + +Later requirements include: + +* Steam identity/authentication, +* distribution, +* patch/update process, +* friends integration where appropriate, +* dedicated server considerations. + +The core account/world architecture must not be unnecessarily coupled directly to Steam APIs. + +Create a provider abstraction for identity where reasonable. + +⸻ + +51. SECURITY + +Threat model includes: + +* modified clients, +* fabricated packets, +* replay attacks, +* speed hacks, +* invalid mutation requests, +* impossible reproduction, +* duplicated region state, +* API abuse, +* compromised game-server process. + +Server authority should eliminate many client cheats. + +Security must include: + +* authenticated sessions, +* protocol validation, +* bounds checking, +* rate limiting, +* server-side validation, +* least privilege, +* Kubernetes RBAC, +* secrets handling. + +Never trust serialized client structures blindly. + +⸻ + +52. PROPOSED REPOSITORY STRUCTURE + +Do not treat this as immutable, but begin from something conceptually like: + +aeternalis-evolution/ +├── CMakeLists.txt +├── cmake/ +├── docs/ +│ ├── architecture/ +│ ├── adr/ +│ ├── engineering/ +│ ├── biology/ +│ ├── networking/ +│ ├── world/ +│ └── infrastructure/ +│ +├── src/ +│ ├── core/ +│ │ ├── math/ +│ │ ├── logging/ +│ │ ├── serialization/ +│ │ ├── jobs/ +│ │ └── time/ +│ │ +│ ├── simulation/ +│ │ ├── ecs/ +│ │ ├── scheduler/ +│ │ └── spatial/ +│ │ +│ ├── biology/ +│ │ ├── genome/ +│ │ ├── development/ +│ │ ├── phenotype/ +│ │ ├── metabolism/ +│ │ ├── reproduction/ +│ │ ├── mutation/ +│ │ └── ecology/ +│ │ +│ ├── world/ +│ │ ├── planet/ +│ │ ├── voxel/ +│ │ ├── terrain/ +│ │ ├── geology/ +│ │ ├── climate/ +│ │ └── resources/ +│ │ +│ ├── network/ +│ │ ├── transport/ +│ │ ├── protocol/ +│ │ ├── replication/ +│ │ └── interest/ +│ │ +│ ├── persistence/ +│ │ ├── snapshots/ +│ │ ├── events/ +│ │ └── database/ +│ │ +│ ├── server/ +│ │ ├── world_director/ +│ │ ├── region_server/ +│ │ └── ecology_worker/ +│ │ +│ ├── render/ +│ │ ├── graphics/ +│ │ ├── terrain/ +│ │ └── organism/ +│ │ +│ └── client/ +│ ├── input/ +│ ├── camera/ +│ └── ui/ +│ +├── apps/ +│ ├── evo-sim/ +│ ├── evo-server/ +│ ├── evo-client/ +│ └── evo-tools/ +│ +├── tests/ +│ ├── unit/ +│ ├── integration/ +│ ├── simulation/ +│ ├── determinism/ +│ ├── fuzz/ +│ └── benchmarks/ +│ +├── schemas/ +├── migrations/ +├── deploy/ +│ ├── docker/ +│ ├── kubernetes/ +│ ├── argocd/ +│ └── workflows/ +│ +└── tools/ + +It may be better to split infrastructure/backend repositories later. + +Do not prematurely create many repositories. + +Start with a structure that makes refactoring/splitting possible. + +⸻ + +53. INITIAL DEVELOPMENT MILESTONES + +MILESTONE 0 — Engineering Foundation + +Goal: + +Create an excellent C++ repository that AI agents can safely extend. + +Deliver: + +* CMake build, +* dependency strategy, +* engineering constitution, +* ADR framework, +* clang-format, +* clang-tidy, +* sanitizers, +* testing framework, +* benchmark framework, +* logging, +* basic metrics abstraction, +* CI skeleton, +* containerized headless build. + +No renderer required. + +⸻ + +MILESTONE 1 — Universal Simulation Kernel + +Create: + +* deterministic tick loop, +* basic ECS, +* entity identifiers, +* component lifecycle, +* job/scheduler foundation, +* seeded RNG service, +* units system, +* basic spatial representation. + +Demonstrate: + +create entity +→ tick simulation +→ serialize +→ restore +→ same deterministic result. + +⸻ + +MILESTONE 2 — Minimal Energy Ecosystem + +Create a simple headless world containing: + +* external energy source, +* resource matter, +* autotroph-like organism, +* consumer organism, +* death, +* decomposition, +* reproduction. + +Demonstrate: + +energy source +→ producer +→ consumer +→ death +→ nutrients +→ producer. + +Run thousands/millions of ticks. + +Expose metrics. + +⸻ + +MILESTONE 3 — Genome v0.1 + +Implement the first developmental genome. + +Initial scope may contain: + +* energy strategy, +* membrane, +* movement, +* ingestion, +* reproduction, +* size, +* environmental tolerance. + +Create: + +Genome +→ Development +→ Phenotype. + +Mutations alter genome. + +Phenotype derives simulation components. + +No arbitrary RPG modifiers. + +⸻ + +MILESTONE 4 — Population Abstraction + +Implement: + +* entity population collapse, +* aggregated population representation, +* background population simulation, +* re-materialization of representatives. + +Demonstrate: + +100 individual organisms +→ collapse into population +→ simulate 10,000 ticks +→ expand into representative organisms. + +Conservation/invariant testing required. + +⸻ + +MILESTONE 5 — Basic Voxel World + +Implement a small experimental voxel environment. + +Initial test volume may be: + +100×100×100 or chunk-based equivalent. + +Support: + +* material types, +* sparse chunks, +* deterministic generation, +* modification, +* snapshot, +* restore. + +Do not initially implement planet-scale geometry. + +⸻ + +MILESTONE 6 — Environmental Resources + +Connect voxel/environment data to organisms. + +Implement limited variables such as: + +* energy/light, +* moisture, +* one or two nutrients, +* organic matter. + +Demonstrate: + +organisms consume environmental resources +→ reproduce +→ die +→ decomposition returns resources. + +⸻ + +MILESTONE 7 — Persistent Region Server + +Create first authoritative headless region server. + +Implement: + +* active world ownership, +* simulation ticks, +* snapshotting, +* crash recovery, +* event persistence, +* health/readiness endpoints, +* metrics. + +Containerize it. + +⸻ + +MILESTONE 8 — Kubernetes World 0 + +Deploy to development Kubernetes. + +Initial workloads: + +* PostgreSQL, +* NATS JetStream if adopted, +* object storage if adopted, +* world director, +* region server, +* Prometheus/Grafana, +* logging. + +Create: + +* dev, +* stage, +* world0 environments. + +Demonstrate deleting the active region-server pod and automatically restoring world state. + +⸻ + +MILESTONE 9 — Custom 2D Client + +Begin graphical client. + +Implement only what cellular gameplay requires: + +* window/input, +* renderer, +* camera, +* UI debugging, +* network connection, +* basic organism rendering, +* environment rendering. + +Avoid building unnecessary 3D engine systems yet. + +⸻ + +MILESTONE 10 — Real-Time Multiplayer Cell Simulation + +Implement: + +* UDP transport, +* snapshots, +* input commands, +* prediction, +* reconciliation, +* interpolation, +* server authority, +* several simultaneous players. + +Demonstrate: + +20+ simulated clients. + +Then stress test much higher. + +⸻ + +MILESTONE 11 — Actual Cellular Gameplay + +Implement the first genuinely playable loop: + +* movement, +* feeding, +* energy, +* predation, +* reproduction, +* mutation selection, +* death, +* total restart, +* NPC descendants. + +This is the first milestone where the project should be judged primarily on FUN rather than architecture. + +⸻ + +MILESTONE 12 — Persistent Ecology + +NPC descendants persist. + +Implement: + +* player-derived lineages, +* population simulation, +* ecology during player absence, +* lineage extinction, +* historical genealogy. + +Test worlds should run unattended for days. + +Analyze: + +* runaway lineages, +* ecosystem collapse, +* starvation, +* predator/prey cycles, +* diversity. + +⸻ + +MILESTONE 13 — 3D Technology R&D + +Only after the cellular world is compelling. + +Research/prototype: + +* 3D renderer, +* smooth voxel terrain, +* body graph, +* procedural organism mesh, +* procedural locomotion, +* multicellular development. + +Do not prematurely integrate everything. + +Create isolated R&D prototypes. + +⸻ + +MILESTONE 14 — Multicellular Transition + +Build the first vertical slice where a player can: + +single cell +→ multicellular organism +→ enter 3D world. + +This is a major project milestone. + +⸻ + +54. FIRST PLAYABLE TARGET + +The first serious playable product is NOT: + +an entire evolutionary history from cell to civilization. + +The first target is: + +a compelling persistent cellular MMO ecosystem. + +Success criteria: + +* cellular movement feels good, +* feeding is interesting, +* predators/prey matter, +* mutation choices create meaningful tradeoffs, +* reproduction matters, +* player-derived descendants affect the world, +* permadeath is emotionally meaningful, +* repeated cellular lives do not feel identical, +* persistent ecology changes between play sessions. + +Only then expand aggressively into multicellularity. + +⸻ + +55. WHAT NOT TO DO + +Do NOT: + +* use Unreal, +* use Unity, +* create conventional RPG classes, +* create a visible linear evolution tree, +* make intelligence the mandatory endgame, +* distinguish NPCs with obvious UI labels, +* let offline characters farm progression, +* persist every simulation tick to PostgreSQL, +* simulate every world organism individually, +* allocate an entire planet’s voxels explicitly, +* build a renderer before validating simulation fundamentals, +* introduce Kafka because “MMOs use Kafka,” +* create 30 microservices immediately, +* create custom cryptography, +* use hand-authored creature animations as the fundamental movement solution, +* let AI implementation silently redefine architecture, +* optimize before measuring, +* sacrifice deterministic testability unnecessarily. + +⸻ + +56. OPEN DESIGN QUESTIONS + +Do not silently choose answers. + +Create design documents/ADRs for major unresolved items. + +Important questions include: + +1. Exact simulation tick frequency. +2. Fixed vs variable timestep boundaries. +3. ECS implementation. +4. C++ dependency management. +5. Units library. +6. Determinism guarantees. +7. Mutation-generation algorithm. +8. Genome representation. +9. Developmental body representation. +10. Reproductive mutation/heredity rules. +11. Whether autonomous NPC descendants mutate. +12. Definition of species/speciation. +13. Definition of lineage extinction. +14. Offline player-state handling. +15. Cellular-to-multicellular transition criteria. +16. Population abstraction math. +17. Active-region dimensions. +18. World/planet coordinate system. +19. Spherical planet voxel strategy. +20. Voxel LOD. +21. Surface meshing. +22. Hydrology. +23. Atmospheric model. +24. Cross-region ownership. +25. Network reliability layer. +26. Serialization. +27. Snapshot/event format. +28. Region recovery. +29. Cross-version simulation migration. +30. Steam identity integration. +31. Friend identification without NPC/player labels. +32. Anti-cheat boundaries. +33. AI behavior architecture. +34. Whether behavior itself can evolve genetically. +35. Player-designed morphology constraints. +36. Procedural animation strategy. +37. Persistence retention policies. +38. Disaster recovery objectives. + +⸻ + +57. DOCUMENTATION REQUIRED BEFORE MAJOR IMPLEMENTATION + +Create at minimum: + +docs/ +├── PROJECT_VISION.md +├── ROADMAP.md +├── engineering/ +│ └── ENGINEERING_CONSTITUTION.md +├── architecture/ +│ ├── SYSTEM_OVERVIEW.md +│ ├── SIMULATION_ARCHITECTURE.md +│ ├── WORLD_ARCHITECTURE.md +│ ├── PERSISTENCE_ARCHITECTURE.md +│ ├── NETWORK_ARCHITECTURE.md +│ └── INFRASTRUCTURE_ARCHITECTURE.md +├── biology/ +│ ├── GENOME_MODEL.md +│ ├── ENERGY_MODEL.md +│ ├── REPRODUCTION_MODEL.md +│ └── ECOLOGY_MODEL.md +└── adr/ + +Do not make these vague essays. + +Include: + +* diagrams, +* interfaces, +* invariants, +* alternatives, +* tradeoffs, +* failure modes. + +⸻ + +58. ADR FORMAT + +Each significant architectural choice should produce an ADR. + +Example: + +ADR-0001: C++ Language Standard +ADR-0002: Build System +ADR-0003: ECS Strategy +ADR-0004: Simulation Tick Model +ADR-0005: Random Number Strategy +ADR-0006: Serialization Format +ADR-0007: Network Transport +ADR-0008: Voxel Storage Model +ADR-0009: Persistence Strategy +ADR-0010: Message Bus + +ADR structure: + +* Context +* Decision +* Alternatives Considered +* Benefits +* Costs +* Risks +* Consequences +* Status + +⸻ + +59. AI AGENT WORK RULES + +Before editing code: + +1. Read relevant architecture docs. +2. Read relevant ADRs. +3. Inspect existing interfaces. +4. Inspect related tests. +5. State affected modules. +6. Preserve module boundaries. + +When introducing a dependency: + +* justify it, +* add an ADR if architecturally meaningful, +* pin/version appropriately. + +When changing a public interface: + +* explain why, +* update docs, +* update tests. + +When discovering architectural conflict: + +STOP expanding implementation. + +Document the conflict. + +Propose resolution. + +Do not silently route around architecture. + +⸻ + +60. IMPLEMENTATION QUALITY RULE + +Every milestone should leave the repository in a buildable, testable state. + +Prefer: + +small correct increments + +over: + +large speculative code dumps. + +Never create thousands of lines of placeholder architecture merely to make the repository look complete. + +Implement real vertical behavior. + +⸻ + +61. FIRST ASSIGNMENT + +Do NOT immediately implement gameplay. + +Perform the following in order. + +Step 1 — Analyze this project brief + +Produce: + +* concise project summary, +* architectural pillars, +* hard requirements, +* assumptions, +* open questions, +* largest technical risks. + +Do not reinterpret locked decisions. + +⸻ + +Step 2 — Produce the initial architecture + +Create: + +* system-context diagram, +* component diagram, +* runtime topology, +* data-flow diagram, +* simulation hierarchy, +* Kubernetes topology, +* persistence flow, +* region ownership flow. + +Mermaid diagrams are acceptable for documentation. + +⸻ + +Step 3 — Create initial ADR proposals + +At minimum evaluate: + +* C++23/toolchain, +* CMake, +* package/dependency manager, +* test framework, +* ECS strategy, +* logging, +* serialization, +* PostgreSQL client, +* metrics, +* NATS, +* voxel storage, +* deterministic PRNG. + +Do not choose libraries merely because they are popular. + +Consider: + +* maturity, +* performance, +* maintenance, +* licensing, +* portability, +* AI coding ergonomics, +* binary size, +* complexity. + +⸻ + +Step 4 — Create a phased implementation plan + +Break Milestones 0–4 into actionable engineering tasks. + +Each task must include: + +* objective, +* files/modules affected, +* dependencies, +* completion criteria, +* tests, +* risks. + +Tasks should usually be small enough to complete and review independently. + +⸻ + +Step 5 — Scaffold Milestone 0 + +After the design documents exist, begin repository setup. + +Expected initial outcome: + +project configures +project compiles +tests run +static analysis runs +sanitizer configuration exists +CI structure exists +documentation exists + +Create only minimal application targets such as: + +* evo-sim +* supporting libraries. + +⸻ + +Step 6 — Implement the smallest simulation proof + +Create the smallest deterministic simulation demonstrating: + +* simulation ticks, +* entity/component state, +* seeded randomness, +* serialization, +* restore, +* deterministic verification. + +No graphics. + +No networking. + +No Kubernetes dependency inside the simulation library. + +⸻ + +62. RESPONSE STYLE + +Do not respond to this project with generic game-development advice. + +Think like an engineer building a long-lived production system. + +Be opinionated, but distinguish: + +LOCKED REQUIREMENT +from +RECOMMENDATION +from +EXPERIMENT. + +When a simpler architecture accomplishes the same objective, prefer it. + +When complexity is required for the persistent-world vision, do not avoid it merely because it is difficult. + +The project is intentionally ambitious. + +The goal is to make that ambition manageable through strong boundaries, testing, simulation abstraction, and incremental implementation. + +⸻ + +63. NORTH STAR + +The ultimate intended experience is: + +A player enters a planet whose entire biological history was created by previous evolutionary success and failure. + +They begin as a single cell. + +They struggle for energy. + +They reproduce. + +Their descendants enter the ecosystem. + +They mutate. + +Perhaps they become photosynthetic. + +Perhaps predatory. + +Perhaps multicellular. + +Perhaps eventually enormous. + +Perhaps they create a lineage that survives for real-world years. + +Eventually they die. + +Their organism is gone permanently. + +The ecosystem remains. + +They begin again as a primitive cell in a world shaped partly by their previous lives. + +The world itself is the persistent protagonist. + +Build the technology that makes that possible. \ No newline at end of file diff --git a/docs/OpenAI_ChatLog.md b/docs/OpenAI_ChatLog.md new file mode 100644 index 0000000..e802577 --- /dev/null +++ b/docs/OpenAI_ChatLog.md @@ -0,0 +1,830 @@ +I’ll establish the architecture and decision record first, then build a small headless simulation proof with replay and restore checks. I’ll inspect the repository and available toolchain before deciding what can be validated here, and keep unresolved game-design choices explicit. + + + + +Ran Get-Location; rg --files --hidden -g '!\.git' -g 'AGENTS.md' -g 'CMakeLists.txt' -g 'README*' -g '*.md' -g 'CMakePresets.json'; git status --short; Get-Command cmake, ninja, clang++, clang-format, clang-tidy, g++, cl, python, docker -ErrorAction SilentlyContinue | Select-Object Name, Source + + + + +Infra architecture, Biology world and Tooling adrs started working + + Ran commands, searched the web + + +The workspace is empty, and Visual Studio provides a usable C++ toolchain. I’m separating firm requirements from provisional choices: the first executable will test deterministic ticks, component state, seeded randomness, and snapshot recovery. It will contain no gameplay rules. +The architecture work is also making durability explicit: acknowledging a permanent death must mean that recovery cannot bring the organism back. + + + + +Edited files, ran commands + + +Tooling adrs, Infra architecture and Biology world updated + +The vision, module boundaries, simulation contract, engineering constitution, and M0–M4 task plan are written. The design keeps irreversible biological outcomes behind a durable commit boundary, and requires entity-to-population conversion to preserve resources and unique ownership. +Library choices are being recorded with scope limits. The proof will use only the standard library; the final ECS, network transport, serialization, and terrain mesher remain decisions with explicit evaluation gates. + + + + + Ran commands, searched the web + + +Tooling adrs updated + +Ran rg --files docs + + + + +Tooling adrs updated + +Edited a file, ran a command + + +I’m defining a frozen deterministic fixture before writing the kernel. An independent reference calculation now specifies the expected positions and state fingerprint after 1,000 ticks, so the test will check more than agreement between two runs of the same code. +One dependency finding affects the infrastructure proposal: MinIO’s community repository is archived. The design retains an S3-compatible storage boundary and leaves the deployed storage implementation open. + + + + +Edited a file, ran a command + + +Infra architecture and Biology world updated + + Ran commands + + +Tooling adrs updated + +The proof’s decoder contract now rejects malformed lengths, unsupported versions, invalid IDs, out-of-range coordinates, and checksum failures before publishing restored state. Recovery checks will compare canonical bytes as well as a state fingerprint. +The available native tools are MSVC 19.44, CMake 3.31.6, and LLVM 19.1.5. Ubuntu has no compiler installed, and Docker’s daemon is stopped; I’ll report those validation limits explicitly. + + + + +Infra architecture updated + +Infra architecture, Biology world and Tooling adrs updated + +The delegated document writes stalled in the tool layer. I’ve stopped those calls and am collecting the prepared drafts for writing through this session. The scope remains the architecture, foundation tooling, and a local simulation proof. + + + + + Ran commands + + +Biology world, Tooling adrs and Infra architecture updated + +Biology world, Tooling adrs and Infra architecture updated + +Edited files + + +Tooling adrs updated + +Edited files + + +Biology world finished + +Edited files + + + +You've hit your usage limit. Upgrade your plan or add credits to continue, or try again at 6:56 PM. + + + + + + + Edited 26 files+1,438-0Review changesUndoReview + +docs/PROJECT_VISION.mddocs/PROJECT_VISION.md+70-0 +docs/architecture/OPEN_QUESTIONS.mddocs/architecture/OPEN_QUESTIONS.md+50-0 +docs/architecture/SIMULATION_ARCHITECTURE.mddocs/architecture/SIMULATION_ARCHITECTURE.md+109-0 +docs/architecture/SYSTEM_OVERVIEW.mddocs/architecture/SYSTEM_OVERVIEW.md+98-0 +docs/engineering/ENGINEERING_CONSTITUTION.mddocs/engineering/ENGINEERING_CONSTITUTION.md+39-0 +AGENTS.mdAGENTS.md+24-0 +docs/ROADMAP.mddocs/ROADMAP.md+90-0 +schemas/proof-snapshot.mdschemas/proof-snapshot.md+10-0 +docs/engineering/TEST_STRATEGY.mddocs/engineering/TEST_STRATEGY.md+35-0 +README.mdREADME.md+85-0 +docs/architecture/WORLD_ARCHITECTURE.mddocs/architecture/WORLD_ARCHITECTURE.md+105-0 +docs/biology/GENOME_MODEL.mddocs/biology/GENOME_MODEL.md+78-0 +docs/adr/0001-language-toolchain.mddocs/adr/0001-language-toolchain.md+34-0 +docs/adr/0002-build-system.mddocs/adr/0002-build-system.md+34-0 +docs/adr/0003-dependencies.mddocs/adr/0003-dependencies.md+34-0 +docs/adr/0004-test-benchmark-framework.mddocs/adr/0004-test-benchmark-framework.md+34-0 +docs/adr/README.mddocs/adr/README.md+20-0 +docs/adr/0005-ecs-strategy.mddocs/adr/0005-ecs-strategy.md+34-0 +docs/adr/0006-tick-model.mddocs/adr/0006-tick-model.md+34-0 +docs/adr/0007-prng.mddocs/adr/0007-prng.md+34-0 +docs/adr/0008-serialization.mddocs/adr/0008-serialization.md+34-0 +docs/adr/0009-units-coordinates.mddocs/adr/0009-units-coordinates.md+34-0 +docs/adr/0019-voxel-storage-and-meshing.mddocs/adr/0019-voxel-storage-and-meshing.md+54-0 +docs/biology/ECOLOGY_MODEL.mddocs/biology/ECOLOGY_MODEL.md+97-0 +docs/biology/ENERGY_MODEL.mddocs/biology/ENERGY_MODEL.md+88-0 +docs/biology/REPRODUCTION_MODEL.mddocs/biology/REPRODUCTION_MODEL.md+80-0 +Collapse files + + + + + + + +Today 1:54 PM +Proceed. + + + + + + + +1:54 PM + + + + + + +Worked for 1h 26m 25s + + + +I’m continuing with the foundation. The implementation will affect only core value types, the headless simulation, its local snapshot codec, CLI telemetry, tests, and build tooling. I’ll use the documented fixture to verify the kernel, then run compilation, static analysis, formatting, and supported sanitizer checks. + + + + +Edited files + + +Infra architecture updated + +Ran Get-Content AGENTS.md,docs/engineering/ENGINEERING_CONSTITUTION.md,docs/architecture/SIMULATION_ARCHITECTURE.md,docs/adr/0005-ecs-strategy.md,docs/adr/0007-prng.md,docs/adr/0008-serialization.md,docs/adr/0010-error-handling.md,docs/adr/0011-thread-ownership.md; rg --files include src tests -ErrorAction SilentlyContinue + + + + +Infra architecture updated + +Ran git status --short; rg --files docs/architecture + + + + +The biology, world, and technology records are now in the repository. Two constraints are explicit: population conversion must preserve funded inventory, and permanent extinction cannot be inferred from a regional zero count while viable organisms, spores, suspended organisms, or transfers remain. +I’m finishing the persistence and deployment contracts, then applying the prepared kernel and tests. + + + + +Infra architecture finished + +Edited files, ran a command + + +Biology world and Infra architecture finished + +Edited files + + +The independent review found a CLI file-safety issue: different filenames can be hard links to the same file. I’m adding identity checks and a regression test so an output report cannot overwrite a snapshot. +The architecture review also tightened recovery: checkpoints must contain committed state, and host-loss recovery needs the complete causal state chain. Retaining death records alone is insufficient to restore a consistent ecosystem. + + + + +Edited files + + +Tooling adrs updated + +Edited files, ran a command + + +Tooling adrs updated + + Ran commands + + +Tooling adrs and Infra architecture updated + +Infra architecture finished + +Edited files, ran commands + + +The first native build passes all five CTest entries, including the frozen simulation result, restore continuation, malformed snapshots, Release-safe test harness check, and CLI file round trips. +The 1,000-tick run matches the independently calculated fingerprint d61ad5bf0c928c76. I’m checking Release, static analysis, and AddressSanitizer next. + + + + +Edited files, ran commands + + + +You've hit your usage limit. Upgrade your plan or add credits to continue, or try again at 6:56 PM. + + + + + + + Edited 37 files+1,974-32Review changesUndoReview + +docs/adr/0010-error-handling.mddocs/adr/0010-error-handling.md+34-0 +docs/adr/0011-thread-ownership.mddocs/adr/0011-thread-ownership.md+34-0 +docs/adr/0012-logging.mddocs/adr/0012-logging.md+34-0 +docs/adr/0013-postgresql-client.mddocs/adr/0013-postgresql-client.md+34-0 +docs/adr/0014-message-bus.mddocs/adr/0014-message-bus.md+34-0 +docs/adr/0015-observability.mddocs/adr/0015-observability.md+34-0 +docs/adr/DEPENDENCY_EVALUATION.mddocs/adr/DEPENDENCY_EVALUATION.md+26-0 +docs/architecture/INFRASTRUCTURE_ARCHITECTURE.mddocs/architecture/INFRASTRUCTURE_ARCHITECTURE.md+104-0 +docs/architecture/NETWORK_ARCHITECTURE.mddocs/architecture/NETWORK_ARCHITECTURE.md+81-0 +docs/architecture/PERSISTENCE_ARCHITECTURE.mddocs/architecture/PERSISTENCE_ARCHITECTURE.md+149-5 +docs/infrastructure/OPERATIONS.mddocs/infrastructure/OPERATIONS.md+74-5 +docs/adr/0016-persistence-and-region-ownership.mddocs/adr/0016-persistence-and-region-ownership.md+34-0 +docs/adr/0017-network-security.mddocs/adr/0017-network-security.md+34-0 +docs/adr/0018-infrastructure-services.mddocs/adr/0018-infrastructure-services.md+34-0 +include/evo/core/random.hppinclude/evo/core/random.hpp+30-0 +include/evo/core/types.hppinclude/evo/core/types.hpp+49-1 +include/evo/simulation/world.hppinclude/evo/simulation/world.hpp+47-0 +include/evo/telemetry/sinks.hppinclude/evo/telemetry/sinks.hpp+34-0 +src/simulation/snapshot.cppsrc/simulation/snapshot.cpp+115-0 +src/simulation/world.cppsrc/simulation/world.cpp+47-0 +apps/evo-sim/main.cppapps/evo-sim/main.cpp+216-16 +tests/benchmarks/simulation_benchmark.cpptests/benchmarks/simulation_benchmark.cpp+46-1 +tests/fuzz/snapshot_fuzz.cpptests/fuzz/snapshot_fuzz.cpp+23-0 +tests/simulation_tests.cpptests/simulation_tests.cpp+231-1 +tests/cli_integration.cmaketests/cli_integration.cmake+62-0 +.clang-format.clang-format+10-0 +.clang-tidy.clang-tidy+7-1 +.editorconfig.editorconfig+15-0 +.gitignore.gitignore+12-0 +CMakeLists.txtCMakeLists.txt+77-0 +CMakePresets.jsonCMakePresets.json+26-0 +cmake/ProjectOptions.cmakecmake/ProjectOptions.cmake+55-1 +tools/check-format.cmaketools/check-format.cmake+14-0 +tools/windows-check.ps1tools/windows-check.ps1+45-1 +.dockerignore.dockerignore+8-0 +deploy/README.mddeploy/README.md+36-0 +deploy/docker/Dockerfiledeploy/docker/Dockerfile+29-0 + + + +Proceed. Setup git. And pushed to Gitea repo. We can setup a git action and setup Argo application + +**Git is already initialized and points to https://git.aeternalisgames.com/dingo/AEvolution.git. What Argo CD URL/project and Kubernetes context or kubeconfig should I use? I propose a manual-sync application in evolution-dev for this foundation.** + +I’ll add the Argo application manually, it will deploy to k8s. + +**Which container registry/repository should Gitea Actions publish to, and which runner label should the workflow use? If Harbor and its credentials are already configured, give me the registry path and secret names; don’t send secret values.** + +You can put placeholder values it would point to registry.aeternalisgames.com (harbor registry) + +Edited 13 files+369-3Review changesUndoReview + +.gitea/workflows/foundation.yml.gitea/workflows/foundation.yml+69-0 +deploy/argocd/application.yaml.exampledeploy/argocd/application.yaml.example+18-0 +deploy/argocd/namespace.yaml.exampledeploy/argocd/namespace.yaml.example+5-0 +deploy/argocd/project.yaml.exampledeploy/argocd/project.yaml.example+20-0 +deploy/docker/Dockerfiledeploy/docker/Dockerfile+23-2 +deploy/kubernetes/dev/job.yamldeploy/kubernetes/dev/job.yaml+44-0 +deploy/kubernetes/dev/kustomization.yamldeploy/kubernetes/dev/kustomization.yaml+11-0 +deploy/kubernetes/dev/networkpolicy.yamldeploy/kubernetes/dev/networkpolicy.yaml+13-0 +deploy/kubernetes/dev/serviceaccount.yamldeploy/kubernetes/dev/serviceaccount.yaml+10-0 +docs/adr/0020-foundation-delivery.mddocs/adr/0020-foundation-delivery.md+73-0 +tests/benchmarks/simulation_benchmark.cpptests/benchmarks/simulation_benchmark.cpp+1-1 +tools/ci/linux-check.shtools/ci/linux-check.sh+49-0 +tools/ci/publish-image.shtools/ci/publish-image.sh+33-0 + +proceed with the project. document what has been done and what the next steps are. I have gitea/argo/registry build all setup, so you can update deploy at any point. + +Pushed to Gitea: 1c6e6e1. Latest CI passed. +- Documented completed work and next steps in [STATUS.md](C:/Dev/AEvolution/docs/STATUS.md). +- Recorded Windows/Linux tests, sanitizers, fuzzing and deterministic replay results. +- Published the Harbor image and pinned the dev manifest to a verified digest. +Next: ECS evaluation → scheduler/input ordering → spatial queries → energy ledger. +Argo rollout remains unverified; I still need its application/GitOps source mapping. + + Edited 15 files+161-30Review changesUndoReview + +.gitattributes.gitattributes+5-0 +README.mdREADME.md+5-3 +deploy/kubernetes/dev/kustomization.yamldeploy/kubernetes/dev/kustomization.yaml+3-2 +docs/ROADMAP.mddocs/ROADMAP.md+1-1 +docs/STATUS.mddocs/STATUS.md+66-0 +docs/adr/0020-foundation-delivery.mddocs/adr/0020-foundation-delivery.md+4-3 +docs/adr/README.mddocs/adr/README.md+2-1 +docs/architecture/INFRASTRUCTURE_ARCHITECTURE.mddocs/architecture/INFRASTRUCTURE_ARCHITECTURE.md+4-2 +tools/ci/publish-image.shtools/ci/publish-image.sh+2-1 +tools/windows-check.ps1tools/windows-check.ps1+10-7 +.gitea/workflows/build.yaml.gitea/workflows/build.yaml+12-1 +deploy/docker/Dockerfiledeploy/docker/Dockerfile+3-1 +tools/ci/tsan-profile.mjstools/ci/tsan-profile.mjs+30-0 +deploy/README.mddeploy/README.md+8-3 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+6-5 + +Continue + + + + + + + +Saturday 10:04 AM + + + + + + +I’ll move into M1.5: compare the current component store with a mature ECS using a small, isolated benchmark. I’ll document the workloads and decision criteria first, then measure both without changing the production simulation API. + + + + + Ran commands, searched the web + + +I’ll use EnTT 4.0.0 as the first comparison candidate, pinned by commit and file hashes. It will be an opt-in experiment; normal builds will still require no downloads. +The benchmark will measure dense and sparse queries, entity churn, canonical serialization/restore, and allocator-visible memory. Both stores must produce identical state. Changes are confined to the experiment, build/test tooling and documentation. + + + + +Edited files, ran a command + + + +You've hit your usage limit. Upgrade your plan or add credits to continue, or try again later. + + + + + + + Edited 2 files+144-0Review changesUndoReview + +docs/adr/0021-ecs-evaluation.mddocs/adr/0021-ecs-evaluation.md+71-0 +docs/engineering/ECS_EVALUATION.mddocs/engineering/ECS_EVALUATION.md+73-0 + +Continue + + + + + + + +Saturday 1:57 PM + + + + + + +Worked for 30m 59s + + + +Completed the ECS evaluation and pushed 8c653b9. Gitea CI passed. +- Windows/Linux results match across all 56 deterministic fingerprints. +- Current storage remains appropriate for the bounded proof; production ECS selection remains open. +- Findings, completed work, and next steps are documented in [project status](C:/Dev/AEvolution/docs/STATUS.md) and [ECS evaluation](C:/Dev/AEvolution/docs/engineering/ECS_EVALUATION.md). +Next: M1.6—deterministic scheduler phases and input ordering. Kubernetes rollout remains unverified. + + Edited 15 files+662-20Review changesUndoReview + +CMakeLists.txtCMakeLists.txt+22-0 +experiments/ecs/comparison.cppexperiments/ecs/comparison.cpp+509-4 +tools/check-format.cmaketools/check-format.cmake+2-1 +tools/entt-pin.cmaketools/entt-pin.cmake+3-0 +tools/prepare-entt.cmaketools/prepare-entt.cmake+11-0 +docs/engineering/ECS_EVALUATION.mddocs/engineering/ECS_EVALUATION.md+57-2 +.gitea/workflows/build.yaml.gitea/workflows/build.yaml+1-1 +deploy/docker/Dockerfiledeploy/docker/Dockerfile+16-0 +docs/adr/README.mddocs/adr/README.md+1-0 +README.mdREADME.md+1-0 +docs/ROADMAP.mddocs/ROADMAP.md+5-3 +docs/STATUS.mddocs/STATUS.md+12-6 +docs/adr/0005-ecs-strategy.mddocs/adr/0005-ecs-strategy.md+19-0 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+2-2 +docs/architecture/OPEN_QUESTIONS.mddocs/architecture/OPEN_QUESTIONS.md+1-1 + +What’s next? + + + + + + + +Saturday 4:24 PM + + + + + + +Next is M1.6: deterministic scheduling and input handling. This establishes how simulation work executes before we add biological systems. +The increment will: +1. Document tick phases, command ordering, and late/duplicate input handling. +2. Implement a sequential scheduler with one authoritative writer. +3. Apply commands at explicit tick boundaries. +4. Test replay equivalence, invalid commands, and snapshot/restore continuation. +5. Update progress documentation and push through Gitea CI. +Then: +- M1.7 — Spatial queries: find nearby entities with tested boundary behavior. +- M2.1 — Energy/matter ledger: conserved transfers and nonnegative balances. +- M2.2 onward — Minimal ecosystem: energy capture, consumption, reproduction, death, and decomposition. +Separately, the existing dev deployment needs a verified Argo run. That doesn’t block simulation development. + + +Saturday 4:24 PM + + + + + + + + +Proceed, Argo confirmed when we are ready for a pod to be made, it can be added to the deployment and it will update in Argo + + + + + + + +Saturday 4:30 PM + + + + + + +I’ll implement M1.6’s deterministic scheduling and input contract, then verify replay and recovery behavior through the existing checks. I’ll also record that Argo is ready for deployment updates when we introduce a persistent workload. + + + + + Ran commands + + +Affected modules are the simulation scheduler, public command contracts, tests, and architecture documentation. The scheduler will admit a bounded batch at one exact tick, order commands by host-assigned sequence, apply lifecycle changes, then advance simulation. Invalid batches will leave state unchanged. This remains a synthetic engineering proof; client authentication and network retry handling belong to the later server boundary. + + + + +Edited files, ran commands + + +The scheduler passes the first Release checks. All six orderings of each test batch produce identical state, rejected batches leave snapshots unchanged, and the existing no-input golden still matches. I’m running static analysis and sanitizers next, then updating the progress record and pushing through CI. + + + + +Edited files, ran commands + + +Native Release, clang-tidy, formatting, and ASan checks all passed. The push found a newer GitOps commit on the remote; it changes the dev image pin. I’ll preserve that change and rebase the scheduler work onto it before retrying the push. + +You've hit your usage limit. Upgrade your plan or add credits to continue, or try again later. + + + + + + + Edited 13 files+388-21Review changesUndoReview + +docs/adr/0022-sequential-command-scheduler.mddocs/adr/0022-sequential-command-scheduler.md+68-0 +docs/adr/README.mddocs/adr/README.md+1-0 +docs/architecture/SCHEDULER_CONTRACT.mddocs/architecture/SCHEDULER_CONTRACT.md+44-0 +docs/architecture/SIMULATION_ARCHITECTURE.mddocs/architecture/SIMULATION_ARCHITECTURE.md+4-0 +CMakeLists.txtCMakeLists.txt+1-1 +include/evo/simulation/scheduler.hppinclude/evo/simulation/scheduler.hpp+44-0 +src/simulation/scheduler.cppsrc/simulation/scheduler.cpp+74-0 +tests/simulation_tests.cpptests/simulation_tests.cpp+99-1 +README.mdREADME.md+1-0 +docs/ROADMAP.mddocs/ROADMAP.md+4-3 +docs/STATUS.mddocs/STATUS.md+22-10 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+18-1 +deploy/README.mddeploy/README.md + +Continue + + + + + + + +Saturday 7:16 PM + + + + + + +35 previous messages + + + +M1.7 is complete and pushed. +- Added deterministic periodic neighborhood queries and boundary tests. +- Windows checks and Linux CI 1409 passed. +- All 72 benchmark results match across platforms. +- [Status and next steps](C:/Dev/AEvolution/docs/STATUS.md) updated. +The implementation is a measured linear-scan baseline; production indexing remains deferred. +Next: M2.1—conserved energy and matter accounting, before introducing organisms. + + Edited 14 files+391-16Review changesUndoReview + +CMakeLists.txtCMakeLists.txt+6-2 +docs/adr/0023-local-neighborhood-queries.mddocs/adr/0023-local-neighborhood-queries.md+58-0 +docs/adr/README.mddocs/adr/README.md+2-1 +docs/architecture/SIMULATION_ARCHITECTURE.mddocs/architecture/SIMULATION_ARCHITECTURE.md+4-1 +docs/architecture/SPATIAL_CONTRACT.mddocs/architecture/SPATIAL_CONTRACT.md+63-0 +include/evo/simulation/spatial.hppinclude/evo/simulation/spatial.hpp+10-0 +src/simulation/spatial.cppsrc/simulation/spatial.cpp+30-0 +tests/benchmarks/spatial_benchmark.cpptests/benchmarks/spatial_benchmark.cpp+75-0 +tests/simulation_tests.cpptests/simulation_tests.cpp+95-4 +README.mdREADME.md+4-2 +docs/ROADMAP.mddocs/ROADMAP.md+3-1 +docs/STATUS.mddocs/STATUS.md+13-5 +tools/ci/linux-check.shtools/ci/linux-check.sh+1-0 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+27-0 + +Proceed + + + + + + + +Saturday 7:36 PM + + + + + + +34 previous messages + + + +M2.1 is complete and pushed. +- Added typed energy/matter inventories with atomic transfers, overflow checks, and replay protection. +- One million seeded transactions passed conservation checks. +- Windows validation and Linux CI 1411 passed. +- [Status and next steps](C:/Dev/AEvolution/docs/STATUS.md) updated. +Next: M2.2—finite energy sources and producer processes, including conversion losses and fractional-rate accounting. + + Edited 12 files+535-12Review changesUndoReview + +CMakeLists.txtCMakeLists.txt+13-2 +docs/adr/0024-conserved-inventory-ledger.mddocs/adr/0024-conserved-inventory-ledger.md+77-0 +include/evo/accounting/ledger.hppinclude/evo/accounting/ledger.hpp+71-0 +src/accounting/ledger.cppsrc/accounting/ledger.cpp+87-0 +docs/adr/README.mddocs/adr/README.md+1-0 +docs/biology/ENERGY_MODEL.mddocs/biology/ENERGY_MODEL.md+31-0 +tests/ledger_tests.cpptests/ledger_tests.cpp+196-0 +README.mdREADME.md+4-2 +docs/ROADMAP.mddocs/ROADMAP.md+7-3 +docs/STATUS.mddocs/STATUS.md+15-3 +docs/architecture/SYSTEM_OVERVIEW.mddocs/architecture/SYSTEM_OVERVIEW.md+4-2 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+29-0 + +Is this attached to a PostgreSQL db already? Or planned + + + + + + + +Saturday 8:08 PM + + + + + + +PostgreSQL is planned, not connected yet. The current simulation and accounting ledger run entirely in memory. The particle proof supports local snapshot files; the new ledger does not yet have persistence. +PostgreSQL is intended for world/region metadata, genome and lineage history, ownership records, and snapshot references. Large snapshot payloads are planned for object storage. +Persistent integration comes with M7’s region server, followed by M8’s Kubernetes deployment. Active simulation will remain in memory, with checkpoints and durable events—not database writes every tick. + + +Saturday 8:08 PM + + + + + + + + +Continue + + + + + + + +Saturday 8:11 PM + + + + + + +I’ll continue with M2.2: finite energy capture and producer processes on top of the ledger. I’ll first define the rate, conversion-loss, and rollback contracts so resource accounting and process state advance together. + + + + +Ran git status --short --branch; Get-Content include/evo/accounting/ledger.hpp; Get-Content docs/biology/ENERGY_MODEL.md; Get-Content docs/adr/0024*; Get-Content docs/engineering/ENGINEERING_CONSTITUTION.md; Get-Content docs/PROJECT_VISION.md -TotalCount 40; Get-Content tests/ledger_tests.cpp -TotalCount 65; Get-Content CMakeLists.txt -TotalCount 90 + + + + +Affected modules are a new synthetic producer-process library, its tests, and the energy-model docs. The process will own its ledger so callers cannot route heat back into usable reserve. It will capture a bounded amount from a finite source, account for conversion losses, then grow only when both energy and the specified material recipe are available. These are test-fixture rules, not organism biology or live-world rules. + + + + +Edited files, ran commands + + +The producer process passes its first Release tests. Hand-calculated cases and 32 seeded runs verify capture, fractional conversion, resource-limited growth, heat accumulation, and replay. Once source energy is exhausted, growth can use only energy already stored in reserve; accumulated heat cannot fund it. I’m adding arithmetic-boundary checks before running sanitizers and analysis. + + + + +Edited files, ran commands + + + +You've hit your usage limit. Upgrade your plan or add credits to continue, or try again later. + + + + + + + Edited 11 files+476-5Review changesUndoReview + +CMakeLists.txtCMakeLists.txt+10-0 +docs/adr/0025-finite-producer-process.mddocs/adr/0025-finite-producer-process.md+76-0 +include/evo/processes/producer.hppinclude/evo/processes/producer.hpp+59-0 +src/processes/producer.cppsrc/processes/producer.cpp+85-0 +tests/producer_tests.cpptests/producer_tests.cpp+181-0 +docs/ROADMAP.mddocs/ROADMAP.md+4-1 +docs/STATUS.mddocs/STATUS.md+11-3 +docs/adr/README.mddocs/adr/README.md+1-0 +docs/architecture/SYSTEM_OVERVIEW.mddocs/architecture/SYSTEM_OVERVIEW.md+2-1 +docs/biology/ENERGY_MODEL.mddocs/biology/ENERGY_MODEL.md+29-0 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+18-0 + +Proceee + + + + + + + +Sunday 8:56 AM + + + + + + +17 previous messages + + + +M2.2 is complete and pushed. +- Added finite energy capture, conversion losses, resource-limited growth, and exact fractional accounting. +- Windows checks and Linux CI 1413 passed. +- [Project status](C:/Dev/AEvolution/docs/STATUS.md) updated. +Next: M2.3—consumer interactions and validated feeding transfers. PostgreSQL remains planned; this is still an in-memory simulation fixture. + + Edited 2 files+7-1Review changesUndoReview + +docs/STATUS.mddocs/STATUS.md+2-0 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+5-1 + + + + + +Sunday 9:04 AM + + + + + + + + +Yesterday 10:22 AM +Proceed + + + + + + + +Sunday 10:22 AM + + + + + + +27 previous messages + + + +M2.3 is complete and pushed. +- Added shared producer/consumer feeding with intake limits, heat/waste accounting, and atomic tick rollback. +- Windows checks and Linux CI 1415 passed. +- [Project status](C:/Dev/AEvolution/docs/STATUS.md) updated. + +Next: M2.4—death with remaining inventory, corpse ownership, and decomposition returning nutrients. This remains an in-memory synthetic simulation. + + Edited 14 files+493-8Review changesUndoReview + +CMakeLists.txtCMakeLists.txt+6-1 +docs/adr/0026-shared-feeding-community.mddocs/adr/0026-shared-feeding-community.md+85-0 +include/evo/processes/feeding.hppinclude/evo/processes/feeding.hpp+51-0 +include/evo/processes/producer.hppinclude/evo/processes/producer.hpp+1-0 +src/processes/feeding.cppsrc/processes/feeding.cpp+129-0 +src/processes/producer.cppsrc/processes/producer.cpp+5-2 +tests/feeding_tests.cpptests/feeding_tests.cpp+139-0 +docs/ROADMAP.mddocs/ROADMAP.md+4-1 +docs/STATUS.mddocs/STATUS.md+15-4 +docs/adr/0025-finite-producer-process.mddocs/adr/0025-finite-producer-process.md+3-0 +docs/adr/README.mddocs/adr/README.md+1-0 +docs/architecture/SYSTEM_OVERVIEW.mddocs/architecture/SYSTEM_OVERVIEW.md+4-0 +docs/biology/ENERGY_MODEL.mddocs/biology/ENERGY_MODEL.md+28-0 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+22-0 + +Proceed + + + + + + + +Sunday 3:21 PM + + + + + + +32 previous messages + + + +M2.4 is complete and pushed. +- Death preserves remaining inventory as a corpse. +- Bounded decomposition returns nutrients and releases energy as heat. +- Tests verify conservation, terminality, rollback, and subsequent producer growth. +- Windows checks and Linux CI 1417 passed. +[Project status](C:/Dev/AEvolution/docs/STATUS.md) is updated. Next: M2.5—funded reproduction and offspring identity. + + Edited 9 files+351-15Review changesUndoReview + +docs/adr/0027-terminal-inventory-and-decomposition.mddocs/adr/0027-terminal-inventory-and-decomposition.md+80-0 +include/evo/processes/feeding.hppinclude/evo/processes/feeding.hpp+20-3 +src/processes/feeding.cppsrc/processes/feeding.cpp+65-6 +tests/feeding_tests.cpptests/feeding_tests.cpp+119-0 +docs/ROADMAP.mddocs/ROADMAP.md+3-1 +docs/STATUS.mddocs/STATUS.md+14-5 +docs/adr/README.mddocs/adr/README.md+1-0 +docs/biology/ENERGY_MODEL.mddocs/biology/ENERGY_MODEL.md+28-0 +docs/engineering/VALIDATION.mddocs/engineering/VALIDATION.md+21-0 + diff --git a/docs/adr/0001-language-toolchain.md b/docs/adr/0001-language-toolchain.md index db6d70e..8e26e05 100644 --- a/docs/adr/0001-language-toolchain.md +++ b/docs/adr/0001-language-toolchain.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0001: C++23 subset and toolchain ## Status diff --git a/docs/adr/0002-build-system.md b/docs/adr/0002-build-system.md index 2e73233..8a70eb4 100644 --- a/docs/adr/0002-build-system.md +++ b/docs/adr/0002-build-system.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0002: CMake target-oriented builds ## Status diff --git a/docs/adr/0003-dependencies.md b/docs/adr/0003-dependencies.md index fc7ffdb..93115d3 100644 --- a/docs/adr/0003-dependencies.md +++ b/docs/adr/0003-dependencies.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0003: Dependency adoption and package management ## Status diff --git a/docs/adr/0004-test-benchmark-framework.md b/docs/adr/0004-test-benchmark-framework.md index 5645276..a4eb7dd 100644 --- a/docs/adr/0004-test-benchmark-framework.md +++ b/docs/adr/0004-test-benchmark-framework.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0004: Bounded test and benchmark harness ## Status diff --git a/docs/adr/0005-ecs-strategy.md b/docs/adr/0005-ecs-strategy.md index 4bc455f..3e11141 100644 --- a/docs/adr/0005-ecs-strategy.md +++ b/docs/adr/0005-ecs-strategy.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0005: Component storage before a general ECS ## Status diff --git a/docs/adr/0006-tick-model.md b/docs/adr/0006-tick-model.md index bfc8be7..ee197cd 100644 --- a/docs/adr/0006-tick-model.md +++ b/docs/adr/0006-tick-model.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0006: Fixed logical ticks ## Status diff --git a/docs/adr/0007-prng.md b/docs/adr/0007-prng.md index 3062701..dd0f3cf 100644 --- a/docs/adr/0007-prng.md +++ b/docs/adr/0007-prng.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0007: Explicit deterministic random streams ## Status diff --git a/docs/adr/0008-serialization.md b/docs/adr/0008-serialization.md index ecd0162..e1e71ec 100644 --- a/docs/adr/0008-serialization.md +++ b/docs/adr/0008-serialization.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0008: Canonical proof snapshots and future codecs ## Status diff --git a/docs/adr/0009-units-coordinates.md b/docs/adr/0009-units-coordinates.md index 7fdbe9c..3cffef8 100644 --- a/docs/adr/0009-units-coordinates.md +++ b/docs/adr/0009-units-coordinates.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0009: Units and spatial frames ## Status diff --git a/docs/adr/0010-error-handling.md b/docs/adr/0010-error-handling.md index 62909bc..48c50ab 100644 --- a/docs/adr/0010-error-handling.md +++ b/docs/adr/0010-error-handling.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0010: Explicit recoverable errors ## Status diff --git a/docs/adr/0011-thread-ownership.md b/docs/adr/0011-thread-ownership.md index 06cd0b3..6ca39fc 100644 --- a/docs/adr/0011-thread-ownership.md +++ b/docs/adr/0011-thread-ownership.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0011: Explicit thread ownership ## Status diff --git a/docs/adr/0012-logging.md b/docs/adr/0012-logging.md index 1d58725..38e67f1 100644 --- a/docs/adr/0012-logging.md +++ b/docs/adr/0012-logging.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0012: Structured application logging ## Status diff --git a/docs/adr/0013-postgresql-client.md b/docs/adr/0013-postgresql-client.md index 4f2660e..8a2bca9 100644 --- a/docs/adr/0013-postgresql-client.md +++ b/docs/adr/0013-postgresql-client.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0013: PostgreSQL client boundary ## Status diff --git a/docs/adr/0014-message-bus.md b/docs/adr/0014-message-bus.md index 07ec825..38ceb1a 100644 --- a/docs/adr/0014-message-bus.md +++ b/docs/adr/0014-message-bus.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0014: Evaluate NATS JetStream ## Status diff --git a/docs/adr/0015-observability.md b/docs/adr/0015-observability.md index 6ada508..52176bf 100644 --- a/docs/adr/0015-observability.md +++ b/docs/adr/0015-observability.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0015: Metrics outside authoritative state ## Status diff --git a/docs/adr/0016-persistence-and-region-ownership.md b/docs/adr/0016-persistence-and-region-ownership.md index 1bdcaf8..8d6c1de 100644 --- a/docs/adr/0016-persistence-and-region-ownership.md +++ b/docs/adr/0016-persistence-and-region-ownership.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0016: Persistence and region ownership ## Status diff --git a/docs/adr/0017-network-security.md b/docs/adr/0017-network-security.md index add9d06..23bc538 100644 --- a/docs/adr/0017-network-security.md +++ b/docs/adr/0017-network-security.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0017: Network transport and security ## Status diff --git a/docs/adr/0018-infrastructure-services.md b/docs/adr/0018-infrastructure-services.md index d25caae..6cdd57a 100644 --- a/docs/adr/0018-infrastructure-services.md +++ b/docs/adr/0018-infrastructure-services.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0018: Initial infrastructure services ## Status diff --git a/docs/adr/0019-voxel-storage-and-meshing.md b/docs/adr/0019-voxel-storage-and-meshing.md index 30509ee..7ee7b7d 100644 --- a/docs/adr/0019-voxel-storage-and-meshing.md +++ b/docs/adr/0019-voxel-storage-and-meshing.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0019: Sparse voxel storage and deferred meshing ## Status diff --git a/docs/adr/0020-foundation-delivery.md b/docs/adr/0020-foundation-delivery.md index 4b35aa1..f49cb50 100644 --- a/docs/adr/0020-foundation-delivery.md +++ b/docs/adr/0020-foundation-delivery.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0020: Gitea delivery and a manual dev verification Job ## Status diff --git a/docs/adr/0021-ecs-evaluation.md b/docs/adr/0021-ecs-evaluation.md index b9e5e59..9b23509 100644 --- a/docs/adr/0021-ecs-evaluation.md +++ b/docs/adr/0021-ecs-evaluation.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0021: Isolated EnTT comparison ## Status diff --git a/docs/adr/0022-sequential-command-scheduler.md b/docs/adr/0022-sequential-command-scheduler.md index 630c27e..2795691 100644 --- a/docs/adr/0022-sequential-command-scheduler.md +++ b/docs/adr/0022-sequential-command-scheduler.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0022: Transactional sequential command scheduling ## Status diff --git a/docs/adr/0023-local-neighborhood-queries.md b/docs/adr/0023-local-neighborhood-queries.md index b58a878..425d9bc 100644 --- a/docs/adr/0023-local-neighborhood-queries.md +++ b/docs/adr/0023-local-neighborhood-queries.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0023: Local periodic neighborhood queries ## Status diff --git a/docs/adr/0024-conserved-inventory-ledger.md b/docs/adr/0024-conserved-inventory-ledger.md index 79edb6d..4bac979 100644 --- a/docs/adr/0024-conserved-inventory-ledger.md +++ b/docs/adr/0024-conserved-inventory-ledger.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0024: Conserved finite inventory ledger ## Status diff --git a/docs/adr/0025-finite-producer-process.md b/docs/adr/0025-finite-producer-process.md index 7ee96e7..8f16eb8 100644 --- a/docs/adr/0025-finite-producer-process.md +++ b/docs/adr/0025-finite-producer-process.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0025: Finite synthetic producer process ## Status diff --git a/docs/adr/0026-shared-feeding-community.md b/docs/adr/0026-shared-feeding-community.md index 6588f6b..55cfecd 100644 --- a/docs/adr/0026-shared-feeding-community.md +++ b/docs/adr/0026-shared-feeding-community.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0026: Shared synthetic feeding community ## Status diff --git a/docs/adr/0027-terminal-inventory-and-decomposition.md b/docs/adr/0027-terminal-inventory-and-decomposition.md index 75624d6..c075f10 100644 --- a/docs/adr/0027-terminal-inventory-and-decomposition.md +++ b/docs/adr/0027-terminal-inventory-and-decomposition.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0027: Terminal inventory ownership and bounded decomposition ## Status diff --git a/docs/adr/0028-funded-reproduction.md b/docs/adr/0028-funded-reproduction.md index 2a3fbd1..c1ddd0e 100644 --- a/docs/adr/0028-funded-reproduction.md +++ b/docs/adr/0028-funded-reproduction.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0028: Funded reproduction and retained lineage identity ## Status diff --git a/docs/adr/0029-ecosystem-driver-and-episodes.md b/docs/adr/0029-ecosystem-driver-and-episodes.md index 4b3674b..f0b59fb 100644 --- a/docs/adr/0029-ecosystem-driver-and-episodes.md +++ b/docs/adr/0029-ecosystem-driver-and-episodes.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0029: Deterministic ecosystem driver and bounded episodes ## Status diff --git a/docs/adr/0030-immutable-genome-record.md b/docs/adr/0030-immutable-genome-record.md index e75be44..916cd84 100644 --- a/docs/adr/0030-immutable-genome-record.md +++ b/docs/adr/0030-immutable-genome-record.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0030: Immutable genome v1 record and canonical encoding ## Status diff --git a/docs/adr/0031-development-and-phenotype.md b/docs/adr/0031-development-and-phenotype.md index 69c84a2..81ddb6e 100644 --- a/docs/adr/0031-development-and-phenotype.md +++ b/docs/adr/0031-development-and-phenotype.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0031: Deterministic development and derived phenotype ## Status diff --git a/docs/adr/0032-metabolic-budgets-from-genome.md b/docs/adr/0032-metabolic-budgets-from-genome.md index a6efc8e..9c389db 100644 --- a/docs/adr/0032-metabolic-budgets-from-genome.md +++ b/docs/adr/0032-metabolic-budgets-from-genome.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0032: Metabolic budgets derived from a phenotype ## Status diff --git a/docs/adr/0033-seeded-mutation-candidates.md b/docs/adr/0033-seeded-mutation-candidates.md index 0231132..a80d009 100644 --- a/docs/adr/0033-seeded-mutation-candidates.md +++ b/docs/adr/0033-seeded-mutation-candidates.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0033: Seeded mutation candidates over a bounded operator catalog ## Status diff --git a/docs/adr/0034-lineage-archive.md b/docs/adr/0034-lineage-archive.md index 19d24e0..46109c2 100644 --- a/docs/adr/0034-lineage-archive.md +++ b/docs/adr/0034-lineage-archive.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0034: Permanent lineage archive and provisional absence ## Status diff --git a/docs/adr/0035-genome-ecology-ensembles.md b/docs/adr/0035-genome-ecology-ensembles.md index 8554e96..ba780cf 100644 --- a/docs/adr/0035-genome-ecology-ensembles.md +++ b/docs/adr/0035-genome-ecology-ensembles.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0035: Genome-derived strategies over an environment gradient ## Status diff --git a/docs/adr/0036-cohort-state-and-ownership.md b/docs/adr/0036-cohort-state-and-ownership.md index 323d9fa..3fbecac 100644 --- a/docs/adr/0036-cohort-state-and-ownership.md +++ b/docs/adr/0036-cohort-state-and-ownership.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0036: Cohort state, declared resolution and exclusive ownership ## Status diff --git a/docs/adr/0037-collapse-to-cohort.md b/docs/adr/0037-collapse-to-cohort.md index 4d6c641..3222b41 100644 --- a/docs/adr/0037-collapse-to-cohort.md +++ b/docs/adr/0037-collapse-to-cohort.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0037: Collapsing individuals into a cohort as one sampled transaction ## Status diff --git a/docs/adr/0038-interval-accounting.md b/docs/adr/0038-interval-accounting.md index a4660e5..793714a 100644 --- a/docs/adr/0038-interval-accounting.md +++ b/docs/adr/0038-interval-accounting.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0038: Accounting a proposed interval without choosing an ecology ## Status diff --git a/docs/adr/0039-materialize-representatives.md b/docs/adr/0039-materialize-representatives.md index d643484..36df098 100644 --- a/docs/adr/0039-materialize-representatives.md +++ b/docs/adr/0039-materialize-representatives.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0039: Materializing representatives without making a round trip profitable ## Status diff --git a/docs/adr/0040-resolution-equivalence.md b/docs/adr/0040-resolution-equivalence.md index dc62442..5b99a51 100644 --- a/docs/adr/0040-resolution-equivalence.md +++ b/docs/adr/0040-resolution-equivalence.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0040: Measuring what aggregation costs, and refusing to call it equivalence ## Status diff --git a/docs/adr/0041-aggregate-budget.md b/docs/adr/0041-aggregate-budget.md index 821970a..38e84f5 100644 --- a/docs/adr/0041-aggregate-budget.md +++ b/docs/adr/0041-aggregate-budget.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0041: Measure aggregate cost before enabling tier selection ## Status diff --git a/docs/adr/0042-local-voxel-contract.md b/docs/adr/0042-local-voxel-contract.md index 2609801..a77fcc2 100644 --- a/docs/adr/0042-local-voxel-contract.md +++ b/docs/adr/0042-local-voxel-contract.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0042: Bounded local voxel addresses and logical cells ## Status diff --git a/docs/adr/0043-chunk-layout.md b/docs/adr/0043-chunk-layout.md index 05828b5..3ab7372 100644 --- a/docs/adr/0043-chunk-layout.md +++ b/docs/adr/0043-chunk-layout.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0043: Bounded chunk layout comparison ## Status diff --git a/docs/adr/0044-abiotic-generation.md b/docs/adr/0044-abiotic-generation.md index ff1dca3..40e2404 100644 --- a/docs/adr/0044-abiotic-generation.md +++ b/docs/adr/0044-abiotic-generation.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0044: Versioned abiotic base generation ## Status diff --git a/docs/adr/0045-bounded-chunk-ownership.md b/docs/adr/0045-bounded-chunk-ownership.md index 4b7e5f3..0f7bdc8 100644 --- a/docs/adr/0045-bounded-chunk-ownership.md +++ b/docs/adr/0045-bounded-chunk-ownership.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0045: Bounded local chunk ownership ## Status diff --git a/docs/adr/0046-transactional-excavation.md b/docs/adr/0046-transactional-excavation.md index b819e30..90cca2d 100644 --- a/docs/adr/0046-transactional-excavation.md +++ b/docs/adr/0046-transactional-excavation.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0046: Atomic local excavation and material volume accounting ## Status diff --git a/docs/adr/0047-world-codec.md b/docs/adr/0047-world-codec.md index 8bc18bd..5a484e8 100644 --- a/docs/adr/0047-world-codec.md +++ b/docs/adr/0047-world-codec.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0047: Bounded world snapshot and edit-journal codecs ## Status diff --git a/docs/adr/0048-local-publication.md b/docs/adr/0048-local-publication.md index c725a39..659e93a 100644 --- a/docs/adr/0048-local-publication.md +++ b/docs/adr/0048-local-publication.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0048: Local snapshot and journal publication ## Status diff --git a/docs/adr/0049-bounded-world-proof.md b/docs/adr/0049-bounded-world-proof.md index 633610b..0ea5b20 100644 --- a/docs/adr/0049-bounded-world-proof.md +++ b/docs/adr/0049-bounded-world-proof.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0049: Bounded world restart proof and measurements ## Status diff --git a/docs/adr/0050-environmental-units-and-coupling.md b/docs/adr/0050-environmental-units-and-coupling.md index 199bb15..2839d78 100644 --- a/docs/adr/0050-environmental-units-and-coupling.md +++ b/docs/adr/0050-environmental-units-and-coupling.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0050: Bounded environmental units and ecological coupling ## Status diff --git a/docs/adr/0051-optional-environmental-fields.md b/docs/adr/0051-optional-environmental-fields.md index b2b4e5a..ef36193 100644 --- a/docs/adr/0051-optional-environmental-fields.md +++ b/docs/adr/0051-optional-environmental-fields.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0051: Optional finite environmental field pages ## Status diff --git a/docs/adr/0052-read-only-environment-views.md b/docs/adr/0052-read-only-environment-views.md index 24037c9..d12a797 100644 --- a/docs/adr/0052-read-only-environment-views.md +++ b/docs/adr/0052-read-only-environment-views.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0052: Read-only environment footprint views ## Status diff --git a/docs/adr/0053-atomic-environmental-transfers.md b/docs/adr/0053-atomic-environmental-transfers.md index f9cd12e..6f144ea 100644 --- a/docs/adr/0053-atomic-environmental-transfers.md +++ b/docs/adr/0053-atomic-environmental-transfers.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0053: Atomic local environment and organism resource transfers ## Status diff --git a/docs/adr/0054-m65-source-persistence-prerequisite.md b/docs/adr/0054-m65-source-persistence-prerequisite.md index b08efff..1785301 100644 --- a/docs/adr/0054-m65-source-persistence-prerequisite.md +++ b/docs/adr/0054-m65-source-persistence-prerequisite.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0054: M6.5 source persistence prerequisite ## Status diff --git a/docs/adr/0055-environmental-process-contract.md b/docs/adr/0055-environmental-process-contract.md index 45f3a8d..143628a 100644 --- a/docs/adr/0055-environmental-process-contract.md +++ b/docs/adr/0055-environmental-process-contract.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0055: Bounded environmental producer/consumer contract ## Status diff --git a/docs/adr/0056-environmental-terminal-decay.md b/docs/adr/0056-environmental-terminal-decay.md index 50cb4f6..f0175ea 100644 --- a/docs/adr/0056-environmental-terminal-decay.md +++ b/docs/adr/0056-environmental-terminal-decay.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0056: Retained environmental corpses and bounded decay ## Status diff --git a/docs/adr/0057-environmental-interval-scheduling.md b/docs/adr/0057-environmental-interval-scheduling.md index a839d26..6dc2656 100644 --- a/docs/adr/0057-environmental-interval-scheduling.md +++ b/docs/adr/0057-environmental-interval-scheduling.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0057: Bounded local environmental intervals ## Status diff --git a/docs/adr/0058-region-durability-contract.md b/docs/adr/0058-region-durability-contract.md index 778522e..d6a5898 100644 --- a/docs/adr/0058-region-durability-contract.md +++ b/docs/adr/0058-region-durability-contract.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0058: Region durability through full checkpoint batches ## Status diff --git a/docs/adr/0059-postgresql-bootstrap.md b/docs/adr/0059-postgresql-bootstrap.md index 687343a..bebe9db 100644 --- a/docs/adr/0059-postgresql-bootstrap.md +++ b/docs/adr/0059-postgresql-bootstrap.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0059: PostgreSQL adapter and migration bootstrap ## Status diff --git a/docs/adr/0060-fenced-region-ownership.md b/docs/adr/0060-fenced-region-ownership.md index 5a3444d..5afa98e 100644 --- a/docs/adr/0060-fenced-region-ownership.md +++ b/docs/adr/0060-fenced-region-ownership.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0060: Fenced region ownership ## Status diff --git a/docs/adr/0061-checkpoint-publication.md b/docs/adr/0061-checkpoint-publication.md index a734e6a..3ff7d13 100644 --- a/docs/adr/0061-checkpoint-publication.md +++ b/docs/adr/0061-checkpoint-publication.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0061: Checkpoint publication and verified recovery ## Status diff --git a/docs/adr/0062-lineage-checkpoint-profile.md b/docs/adr/0062-lineage-checkpoint-profile.md index a61f8ab..75b49b4 100644 --- a/docs/adr/0062-lineage-checkpoint-profile.md +++ b/docs/adr/0062-lineage-checkpoint-profile.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0062: Lineage archive codec and history-capable checkpoint profile ## Status diff --git a/docs/adr/0063-batch-outcomes.md b/docs/adr/0063-batch-outcomes.md index 4d5bf2a..7e9458a 100644 --- a/docs/adr/0063-batch-outcomes.md +++ b/docs/adr/0063-batch-outcomes.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0063: Batch evidence, durable outcomes and commit resolution ## Status diff --git a/docs/adr/0064-region-host.md b/docs/adr/0064-region-host.md index 2f1dcdf..63aebf9 100644 --- a/docs/adr/0064-region-host.md +++ b/docs/adr/0064-region-host.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0064: Bounded authoritative region host ## Status diff --git a/docs/adr/0065-recovery-before-readiness.md b/docs/adr/0065-recovery-before-readiness.md index e048daa..3d01777 100644 --- a/docs/adr/0065-recovery-before-readiness.md +++ b/docs/adr/0065-recovery-before-readiness.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0065: Recovery verification before readiness ## Status diff --git a/docs/adr/0066-operations-endpoints.md b/docs/adr/0066-operations-endpoints.md index c320c9e..d7e415c 100644 --- a/docs/adr/0066-operations-endpoints.md +++ b/docs/adr/0066-operations-endpoints.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0066: Operations endpoints and development server image ## Status diff --git a/docs/adr/0067-region-clones.md b/docs/adr/0067-region-clones.md index b3b4ede..b7f70e5 100644 --- a/docs/adr/0067-region-clones.md +++ b/docs/adr/0067-region-clones.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0067: Region clones and retained-history audit ## Status diff --git a/docs/adr/0068-upgrade-barrier.md b/docs/adr/0068-upgrade-barrier.md index 97486eb..a95e14d 100644 --- a/docs/adr/0068-upgrade-barrier.md +++ b/docs/adr/0068-upgrade-barrier.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0068: Upgrade barrier, build-bound authority and durability qualification ## Status diff --git a/docs/adr/0069-environment-isolation.md b/docs/adr/0069-environment-isolation.md index d5f3979..b889800 100644 --- a/docs/adr/0069-environment-isolation.md +++ b/docs/adr/0069-environment-isolation.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0069: Environment isolation and World0 protection ## Status diff --git a/docs/adr/0070-dev-stage-stores.md b/docs/adr/0070-dev-stage-stores.md index cb6b466..0207374 100644 --- a/docs/adr/0070-dev-stage-stores.md +++ b/docs/adr/0070-dev-stage-stores.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0070: Durable stores for dev and stage ## Status diff --git a/docs/adr/0071-region-host-deployment.md b/docs/adr/0071-region-host-deployment.md index 0c72a3c..9c3ff21 100644 --- a/docs/adr/0071-region-host-deployment.md +++ b/docs/adr/0071-region-host-deployment.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0071: Region host deployment in dev and stage ## Status diff --git a/docs/adr/0072-observability.md b/docs/adr/0072-observability.md index cc7cefc..a42cfc8 100644 --- a/docs/adr/0072-observability.md +++ b/docs/adr/0072-observability.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0072: Observability, alerting and background delivery for dev and stage ## Status diff --git a/docs/adr/0073-fault-drills.md b/docs/adr/0073-fault-drills.md index 4161128..aa91ff4 100644 --- a/docs/adr/0073-fault-drills.md +++ b/docs/adr/0073-fault-drills.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0073: Synthetic load and fault drills in dev and stage ## Status diff --git a/docs/adr/0074-world-backup-and-restore.md b/docs/adr/0074-world-backup-and-restore.md index b601624..bea2697 100644 --- a/docs/adr/0074-world-backup-and-restore.md +++ b/docs/adr/0074-world-backup-and-restore.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0074: World backup bundles and verified restore ## Status diff --git a/docs/adr/0075-world0-acknowledgment-gate.md b/docs/adr/0075-world0-acknowledgment-gate.md index fe7c183..78ca28c 100644 --- a/docs/adr/0075-world0-acknowledgment-gate.md +++ b/docs/adr/0075-world0-acknowledgment-gate.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0075: World0 acknowledgment gate, host-loss recovery and promotion ## Status diff --git a/docs/adr/0076-upgrade-and-growth.md b/docs/adr/0076-upgrade-and-growth.md index 3a7cec1..8cecac1 100644 --- a/docs/adr/0076-upgrade-and-growth.md +++ b/docs/adr/0076-upgrade-and-growth.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0076: Upgrade rehearsal on clones, version barrier in dev/stage, and node growth ## Status diff --git a/docs/adr/0077-scoped-native-client-dependencies.md b/docs/adr/0077-scoped-native-client-dependencies.md index 2d068c7..714bc64 100644 --- a/docs/adr/0077-scoped-native-client-dependencies.md +++ b/docs/adr/0077-scoped-native-client-dependencies.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0077: Scoped native 2D client dependencies ## Status diff --git a/docs/adr/0078-native-client-lifecycle.md b/docs/adr/0078-native-client-lifecycle.md index c73e545..9e23812 100644 --- a/docs/adr/0078-native-client-lifecycle.md +++ b/docs/adr/0078-native-client-lifecycle.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0078: Native client lifecycle and immutable presentation frames ## Status diff --git a/docs/adr/0079-camera-and-input-intentions.md b/docs/adr/0079-camera-and-input-intentions.md index 40fcf43..870c018 100644 --- a/docs/adr/0079-camera-and-input-intentions.md +++ b/docs/adr/0079-camera-and-input-intentions.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0079: Local camera and bounded input intentions ## Status diff --git a/docs/adr/0080-environment-presentation.md b/docs/adr/0080-environment-presentation.md index 2542b35..b3fa982 100644 --- a/docs/adr/0080-environment-presentation.md +++ b/docs/adr/0080-environment-presentation.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0080: Revision-tagged environment presentation ## Status diff --git a/docs/adr/0081-organism-presentation.md b/docs/adr/0081-organism-presentation.md index 934f508..f17f776 100644 --- a/docs/adr/0081-organism-presentation.md +++ b/docs/adr/0081-organism-presentation.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0081: Biology-derived organism presentation and engineering inspector ## Status diff --git a/docs/adr/0082-dev-session-transport.md b/docs/adr/0082-dev-session-transport.md index 51db06a..4ce3d55 100644 --- a/docs/adr/0082-dev-session-transport.md +++ b/docs/adr/0082-dev-session-transport.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0082: Narrow secure dev-session protocol and transport security ## Status diff --git a/docs/adr/0083-dev-region-sessions.md b/docs/adr/0083-dev-region-sessions.md index 50025f3..bb7d74a 100644 --- a/docs/adr/0083-dev-region-sessions.md +++ b/docs/adr/0083-dev-region-sessions.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0083: Dev region sessions, no-effect intentions and the session drill ## Status diff --git a/docs/adr/0084-engineering-ui-toolkit.md b/docs/adr/0084-engineering-ui-toolkit.md index b470ea7..3ee8ad5 100644 --- a/docs/adr/0084-engineering-ui-toolkit.md +++ b/docs/adr/0084-engineering-ui-toolkit.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0084: Engineering UI toolkit and ownership boundary ## Status diff --git a/docs/adr/0085-rebindable-engineering-controls.md b/docs/adr/0085-rebindable-engineering-controls.md index 8efac0d..c41a284 100644 --- a/docs/adr/0085-rebindable-engineering-controls.md +++ b/docs/adr/0085-rebindable-engineering-controls.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0085: Rebindable engineering controls ## Status diff --git a/docs/adr/0086-windows-client-package.md b/docs/adr/0086-windows-client-package.md index d7ee865..5c8a4f7 100644 --- a/docs/adr/0086-windows-client-package.md +++ b/docs/adr/0086-windows-client-package.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0086: Windows client package ## Status diff --git a/docs/adr/0087-dev-session-route.md b/docs/adr/0087-dev-session-route.md index d634d5d..a406163 100644 --- a/docs/adr/0087-dev-session-route.md +++ b/docs/adr/0087-dev-session-route.md @@ -1,10 +1,12 @@ +[Reviewed] # ADR-0087: Dev session route and operator-opened session windows ## Status -Accepted for M9.8f as design (2026-10-02), evolution-dev only. The route is committed -**disabled**; nothing was applied to the cluster. The M9.8f gate stays open until the -route is enabled and connectivity is recorded. Enabling it is blocked by policy until -the inputs and server-side window enforcement below exist. Narrowly supersedes +Accepted for M9.8f as design (2026-10-02), evolution-dev only. Repository status +reconciled 2026-10-08: `region/dev` includes the route component, the policy permits +it, and the server implements an absolute session window. These repository facts +do not establish current live availability or completion of every qualification +check below. The original disabled-route status is historical. Narrowly supersedes ADR-0083 (loopback-only listener, never a Service) and ADR-0069 (no LoadBalancer Services) for evolution-dev, and only once enabled. @@ -13,7 +15,9 @@ Internal testers need the native client (M9.8e ZIP) to reach the dev region with `kubectl port-forward`. The cluster inventory (INVENTORY.md, 2026-09-29) shows RKE2's ingress-nginx 1.12.1 DaemonSet serving 80/443 on all four node addresses (public sites included), MetalLB 0.15.2 in FRR mode with one LoadBalancer (Gitea SSH), and an existing -HTTP Ingress for void.aeternalisgames.com in namespace `void`. The session protocol was +HTTP Ingress for void.aeternalisgames.com in namespace `void` at that inventory date. +On 2026-10-08 the maintainer confirmed that the deprecated HTTP service and Ingress +have been removed; there is no remaining HTTP site using this hostname. The session protocol was TLS 1.3 over raw TCP (ADR-0082) when this was written; since 2026-10-05 the route carries the M10 session, QUIC over UDP (ADR-0090/0091/0092; amendment below). Never HTTP. Sessions need synthetic carrier inputs, which ADR-0073 keeps drill-time only so dev history does not grow continuously. @@ -63,8 +67,8 @@ Expiry is enforced **inside evo-server**, not by a delayed cleanup job: closed Git configuration. Grant expiry alone does not stop the generator. ## Enabling (all required; `tools/ci/deploy-policy-check.py` refuses otherwise) -0. `ROUTE_ENABLING_PERMITTED` in the policy check is `False` and is changed only together - with an amendment here that records the implemented window argument/configuration +0. `ROUTE_ENABLING_PERMITTED` in the policy check is now `True`. Its original activation + requirement remains an evidence obligation: record the implemented window argument/configuration contract and its runtime expiry tests (expiry during an active session, restart after expiry, delayed application, extend/close races, clock movement, synthetic inputs stopping while pending commits drain). A flag string in a manifest is not evidence. @@ -89,23 +93,20 @@ Expiry is enforced **inside evo-server**, not by a delayed cleanup job: 6. The rendered-output checks (ADR-0088) pass for every overlay with the route included. ## Open points for the maintainer -Review recommendations (M9.8f review, 2026-10-02), pending the maintainer's decision: -keep manual Argo sync for the first delivery and report a workflow-created window as -pending until applied, with an absolute expiry that delayed sync never shifts (Close -also needs propagation; the server deadline is the upper bound); keep the existing void -HTTP endpoint unless explicitly retired, possibly choosing a dedicated session hostname -instead (DNS cannot select by TCP port), before issuing the certificate; confirm the -actual MetalLB pool and client addresses; clock-skew handling remains open. +Manual Argo delivery was confirmed by the maintainer on 2026-10-08 (amendment below). +The maintainer confirmed retention of the void session hostname and removal of the +deprecated HTTP Ingress on 2026-10-08 (D-003). Actual MetalLB, DNS and client-address +configuration still require operational verification. Running-window clock behavior was decided +on 2026-10-08; numerical host clock-health tolerances remain to be specified. -- **Argo delivery.** The aevolution-dev Application has no automated sync, and the - policy forbids auto-sync outside the platform app (ADR-0069). A workflow commit alone - will not deploy; either a manual sync per window or a scoped dev exception must be - decided before implementing the workflow. CI holds no cluster credentials (ADR-0020), - so Status can report Git state; live fields need a defined read path. -- **void namespace.** void.aeternalisgames.com already has an HTTP Ingress (namespace - `void`). Pointing internal DNS at the VIP changes what internal clients reach for that - name; confirm or retire the existing route. -- Clock skew: the four-hour maximum is decided; define the permitted clock-skew tolerance. +- **Status observation.** Manual delivery is decided. A workflow commit reports desired + Git state, not applied state. Live status still needs an explicitly defined read path; + until then the operator verifies it through Argo and server observations. +- **Hostname.** Resolved by D-003: retain `void.aeternalisgames.com` for sessions; + the prior HTTP service and Ingress were deprecated and removed, per maintainer. +- **Clock health.** Dual-deadline expiry is decided below. Host synchronization checks + and their numerical tolerance, especially across restarts, remain an engineering + follow-up; a process-local elapsed timer cannot prove UTC accuracy after a restart. ## Alternatives considered - ingress-nginx tcp-services or SNI passthrough on 443: couples game sessions to the @@ -114,6 +115,55 @@ actual MetalLB pool and client addresses; clock-skew handling remains open. - NodePort: opens a port on every node; forbidden by ADR-0069. - Always-on sessions in dev: continuous synthetic history; rejected for now. +## Amendment 2026-10-08: Manual application of session-window changes + +Maintainer selected option A during the decision review. The Open/Extend/Close +workflow prepares and commits the desired dev-window configuration. The operator +manually syncs `aevolution-dev` to apply it. This decision grants no automated +Argo sync or deployment credentials to CI. + +A successful commit means the change is pending application, not that the server +has opened, extended or closed its window. The committed expiry remains absolute; +a delayed sync never grants a fresh four-hour duration. Close takes effect when +applied; server-enforced expiry remains the automatic upper bound. The existing +four-hour default and maximum remain unchanged. Workflow implementation and live +status verification are follow-up work, not certified by this decision. + +## Amendment 2026-10-08: Retain the void session hostname + +Maintainer selected option B during the decision review (D-003), confirming that +the old HTTP Ingress was removed and no HTTP site remains for this hostname. +Keep `void.aeternalisgames.com` as the dev-session hostname, using the selected +internal VIP and UDP 7400 route. A separate session hostname or shared web routing +is unnecessary for this use. This records maintainer-provided infrastructure +information; it is not a new live cluster inspection or an instruction to delete +any resources. + +## Amendment 2026-10-08: UTC and suspend-aware elapsed expiry + +Maintainer selected option A during the decision review (D-002). A running window +closes when either its absolute UTC expiry or its suspend-aware elapsed-time +deadline is reached. At admission, derive the elapsed allowance from the remaining +time until the original UTC expiry, bounded by the existing four-hour maximum. +Capture the elapsed deadline once; ordinary clock checks never move it later. + +A backward UTC correction cannot prolong the established elapsed allowance. +A forward correction reaching UTC expiry closes the window immediately. Closure +is latched for that admitted window, including if UTC subsequently moves backward. +The elapsed clock must include host suspend; an arbitrary steady clock is not +sufficient without verifying that property on the platform. + +Restarts still use the committed original UTC expiry and only its remaining time, +not a new four-hour duration. Synchronized host clocks remain required; the elapsed +guard alone cannot establish clock accuracy across process or host restarts. +An explicit operator extension follows D-001 and is not an automatic response to +clock correction. + +Implementation remains pending. Qualification must cover backward and forward UTC +changes, suspend/resume, latched closure, delayed application, and restart with the +original expiry. Existing expiry consequences (session closure, stopping synthetic +inputs, and draining pending commits) apply to either deadline. + Policy evaluation (ADR-0088): the check renders every overlay with the pinned kustomize and validates the effective objects, so inline or JSON patches and namespace changes cannot enable listeners, sessions, inputs or session ports outside the route. diff --git a/docs/adr/0088-rendered-deployment-policy.md b/docs/adr/0088-rendered-deployment-policy.md index 9048a95..732aef0 100644 --- a/docs/adr/0088-rendered-deployment-policy.md +++ b/docs/adr/0088-rendered-deployment-policy.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0088: Rendered deployment-policy checks with pinned kustomize ## Status diff --git a/docs/adr/0089-m10-timing-and-budgets.md b/docs/adr/0089-m10-timing-and-budgets.md index ebd1faa..f8241b9 100644 --- a/docs/adr/0089-m10-timing-and-budgets.md +++ b/docs/adr/0089-m10-timing-and-budgets.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0089: M10 protocol timing and workload budgets ## Status diff --git a/docs/adr/0090-m10-quic-transport.md b/docs/adr/0090-m10-quic-transport.md index fba8b1e..9732eef 100644 --- a/docs/adr/0090-m10-quic-transport.md +++ b/docs/adr/0090-m10-quic-transport.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0090: M10 transport — QUIC with msquic and OpenSSL ## Status diff --git a/docs/adr/0091-m10-session-identity-and-control.md b/docs/adr/0091-m10-session-identity-and-control.md index 780a78a..fffa4c8 100644 --- a/docs/adr/0091-m10-session-identity-and-control.md +++ b/docs/adr/0091-m10-session-identity-and-control.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0091: M10 session identity, grants and control authority ## Status diff --git a/docs/adr/0092-m10-intentions-and-durable-outcomes.md b/docs/adr/0092-m10-intentions-and-durable-outcomes.md index 11c9eba..eaeb234 100644 --- a/docs/adr/0092-m10-intentions-and-durable-outcomes.md +++ b/docs/adr/0092-m10-intentions-and-durable-outcomes.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0092: M10 intentions, actions and durable outcomes ## Status diff --git a/docs/adr/0093-m10-snapshots-and-interest.md b/docs/adr/0093-m10-snapshots-and-interest.md index 7761596..f658e56 100644 --- a/docs/adr/0093-m10-snapshots-and-interest.md +++ b/docs/adr/0093-m10-snapshots-and-interest.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0093: M10 snapshots, spatial interest and session protocol v2 ## Status diff --git a/docs/adr/0094-m10-probe-motion-experiment.md b/docs/adr/0094-m10-probe-motion-experiment.md index e337576..b08a186 100644 --- a/docs/adr/0094-m10-probe-motion-experiment.md +++ b/docs/adr/0094-m10-probe-motion-experiment.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0094: M10 probe-motion experiment, prediction and reconciliation ## Status diff --git a/docs/adr/0095-m10-interpolation-and-session-loss.md b/docs/adr/0095-m10-interpolation-and-session-loss.md index 02e4bf1..10cf2bc 100644 --- a/docs/adr/0095-m10-interpolation-and-session-loss.md +++ b/docs/adr/0095-m10-interpolation-and-session-loss.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0095: M10 tick clock, remote interpolation and session loss ## Status diff --git a/docs/adr/0096-m10-probe-handoff.md b/docs/adr/0096-m10-probe-handoff.md index 3fe95ea..395d680 100644 --- a/docs/adr/0096-m10-probe-handoff.md +++ b/docs/adr/0096-m10-probe-handoff.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0096: M10 cross-region handoff of probe records ## Status diff --git a/docs/adr/0097-m10-load-and-abuse-qualification.md b/docs/adr/0097-m10-load-and-abuse-qualification.md index 17043c6..f579d3f 100644 --- a/docs/adr/0097-m10-load-and-abuse-qualification.md +++ b/docs/adr/0097-m10-load-and-abuse-qualification.md @@ -1,3 +1,4 @@ +[Reviewed] # ADR-0097: M10 load and abuse qualification and overload response ## Status @@ -24,6 +25,34 @@ Delivery: Each segment amends this ADR. Every threshold here is an engineering budget under `schemas/network/m10-budgets-v1.md`, not a game rule. +## Amendment 2026-10-08: Separate qualification gates on the target environment + +Maintainer selected option A during reassessment (D-004), with the explicit +requirement that qualification runs use the expected deployment environment. + +- **Steady-state capacity:** measure sustained load after a bounded, recorded + warm-up. Failure to reach the required stable state within that bound is a + failed run; do not wait indefinitely or selectively discard slow samples. +- **Startup and recovery:** separately measure cold starts, reconnect storms, + fault recovery, client recovery and durable outcomes from the start of each + event. Retain startup spikes and failures in this report. Both gates must pass; + warm-up exclusion from capacity does not excuse a recovery failure. +- **Venue for both gates:** use the intended evolution-dev Kubernetes deployment + on the ADR-0089 reference RKE2 worker, with deployed image, resource limits, + network route, PostgreSQL and object-storage configuration recorded. Capture + hardware and placement for each run; reconcile reference changes before + comparing results. A workstation or WSL-hosted server is not a substitute. +- **Local evidence:** WSL, loopback and developer-host runs remain useful for + correctness, regression and smoke tests. They do not qualify capacity or + deployment recovery, even if their numbers meet the budgets. A workstation + may generate test clients against the actual cluster; report generator limits. + +The first evolution-dev reference run documented below remains a failed capacity +qualification. Earlier local tests and that cluster attempt must be labelled +separately. Implement explicit warm-up bounds, separate acceptance reports and +target-environment evidence before declaring M10.9 qualified. Existing budgets +and durability requirements are not relaxed by this decision. + ## Context ADR-0089 budgets: - per-tick region work: p99 ≤ 25 ms on the reference worker; diff --git a/docs/architecture/DECISION_REGISTER.md b/docs/architecture/DECISION_REGISTER.md new file mode 100644 index 0000000..fc17a1f --- /dev/null +++ b/docs/architecture/DECISION_REGISTER.md @@ -0,0 +1,160 @@ +# Decision Register + +This is the working record of decisions made while reviewing the architecture +decision records (ADRs) and `OPEN_QUESTIONS.md`. A `[Reviewed]` tag means the +record was reviewed in this process; it does not mean every deferred question +inside it is resolved. Pending items remain here so the same ADR need not be +reopened to find them. + +Authority remains: founding brief → architecture → scoped accepted ADRs → public +contracts → tests → implementation. Existing accepted ADRs are recorded as the +current baseline, not silently re-ratified as new game rules. + +## Confirmed decisions from the interactive reassessment + +| ID | Date | Reference | Maintainer decision | Follow-up | +|---|---|---|---|---| +| D-001 | 2026-10-08 | ADR-0087: session-window delivery | **A accepted.** Workflow commits Open/Extend/Close configuration; operator manually syncs `aevolution-dev`. Four-hour default/maximum and absolute expiry remain. Commit success is pending application, not live success. | Align workflow/status wording and verify application through operator observations. No automatic sync or CI deployment credentials authorized. | +| D-002 | 2026-10-08 | ADR-0087: session-window clock behavior | **A accepted.** Close at the earlier of absolute UTC expiry and a suspend-aware elapsed deadline captured from remaining time at admission. Clock corrections cannot extend that elapsed allowance; closure is latched. Restart retains original UTC expiry; synchronized hosts remain required. | Implement and test both deadlines, suspend/resume, clock jumps and restart. Host clock-health tolerance remains a separate engineering detail; this decision does not certify current runtime behavior. | +| D-003 | 2026-10-08 | ADR-0087: session hostname | **B accepted.** Retain `void.aeternalisgames.com` for dev sessions. Maintainer confirms the deprecated HTTP Ingress was removed and no HTTP site remains on that hostname. | Preserve the existing session hostname/VIP/certificate contract. Infrastructure removal is maintainer-confirmed; no new cluster verification or deletion was performed. | +| D-004 | 2026-10-08 | ADR-0097: capacity and recovery qualification | **A accepted with environment constraint.** Qualify steady-state capacity after bounded warm-up and cold-start/restart recovery separately; both must pass on the intended evolution-dev Kubernetes/reference-worker deployment. WSL/developer-host runs cannot qualify these gates. | Record deployed image/resources/network/stores/hardware; retain startup evidence; define bounded warm-up and separate reports. Workstation-generated clients may exercise the real cluster. No tests executed or gate closed by this decision. | + +The inventory below is the earlier document survey. Its Reviewed labels do not +certify a completed critical reassessment; the confirmed decisions above track +the current one-question-at-a-time review. Other recommendations remain proposals. + +## Inventory review status + +| Reference | Review status | Current decision or unresolved item | +|---|---|---| +| [ADR-0001](../adr/0001-language-toolchain.md) | Reviewed | Retain C++23 subset; verify compiler/library feature support in each toolchain lane. | +| [ADR-0002](../adr/0002-build-system.md) | Reviewed | Retain target-oriented CMake, Ninja, and checked-in presets. | +| [ADR-0003](../adr/0003-dependencies.md) | Reviewed | **Pending:** decide whether to compare/select a package manager now or defer selection until a dependency needs managed acquisition. Recommendation: defer; when that gate arrives compare vcpkg and Conan against the ADR's reproducibility, licensing, offline, and maintenance criteria. | +| [ADR-0004](../adr/0004-test-benchmark-framework.md) | Reviewed | Retain the bounded owned harness for now. **Pending:** decide whether the current test volume justifies adopting Catch2 (or another framework) and Google Benchmark; recommendation: avoid a migration absent concrete maintenance or measurement pain, and set a decision gate before the next major test-suite expansion. | +| [ADR-0005](../adr/0005-ecs-strategy.md) | Reviewed | Retain sorted component rows for the bounded proof; production ECS remains open. Re-evaluate with variable components, capability churn, long-lived entity churn, interacting systems, and external-ID mapping before biological entity expansion. | +| [ADR-0006](../adr/0006-tick-model.md) | Reviewed | Fixed logical ticks retained. The old 50 ms value is superseded as an experiment by ratified M10 timing in [ADR-0089](../adr/0089-m10-timing-and-budgets.md): 50 ms. Rate changes require a versioned review. | +| [ADR-0007](../adr/0007-prng.md) | Reviewed | SplitMix64 remains the synthetic proof generator. Production biology requires named subsystem streams and versioned distributions; no world-wide production stream choice is needed before those systems are specified. | +| [ADR-0008](../adr/0008-serialization.md) | Reviewed | Keep the local proof codec local. Durable checkpoints and replay use the later accepted formats/contracts in ADRs 0061–0065; M10 protocol is versioned separately. A universal serialization library remains unselected pending a concrete schema/workload comparison. | +| [ADR-0009](../adr/0009-units-coordinates.md) | Reviewed | Keep explicit typed integer units and local frames. Dimensional library and planetary coordinate mapping remain deferred to biology/planet prototypes. | +| [ADR-0010](../adr/0010-error-handling.md) | Reviewed | Retain `std::expected` for recoverable failures, `optional` only for legitimate absence, and process-boundary exception handling. | +| [ADR-0011](../adr/0011-thread-ownership.md) | Reviewed | Retain single-writer simulation ownership; no general parallel scheduler until profiled immutable work and stable merge contracts justify it. | +| [ADR-0012](../adr/0012-logging.md) | Reviewed | Keep bounded structured application logging at the current boundary. `spdlog` remains unadopted; reconsider only with measured sink/queue needs. | +| [ADR-0013](../adr/0013-postgresql-client.md) | Reviewed | Historical recommendation superseded by [ADR-0059](../adr/0059-postgresql-bootstrap.md), which adopts the scoped direct-libpq adapter. No decision needed here. | +| [ADR-0014](../adr/0014-message-bus.md) | Reviewed | No broker currently: [ADR-0072](../adr/0072-observability.md) uses the PostgreSQL outbox. Reconsider NATS only if measured fan-out/backpressure warrants an independent broker. | +| [ADR-0015](../adr/0015-observability.md) | Reviewed | Keep simulation metrics separate from authoritative state. Later M7–M8 ADRs establish bounded server exposition and the selected observability stack; no metrics-client library is required now. | +| [ADR-0016](../adr/0016-persistence-and-region-ownership.md) | Reviewed | The initial persistence/ownership proposal is now scoped by accepted M7 contracts (ADRs 0058–0068), M8 durability (0069–0076), and M10 probe handoff experiment (0096). General production cross-region ownership remains a later-world-scale gate. | +| [ADR-0017](../adr/0017-network-security.md) | Reviewed | Server authority and no custom cryptography remain locked. M10 transport is QUIC with DATAGRAM plus reliable streams (ADR-0090); session identity/actions are scoped by ADRs 0091–0092. Sensory interest and production threat review remain later work. | +| [ADR-0018](../adr/0018-infrastructure-services.md) | Reviewed | Keep modular backend, PostgreSQL, durable object/snapshot boundaries, no Redis by default, and no broker absent measured need. M8 ADRs scope current dev/stage deployment and backup. MinIO must not be adopted as the default while its upstream distribution is archived; choose a maintained S3-compatible backend only when storage deployment is scheduled. | +| [ADR-0019](../adr/0019-voxel-storage-and-meshing.md) | Reviewed | Sparse procedural base and persisted modifications remain locked. M5 local chunk representation is accepted (ADRs 0042–0049); planetary topology, global coordinates, LOD, mesher and hydrology remain experiments for M13/R&D. | +| [ADR-0020](../adr/0020-foundation-delivery.md) | Reviewed | Gitea Actions and the finite dev verification Job were accepted for foundation delivery; persistent region deployment is governed by later M7/M8 ADRs. | +| [ADR-0021](../adr/0021-ecs-evaluation.md) | Reviewed | EnTT is an opt-in measurement dependency only; benchmark evidence retains sorted rows for the bounded proof and does not decide production ECS. | +| [ADR-0022](../adr/0022-sequential-command-scheduler.md) | Reviewed | Sequential bounded atomic lifecycle-command scheduling is a synthetic M1.6 contract only; it does not authorize client/gameplay commands or concurrency. | +| [ADR-0023](../adr/0023-local-neighborhood-queries.md) | Reviewed | Exact linear periodic-neighborhood query is the M1.7 baseline; no production spatial index or planetary geometry is selected. | +| [ADR-0024](../adr/0024-conserved-inventory-ledger.md) | Reviewed | Exact bounded integer inventory ledger is adopted for synthetic accounting; it does not establish production biochemical units or rates. | +| [ADR-0025](../adr/0025-finite-producer-process.md) | Reviewed | Finite-source producer capture/growth is an M2.2 fixture; synthetic parameters are not game biology. | +| [ADR-0026](../adr/0026-shared-feeding-community.md) | Reviewed | Shared-owner feeding fixture is adopted for M2.3; intake/priority behavior remains a proof contract, not a final feeding rule. | +| [ADR-0027](../adr/0027-terminal-inventory-and-decomposition.md) | Reviewed | Terminal/decomposition accounting is a bounded M2.4 fixture; it does not settle real corpse or nutrient-cycle rates. | +| [ADR-0028](../adr/0028-funded-reproduction.md) | Reviewed | Reproduction is fully funded and retains ancestry in M2 fixtures; duplication and construction overhead are explicitly not hereditary/gameplay rules. | +| [ADR-0029](../adr/0029-ecosystem-driver-and-episodes.md) | Reviewed | Seeded short-episode driver is measurement tooling only; lifespan, targeting and contention restrictions are not ecology or AI decisions. | +| [ADR-0030](../adr/0030-immutable-genome-record.md) | Reviewed | Immutable, validated, canonical genome v1 record is accepted for M3.1. Capability set/ranges are schema scope, not a complete mutation/development/gameplay decision. | +| [ADR-0031](../adr/0031-development-and-phenotype.md) | Reviewed | Deterministic development and phenotype derivation are accepted for M3.2; v1 cube geometry/rule constants are a prototype, not the final body/development model. | +| [ADR-0032](../adr/0032-metabolic-budgets-from-genome.md) | Reviewed | Derived compartment composition and physical-resource budgets are accepted for M3.3; constants are explicitly not balance, viability, starvation or death rules. | +| [ADR-0033](../adr/0033-seeded-mutation-candidates.md) | Reviewed | Uniform seeded candidates over a bounded operator catalog are accepted as an M3.4 experiment. Environmental weighting, mutation count/cost rules, NPC mutation, recombination and inherited/acquired expression remain open gameplay decisions. | +| [ADR-0034](../adr/0034-lineage-archive.md) | Reviewed | Immutable ancestry archive admission/birth/death rules are accepted; archive durability is later ADR-0062. This does not decide mutation by NPCs or species. | +| [ADR-0035](../adr/0035-genome-ecology-ensembles.md) | Reviewed | Seeded genome-derived ensemble evidence closes M3; no mutation happens during episodes and the results are not gameplay fitness/balance. | +| [ADR-0036](../adr/0036-cohort-state-and-ownership.md) | Reviewed | M4 cohort value/registry ownership contract is accepted with later M4.3 amendments; it is an abstraction representation, not proof of ecological fidelity. | +| [ADR-0037](../adr/0037-collapse-to-cohort.md) | Reviewed | Atomic identified-individual to cohort collapse is accepted for M4.2; no production persistence or behavior equivalence follows. | +| [ADR-0038](../adr/0038-interval-accounting.md) | Reviewed | Bounded interval accounting is accepted without selecting a birth/mortality/ecology model. | +| [ADR-0039](../adr/0039-materialize-representatives.md) | Reviewed | Conservative bounded rematerialization is accepted; lossy cohort smoothing is explicitly exposed and cannot be read as an inverse. | +| [ADR-0040](../adr/0040-resolution-equivalence.md) | Reviewed | M4.5 reports resolution-dependent error and a non-equivalence result for its fixture. Production tier thresholds require new multi-genome ecological evidence. | +| ADR-0041–0049 | Reviewed | M4.6 measures abstraction cost without enabling a runtime tier selector. M5 accepts a local 16³ chunk experiment, deterministic abiotic base, bounded edit ownership, codecs, and file publication/restart proof. These do not settle planet topology, world-scale resolution, meshing, chemistry, or the M7 durable store. | +| ADR-0050–0057 | Reviewed | M6 accepts typed bounded habitat/resource units, sparse field pages, views, atomic local transfers, coupled checkpointing, and synthetic process/decay/interval rules. These are versioned fixture rules; they do not settle planetary chemistry, hydrology, atmosphere, or final biological rates. | +| [ADR-0058](../adr/0058-region-durability-contract.md) | Reviewed | Region authority must commit complete checkpoints, including resource/source/retry state, under fenced ownership. This is the M7 recovery boundary, with implementation details delegated to later accepted ADRs. | +| ADR-0059–0068 | Reviewed | M7 contracts select the scoped direct-libpq adapter, database-time fencing, immutable checkpoint publication, durable outcomes, single-owner region host, recovery-before-readiness, operational endpoints, isolated clones, and build-bound upgrade barrier. Rules/format conversion still fails closed until a separately reviewed converter exists. | +| ADR-0069–0073 | Reviewed | M8 selects protected environment namespaces, provisional dev/stage store layout, single-replica host deployment, bounded Prometheus/Alertmanager/logging, DB-outbox background delivery, and operator-run deterministic fault drills. No World0 deployment is authorized by these records. | +| [ADR-0074](../adr/0074-world-backup-and-restore.md) | Reviewed | Verified snapshot-consistent backup/restore bundle and audit are accepted. **Open:** independent permanent destination, encryption, schedule/retention and PostgreSQL WAL archiving. | +| [ADR-0075](../adr/0075-world0-acknowledgment-gate.md) | Reviewed | Dev/stage recovery target is worker-loss RPO 0/RTO ≤60s; host-loss restoration is an explicit rewind. World0 remains blocked until acknowledged outcomes survive host loss in an independent failure domain and promotion controls are satisfied. | +| [ADR-0076](../adr/0076-upgrade-and-growth.md) | Reviewed | Clone-based accelerated upgrade comparison, guarded simulation-version barrier, failure rehearsal, and policy-checked storage/compute node placement are accepted. Hardware and storage inventory still need validation before expansion. | +| ADR-0077–0086 | Reviewed | M9 accepts the scoped SDL engineering client, lifecycle/presentation/input boundaries, engineering-only ImGui and rebindable controls, plus a local reproducible Windows ZIP. These do not choose final player UI, 3D renderer, audio or physics. The absent Windows runner remains a packaging/CI limitation rather than a design choice. | +| [ADR-0087](../adr/0087-dev-session-route.md) | Reassessment in progress | Route is included in the dev overlay and permitted by policy; absolute session-window code exists. VIP 172.10.1.202, UDP 7400, subnet 172.10.1.0/24 and four-hour windows remain the recorded choices. D-001 confirms manual Argo application. Live state and qualification evidence must be assessed separately. | +| [ADR-0088](../adr/0088-rendered-deployment-policy.md) | Reviewed | Render all overlays with pinned checksum-verified kustomize and validate effective resources; route activation remains fail-closed until its full contract is implemented and amended. | +| ADR-0089–0096 | Reviewed | M10 has ratified 50 ms ticks and budgets, QUIC/msquic+OpenSSL transport, signed provider-independent grants, durable no-effect actions, bounded datagram snapshots, probe-only motion/interpolation, and a durable two-process handoff experiment. Probe movement/handoff do not establish organism rules. | +| [ADR-0097](../adr/0097-m10-load-and-abuse-qualification.md) | Reviewed | Qualification must run on evolution-dev reference hardware; overload policy is refuse then shed; the first reference run was invalidated by cold-start governor behavior and grant retry consumption. The 10.9d corrected reference rerun remains an operational gate. | + +## Open questions + +| Reference | Question | Options to consider | Current recommendation | Decision | +|---|---|---|---|---| +| ADR-0003 | When to select a general C++ package manager? | A. Select and compare now. B. Defer until a dependency requires managed acquisition. | B; keep explicit, pinned dependency acquisition until a real need gives us a representative workload. | Pending user response | +| ADR-0004 | Should test/benchmark frameworks be standardized now? | A. Adopt a framework now and migrate suitable suites. B. Keep existing harnesses until specific diagnostic/statistical gaps justify a migration. | B; preserve low-friction tests and avoid churn unless the current harness is measurably limiting. | Pending user response | +| ADR-0005 | When to decide production ECS? | A. Benchmark/adopt before the first biological entity systems. B. Keep the bounded rows through the next gate and decide when realistic component churn exists. | B; defer to representative biological workloads, while explicitly preventing the proof storage from becoming an unreviewed production commitment. | Pending user response | +| ADR-0006 | Does the ratified 50 ms M10 tick need revisiting now? | A. Retain it until evidence requires change. B. Reopen timing before M11.1. | A; ADR-0089 ratified it and requires future rate changes to be versioned and evidenced. | No change requested; retain current contract | +| ADR-0007 | When to specify production biological PRNG streams? | A. Specify before genome/mutation implementation. B. Defer exact stream partitioning until the M11 biology contracts, preserving explicit seeded streams in the meantime. | B, with the M11 gate required to freeze stream names, draw ownership, versioning and regression vectors before gameplay use. | Pending at M11 biology contract | +| ADR-0008 | Which production serialization library/schema should be used? | A. Choose a cross-project library now. B. Keep explicit versioned codecs per domain until a shared workload justifies a library comparison. | B; the repo already has concrete persistence and wire contracts, and a library should not replace them without evidence. | Pending until schema consolidation need | +| ADR-0009 | Adopt a dimensional-units library? | A. Evaluate/adopt before M11 biology expands. B. Keep typed integer quantity wrappers and evaluate only if conversion complexity or dimensional mistakes justify it. | B for current integer accounting; revisit before introducing broad continuous physical quantities. | Pending at biology/physics boundary | +| ADR-0012 | Adopt a general logging library? | A. Adopt spdlog now. B. Retain current bounded sink boundary until operational needs are measured. | B; no concrete shortfall is recorded, and logging cannot become simulation truth. | No change requested; retain current boundary | +| ADR-0014 | Add NATS JetStream? | A. Introduce for asynchronous fan-out. B. Keep PostgreSQL outbox/direct calls unless measured fan-out requires a broker. | B; later ADR-0072 selected the outbox and did not adopt a broker. | No broker now; revisit only on measured need | +| ADR-0015 | Add a Prometheus/Otel client library? | A. Adopt a client library. B. Keep the tested bounded exposition/adapters. | B; later ADRs already define the implemented observability boundary. | Resolved by later scoped ADRs | +| ADR-0016 | What durability/ownership guarantees apply beyond the M7–M8 single-region contracts and M10 probe transfer experiment? | A. Extend the accepted fenced/checkpoint model to real cross-region ownership only when gameplay requires it. B. Specify global multi-region authority now. | A; current process has no real organism migration requirement, and M10.6 is explicitly experimental. | Defer to real cross-region gameplay gate | +| ADR-0017 | Is ADR-0090's QUIC choice sufficient for current M10, and when revisit perception-aware interest/security? | A. Keep QUIC for M10 and schedule a separate security/perception gate before real gameplay. B. Reopen transport now. | A; M10 includes measured channel behavior, while sensory interest is not implemented. | Current transport settled; future security/perception review pending | +| ADR-0018 | Which S3-compatible object store and backup destination? | A. Select a maintained backend and independent destination before persistent-store rollout. B. Defer store selection until dedicated storage rebuild/backup gate. | B for now; ADR-0074 records destination, encryption, schedule and WAL archiving as pending. Avoid archived MinIO upstream by default. | Pending storage/backup gate | +| ADR-0019 | Which planetary topology, voxel LOD and surface mesher? | A. Choose a candidate now. B. Prototype cubed sphere/topology and compare meshers with shared fixtures in M13. | B; topology and geometry are explicitly experiments and no renderer is needed yet. | Pending M13 R&D | +| ADR-0020 | Is the foundation delivery model still appropriate? | A. Keep Gitea CI plus manual reviewed digest promotion. B. Reopen delivery architecture. | A; later GitOps/Argo ADRs preserve separation between image build and cluster sync. | No change requested; retain | +| ADR-0030–0035 | Are M3 genome/development/mutation rules final gameplay rules? | A. Treat these contracts as the game rules. B. Keep them as an initial schema/prototype and decide omitted heredity/ecological pressures before gameplay. | B; every M3 ADR scopes parameters and candidate generation as experiments and defers the major biological questions to later gates. | Keep prototype scope; reopen before gameplay integration | +| ADR-0036–0040 / OPEN_QUESTIONS #16 | What fidelity/error envelope is acceptable for production population abstraction? | A. Adopt the M4 fixture thresholds as production gates. B. Use M4 only as proof of measurable loss, then validate thresholds against representative multi-genome cellular ecology. | B; M4 evidence explicitly says its one-genome fixture does not generalize. | Pending representative population-model gate | +| ADR-0070, 0074 / OPEN_QUESTIONS additional blockers | Where are durable object snapshots and backups stored, encrypted, retained and verified? | A. Finalize after storage/RAID rebuild with an independent failure domain. B. Treat current node-local dev/stage volumes as sufficient for World0. | A; ADR-0070 calls its storage provisional and ADR-0075 blocks World0 until independent durability is proven. | Pending storage rebuild and backup plan | +| ADR-0072 | Where should actionable alerts be delivered? | A. Configure a destination once operational ownership/contact path is chosen. B. Keep alerts local-only. | A before persistent unattended operation; destination is intentionally pending. | Pending operations/contact decision | +| ADR-0075 / OPEN_QUESTIONS #38 | What World0 RPO/RTO and promotion approvers are acceptable? | A. Use the dev/stage limits and explicitly accept host-loss rewind. B. Define stricter independent durability and named human approvers before World0. | B; current ADR blocks World0 until independent-failure-domain ACK durability and promotion authority exist. | Pending before World0, not before current development | +| ADR-0087 | Does route documentation match repository and live evidence? | Reconcile existing configuration and qualification evidence; this is factual verification, not a new enable/disable choice. | The dev overlay already includes the route; the earlier disabled assertion was stale. | Repository status corrected; live qualification evidence still requires reconciliation. | +| ADR-0087 | How should workflow-created windows reach Argo? | A. Workflow prepares the change; operator manually syncs. B. Restricted workflow-driven Argo sync. | A. | **A accepted, 2026-10-08; D-001.** Live Status read path is separate follow-up work. | +| ADR-0087 | How should clock changes affect a running session window? | A. Close at either UTC expiry or a suspend-aware elapsed deadline, whichever comes first. B. Rely on UTC expiry and host synchronization alone. | A. | **A accepted, 2026-10-08; D-002.** Implementation/tests and numerical clock-health tolerances remain follow-up work. | +| ADR-0097 | When should the corrected reference load drill run? | A. After the new image is promoted and a grant bundle is prepared, run the 10.9d reference test on evolution-dev. B. Defer the qualification and leave M10.9 open. | A, because the first run did not qualify capacity and the corrected harness is now in user changes. | Awaiting operator window/image promotion | + +## Reviewed open-question register + +The crosswalk below preserves the original numbering in +[`OPEN_QUESTIONS.md`](OPEN_QUESTIONS.md). “Pending” means the architecture needs a +future design decision; it does not necessarily block the current engineering +milestone. User decisions can be submitted in plain text by question number (for +example, “Q3 B; Q14 A, with…”); the register will record the choice and any limits. + +| # | Topic | Options (A / B) | Recommendation | Disposition / source | +|---:|---|---|---|---| +| 1 | Tick frequency and biological rates | A. Keep 50 ms. B. Reopen the tick quantum. | A; time-based biological rates convert deterministically at the tick boundary. | Ratified in ADR-0089; rate migration/precision is M11.1. | +| 2 | Fixed/variable boundaries | A. Fixed authoritative ticks, host wall-clock pacing. B. Variable authoritative dt. | A; variable dt would weaken replay and rate accounting. | Settled by ADR-0006/0089; ecology uses integer tick multiples. | +| 3 | ECS | A. Keep sorted rows until realistic component churn exists. B. Adopt a production ECS now. | A; benchmark against biological workloads before exposing library handles or changing IDs. | Pending production ECS gate; ADR-0005/0021. | +| 4 | Dependency manager | A. Compare/select now. B. Defer until managed acquisition solves a concrete dependency problem. | B; compare vcpkg and Conan on a real compiled dependency and include offline/reproducibility/license evidence. | Pending; ADR-0003. | +| 5 | Units library | A. Keep typed integer wrappers for current exact accounting. B. Evaluate a dimensional library before continuous physics expands. | A now, with a review gate before continuous biological/physical equations. | Pending at that gate; ADR-0009 and ADR-0024. | +| 6 | Determinism guarantees | A. Require bit-exact determinism for all systems/platforms. B. Define exactness per integer system and explicit tolerances for floating-point/physics. | B; keep authoritative decisions reproducible and versioned, but do not promise universal floating-point identity. | Pending a per-system contract; ADR-0007/0089. | +| 7 | Mutation generation | A. Keep uniform seeded valid candidates as a baseline. B. Add bounded environmental/behavioral context without a ranked “best build.” | B for gameplay, with explicit and testable context inputs; preserve the unweighted catalog as a baseline. | Pending before player-facing mutation; ADR-0033. | +| 8 | Genome representation | A. Extend the immutable developmental-capability record. B. Replace it with literal DNA or a new representation. | A; maintain versioned capability schemas, not literal DNA. | v1 accepted; determine capability expansion/versioning before gameplay; ADR-0030. | +| 9 | Developmental body representation | A. Typed developmental/body graph. B. Direct arbitrary mesh editing. | A; geometry must derive from capabilities and validated attachments. | Pending M13 morphology contract; ADR-0031 and OPEN_QUESTIONS. | +| 10 | Heredity and reproductive mutation | A. Funded offspring with explicit seeded mutation and parent ancestry. B. Copy the genome unchanged. | A as a design direction; define mutation timing, costs, count, and inheritance before M11 gameplay. | Pending gameplay rule; ADR-0028/0033. | +| 11 | NPC mutation | A. Descendants can diverge under the same bounded mutation rules. B. NPC descendants retain their genome unless a player acts. | A is more consistent with autonomous evolution, but must be simulated and validated before adoption. | Explicitly undecided until M12; ADR-0034/0035. | +| 12 | Species/speciation | A. Derived, versioned biological classification with no class mechanics. B. Player-selected species/class labels. | A; taxonomy must not gate capabilities or progression. | Classification threshold/identity remains open for M12; founding requirement. | +| 13 | Lineage extinction | A. Extinct only with no living members and no viable reserve at any simulation tier. B. Mark extinct when no active individuals remain. | A; aggregate populations and durable reserves must count. | Define viability evidence/reserve semantics before M12; ADR-0034/0036. | +| 14 | Offline player state | A. Remove/park the controlled organism with zero progression and explicit reconnect policy. B. Leave it active in-world and vulnerable. | A; never allow offline farming, and specify whether logout safely removes or leaves a non-progressing body before persistence. | Pending player-persistence design; founding requirement. | +| 15 | Cellular-to-multicellular transition | A. Require physiological capability and ecological viability, without a linear ladder. B. Use a fixed progression threshold. | A; transition should emerge from development and available resources. | Pending M14 criteria; biology/world design. | +| 16 | Population abstraction math | A. Use the M4 measured fixture bounds. B. Calibrate cohorts against representative multi-genome cellular ecology and declare error envelopes. | B; M4 proves loss can be measured but its numbers do not generalize. | Pending population model; ADR-0036–0041. | +| 17 | Active region dimensions | A. Benchmark against interest, entity count and migration overhead. B. Pick a fixed size now. | A; dimensions are operational performance choices, not permanent world identity. | Pending M7/M10 production workload; ADR-0060/0096. | +| 18 | Planet coordinates | A. Keep bounded local integer frames with stable global addresses. B. Commit to a full planetary projection now. | A now; prototype global mapping before the voxel planet. | Local contract accepted; planetary mapping pending M13; ADR-0009/0042. | +| 19 | Spherical voxel strategy | A. Prototype cubed sphere and compare alternatives. B. Use one global Cartesian grid. | A; test poles, seams, deep edits and LOD. | Pending M13; ADR-0019. | +| 20 | Voxel LOD | A. Sparse procedural base, aggregate far fields, active detailed chunks. B. Uniform meter voxels everywhere. | A; it is required by the sparse-world vision. | Principle locked; thresholds/refinement policies pending prototypes; ADR-0019. | +| 21 | Surface meshing | A. Compare Marching Cubes, Surface Nets and Dual Contouring on shared fixtures. B. Select a familiar mesher now. | A; measure seams, topology, collision, edits and cost. | Pending M13; ADR-0019. | +| 22 | Hydrology | A. Start with conserved regional reservoirs/flux. B. Build full fluid dynamics first. | A; constrain water accounting before more detailed flow. | Pending environmental R&D; ADR-0050/0051. | +| 23 | Atmosphere | A. Aggregate mass/species budgets. B. Global computational fluid dynamics. | A; no global CFD promise without a demonstrated need. | Architecture direction recorded; detailed model pending world/ecology design. | +| 24 | Cross-region ownership | A. Fenced lease and explicit prepare/transfer/commit recovery. B. Duplicate state during handoff. | A; exactly one authoritative owner at every step. | Probe experiment accepted; production organism semantics pending gameplay; ADR-0060/0096. | +| 25 | Reliability layer | A. Use library-backed QUIC streams plus datagrams. B. Implement reliability over UDP. | A. | Settled for M10 by ADR-0090; revisit only with new platform or workload evidence. | +| 26 | Serialization | A. Keep explicit bounded versioned codecs per domain. B. Adopt one universal schema library now. | A until a shared workload and migration need justify a measured comparison. | Pending only if consolidation is needed; ADR-0008/0061/0090. | +| 27 | Snapshot/events | A. Snapshots + bounded replay batches + durable semantic history. B. Persist every tick/event as universal event sourcing. | A; keep full recovery state and history records distinct. | M7 contract accepted; ADR-0058/0061–0063. | +| 28 | Recovery | A. Replay a committed contiguous range under a unique fenced epoch. B. Resume from latest snapshot without full verification. | A. | Settled for M7 region host; ADR-0060/0065. | +| 29 | Cross-version migration | A. Clone, migrate, accelerated compare, then explicit barrier/approval. B. Allow mixed simulation versions in adjacent live regions. | A; no live-world rule drift. | Framework accepted; actual converters and approval policy pending per migration; ADR-0068/0076. | +| 30 | Steam identity | A. Provider subject maps through an adapter to internal AccountId. B. Make Steam ID the account key. | A; preserve provider independence. | Architecture direction accepted; integration deferred until Steam milestone; ADR-0091. | +| 31 | Friend recognition | A. Separate authenticated social signal; no player/NPC tags. B. Show ownership/player labels. | A; this preserves the shared biological presentation requirement. | Principle locked; authorization and presentation details pending social feature. | +| 32 | Anti-cheat | A. Server authority, bounded authenticated intents, rate limits and validation. B. Trust client state and reconcile abuses later. | A. | Core policy locked; threat review/abuse coverage continues at M10 and before gameplay; ADR-0017/0091/0097. | +| 33 | AI behavior | A. Shared bounded intention interface and deterministic controller. B. Separate AI-only command path. | A; prevent privileged AI outcomes and keep control source separate from biology. | Pending behavior architecture before M11 AI; ADR-0022/0079. | +| 34 | Evolvable behavior | A. Optional heritable behavior capabilities with costs. B. Keep intelligence/behavior fixed and outside evolution. | A as an experiment only; intelligence must remain optional. | Pending M12/R&D; foundational design is explicit. | +| 35 | Morphology limits | A. Body graph validates material, attachment and genetic capability. B. Allow arbitrary player geometry. | A. | Pending M13; ADR-0030/0031 and body-graph proposal. | +| 36 | Procedural animation | A. Prototype IK/gaits/locomotion from morphology. B. Depend on hand-authored species animations. | A; hand-authored animation cannot define the open-ended body system. | R&D pending M13; no early implementation required. | +| 37 | Retention | A. Keep genome ancestry permanently and tier older replay/snapshots/backups. B. Retain every raw event and snapshot forever at full resolution. | A; preserve history while defining separate replay/archive retention and verified backup policies. | Ancestry permanence locked; concrete retention periods pending backup design; ADR-0034/0062/0074. | +| 38 | Disaster recovery objectives | A. Dev/stage worker-loss RPO 0, RTO ≤60 s; host-loss restore is explicit rewind. B. World0 requires acknowledged outcomes in an independent failure domain before ACK. | Both, applied to their respective environments; do not relax the World0 gate. | Dev/stage ratified; World0 remains blocked; ADR-0075. |