Current Architecture Decisions
Keep only current rules. See the mapping for terms and implementation gaps, and root todo.md for tasks.
ADR-001:Persistent and simulation authority
Base owns base::Avatar and persistent gameplay; cell owns authoritative cell::Avatar/Entity simulation; database accesses storage. Each domain has one writer. Cross-server play and Instance destruction do not move profiles.
ADR-002:Space, Cell, and existing Scene
Space is an independent runtime space corresponding to Scene semantics, without a synonymous container chain. Cell is a partition; cell is an executor. Initially one process and one Cell per Space; reserve multiple Cells per Space. Current Scene remains local.
ADR-003:Instance lifecycle
Base validates groups, World places space/executors, and cell runs Instance and submits settlement to owning Bases for durable database confirmation. Reuse eight states. Instance is neither space nor process; shared state has one logical owner.
ADR-004:Space changes and Cell handoff
Explicit Space changes differ from same-Space Cell handoff. Current SceneTransfer recreates Avatar, without continuous partition transfer. Freeze, prepare, conditionally commit, activate, and clean while retaining Base. Reconcile ambiguity first.
ADR-005:Local AOI and observer views
SceneAoi/ViewerState are local visibility primitives executed by cell. Neighbor Ghosts, merged visibility, and complete Witness semantics are future work, without an AOI business process.
ADR-006:Combat and settlement
cell runs BattleRuntime with explicit randomness, ordering, and clocks. Owning Bases validate stable settlement IDs; database commits profiles and deduplication credentials durably. Delivery, admission, and in-memory rewards are not persistence.
ADR-007:Independent storage
database owns profile operations, routing, and durable results; Base owns business rules. Extract JSON, SaveQueue, and PersistJournal. Executors receive neither full profiles nor home database credentials. External MySQL/Redis remain requirement-driven.
ADR-008:Recovery scope
Journal replay/restart does not restore active simulation. Recover Base profiles, World topology, and cell simulation separately; reestablish authority/routes and define failure for unvalidated activity recovery.
ADR-009:Simulation threads
Each entity has one authoritative Cell writer. Logical executors modify sequentially; IO/background workers submit bounded intents. Shared multi-Cell Instance state has one logical owner without shared memory or global lockstep.
ADR-010:Registration and supervision
Base/World register with loginServer; executors register with their World. World decides topology; directories project location. machined only supervises locally and is optional beside World/cell. Cross-machine standby/arbitration remain deferred.
ADR-011:Gateway and two update schemes
gateway retains sockets and separate Base/cell routes. Protocol replacement converts state; Base, cell, and World management hand off their own state. Code-only changes preserve wire and may update Lua. Validate TCP, sessions, and complete activity continuity separately.
ADR-012:Default deployment and scaling
Initially one executor hosts full Cells for multiple Spaces, without one process per instance. More executors register with World; place whole Space/Cells first, enable same-Space partitions later. Spawn/readiness/failure protocols remain work.
ADR-013:Observability status
Reuse custom logging, MetricRegistry, span/trace, and M1 collection without blocking simulation. Dedicated Profiler and OpenTelemetry SDK/OTLP exporter are not integrated. External observability deployment is requirement-driven.
ADR-014:Names and correspondence
Executables are gateway, login, base, world, cellServer, database, and machined; loginServer/baseServer/worldServer in the design docs name the roles of those binaries. Add the discussed cell execution role (standalone cellServer binary; world --role=cell is explicitly rejected). World management overlaps CellAppMgr, cell overlaps CellApp, Scene corresponds to Space, and Instance is Apollo gameplay. Preserve external names.
ADR-015:Asynchronous admission
Current WorldApp::gameLoop pumps/consumes acceptanceQueue_ and advances World. Move that simulation loop into cell, leaving management in World. Admission is not execution; never block IO waiting for ticks.
ADR-016:Overload and shutdown
Define capacity, thresholds, budgets, and rejection; never silently discard accepted work. Close admission, sweep, settle, release, then stop. Management placement drain differs from executor activity drain.
ADR-017:Reply semantics
Correlate request_id and distinguish delivery, admission, execution, and persistence. Consumption acknowledgement does not replace validation, idempotent settlement, or durable save confirmation.
