Files
aevolution/docs/architecture/WORLD_ARCHITECTURE.md
T

10 KiB

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.

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.

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 and the local voxel contract 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 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 and the base generation contract 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 adds compact immutable cells and a fixed-slot, byte-budgeted local store. The contract 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 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 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 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. This adds no production ownership or biological resource conversion contract.

M6.1 environmental coupling boundary

ADR-0050 scopes a one-voxel, axis-aligned habitat with explicit micrometre depth. The units contract 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 implements a separate bounded FieldStore. 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 adds environment views 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.