Files
aevolution/docs/architecture/SYSTEM_OVERVIEW.md
T
dingoandClaude Opus 5.5 9bb147de82 Implement M9.5 biology-derived organism rendering and inspector
Add OrganismPresentation cells derived via biology::derive_phenotype with
no controller, owner or level fields (pinned by test), so identical
biology renders identically for players and NPCs. OrganismLayer reuses
the ADR-0080 ordering/freshness semantics; death is a remnant state and
removal is absence. Rendering takes an explicit rectangle budget, falls
back to body-only detail and marks truncation instead of dropping data.
An opt-in rectangle-only hover inspector shows phenotype gauges; ImGui is
not adopted. ADR-0081 records the decision; evidence in VALIDATION.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 18:21:53 -04:00

128 lines
7.0 KiB
Markdown

# System overview
Status: architecture recommendation; locked product constraints are in
[PROJECT_VISION](../PROJECT_VISION.md). Only the local proof described in
[SIMULATION_ARCHITECTURE](SIMULATION_ARCHITECTURE.md) is implemented initially.
## System context
```mermaid
flowchart LR
Player[Player / Steam desktop client] -->|intentions| Game[Aeternalis world services]
Steam[Steam identity provider] -->|validated identity| Game
Operator[Operator] -->|approved GitOps release| Game
Game -->|perceived state / outcomes / history| Player
Game --> History[(Persistent world and phylogeny)]
Game --> Telemetry[Metrics / logs / traces]
Backups[Independent backup failure domain] <-->|verified archives / restore| History
```
## Component and dependency boundaries
```mermaid
flowchart TD
Client[Custom desktop client] --> Protocol[Protocol / prediction adapter]
Region[Region process] --> Network[Transport / validation / interest]
Region --> Persist[Persistence adapter]
Region --> Sim[libevo simulation]
Sim --> Biology[Genome / development / phenotype / ecology]
Sim --> Environment[World / resources / sparse terrain interfaces]
Sim --> Core[IDs / units / ticks / PRNG]
Biology --> Core
Environment --> Core
Protocol --> Core
CLI[evo-sim / tests / benchmarks] --> Sim
Backend[Modular backend: identity / history / director] --> Persist
Persist --> Stores[PostgreSQL / object store]
Network --> Protocol
```
The renderer may consume phenotype and terrain views. Biology never consumes a
mesh, graphics device, network session or database connection. Public simulation
headers expose values and bounded commands, not third-party ECS/storage types.
No Steam ID, socket, Kubernetes API, logger clock or storage handle belongs in
the simulation state. Durable account references live in orchestration mapping.
M9.2 implements the opt-in [native client boundary](CLIENT_ARCHITECTURE.md):
copied immutable presentation frames and one main-thread platform owner. M9.4
projects owned copies of M6.3 environment views (ADR-0080); the dependency runs
world -> client views -> render only. M9.5 renders organisms from M3 phenotypes
(ADR-0081) without controller or ownership labels. It does not yet connect to a
region server.
| Boundary | Owns | Must not own |
|---|---|---|
| core | Value types, deterministic algorithms, explicit version constants | Global state, threads, I/O |
| simulation (`evo_simulation`, alias `evo::simulation`) | State, stable tick ordering, component lifecycle, pure restore validation | Wall clock, transport, database or rendering |
| accounting (`evo_accounting`, alias `evo::accounting`) | Typed finite inventories, atomic conserved transfers, in-memory action watermark | Chemistry, minting resources, entity lifecycle or durable storage |
| processes (`evo_processes`, alias `evo::processes`) | Synthetic source/producer rules and atomic process/accounting state | Live organism ancestry, persistence, heat recycling or external I/O |
| biology | Genotype → development → phenotype; energetic transfers | Account rewards, player/NPC subclasses |
| world | Procedural base identity, spatial/environmental fields | Dense planet allocation, gameplay authority |
| persistence | Durable metadata, snapshots, replay batches, migration | Per-tick simulation decisions |
| network | Input validation, authentication boundary, bounded codecs and relevance | Trust in client-provided positions or biology |
| backend | Identity adapters, account/world metadata, history queries, directory/lease coordination | Every noun deployed as a service |
| app / server | Tick pacing, I/O ownership, durable outcome barrier, metrics export | Alternative biological implementation |
Core, simulation, local snapshot codec, accounting, processes and `evo-sim` are source modules
in the proof. Accounting has an independent tested contract; it is not yet wired
into particle state. Future rows are boundaries, not empty directories or dummy services.
Split a library when a real independently tested contract exists.
The processes library now includes a shared feeding community (ADR-0026): producer
and consumer reservoirs have one owner, with heat/waste and activity flags committed
atomically. Standalone producer fixtures remain available for focused testing.
## Runtime topology and data flow (target)
```mermaid
flowchart LR
Client[Client] -->|HTTPS identity / world selection| API[Backend API]
API -->|session and routing grant| Client
Client -->|authenticated input channel| Worker[Region worker]
Director[Director] -->|assignment hint| Worker
Worker -->|fenced lease / commit| PG[(PostgreSQL)]
Worker -->|immutable snapshots| S3[(Object store)]
Worker -->|tick-boundary commands| Sim[In-memory simulation]
Sim -->|events and views| Worker
Worker -->|perception-filtered snapshots / durable outcomes| Client
PG -->|transactional outbox| Bus[Optional JetStream]
Bus -->|idempotent projections| History[History queries / ecology jobs]
```
Simulation reads an immutable ordered command batch at a tick boundary. It emits
state and domain outcomes. The host stages durable records and marks an outcome
committed only after the durable barrier. Projection notifications are not the
source of authority. Simulation metrics are deterministic counters; timing and
tracing are measured outside the simulation.
## Failure containment
- Worker crash: recover a consistent snapshot plus complete committed replay
range under a new lease epoch. Never accept an old worker's writes.
- Database unavailable: stop durable decisions and eventually pause simulation;
do not continue granting irreversible uncommitted outcomes.
- Object storage unavailable: retain/retry bounded pending snapshots; enforce
journal/storage budgets rather than silently dropping recovery data.
- Backend unavailable: availability degrades separately from existing regions,
within session and lease policies. This does not grant workers perpetual
authority.
- Shared-host outage: all initial workloads can stop. Off-host recovery is an
explicit operations requirement, not a benefit Kubernetes provides by itself.
See persistence, network and infrastructure architecture for detailed contracts.
## M6.5b environmental process boundary
[ADR-0055](../adr/0055-environmental-process-contract.md) specifies a separate
process fixture that privately owns tagged world resources and process progress.
The process library may depend on world; world must not depend on process or genome
code. Only constrained process operations may create private resource checkpoints.
Complete rate/biology persistence precedes executable stepping in M6.5c. Existing
M2 process interfaces and results remain unchanged.
M6.5c now implements `evo::processes::EnvironmentalCommunity` and its complete
[rate/biology envelope](../../schemas/environmental-community.md). World only exposes
a private conserved checkpoint to this constrained process owner; no genome or
process-type dependency enters the world library. New public stepping lives in the
process layer; existing M2 process interfaces remain unchanged.