Module key 

Order-preserving byte encoding for index keys.

See docs/format.md § Index key encoding for the authoritative byte specification. This module is the reference implementation.

Encoding contract

For two Dynamic values a and b, encode_field(a) < encode_field(b) (lexicographic byte comparison) iff a < b (semantic comparison) within their shared type. Cross-type comparisons follow the tag ordering documented in docs/format.md: NULL < false < true < numeric < string < bytes.

The format is distinct from the tagged-Dynamic wire format in crate::codec::dynamic: that format is round-trip-correct but NOT order-preserving (negative integers, in particular, sort wrong under varint encoding). The two encodings serve different purposes — migration uses tagged-Dynamic for reflective access, indexes use this module for lexicographic ordering.

Non-unique key disambiguation

Standard, Each, and Composite indexes are non-unique: two documents may share the same encoded user key. The M4 B+tree rejects duplicate keys (Error::BTreeKeyExists); the index maintenance path side-steps this by appending the document’s Id (8 bytes big-endian) to the encoded user key before writing into the B+tree. Unique indexes do not append the suffix — a collision is the whole point.

encode_index_key returns the user key portion only; the caller (the maintenance path in #58) is responsible for appending the Id suffix for non-unique kinds. The encoded_id_suffix_len constant is exported so range-scan readers can trim the suffix back off.

Power-of-ten posture

• Rule 1. No recursion: every encoder walks a flat &[Dynamic] or a fixed-width primitive.
• Rule 2. Per-field loops iterate over a slice whose length was already validated against IndexSpec::key_paths.len().
• Rule 5. Field-count mismatch is the runtime boundary; type mismatch surfaces as crate::Error::Codec on embedded NUL in a String.
• Rule 7. No unwrap / expect on the production path. Embedded-0x00 in a String field surfaces as crate::Error::InvalidArgument.

Structs

EncodedIndexKey

The byte representation of a single field encoded under the order-preserving format documented in docs/format.md.

Constants

COMPOSITE_TAG

Tag byte distinguishing a composite key envelope from a single primitive key. Pinned by docs/format.md § Index key encoding.

ENCODED_ID_SUFFIX_LEN

Length in bytes of the Id big-endian suffix that the maintenance path appends to non-unique encoded keys. The suffix is the document’s Id as 8 bytes big-endian.

Functions

encode_field

Encode a single Dynamic value to its order-preserving byte representation. Used both by the public encode_index_key and by the composite encoder.

encode_index_key

Encode fields into a single index key under the kind-specific rules.

encode_index_key_parts

Reference-based index-key encode (#84). Takes the index kind (a Copy discriminator) and key_paths BY REFERENCE so a caller holding an crate::catalog::IndexDescriptor can encode a lookup key WITHOUT cloning name / key_paths into a transient IndexSpec (and without re-running IndexSpec::validate).

encoded_id_suffix_len

Length of the trailing Id suffix appended to non-unique keys by the maintenance path. See module docs.