Module repr 

The storable shape of a Value, and the binary encoding of it.

Why this is not serde_json::Value

crate::core::value_to_repr produces a self-describing JSON tree, and that is the right thing for anything a person reads. It is the wrong thing for the log, for two reasons that compound:

1. Size. The JSON repr tags every scalar: Value::Int(1) becomes {"$":"int","v":1} — 19 bytes carrying eight bits. A Toggled(id) event is a few dozen bytes of information and around two hundred of punctuation.
2. Work. Every append builds a whole serde_json::Value tree, then serialises it to text; every read parses text into a tree, then walks the tree to rebuild the Value. Four traversals and two allocations per event, in the one place §3.7 makes the whole system serial.

Phase 0 stored events with postcard and measured 7,660 events/s through Postgres (docs/18-phase-0-report.md §18.3.2). Phase 1 rewrote the log against beck_core::Value — which the runtime must not know the shape of — and reached for JSON because it is self-describing, which is exactly what postcard is not. That was a real constraint and this module is the answer to it: a concrete type postcard can encode, plus total conversions to and from Value.

Why a second type rather than Serialize on Value

Value carries Arcs, a persistent map, and three variants that are not storable at all — Html, Attr, Closure. A derived Serialize would have to either panic on those or invent an encoding for them, and inventing one is how a view ends up in the log (crate::secure, §3.5). Making the storable subset a separate type means the encoder cannot be handed something unstorable: the conversion returns NotStorable, at the boundary, once.

Format stability

This encoding is on disk, so it is a compatibility surface. FORMAT is stamped into every store and checked on open, because a log read back under a different encoding does not fail — it produces plausible nonsense, which is the one outcome an append-only audit trail may never have.

Enums

Repr

A Value restricted to what may be stored, as a concrete type a non-self-describing codec can encode.

Constants

FORMAT

The on-disk format version.

Functions

from_bytes

Decode a value written by to_bytes.

to_bytes

Encode a value for storage.