Files
aevolution/docs/architecture/WORLD_ARCHITECTURE.md
T

144 lines
7.8 KiB
Markdown

# World architecture
Status: locked sparse, persistent, editable-world requirements; recommended
contracts below; planetary topology, resolution and solvers remain experiments.
These are future boundaries, not implemented environmental systems in M0.
```mermaid
flowchart TD
P[Planet seed and generation version] --> C[Planetary aggregate cells]
C --> R[Regions with leased authority]
R --> M[2D microscopic habitats]
R --> V[Sparse 3D environmental chunks]
V --> F[Derived fine detail and mesh caches]
M <--> L[Conservative ecological transfer ledger]
V <--> L
B[Immutable procedural base] --> V
D[Persisted modifications and snapshots] --> V
```
Region, terrain-chunk and ecological-cell boundaries need not coincide. A world
mapping contract resolves them; assigning another process never changes durable
addresses. Every lineage ultimately refers to a player-influenced founder; base
generation supplies geology, chemistry and energy, never implicit wildlife.
## Coordinates and contracts
Recommend a planet-centered right-handed reference frame for interchange,
bounded region-local right-handed frames (+Z up) for active simulation and stable
integer chunk addresses. Persist frame transforms, resolution, origin, units and
versions. A microscopic habitat defines two metric axes and effective depth;
2D area never implicitly becomes 3D biomass. Render origin shifts do not move
authoritative state. Use coarse addresses plus local offsets, not global hot
entity floats. Final spherical indexing, radius, region/chunk sizes and precision
remain open. M5 starts with a small local test volume.
| Logical contract | Inputs / outputs and invariant |
|---|---|
| GenerateBaseChunk | seed, generator/material versions, address → deterministic samples; no I/O clock |
| ReadEnvironment | footprint, requested fields, view → units, resolution, valid tick and error bound |
| ProposeEnvironmentalTransfer | action ID, owners, quantities → reserved inventory or insufficiency |
| CommitEnvironmentalTransfer | reservation, epoch → exactly one debit/credit; retry returns prior outcome |
| ApplyTerrainEdit | command ID, expected revision, geometry, matter destinations → new chunk revision |
| BuildSurface | immutable samples, neighbor revisions, mesher/LOD versions → disposable mesh/collision cache |
## Representation and storage
See ADR-0019. Evaluate palette material IDs, quantized geometry, constant uniform
channels, sparse varying field pages and coarser chemistry grids. Material tables
hold shared coefficients. Allocate only relevant changing fields. Concentration
derives from inventory/volume; temperature derives from thermal energy and heat
capacity. A material ID does not imply unlimited extractable nutrients.
Quantization defines units, range, rounding and residuals. Refinement partitions
existing inventory; coarsening sums extensive quantities before deriving intensive
ones. Fine detail cannot contribute consumable matter without a parent budget.
Benchmarks include geometry, fields, indexes, halos, dirty journals and caches;
stress uniform, heterogeneous and heavily excavated worlds, including deep edits.
```mermaid
sequenceDiagram
participant W as Worker
participant G as Versioned generator
participant S as Object store
participant J as Durable manifest and journal
W->>J: Read committed manifest / covered sequence
W->>S: Read verified compacted payload if present
W->>G: Otherwise generate exact recorded base version
W->>J: Read complete committed edits after covered sequence
W->>W: Replay edits and validate inventory
W->>S: Upload immutable compacted candidate and verify
W->>J: Atomically publish new manifest / covered sequence
```
Keep generator versions required by existing territory. Never regenerate old
chunks under new geology implicitly. Compaction records base/version/address,
revision, covered sequence and digest. Upload alone is not a commit; deletion
waits for clone/backup references and retention. Neighbor halos are read-only,
revision-tagged state. Stale mesh work is discarded. Collision revision gating
requires a later gameplay ADR; visually completed edits cannot bypass physics.
## Ecological coupling and fidelity
2D organisms/cohorts debit biomass through a transfer ledger to 3D plankton
density. Corpses debit organic matter to decomposition/nutrient reservoirs.
Domains do not share literal physics. Each inventory has exactly one owner;
active detail reserves a disjoint share of its aggregate. Transfers record ID,
source/destination, epochs, logical interval, composition, amount and causal event.
Across regions, durably escrow the source before idempotent destination credit.
Recovery retries or cancels using durable transfer state; elapsed time cannot
authorize another credit. In-transit inventory remains in conservation totals.
Edits displace mass to soil, carried resources, debris/fluid or an explicit sink.
Excavation cannot simply delete matter.
Solver intervals are explicit integer multiples of world ticks. Use committed
boundary views and apply integrated fluxes once. Catch-up is bounded and measured;
never silently drop intervals. Hydrology, atmospheric chemistry, erosion,
boundary conditions and acceptable numerical residuals remain experiments. M6
uses light, moisture and one or two nutrients, not global CFD.
Required tests: address round trips and seams; generator golden versions;
duplicate edit idempotency; crash at every compaction boundary; oscillating LOD
without resource gain; stale halo invalidation; stalled transfer escrow; corrupt
objects/full disk rejection. No planet topology or smooth mesher is accepted
until its comparison demonstrates precision, seam correctness and bounded cost.
## Implemented M5.1 boundary
[ADR-0042](../adr/0042-local-voxel-contract.md) and the
[local voxel contract](../world/LOCAL_VOXEL_CONTRACT.md) implement pure signed
address mapping, logical ordinal enumeration, metric corners and cell-fill
validation in `evo::world`. The 1m pitch and bounded local domain are experiments;
8/16/32/64-cell chunk edges remain comparison candidates, not a selected layout.
No data allocation, terrain generation, material table, mass transfer, persistence,
meshing or planet mapping is implemented by this contract. M5.2 measured storage; [ADR-0043](../adr/0043-chunk-layout.md) selects
16-cube uniform/palette/dense geometry for the bounded M5 implementation. Production
chunk ownership/allocation limits remain M5.4; optional chemistry pages remain M6.
## Implemented M5.3 generation boundary
[ADR-0044](../adr/0044-abiotic-generation.md) and the
[base generation contract](../world/BASE_GENERATION.md) add pure versioned point and
16-cube queries. Synthetic abiotic strata use global integer addresses and create no
life. Unsupported versions fail explicitly. Temporary logical output is not resident
storage; bounded chunk ownership/eviction is M5.4. There is no persistence or mesher.
## Implemented M5.4 ownership boundary
[ADR-0045](../adr/0045-bounded-chunk-ownership.md) adds compact immutable cells and a
fixed-slot, byte-budgeted local store. [The contract](../world/CHUNK_OWNERSHIP.md)
specifies construction scratch accounting, current-revision read tokens, regeneration
and dirty eviction refusal. No database, distributed lease or durable acknowledgement
is implied. Cell edits remain M5.5 and persistence M5.6/5.7.
## Implemented M5.5 edit boundary
[ADR-0046](../adr/0046-transactional-excavation.md) implements bounded single-store
atomic excavation, per-material occupied-volume transfer to debris, current revisions,
request digest plus full-payload retry identity, and bounded history with a command
high-water mark. [The contract](../world/TERRAIN_EDITS.md) specifies failure semantics.
No mass/density model or persistence is implied. Debris/retry state must accompany
geometry in M5.6/5.7 recovery, and M6 must reconcile volume with chemical inventories.