Skip to main content

Module codec

spacedb_store

Module codec 

Source
Expand description

The two codecs every layer above rests on: a value codec and an order-preserving key codec.

§Value codec — postcard

Values serialize through postcard: compact and deterministic (the same value always produces the same bytes). Determinism is not a nicety here — in later milestones encoded values feed content-addressing (L2) and re-execution corroboration (L4), both of which compare bytes/hashes across machines.

§Key codec — order-preserving

Keys are encoded so that byte-lexicographic order equals logical order:

    a < b   ⟺   encode(a) < encode(b)

This is the single property that makes crate::engine::Readable::range_raw return rows in logical key order — the basis for time-ordered audit, ledger replay, and pushed-down range scans in the milestones above. It is verified as a law by the proptests at the bottom of this file.

§How each type achieves it

  • Fixed-width integers (u64) encode as big-endian bytes — BE byte order is numeric order for unsigned integers.
  • Signed integers (i64) flip the sign bit before BE encoding, so the negative range (which has the high bit set) sorts below the non-negative range.
  • Strings / byte strings use an escaped, terminated encoding: a 0x00 content byte becomes 0x00 0x01, and the value ends with the terminator 0x00 0x00. Because the terminator sorts below every escaped content byte, a string that is a prefix of another sorts first ("aa" < "aab") — plain concatenation would get this wrong.
  • Tuples concatenate their components’ encodings. This stays order-preserving only because every component encoding is self-delimiting (integers are fixed-width; strings are terminated), so a shorter first component can never bleed into the second.

Each encoding is also a bijection — KeyDecode reverses it via a cursor so composite keys can be taken apart in the same order they were built.

Traits§

KeyDecode
The inverse of KeyEncode: decode a value from the front of a byte cursor, advancing the cursor past the bytes consumed (so tuple components decode in sequence).
KeyEncode
A type that can be encoded into an order-preserving byte key.

Functions§

decode_value
Deserialize a value from its postcard bytes.
encode_value
Serialize a value to its canonical postcard bytes.