Files
aevolution/docs/adr/0008-serialization.md
2026-10-08 12:08:53 -04:00

1.5 KiB

[Reviewed]

ADR-0008: Canonical proof snapshots and future codecs

Status

Local proof format adopted; durable-world and network formats deferred.

Context

Restore must reproduce state while bounded parsing rejects malformed/incompatible input.

Decision

Explicit LE AEVOPRF0 header, u32 format/rules, u64 quantum/seed/tick/nextID, u32 count; sorted rows id/u32x/u32y/u64rng; trailing FNV1a. Validate size/count before allocation, versions/ranges/IDs before publication. Exact format in SIMULATION_ARCHITECTURE. FNV is accidental-corruption detection only.

Alternatives Considered

Protobuf fits backend schemas; FlatBuffers provides direct buffer access; Cap'n Proto includes serialization/RPC machinery. All require codegen/runtime governance and measured comparison. Protobuf deterministic encoding is explicitly not canonical.

Benefits

Exact portable bytes and bounded dependency-free surface.

Costs

Owned codec/fuzzing with no schema-evolution tooling.

Risks

Overflow/allocation amplification/omitted state/checksum confusion or accidental production use.

Consequences

Semantic hash order remains explicit whichever codec is selected. Test malformed/corrupt input and restore-continuation. Production needs stronger integrity, migration manifests and authenticated transport. Never serialize padding/pointers/client structs. Protobuf canonicality, FlatBuffers, Cap'n Proto.