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>
128 lines
7.0 KiB
Markdown
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.
|