Files
aevolution/docs/world/WORLD_CODEC.md
T

91 lines
5.4 KiB
Markdown

# M5.6 world snapshot and edit-journal contract
[ADR-0047](../adr/0047-world-codec.md) 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.
```mermaid
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](../../schemas/world-snapshot.md) and
[journal schema](../../schemas/world-journal.md) 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](../adr/0048-local-publication.md)
and [the manifest schema](../../schemas/local-world-manifest.md). 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.