Files
aevolution/docs/world/WORLD_CODEC.md
T

5.4 KiB

M5.6 world snapshot and edit-journal contract

ADR-0047 accepts bounded local byte codecs. Public API is in evo/world/chunks.hpp; evo::world remains free of database, networking, rendering and Kubernetes dependencies. No existing biology/particle snapshot format changed.

API and ownership

  • store.snapshot(identity) returns canonical bytes for the current coherent store. Caller supplies nonzero world/frame IDs and owns their association with this store.
  • ChunkStore::restore(bytes, expected_identity, byte_budget) returns a new owning store only on full validation. Never replaces an existing live store in-place.
  • make_edit_journal(base, identity, requests, byte_budget) validates/restores a base, executes up to 64 fresh requests privately and encodes their expected result.
  • replay_edit_journal(base, journal, identity, byte_budget) restores the base, applies the whole bounded journal and verifies the final state before returning a new store.

All are single-owner operations; input spans remain immutable/readable through return. Use typed WorldCodecError for invalid input/budget/state. Allocation exceptions reach the host. Views of the source store never become valid views of the restored store. Budget is host policy, supplied explicitly and excluded from canonical state. Restore preserves slot capacity, versions, revisions, successful edit count, debris and exact bounded replay history. The snapshot covered sequence is command high-water, not a tick or contiguous ordinal. Journal requests cannot contain retries or cache operations.

flowchart LR
  S[Canonical snapshot] --> V[Envelope and semantic validation]
  V --> C[Detached compact store]
  J[Ordered journal] --> R[Predecessor and command validation]
  C --> R
  R --> H[Final canonical checksum verification]
  H --> O[Return owning candidate]

The snapshot carries all loaded chunks including clean ones because loaded membership and revisions affect admitted edits. Unloaded clean regions remain procedural. Dirty chunks cannot be evicted; all removed material therefore remains accountable against resident geometry. No implicit clean/regenerate operation discards edits.

Version and conservation rules

Snapshot schema and journal schema specify every byte and bound. Unknown versions, identities, materials and malformed/trailing data fail closed. Restore compares cells against deterministic generation: no new fill or changed material; clean chunks must match base. Summed removed volume equals stored debris per material. Replay receipts and revision chains are checked; no digest-only retry. All retained history can be undone without exceeding original base fill.

FNV is an accidental-corruption check, not security. Untrusted/unauthenticated world state is not authorized by a correct checksum. M5.7 and production infrastructure must establish trusted manifests and complete journal coverage. Creating bytes alone is neither durable acknowledgement nor permission to clear dirty flags.

Resource bounds and limitations

Snapshot <=70 MiB, journal <=256 KiB, slots <=4096, retained/journal commands <=64, cuts <=64 each, chunks per edit <=4. Restore validates framing/count bounds before allocation and enforces the candidate's resident budget for metadata and payloads. Codec input/output buffers are outside that budget: the host must separately admit up to one input and one output snapshot plus journal and fixed codec workspace. Largest explicit encoding workspace is a 4096-entry index array plus a 64-entry history order array; restoration uses one 4096-word chunk and bounded history scans. Reserve 64 KiB for codec workspace in addition to ordinary runtime/allocator overhead. No compression or performance SLA is claimed; full restore recomputes base geometry and checks at most 4096 retained cuts against later retained cuts.

Evidence and next step

Tests cover independently encoded empty v1 bytes, canonical round trips, 65 edits and history wrap, post-restore continuation/retries, seam journal replay, empty segments, every truncation of fixtures, checksums, recomputed-checksum semantic corruption, unknown versions, wrong identity, counts, trailing/oversized input and insufficient memory. A 128-input deterministic fuzz smoke is in CTest; Linux CI adds 10000 libFuzzer cases. The harness repairs mutated checksums to exercise semantic validation instead of stopping only at the envelope. Local Windows smoke is not a claim that Linux coverage-guided fuzzing has executed.

M5.7 adds a separate local publication contract in ADR-0048 and the manifest schema. Two alternating manifest slots select immutable M5.6 snapshot/journal payloads. Recovery validates the selected snapshot and optional journal into a detached store. The manifest replacement is the local commit point; this provides no multi-host durability, production lease, authentication or disaster recovery guarantee. Compaction while a journal is active accepts only its byte-identical replay result, and poisoned handles must reopen before recovery. Partial-write and post-replacement sync failures have deterministic test injection. M5.6 does not write files, fsync, delete journals, clear dirty state or recover a live server process. M7 supplies the production durability/ownership path.