Files
aevolution/schemas/world-snapshot.md
T

3.4 KiB

Local world snapshot v1

Scope: ADR-0047; canonical bounded buffers, not native structs or a database format. All integers are unsigned little endian. Signed chunk axes encode modulo 2^64 and decode without implementation-defined unsigned-to-signed overflow. No optional fields.

Offset Field Width
0 Magic 0x31504e5357564541 u64
8 Format version 1 u32
12 Total byte length including checksum u32
16 World ID, frame ID (both nonzero) 2*u64
32 Base seed u64
40 Coordinate, generator, material versions; edge 4*u32
56 Slot capacity; resident chunk count 2*u32
64 Local revision high-water u64
72 Covered command high-water (IDs can have gaps) u64
80 Number of successful fresh edits since store creation u64
88 Rock and regolith debris capacities 2*u64
104 Rock and regolith debris balances 2*u64
120 Retained request count, min(successful edits,64) u32
124 Chunk records, then replay records variable
final 8 FNV-1a checksum of all preceding bytes u64

Chunk records are strictly lexicographic by signed x/y/z: address 3*u64, revision u64, dirty u8 (0 or 1), then 4096 X-fast logical cells (material u16, fill u16). Each chunk is 16417 bytes; native resident compression does not affect encoding. Revisions are nonzero, unique among current chunks and <= revision high-water. All geometry must be an excavation-only reduction of the recorded base. Clean chunks must equal the base. Dirty pins can still contain unchanged base geometry.

Replay records are strictly increasing command ID: command u64, request digest u64, destination u32, cut count u32, followed by cuts. Each cut is address 3u64, local x/y/z 3u32, expected revision u64, removed fill u32 (48 bytes). Then receipt removed volumes 2u64, receipt chunk count u32, and receipt chunks (address 3u64, revision u64). This is 44+48cuts+32receipt_chunks bytes. Digest rules are in world-edits.md. Unused array tails, directory slots, replay ring cursor, pointers, C++ padding and host byte budget are not encoded. Restore rebuilds compact data and canonical ring ordering. Recipe/version and logical geometry are preserved, not allocation layout.

Bounds: 1..4096 slots, resident count <= slots, 0..64 replay records, 1..64 cuts per record, 1..4 receipt chunks. Empty snapshot length is 132. Total <=70 MiB, with exact length/no trailing bytes. Validate envelope before counts allocate state. Compare supplied world/frame IDs exactly and reject unsupported base/format versions.

FNV-1a uses offset 14695981039346656037, prime 1099511628211, unsigned 64-bit wrap. It detects accidental corruption and is NOT authentication. Durable manifests need trusted provenance and a later strong digest; never authorize a client from this hash.

Semantic checks include terrain loss==debris per material, balance<=capacity, request/receipt consistency, history counts/high-water, receipt revision chronology, current/next-request revision linkage, and undo feasibility of retained cuts. When all edits remain retained, receipt totals equal debris; otherwise they cannot exceed it. Edited history chunks cannot be absent or clean. Serialization never clears dirty.

Independent empty fixture: tools/world_snapshot_reference.py and tests/fixtures/world_empty_v1.hpp. Changes to bytes/semantics require format/version review; do not update a golden merely to satisfy tests.