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.