Architecture

Condensed from docs/01-architecture.md.

Status: architecture specified. A-01 contracts/coords.rs is frozen (2026-10-11, on ADR-029's sign-off) — every layer may now implement against the coordinate surface. The rest of contracts/ is not frozen. A layer whose subsystem doc cites an open SPEC/OQ is a description, not a build target.

The stack

Layer	Choice	Property
Engine runtime	Rust + WebGPU/WGSL	memory-safe, cross-platform, browser-capable
Coordinates	HDCS: i64 global + camera-relative f32	infinite range, bit-identical across machines
Macro state	Merkle ledger + localized octree roots, LSM-style compaction	world bounded by hash/disk, not RAM/tick rate
Micro edits	Sparse delta mask, bitpacked u64 in slabs	O(1) write, cleared at commit
Memory	Slab allocator, bump pointer, L1 VRAM / L2 RAM, LRU	zero fragmentation, O(1) mass reset
Rendering	GPU compute SDF raymarching	no meshes, no textures, infinite detail
Culling	Spatial BVH keyed to slabs	O(log N) entity skip
Physics	Analytic ∇SDF gradient queries	normals without vertex buffers
Animation	Domain deformation over time	no skeletons
Audio	Sphere-traced SDF occlusion	sound knows the geometry, nothing baked
Circuits	Compiled graph topology f(inputs, t)	zero wire latency, runs while unloaded
Macro simulation	Time functions + bounded CA + event tags	lazy, fast-forwarded at observation
Logic & mods	Polyglot WASM behind WIT contracts	deterministic, sandboxed, hot-reloaded
Assets	RON/JSON/KDL/TOML authored → FlatBuffers runtime	human to write, zero-copy to run
Multiplayer	Signed intent streams + rollback + epoch root verification	32 bytes proves world equality

Data lifecycle

AUTHORING (RON · JSON · KDL · TOML · Rust/TS/C++/Python/Go · WGSL)
      │  assetc: parse once, validate, emit binary   (<5 ms, never at frame time)
      ▼
CONTRACTS (FlatBuffers .fbs + WIT worlds)            ← the only thing the runtime trusts
      │  mmap / memcpy → GPU storage buffers
      ▼
ENGINE RUNTIME  (ledger · slabs · BVH · gradients · WASM · graphs)
      │  per frame, camera-relative f32
      ▼
RENDER PROJECTION (WGSL compute raymarcher → pixels)

The rule this encodes: text exists only to the left of the compile step. The runtime never parses.

Two-layer state

        GLOBAL MERKLE LEDGER   (slow, cheap, authoritative, hashable)
                    ▲ commit at epoch / sleep
   LOCAL DELTA MASK ┘──► GPU RENDER PROJECTION   (fast, local, disposable)

The ledger records what happened as transactions and named event tags. The projection computes what you see from MerkleRoot_N ⊕ LocalDelta for this frame's frustum.

Core equations

Name	Form
view-time state	BlockState = f(Position, CurrentTick) ⊕ PlayerDelta
rendered state	Final = S_base ⊕ M_local
epoch commit	S_new = S_old ⊕ M_local, then M_local = ∅
render pass	pixels = Render(SlabState(FrustumSlabs), C_global) — state arrives by buffer, the shader only projects it
clock circuit	state(t) = ⌊(t + φ)·ω⌋ mod 2
factory output	items = ∫[t_start → t_sleep] ProductionRate(t) dt
epoch proof	EpochHash = MerkleHash(BaseGenesisRoot ⊕ CommittedSlabs)
surface normal	N = ∇SDF(p) (central differences, 6 evaluations)
camera transform	P_local = P_global − C_global

Note on the render-pass row. The source wrote it as VoxelOutput = ComputeShader(XYZ, MerkleRoot_N) ⊕ LocalDelta — the GPU deriving voxel state from a Merkle root. That form is rejected (SPEC-02, ADR-017): f(pos, epoch) runs in deterministic Rust/WASM, because WGSL float math differs per adapter and two GPUs would produce two roots. The row above is the sanctioned reading; the original is kept here so the correction is visible rather than silent.

Invariants

1. One coordinate truth — every subsystem resolves space through HDCS; no private axes.
2. Simulation never reads the GPU — gradients come from SDF source on CPU/WASM, not VRAM.
3. Hot path is allocation-free — pre-reserved slab slots only.
4. Runtime parses nothing — FlatBuffers / static WASM memory.
5. Deterministic or not shipped — canonical state uses integers, fixed-point, or deterministic WASM float ops whose result nothing hashes; nothing a hash depends on comes from a shader (ADR-017, the fix for the design's most dangerous inconsistency).
6. The delta mask is the memory — player changes survive in M_local or a committed epoch; untouched base land is regenerable and never treated as storage.
7. Epochs are total — mid-epoch truth is always base ⊕ pending.
8. Mods are transactions — never direct block-array writes.
9. Contracts change by ADR only.

What it buys, what it costs

Buys: world scale bounded by disk/hashes; no state loading screens (fast-forwarding centuries is a hash-and-flag update); near-zero storage for untouched terrain; a visibly aged world without per-entity pathfinding; every asset expressible as text; verifiable multiplayer in 32 bytes.

Costs (each tracked as an open question, not a footnote): traditional redstone-style sequential logic is unsolved (OQ-02); distant causality needs a mechanism nobody has proven (OQ-01 — the spike that can invalidate the design); SDF raymarching costs fill-rate and lives or dies on culling discipline; and the world gives up exact mid-simulation history in exchange for endpoint correctness.