91 lines
5.4 KiB
Markdown
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.
|