Files
aevolution/docs/architecture/WORLD_ARCHITECTURE.md
T

200 lines
11 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.
## Implemented M5.6 snapshot/replay boundary
The [world codec](../world/WORLD_CODEC.md) preserves loaded membership, dirty cells,
versions, revisions, finite debris and retry history in one validated snapshot.
Journal replay uses the existing excavation transaction on a detached store. Dirty
chunks remain pinned; encoding does not acknowledge durability. M5.7 supplies local
file publication and compaction; no production persistence dependency was added.
M5.8 validates the local stack through separate prepare/compact/verify processes; see
[bounded world proof and measurements](../engineering/WORLD_PROOF.md). This adds no
production ownership or biological resource conversion contract.
## M6.1 environmental coupling boundary
[ADR-0050](../adr/0050-environmental-units-and-coupling.md) scopes a one-voxel,
axis-aligned habitat with explicit micrometre depth. The
[units contract](../world/ENVIRONMENTAL_UNITS.md) defines finite extensive stocks,
derived concentrations/moisture, dimensional examples, closed/open accounting,
rate residual ownership and rejection of unsupported terrain mass conversions.
The implemented helpers are pure computations. Inventory pages, reservations,
ownership enforcement, transfer commits and persistence follow in M6.2-6.4.
## M6.2 optional field storage
[ADR-0051](../adr/0051-optional-environmental-fields.md) implements a separate
bounded [FieldStore](../world/ENVIRONMENTAL_FIELDS.md). It owns fixed habitat sites,
explicit finite inventories, property-only material defaults and optional uniform/
sparse scalar pages. Its versioned codec retains all field state and local transfer
watermark, without relying on procedural resource regeneration. M5 LocalWorldFiles
still publishes only terrain state: integrated terrain/fields/biology recovery must
use a later version bundle. No cross-store biological transfer is authorized here.
## M6.3 environment reads
[ADR-0052](../adr/0052-read-only-environment-views.md) adds
[environment views](../world/ENVIRONMENT_VIEWS.md) across a bounded voxel footprint.
Samples carry exact typed field quantities, habitat volume, terrain chunk revision
and an explicit host tick. Queries never load chunks or mutate inventories. A
separate validator rejects stale ticks, field watermarks, foreign store instances
and stale sampled chunk tokens. Coherent store pairing and single-owner scheduling
remain host obligations; M6.4 must validate and commit in one ownership phase.
## M6.4 coordinated resource ownership
[ADR-0053](../adr/0053-atomic-environmental-transfers.md) and the
[transfer contract](../world/ENVIRONMENTAL_TRANSFERS.md) define one owner of field
stocks, terrain binding and tagged organism resource accounts. Fresh views authorize
only staged transfers; both endpoints and the retry receipt publish together after
validation and allocation. Accounts are resource endpoints; biological lifecycle
integration follows in M6.5. Field-only snapshots cannot recover a coupled owner.
M6.5a now provides [coupled resource snapshots](../../schemas/coupled-resources.md)
under accepted ADR-0054. This is a detached, bounded buffer codec; M7 still owns
file publication and durable acknowledgment. M6.5c must extend persistence to
source-rate and biological progress before enabling the corresponding simulation.