@lix-js/sdk 0.6.0-preview.1 → 0.6.0-preview.3

package/dist-engine-src/src/tracked_state/codec.rs

@@ -0,0 +1,2085 @@
+use std::collections::HashMap;
+
+use xxhash_rust::xxh3::xxh3_64_with_seed;
+
+use crate::commit_store::ChangeLocator;
+use crate::entity_identity::EntityIdentity;
+use crate::json_store::JsonRef;
+use crate::tracked_state::types::{
+    TrackedStateDeltaEntry, TrackedStateDeltaRef, TrackedStateIndexValue,
+    TrackedStateIndexValueRef, TrackedStateKey, TrackedStateKeyRef, TRACKED_STATE_HASH_BYTES,
+};
+use crate::LixError;
+
+const NODE_VERSION: u8 = 2;
+const VALUE_VERSION: u8 = 7;
+const VALUE_DELETED_FLAG: u8 = 0b1000_0000;
+const VALUE_VERSION_MASK: u8 = 0b0111_1111;
+const DELTA_PACK_VERSION: u8 = 7;
+const DELTA_LOCATOR_SAME_COMMIT: u8 = 0;
+const DELTA_LOCATOR_FULL: u8 = 1;
+const DELTA_JSON_REFS_INLINE: u8 = 0;
+const DELTA_JSON_REFS_MIXED_PACK_INDEX: u8 = 1;
+const DELTA_JSON_REF_NONE: u8 = 0;
+const DELTA_JSON_REF_PACK_INDEX: u8 = 1;
+const DELTA_JSON_REF_INLINE: u8 = 2;
+const DELTA_CHANGE_ID_FULL: u8 = 0;
+const DELTA_CHANGE_ID_COMMIT_SUFFIX: u8 = 1;
+const TIMESTAMP_UPDATED_SAME: u8 = 0;
+const TIMESTAMP_UPDATED_DISTINCT: u8 = 1;
+const NODE_KIND_LEAF: u8 = 1;
+const NODE_KIND_INTERNAL: u8 = 2;
+const WEIBULL_K: i32 = 4;
+const ENTITY_IDENTITY_END: u8 = 0;
+const ENTITY_IDENTITY_STRING: u8 = 1;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct DeltaKeyPrefixRef<'a> {
+    schema_key: &'a str,
+    file_id: Option<&'a str>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct DeltaKeyPrefix {
+    schema_key: String,
+    file_id: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct EncodedLeafEntry {
+    pub(crate) key: Vec<u8>,
+    pub(crate) value: Vec<u8>,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct EncodedLeafEntryRef<'a> {
+    pub(crate) key: &'a [u8],
+    pub(crate) value: &'a [u8],
+}
+
+impl EncodedLeafEntry {
+    pub(crate) fn as_ref(&self) -> EncodedLeafEntryRef<'_> {
+        EncodedLeafEntryRef {
+            key: &self.key,
+            value: &self.value,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct PendingChunkWrite {
+    pub(crate) hash: [u8; TRACKED_STATE_HASH_BYTES],
+    pub(crate) data: Vec<u8>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct ChildSummary {
+    pub(crate) first_key: Vec<u8>,
+    pub(crate) last_key: Vec<u8>,
+    pub(crate) child_hash: [u8; TRACKED_STATE_HASH_BYTES],
+    pub(crate) subtree_count: u64,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct ChildSummaryRef<'a> {
+    pub(crate) first_key: &'a [u8],
+    pub(crate) last_key: &'a [u8],
+    pub(crate) child_hash: [u8; TRACKED_STATE_HASH_BYTES],
+    pub(crate) subtree_count: u64,
+}
+
+impl ChildSummary {
+    pub(crate) fn as_ref(&self) -> ChildSummaryRef<'_> {
+        ChildSummaryRef {
+            first_key: &self.first_key,
+            last_key: &self.last_key,
+            child_hash: self.child_hash,
+            subtree_count: self.subtree_count,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub(crate) enum DecodedNode {
+    Leaf(DecodedLeafNode),
+    Internal(DecodedInternalNode),
+}
+
+#[derive(Debug, Clone)]
+pub(crate) enum DecodedNodeRef<'a> {
+    Leaf(DecodedLeafNodeRef<'a>),
+    Internal(DecodedInternalNode),
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct DecodedLeafNode {
+    entries: Vec<EncodedLeafEntry>,
+}
+
+impl DecodedLeafNode {
+    pub(crate) fn entries(&self) -> &[EncodedLeafEntry] {
+        &self.entries
+    }
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct DecodedLeafNodeRef<'a> {
+    bytes: &'a [u8],
+    payload_start: usize,
+    offsets: Vec<usize>,
+}
+
+impl<'a> DecodedLeafNodeRef<'a> {
+    pub(crate) fn len(&self) -> usize {
+        self.offsets.len().saturating_sub(1)
+    }
+
+    pub(crate) fn entry(&self, index: usize) -> Result<Option<EncodedLeafEntryRef<'a>>, LixError> {
+        if index >= self.len() {
+            return Ok(None);
+        }
+        let start = self.payload_start + self.offsets[index];
+        let end = self.payload_start + self.offsets[index + 1];
+        let record = self.bytes.get(start..end).ok_or_else(|| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                "tracked-state leaf offset points outside node payload",
+            )
+        })?;
+        let mut cursor = 0usize;
+        let key = read_sized_slice(record, &mut cursor, "leaf key")?;
+        let value = read_sized_slice(record, &mut cursor, "leaf value")?;
+        if cursor != record.len() {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                "tracked-state leaf entry decode found trailing bytes",
+            ));
+        }
+        Ok(Some(EncodedLeafEntryRef { key, value }))
+    }
+
+    pub(crate) fn key(&self, index: usize) -> Result<Option<&'a [u8]>, LixError> {
+        let Some(entry) = self.entry(index)? else {
+            return Ok(None);
+        };
+        Ok(Some(entry.key))
+    }
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct DecodedInternalNode {
+    children: Vec<ChildSummary>,
+}
+
+impl DecodedInternalNode {
+    pub(crate) fn children(&self) -> &[ChildSummary] {
+        &self.children
+    }
+}
+
+pub(crate) fn hash_bytes(bytes: &[u8]) -> [u8; TRACKED_STATE_HASH_BYTES] {
+    *blake3::hash(bytes).as_bytes()
+}
+
+pub(crate) fn encode_key(key: &TrackedStateKey) -> Vec<u8> {
+    encode_key_ref(TrackedStateKeyRef {
+        schema_key: &key.schema_key,
+        file_id: key.file_id.as_deref(),
+        entity_id: &key.entity_id,
+    })
+}
+
+pub(crate) fn encode_key_ref(key: TrackedStateKeyRef<'_>) -> Vec<u8> {
+    let mut out = Vec::new();
+    append_key_ref(&mut out, key);
+    out
+}
+
+fn append_key_ref(out: &mut Vec<u8>, key: TrackedStateKeyRef<'_>) {
+    push_sized_bytes(out, key.schema_key.as_bytes());
+    match key.file_id {
+        Some(file_id) => {
+            out.push(1);
+            push_sized_bytes(out, file_id.as_bytes());
+        }
+        None => out.push(0),
+    }
+    push_entity_identity(out, key.entity_id);
+}
+
+pub(crate) fn encode_schema_key_prefix(schema_key: &str) -> Vec<u8> {
+    let mut out = Vec::new();
+    push_sized_bytes(&mut out, schema_key.as_bytes());
+    out
+}
+
+pub(crate) fn encode_schema_file_prefix(schema_key: &str, file_id: Option<&str>) -> Vec<u8> {
+    let mut out = encode_schema_key_prefix(schema_key);
+    match file_id {
+        Some(file_id) => {
+            out.push(1);
+            push_sized_bytes(&mut out, file_id.as_bytes());
+        }
+        None => out.push(0),
+    }
+    out
+}
+
+pub(crate) fn decode_key(bytes: &[u8]) -> Result<TrackedStateKey, LixError> {
+    let mut cursor = 0usize;
+    let schema_key = read_sized_string(bytes, &mut cursor, "schema_key")?;
+    let file_id = match read_u8(bytes, &mut cursor, "file_id presence")? {
+        0 => None,
+        1 => Some(read_sized_string(bytes, &mut cursor, "file_id")?),
+        other => {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("tracked-state tree key has invalid file_id presence byte {other}"),
+            ))
+        }
+    };
+    let entity_id = read_entity_identity(bytes, &mut cursor)?;
+    if cursor != bytes.len() {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state tree key decode found trailing bytes",
+        ));
+    }
+    Ok(TrackedStateKey {
+        schema_key,
+        file_id,
+        entity_id,
+    })
+}
+
+/// Decodes a key after the caller has already proven the schema/file prefix.
+///
+/// This is for scan paths that have matched an encoded prefix range and only
+/// need to materialize the entity suffix plus the known projection fields.
+pub(crate) fn decode_key_with_trusted_prefix(
+    bytes: &[u8],
+    schema_key: &str,
+    file_id: Option<&str>,
+    prefix_len: usize,
+) -> Result<TrackedStateKey, LixError> {
+    let mut cursor = prefix_len;
+    let entity_id = read_entity_identity(bytes, &mut cursor)?;
+    if cursor != bytes.len() {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state tree key decode found trailing bytes",
+        ));
+    }
+    Ok(TrackedStateKey {
+        schema_key: schema_key.to_string(),
+        file_id: file_id.map(str::to_string),
+        entity_id,
+    })
+}
+
+#[cfg(test)]
+pub(crate) fn encode_value(value: &TrackedStateIndexValue) -> Vec<u8> {
+    encode_value_ref(TrackedStateIndexValueRef {
+        change_locator: value.change_locator.as_ref(),
+        deleted: value.deleted,
+        snapshot_ref: value.snapshot_ref.as_ref(),
+        metadata_ref: value.metadata_ref.as_ref(),
+        created_at: &value.created_at,
+        updated_at: &value.updated_at,
+    })
+}
+
+pub(crate) fn encode_value_ref(value: TrackedStateIndexValueRef<'_>) -> Vec<u8> {
+    let mut out = Vec::new();
+    append_value_ref(&mut out, value);
+    out
+}
+
+fn append_value_ref(out: &mut Vec<u8>, value: TrackedStateIndexValueRef<'_>) {
+    out.push(VALUE_VERSION | if value.deleted { VALUE_DELETED_FLAG } else { 0 });
+    push_sized_bytes(out, value.change_locator.source_commit_id.as_bytes());
+    out.extend_from_slice(&value.change_locator.source_pack_id.to_be_bytes());
+    out.extend_from_slice(&value.change_locator.source_ordinal.to_be_bytes());
+    push_sized_bytes(out, value.change_locator.change_id.as_bytes());
+    push_timestamp_pair(out, value.created_at, value.updated_at);
+    push_optional_json_ref(out, value.snapshot_ref);
+    push_optional_json_ref(out, value.metadata_ref);
+}
+
+#[cfg(test)]
+pub(crate) fn encoded_value_len(value: &TrackedStateIndexValue) -> usize {
+    1 + sized_bytes_len(value.change_locator.source_commit_id.as_bytes())
+        + 4
+        + 4
+        + sized_bytes_len(value.change_locator.change_id.as_bytes())
+        + timestamp_pair_len(&value.created_at, &value.updated_at)
+        + optional_json_ref_len(value.snapshot_ref.as_ref())
+        + optional_json_ref_len(value.metadata_ref.as_ref())
+}
+
+pub(crate) fn decode_value(bytes: &[u8]) -> Result<TrackedStateIndexValue, LixError> {
+    let mut cursor = 0usize;
+    let value_header = read_u8(bytes, &mut cursor, "value header")?;
+    let deleted = decode_value_header(value_header)?;
+    decode_value_after_header(bytes, cursor, deleted)
+}
+
+pub(crate) fn decode_visible_value(
+    bytes: &[u8],
+    include_tombstones: bool,
+) -> Result<Option<TrackedStateIndexValue>, LixError> {
+    let mut cursor = 0usize;
+    let value_header = read_u8(bytes, &mut cursor, "value header")?;
+    let deleted = decode_value_header(value_header)?;
+    if deleted && !include_tombstones {
+        return Ok(None);
+    }
+    decode_value_after_header(bytes, cursor, deleted).map(Some)
+}
+
+fn decode_value_header(value_header: u8) -> Result<bool, LixError> {
+    let version = value_header & VALUE_VERSION_MASK;
+    let deleted = value_header & VALUE_DELETED_FLAG != 0;
+    if version != VALUE_VERSION {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("unsupported tracked-state tree value version {version}"),
+        ));
+    }
+    Ok(deleted)
+}
+
+fn decode_value_after_header(
+    bytes: &[u8],
+    mut cursor: usize,
+    deleted: bool,
+) -> Result<TrackedStateIndexValue, LixError> {
+    let source_commit_id = read_sized_string(bytes, &mut cursor, "source_commit_id")?;
+    let source_pack_id =
+        u32::try_from(read_u32(bytes, &mut cursor, "source_pack_id")?).map_err(|_| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "tracked-state source_pack_id exceeds u32",
+            )
+        })?;
+    let source_ordinal =
+        u32::try_from(read_u32(bytes, &mut cursor, "source_ordinal")?).map_err(|_| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "tracked-state source_ordinal exceeds u32",
+            )
+        })?;
+    let change_id = read_sized_string(bytes, &mut cursor, "change_id")?;
+    let (created_at, updated_at) = read_timestamp_pair(bytes, &mut cursor)?;
+    let snapshot_ref = read_optional_json_ref(bytes, &mut cursor, "snapshot_ref")?;
+    let metadata_ref = read_optional_json_ref(bytes, &mut cursor, "metadata_ref")?;
+    if cursor != bytes.len() {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state tree value decode found trailing bytes",
+        ));
+    }
+    Ok(TrackedStateIndexValue {
+        change_locator: ChangeLocator {
+            source_commit_id,
+            source_pack_id,
+            source_ordinal,
+            change_id,
+        },
+        deleted,
+        snapshot_ref,
+        metadata_ref,
+        created_at,
+        updated_at,
+    })
+}
+
+pub(crate) fn encode_delta_pack_refs(
+    commit_id: &str,
+    deltas: &[TrackedStateDeltaRef<'_>],
+) -> Result<Vec<u8>, LixError> {
+    encode_delta_pack_refs_with_json_pack_indexes(commit_id, deltas, None)
+}
+
+pub(crate) fn encode_delta_pack_refs_with_json_pack_indexes(
+    commit_id: &str,
+    deltas: &[TrackedStateDeltaRef<'_>],
+    json_pack_indexes: Option<&HashMap<[u8; TRACKED_STATE_HASH_BYTES], usize>>,
+) -> Result<Vec<u8>, LixError> {
+    let json_pack_indexes = json_pack_indexes.filter(|indexes| !indexes.is_empty());
+    let mut out = Vec::new();
+    out.extend_from_slice(b"LXTD");
+    out.push(DELTA_PACK_VERSION);
+    push_var_sized_bytes(&mut out, commit_id.as_bytes(), "delta pack commit_id")?;
+    let (key_prefixes, delta_prefix_indexes) = delta_key_prefixes(deltas);
+    push_var_u32(&mut out, key_prefixes.len(), "delta key prefix count")?;
+    for prefix in &key_prefixes {
+        append_delta_key_prefix_ref(&mut out, *prefix)?;
+    }
+    push_var_u32(&mut out, deltas.len(), "delta pack entry count")?;
+    out.push(if json_pack_indexes.is_some() {
+        DELTA_JSON_REFS_MIXED_PACK_INDEX
+    } else {
+        DELTA_JSON_REFS_INLINE
+    });
+    for (delta, prefix_index) in deltas.iter().zip(delta_prefix_indexes) {
+        append_delta_key_ref(
+            &mut out,
+            &key_prefixes,
+            prefix_index,
+            TrackedStateKeyRef {
+                schema_key: delta.change.schema_key,
+                file_id: delta.change.file_id,
+                entity_id: delta.change.entity_id,
+            },
+        )?;
+        append_delta_value_ref(
+            &mut out,
+            commit_id,
+            json_pack_indexes,
+            TrackedStateIndexValueRef {
+                change_locator: delta.locator,
+                deleted: delta.change.snapshot_ref.is_none(),
+                snapshot_ref: delta.change.snapshot_ref,
+                metadata_ref: delta.change.metadata_ref,
+                created_at: delta.created_at,
+                updated_at: delta.updated_at,
+            },
+        )?;
+    }
+    Ok(out)
+}
+
+fn delta_key_prefixes<'a>(
+    deltas: &'a [TrackedStateDeltaRef<'a>],
+) -> (Vec<DeltaKeyPrefixRef<'a>>, Vec<usize>) {
+    let mut prefixes = Vec::new();
+    let mut delta_prefix_indexes = Vec::with_capacity(deltas.len());
+    for delta in deltas {
+        let prefix = DeltaKeyPrefixRef {
+            schema_key: delta.change.schema_key,
+            file_id: delta.change.file_id,
+        };
+        let prefix_index = match prefixes.iter().position(|candidate| *candidate == prefix) {
+            Some(prefix_index) => prefix_index,
+            None => {
+                let prefix_index = prefixes.len();
+                prefixes.push(prefix);
+                prefix_index
+            }
+        };
+        delta_prefix_indexes.push(prefix_index);
+    }
+    (prefixes, delta_prefix_indexes)
+}
+
+fn append_delta_key_prefix_ref(
+    out: &mut Vec<u8>,
+    prefix: DeltaKeyPrefixRef<'_>,
+) -> Result<(), LixError> {
+    push_var_sized_bytes(
+        out,
+        prefix.schema_key.as_bytes(),
+        "delta key prefix schema_key",
+    )?;
+    match prefix.file_id {
+        Some(file_id) => {
+            out.push(1);
+            push_var_sized_bytes(out, file_id.as_bytes(), "delta key prefix file_id")?;
+        }
+        None => out.push(0),
+    }
+    Ok(())
+}
+
+fn decode_delta_key_prefix(bytes: &[u8], cursor: &mut usize) -> Result<DeltaKeyPrefix, LixError> {
+    let schema_key = read_var_sized_string(bytes, cursor, "delta key prefix schema_key")?;
+    let file_id = match read_u8(bytes, cursor, "delta key prefix file_id presence")? {
+        0 => None,
+        1 => Some(read_var_sized_string(
+            bytes,
+            cursor,
+            "delta key prefix file_id",
+        )?),
+        other => {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("tracked-state delta key prefix has invalid file_id presence byte {other}"),
+            ))
+        }
+    };
+    Ok(DeltaKeyPrefix {
+        schema_key,
+        file_id,
+    })
+}
+
+fn append_delta_key_ref(
+    out: &mut Vec<u8>,
+    prefixes: &[DeltaKeyPrefixRef<'_>],
+    prefix_index: usize,
+    key: TrackedStateKeyRef<'_>,
+) -> Result<(), LixError> {
+    let prefix = DeltaKeyPrefixRef {
+        schema_key: key.schema_key,
+        file_id: key.file_id,
+    };
+    debug_assert_eq!(prefixes.get(prefix_index), Some(&prefix));
+    push_var_u32(out, prefix_index, "delta key prefix index")?;
+    push_var_entity_identity(out, key.entity_id)?;
+    Ok(())
+}
+
+fn append_delta_value_ref(
+    out: &mut Vec<u8>,
+    pack_commit_id: &str,
+    json_pack_indexes: Option<&HashMap<[u8; TRACKED_STATE_HASH_BYTES], usize>>,
+    value: TrackedStateIndexValueRef<'_>,
+) -> Result<(), LixError> {
+    out.push(VALUE_VERSION | if value.deleted { VALUE_DELETED_FLAG } else { 0 });
+    if value.change_locator.source_commit_id == pack_commit_id {
+        out.push(DELTA_LOCATOR_SAME_COMMIT);
+    } else {
+        out.push(DELTA_LOCATOR_FULL);
+        push_var_sized_bytes(
+            out,
+            value.change_locator.source_commit_id.as_bytes(),
+            "source_commit_id",
+        )?;
+    }
+    push_var_u32(
+        out,
+        value.change_locator.source_pack_id as usize,
+        "source_pack_id",
+    )?;
+    push_var_u32(
+        out,
+        value.change_locator.source_ordinal as usize,
+        "source_ordinal",
+    )?;
+    push_var_delta_change_id(
+        out,
+        value.change_locator.source_commit_id,
+        value.change_locator.change_id,
+    )?;
+    push_var_timestamp_pair(out, value.created_at, value.updated_at)?;
+    match json_pack_indexes {
+        Some(indexes) => {
+            push_mixed_optional_json_ref(out, indexes, value.snapshot_ref)?;
+            push_mixed_optional_json_ref(out, indexes, value.metadata_ref)?;
+        }
+        None => {
+            push_optional_json_ref(out, value.snapshot_ref);
+            push_optional_json_ref(out, value.metadata_ref);
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn decode_delta_pack(
+    bytes: &[u8],
+    pack_json_refs: Option<&[JsonRef]>,
+) -> Result<(String, Vec<TrackedStateDeltaEntry>), LixError> {
+    let mut cursor = 0usize;
+    let magic = bytes.get(0..4).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state delta pack is truncated before magic",
+        )
+    })?;
+    if magic != b"LXTD" {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state delta pack has invalid magic",
+        ));
+    }
+    cursor += 4;
+    let version = read_u8(bytes, &mut cursor, "delta pack version")?;
+    if version != DELTA_PACK_VERSION {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("unsupported tracked-state delta pack version {version}"),
+        ));
+    }
+    let commit_id = read_var_sized_string(bytes, &mut cursor, "delta pack commit_id")?;
+    let prefix_count = read_var_u32(bytes, &mut cursor, "delta key prefix count")?;
+    let mut key_prefixes = Vec::new();
+    for _ in 0..prefix_count {
+        key_prefixes.push(decode_delta_key_prefix(bytes, &mut cursor)?);
+    }
+    let count = read_var_u32(bytes, &mut cursor, "delta pack entry count")?;
+    let json_ref_mode = decode_delta_json_ref_mode(bytes, &mut cursor, pack_json_refs)?;
+    let mut entries = Vec::new();
+    for _ in 0..count {
+        let key = decode_delta_key(bytes, &mut cursor, &key_prefixes)?;
+        let value = decode_delta_value(bytes, &mut cursor, &commit_id, &json_ref_mode)?;
+        entries.push(TrackedStateDeltaEntry { key, value });
+    }
+    if cursor != bytes.len() {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state delta pack decode found trailing bytes",
+        ));
+    }
+    Ok((commit_id, entries))
+}
+
+pub(crate) fn delta_pack_uses_json_pack_indexes(bytes: &[u8]) -> Result<bool, LixError> {
+    let mut cursor = 0usize;
+    let magic = bytes.get(0..4).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state delta pack is truncated before magic",
+        )
+    })?;
+    if magic != b"LXTD" {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state delta pack has invalid magic",
+        ));
+    }
+    cursor += 4;
+    let version = read_u8(bytes, &mut cursor, "delta pack version")?;
+    if version != DELTA_PACK_VERSION {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("unsupported tracked-state delta pack version {version}"),
+        ));
+    }
+    let _commit_id = read_var_sized_string(bytes, &mut cursor, "delta pack commit_id")?;
+    let prefix_count = read_var_u32(bytes, &mut cursor, "delta key prefix count")?;
+    for _ in 0..prefix_count {
+        let _ = decode_delta_key_prefix(bytes, &mut cursor)?;
+    }
+    let _count = read_var_u32(bytes, &mut cursor, "delta pack entry count")?;
+    match read_u8(bytes, &mut cursor, "delta JSON ref mode")? {
+        DELTA_JSON_REFS_INLINE => Ok(false),
+        DELTA_JSON_REFS_MIXED_PACK_INDEX => Ok(true),
+        other => Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state delta pack has invalid JSON ref mode {other}"),
+        )),
+    }
+}
+
+fn decode_delta_key(
+    bytes: &[u8],
+    cursor: &mut usize,
+    prefixes: &[DeltaKeyPrefix],
+) -> Result<TrackedStateKey, LixError> {
+    let prefix_index = read_var_u32(bytes, cursor, "delta key prefix index")?;
+    let prefix = prefixes.get(prefix_index).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state delta key prefix index {prefix_index} is out of bounds"),
+        )
+    })?;
+    let entity_id = read_var_entity_identity(bytes, cursor)?;
+    Ok(TrackedStateKey {
+        schema_key: prefix.schema_key.clone(),
+        file_id: prefix.file_id.clone(),
+        entity_id,
+    })
+}
+
+enum DeltaJsonRefDecodeMode<'a> {
+    Inline,
+    MixedPackIndex(&'a [JsonRef]),
+}
+
+fn decode_delta_json_ref_mode<'a>(
+    bytes: &[u8],
+    cursor: &mut usize,
+    pack_json_refs: Option<&'a [JsonRef]>,
+) -> Result<DeltaJsonRefDecodeMode<'a>, LixError> {
+    match read_u8(bytes, cursor, "delta JSON ref mode")? {
+        DELTA_JSON_REFS_INLINE => Ok(DeltaJsonRefDecodeMode::Inline),
+        DELTA_JSON_REFS_MIXED_PACK_INDEX => {
+            let refs = pack_json_refs.ok_or_else(|| {
+                LixError::new(
+                    LixError::CODE_INTERNAL_ERROR,
+                    "tracked-state delta pack needs JSON pack refs but none were provided",
+                )
+            })?;
+            Ok(DeltaJsonRefDecodeMode::MixedPackIndex(refs))
+        }
+        other => Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state delta pack has invalid JSON ref mode {other}"),
+        )),
+    }
+}
+
+fn decode_delta_value(
+    bytes: &[u8],
+    cursor: &mut usize,
+    pack_commit_id: &str,
+    json_ref_mode: &DeltaJsonRefDecodeMode<'_>,
+) -> Result<TrackedStateIndexValue, LixError> {
+    let value_header = read_u8(bytes, cursor, "delta value header")?;
+    let deleted = decode_value_header(value_header)?;
+    let source_commit_id = match read_u8(bytes, cursor, "delta locator tag")? {
+        DELTA_LOCATOR_SAME_COMMIT => pack_commit_id.to_string(),
+        DELTA_LOCATOR_FULL => read_var_sized_string(bytes, cursor, "source_commit_id")?,
+        other => {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("tracked-state delta value has invalid locator tag {other}"),
+            ))
+        }
+    };
+    let source_pack_id =
+        u32::try_from(read_var_u32(bytes, cursor, "source_pack_id")?).map_err(|_| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "tracked-state source_pack_id exceeds u32",
+            )
+        })?;
+    let source_ordinal =
+        u32::try_from(read_var_u32(bytes, cursor, "source_ordinal")?).map_err(|_| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "tracked-state source_ordinal exceeds u32",
+            )
+        })?;
+    let change_id = read_var_delta_change_id(bytes, cursor, &source_commit_id)?;
+    let (created_at, updated_at) = read_var_timestamp_pair(bytes, cursor)?;
+    let (snapshot_ref, metadata_ref) = match json_ref_mode {
+        DeltaJsonRefDecodeMode::Inline => (
+            read_optional_json_ref(bytes, cursor, "snapshot_ref")?,
+            read_optional_json_ref(bytes, cursor, "metadata_ref")?,
+        ),
+        DeltaJsonRefDecodeMode::MixedPackIndex(refs) => (
+            read_mixed_optional_json_ref(bytes, cursor, refs, "snapshot_ref")?,
+            read_mixed_optional_json_ref(bytes, cursor, refs, "metadata_ref")?,
+        ),
+    };
+    Ok(TrackedStateIndexValue {
+        change_locator: ChangeLocator {
+            source_commit_id,
+            source_pack_id,
+            source_ordinal,
+            change_id,
+        },
+        deleted,
+        snapshot_ref,
+        metadata_ref,
+        created_at,
+        updated_at,
+    })
+}
+
+#[cfg(test)]
+fn sized_bytes_len(bytes: &[u8]) -> usize {
+    4 + bytes.len()
+}
+
+pub(crate) fn encode_leaf_node(entries: &[EncodedLeafEntry]) -> Vec<u8> {
+    let entries = entries
+        .iter()
+        .map(EncodedLeafEntry::as_ref)
+        .collect::<Vec<_>>();
+    encode_leaf_node_refs(&entries)
+}
+
+pub(crate) fn encode_leaf_node_refs(entries: &[EncodedLeafEntryRef<'_>]) -> Vec<u8> {
+    let mut out = Vec::new();
+    out.push(NODE_KIND_LEAF);
+    out.push(NODE_VERSION);
+    push_u32(&mut out, entries.len());
+
+    let mut offsets = Vec::with_capacity(entries.len().saturating_add(1));
+    let mut payload = Vec::new();
+    offsets.push(0usize);
+    for entry in entries {
+        push_sized_bytes(&mut payload, entry.key);
+        push_sized_bytes(&mut payload, entry.value);
+        offsets.push(payload.len());
+    }
+    for offset in offsets {
+        push_u32(&mut out, offset);
+    }
+    out.extend_from_slice(&payload);
+    out
+}
+
+pub(crate) fn encode_internal_node(children: &[ChildSummary]) -> Vec<u8> {
+    let children = children
+        .iter()
+        .map(ChildSummary::as_ref)
+        .collect::<Vec<_>>();
+    encode_internal_node_refs(&children)
+}
+
+pub(crate) fn encode_internal_node_refs(children: &[ChildSummaryRef<'_>]) -> Vec<u8> {
+    let mut out = Vec::new();
+    out.push(NODE_KIND_INTERNAL);
+    out.push(NODE_VERSION);
+    push_u32(&mut out, children.len());
+    for child in children {
+        push_sized_bytes(&mut out, child.first_key);
+        push_sized_bytes(&mut out, child.last_key);
+        out.extend_from_slice(&child.child_hash);
+        out.extend_from_slice(&child.subtree_count.to_be_bytes());
+    }
+    out
+}
+
+pub(crate) fn decode_node(bytes: &[u8]) -> Result<DecodedNode, LixError> {
+    match decode_node_ref(bytes)? {
+        DecodedNodeRef::Leaf(leaf) => {
+            let mut entries = Vec::with_capacity(leaf.len());
+            for index in 0..leaf.len() {
+                let entry = leaf.entry(index)?.ok_or_else(|| {
+                    LixError::new(
+                        "LIX_ERROR_UNKNOWN",
+                        "tracked-state leaf entry disappeared during owned decode",
+                    )
+                })?;
+                entries.push(EncodedLeafEntry {
+                    key: entry.key.to_vec(),
+                    value: entry.value.to_vec(),
+                });
+            }
+            Ok(DecodedNode::Leaf(DecodedLeafNode { entries }))
+        }
+        DecodedNodeRef::Internal(internal) => Ok(DecodedNode::Internal(internal)),
+    }
+}
+
+pub(crate) fn decode_node_ref(bytes: &[u8]) -> Result<DecodedNodeRef<'_>, LixError> {
+    let mut cursor = 0usize;
+    let kind = read_u8(bytes, &mut cursor, "node kind")?;
+    let version = read_u8(bytes, &mut cursor, "node version")?;
+    if version != NODE_VERSION {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("unsupported tracked-state tree node version {version}"),
+        ));
+    }
+    let count = read_u32(bytes, &mut cursor, "entry count")?;
+    let node = match kind {
+        NODE_KIND_LEAF => {
+            let leaf = decode_leaf_node_ref_after_count(bytes, &mut cursor, count)?;
+            DecodedNodeRef::Leaf(leaf)
+        }
+        NODE_KIND_INTERNAL => {
+            let mut children = Vec::with_capacity(count);
+            for _ in 0..count {
+                let first_key = read_sized_bytes(bytes, &mut cursor, "internal first_key")?;
+                let last_key = read_sized_bytes(bytes, &mut cursor, "internal last_key")?;
+                let child_hash = read_fixed_hash(bytes, &mut cursor, "internal child_hash")?;
+                let subtree_count = read_u64(bytes, &mut cursor, "internal subtree_count")?;
+                children.push(ChildSummary {
+                    first_key,
+                    last_key,
+                    child_hash,
+                    subtree_count,
+                });
+            }
+            DecodedNodeRef::Internal(DecodedInternalNode { children })
+        }
+        other => {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("unknown tracked-state tree node kind {other}"),
+            ))
+        }
+    };
+    if cursor != bytes.len() {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state tree node decode found trailing bytes",
+        ));
+    }
+    Ok(node)
+}
+
+fn decode_leaf_node_ref_after_count<'a>(
+    bytes: &'a [u8],
+    cursor: &mut usize,
+    count: usize,
+) -> Result<DecodedLeafNodeRef<'a>, LixError> {
+    let mut offsets = Vec::with_capacity(count.saturating_add(1));
+    for _ in 0..=count {
+        offsets.push(read_u32(bytes, cursor, "leaf entry offset")?);
+    }
+    if offsets.first().copied() != Some(0) {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state leaf offset table must start at zero",
+        ));
+    }
+    for window in offsets.windows(2) {
+        if window[0] > window[1] {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                "tracked-state leaf offsets must be monotonic",
+            ));
+        }
+    }
+    let payload_len = bytes.len().checked_sub(*cursor).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state leaf payload start is past node end",
+        )
+    })?;
+    if offsets.last().copied().unwrap_or_default() != payload_len {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state leaf offset table does not cover full payload",
+        ));
+    }
+    let payload_start = *cursor;
+    *cursor = bytes.len();
+    Ok(DecodedLeafNodeRef {
+        bytes,
+        payload_start,
+        offsets,
+    })
+}
+
+pub(crate) fn child_summary_from_node(
+    node_bytes: Vec<u8>,
+    first_key: Vec<u8>,
+    last_key: Vec<u8>,
+    subtree_count: u64,
+) -> (PendingChunkWrite, ChildSummary) {
+    let hash = hash_bytes(&node_bytes);
+    (
+        PendingChunkWrite {
+            hash,
+            data: node_bytes,
+        },
+        ChildSummary {
+            first_key,
+            last_key,
+            child_hash: hash,
+            subtree_count,
+        },
+    )
+}
+
+pub(crate) fn boundary_trigger(
+    encoded_key: &[u8],
+    level: usize,
+    chunk_size: usize,
+    item_size: usize,
+    target_chunk_bytes: usize,
+) -> bool {
+    if item_size == 0 || target_chunk_bytes == 0 {
+        return false;
+    }
+
+    let start =
+        weibull_cdf(chunk_size.saturating_sub(item_size) as f64 / target_chunk_bytes as f64);
+    let end = weibull_cdf(chunk_size as f64 / target_chunk_bytes as f64);
+    let remaining = 1.0 - start;
+    if remaining <= 0.0 {
+        return true;
+    }
+
+    let split_probability = ((end - start) / remaining).clamp(0.0, 1.0);
+    let hash = xxh3_64_with_seed(encoded_key, level_salt(level));
+    (hash as f64) < split_probability * (u64::MAX as f64)
+}
+
+fn weibull_cdf(normalized_size: f64) -> f64 {
+    if normalized_size <= 0.0 {
+        return 0.0;
+    }
+    -f64::exp_m1(-normalized_size.powi(WEIBULL_K))
+}
+
+fn level_salt(level: usize) -> u64 {
+    let mut value = (level as u64).wrapping_add(0x9e37_79b9_7f4a_7c15);
+    value = (value ^ (value >> 30)).wrapping_mul(0xbf58_476d_1ce4_e5b9);
+    value = (value ^ (value >> 27)).wrapping_mul(0x94d0_49bb_1331_11eb);
+    value ^ (value >> 31)
+}
+
+fn push_entity_identity(out: &mut Vec<u8>, identity: &EntityIdentity) {
+    assert!(
+        !identity.parts.is_empty(),
+        "tracked-state key entity identity must contain at least one part"
+    );
+    for part in &identity.parts {
+        out.push(ENTITY_IDENTITY_STRING);
+        push_sized_bytes(out, part.as_bytes());
+    }
+    out.push(ENTITY_IDENTITY_END);
+}
+
+fn read_entity_identity(bytes: &[u8], cursor: &mut usize) -> Result<EntityIdentity, LixError> {
+    let mut parts = Vec::new();
+    loop {
+        let tag = read_u8(bytes, cursor, "entity identity part tag")?;
+        match tag {
+            ENTITY_IDENTITY_END => break,
+            ENTITY_IDENTITY_STRING => {
+                parts.push(read_sized_string(
+                    bytes,
+                    cursor,
+                    "entity identity string part",
+                )?);
+            }
+            other => {
+                return Err(LixError::new(
+                    "LIX_ERROR_UNKNOWN",
+                    format!("tracked-state tree key has invalid entity identity part tag {other}"),
+                ))
+            }
+        }
+    }
+    if parts.is_empty() {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state tree key entity identity must contain at least one part",
+        ));
+    }
+    Ok(EntityIdentity { parts })
+}
+
+fn push_sized_bytes(out: &mut Vec<u8>, bytes: &[u8]) {
+    push_u32(out, bytes.len());
+    out.extend_from_slice(bytes);
+}
+
+fn push_var_u32(out: &mut Vec<u8>, value: usize, field_name: &str) -> Result<(), LixError> {
+    let (encoded, len) = var_u32_bytes(value, field_name)?;
+    out.extend_from_slice(&encoded[..len]);
+    Ok(())
+}
+
+fn var_u32_bytes(value: usize, field_name: &str) -> Result<([u8; 5], usize), LixError> {
+    let mut value = u32::try_from(value).map_err(|_| {
+        LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            format!("tracked-state delta pack field '{field_name}' exceeds u32"),
+        )
+    })?;
+    let mut encoded = [0_u8; 5];
+    let mut len = 0usize;
+    while value >= 0x80 {
+        encoded[len] = (value as u8 & 0x7f) | 0x80;
+        len += 1;
+        value >>= 7;
+    }
+    encoded[len] = value as u8;
+    len += 1;
+    Ok((encoded, len))
+}
+
+fn push_var_sized_bytes(out: &mut Vec<u8>, bytes: &[u8], field_name: &str) -> Result<(), LixError> {
+    push_var_u32(out, bytes.len(), field_name)?;
+    out.extend_from_slice(bytes);
+    Ok(())
+}
+
+fn push_var_entity_identity(out: &mut Vec<u8>, identity: &EntityIdentity) -> Result<(), LixError> {
+    assert!(
+        !identity.parts.is_empty(),
+        "tracked-state delta key entity identity must contain at least one part"
+    );
+    push_var_u32(out, identity.parts.len(), "entity identity part count")?;
+    for part in &identity.parts {
+        push_var_sized_bytes(out, part.as_bytes(), "entity identity string part")?;
+    }
+    Ok(())
+}
+
+fn push_optional_json_ref(out: &mut Vec<u8>, json_ref: Option<&JsonRef>) {
+    match json_ref {
+        Some(json_ref) => {
+            out.push(1);
+            out.extend_from_slice(json_ref.as_hash_bytes());
+        }
+        None => out.push(0),
+    }
+}
+
+fn push_mixed_optional_json_ref(
+    out: &mut Vec<u8>,
+    indexes: &HashMap<[u8; TRACKED_STATE_HASH_BYTES], usize>,
+    json_ref: Option<&JsonRef>,
+) -> Result<(), LixError> {
+    let Some(json_ref) = json_ref else {
+        out.push(DELTA_JSON_REF_NONE);
+        return Ok(());
+    };
+    if let Some(index) = indexes.get(json_ref.as_hash_array()).copied() {
+        out.push(DELTA_JSON_REF_PACK_INDEX);
+        push_var_u32(out, index, "json ref pack index")
+    } else {
+        out.push(DELTA_JSON_REF_INLINE);
+        out.extend_from_slice(json_ref.as_hash_bytes());
+        Ok(())
+    }
+}
+
+fn push_var_delta_change_id(
+    out: &mut Vec<u8>,
+    source_commit_id: &str,
+    change_id: &str,
+) -> Result<(), LixError> {
+    if let Some(suffix) = change_id.strip_prefix(source_commit_id) {
+        out.push(DELTA_CHANGE_ID_COMMIT_SUFFIX);
+        push_var_sized_bytes(out, suffix.as_bytes(), "change_id")
+    } else {
+        out.push(DELTA_CHANGE_ID_FULL);
+        push_var_sized_bytes(out, change_id.as_bytes(), "change_id")
+    }
+}
+
+fn read_var_delta_change_id(
+    bytes: &[u8],
+    cursor: &mut usize,
+    source_commit_id: &str,
+) -> Result<String, LixError> {
+    let tag = read_u8(bytes, cursor, "delta change_id tag")?;
+    let value = read_var_sized_string(bytes, cursor, "change_id")?;
+    match tag {
+        DELTA_CHANGE_ID_FULL => Ok(value),
+        DELTA_CHANGE_ID_COMMIT_SUFFIX => Ok(format!("{source_commit_id}{value}")),
+        other => Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state delta value has invalid change_id tag {other}"),
+        )),
+    }
+}
+
+#[cfg(test)]
+fn optional_json_ref_len(json_ref: Option<&JsonRef>) -> usize {
+    1 + json_ref.map_or(0, |_| TRACKED_STATE_HASH_BYTES)
+}
+
+fn push_timestamp_pair(out: &mut Vec<u8>, created_at: &str, updated_at: &str) {
+    push_sized_bytes(out, created_at.as_bytes());
+    if updated_at == created_at {
+        out.push(TIMESTAMP_UPDATED_SAME);
+    } else {
+        out.push(TIMESTAMP_UPDATED_DISTINCT);
+        push_sized_bytes(out, updated_at.as_bytes());
+    }
+}
+
+fn push_var_timestamp_pair(
+    out: &mut Vec<u8>,
+    created_at: &str,
+    updated_at: &str,
+) -> Result<(), LixError> {
+    push_var_sized_bytes(out, created_at.as_bytes(), "created_at")?;
+    if updated_at == created_at {
+        out.push(TIMESTAMP_UPDATED_SAME);
+    } else {
+        out.push(TIMESTAMP_UPDATED_DISTINCT);
+        push_var_sized_bytes(out, updated_at.as_bytes(), "updated_at")?;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+fn timestamp_pair_len(created_at: &str, updated_at: &str) -> usize {
+    sized_bytes_len(created_at.as_bytes())
+        + 1
+        + if updated_at == created_at {
+            0
+        } else {
+            sized_bytes_len(updated_at.as_bytes())
+        }
+}
+
+fn read_timestamp_pair(bytes: &[u8], cursor: &mut usize) -> Result<(String, String), LixError> {
+    let created_at = read_sized_string(bytes, cursor, "created_at")?;
+    let updated_at = match read_u8(bytes, cursor, "updated_at tag")? {
+        TIMESTAMP_UPDATED_SAME => created_at.clone(),
+        TIMESTAMP_UPDATED_DISTINCT => read_sized_string(bytes, cursor, "updated_at")?,
+        other => {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("tracked-state timestamp pair has invalid updated_at tag {other}"),
+            ))
+        }
+    };
+    Ok((created_at, updated_at))
+}
+
+fn read_var_timestamp_pair(bytes: &[u8], cursor: &mut usize) -> Result<(String, String), LixError> {
+    let created_at = read_var_sized_string(bytes, cursor, "created_at")?;
+    let updated_at = match read_u8(bytes, cursor, "updated_at tag")? {
+        TIMESTAMP_UPDATED_SAME => created_at.clone(),
+        TIMESTAMP_UPDATED_DISTINCT => read_var_sized_string(bytes, cursor, "updated_at")?,
+        other => {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("tracked-state timestamp pair has invalid updated_at tag {other}"),
+            ))
+        }
+    };
+    Ok((created_at, updated_at))
+}
+
+fn push_u32(out: &mut Vec<u8>, value: usize) {
+    out.extend_from_slice(&(value as u32).to_be_bytes());
+}
+
+fn read_sized_string(
+    bytes: &[u8],
+    cursor: &mut usize,
+    field_name: &str,
+) -> Result<String, LixError> {
+    String::from_utf8(read_sized_bytes(bytes, cursor, field_name)?).map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' is invalid UTF-8: {error}"),
+        )
+    })
+}
+
+fn read_sized_bytes(
+    bytes: &[u8],
+    cursor: &mut usize,
+    field_name: &str,
+) -> Result<Vec<u8>, LixError> {
+    read_sized_slice(bytes, cursor, field_name).map(<[u8]>::to_vec)
+}
+
+fn read_sized_slice<'a>(
+    bytes: &'a [u8],
+    cursor: &mut usize,
+    field_name: &str,
+) -> Result<&'a [u8], LixError> {
+    let len = read_u32(bytes, cursor, field_name)?;
+    let end = cursor.checked_add(len).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' length overflow"),
+        )
+    })?;
+    let slice = bytes.get(*cursor..end).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' is truncated"),
+        )
+    })?;
+    *cursor = end;
+    Ok(slice)
+}
+
+fn read_var_sized_string(
+    bytes: &[u8],
+    cursor: &mut usize,
+    field_name: &str,
+) -> Result<String, LixError> {
+    String::from_utf8(read_var_sized_slice(bytes, cursor, field_name)?.to_vec()).map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state delta pack field '{field_name}' is invalid UTF-8: {error}"),
+        )
+    })
+}
+
+fn read_var_sized_slice<'a>(
+    bytes: &'a [u8],
+    cursor: &mut usize,
+    field_name: &str,
+) -> Result<&'a [u8], LixError> {
+    let len = read_var_u32(bytes, cursor, field_name)?;
+    let end = cursor.checked_add(len).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state delta pack field '{field_name}' length overflow"),
+        )
+    })?;
+    let slice = bytes.get(*cursor..end).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state delta pack field '{field_name}' is truncated"),
+        )
+    })?;
+    *cursor = end;
+    Ok(slice)
+}
+
+fn read_var_entity_identity(bytes: &[u8], cursor: &mut usize) -> Result<EntityIdentity, LixError> {
+    let count = read_var_u32(bytes, cursor, "entity identity part count")?;
+    let mut parts = Vec::new();
+    for _ in 0..count {
+        parts.push(read_var_sized_string(
+            bytes,
+            cursor,
+            "entity identity string part",
+        )?);
+    }
+    if parts.is_empty() {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "tracked-state delta key entity identity must contain at least one part",
+        ));
+    }
+    Ok(EntityIdentity { parts })
+}
+
+fn read_fixed_hash(
+    bytes: &[u8],
+    cursor: &mut usize,
+    field_name: &str,
+) -> Result<[u8; TRACKED_STATE_HASH_BYTES], LixError> {
+    let end = *cursor + TRACKED_STATE_HASH_BYTES;
+    let slice = bytes.get(*cursor..end).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' is truncated"),
+        )
+    })?;
+    let mut out = [0_u8; TRACKED_STATE_HASH_BYTES];
+    out.copy_from_slice(slice);
+    *cursor = end;
+    Ok(out)
+}
+
+fn read_optional_json_ref(
+    bytes: &[u8],
+    cursor: &mut usize,
+    field_name: &str,
+) -> Result<Option<JsonRef>, LixError> {
+    match read_u8(bytes, cursor, field_name)? {
+        0 => Ok(None),
+        1 => Ok(Some(JsonRef::from_hash_bytes(read_fixed_hash(
+            bytes, cursor, field_name,
+        )?))),
+        other => Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' has invalid JSON ref tag {other}"),
+        )),
+    }
+}
+
+fn read_mixed_optional_json_ref(
+    bytes: &[u8],
+    cursor: &mut usize,
+    refs: &[JsonRef],
+    field_name: &str,
+) -> Result<Option<JsonRef>, LixError> {
+    match read_u8(bytes, cursor, field_name)? {
+        DELTA_JSON_REF_NONE => Ok(None),
+        DELTA_JSON_REF_PACK_INDEX => {
+            let index = read_var_u32(bytes, cursor, field_name)?;
+            refs.get(index).copied().map(Some).ok_or_else(|| {
+                LixError::new(
+                    "LIX_ERROR_UNKNOWN",
+                    format!("tracked-state delta JSON ref index {index} is out of bounds"),
+                )
+            })
+        }
+        DELTA_JSON_REF_INLINE => {
+            let hash = read_fixed_hash(bytes, cursor, field_name)?;
+            Ok(Some(JsonRef::from_hash_bytes(hash)))
+        }
+        other => Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' has invalid JSON ref tag {other}"),
+        )),
+    }
+}
+
+fn read_u8(bytes: &[u8], cursor: &mut usize, field_name: &str) -> Result<u8, LixError> {
+    let value = *bytes.get(*cursor).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' is truncated"),
+        )
+    })?;
+    *cursor += 1;
+    Ok(value)
+}
+
+fn read_var_u32(bytes: &[u8], cursor: &mut usize, field_name: &str) -> Result<usize, LixError> {
+    let mut value = 0u32;
+    let mut shift = 0u32;
+    for byte_index in 0..5 {
+        let byte = read_u8(bytes, cursor, field_name)?;
+        if shift == 28 && (byte & 0x80 != 0 || byte & 0x70 != 0) {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("tracked-state delta pack field '{field_name}' varint exceeds u32"),
+            ));
+        }
+        if byte_index > 0 && byte & 0x80 == 0 && byte == 0 {
+            return Err(LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("tracked-state delta pack field '{field_name}' has non-canonical varint"),
+            ));
+        }
+        value |= ((byte & 0x7f) as u32) << shift;
+        if byte & 0x80 == 0 {
+            return Ok(value as usize);
+        }
+        shift += 7;
+    }
+    Err(LixError::new(
+        "LIX_ERROR_UNKNOWN",
+        format!("tracked-state delta pack field '{field_name}' varint exceeds u32"),
+    ))
+}
+
+fn read_u32(bytes: &[u8], cursor: &mut usize, field_name: &str) -> Result<usize, LixError> {
+    let end = *cursor + 4;
+    let slice = bytes.get(*cursor..end).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' is truncated"),
+        )
+    })?;
+    let mut out = [0_u8; 4];
+    out.copy_from_slice(slice);
+    *cursor = end;
+    Ok(u32::from_be_bytes(out) as usize)
+}
+
+fn read_u64(bytes: &[u8], cursor: &mut usize, field_name: &str) -> Result<u64, LixError> {
+    let end = *cursor + 8;
+    let slice = bytes.get(*cursor..end).ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("tracked-state tree field '{field_name}' is truncated"),
+        )
+    })?;
+    let mut out = [0_u8; 8];
+    out.copy_from_slice(slice);
+    *cursor = end;
+    Ok(u64::from_be_bytes(out))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn key_codec_distinguishes_null_and_value_file_id() {
+        let null_key = encode_key(&TrackedStateKey {
+            schema_key: "schema".to_string(),
+            file_id: None,
+            entity_id: EntityIdentity::single("entity"),
+        });
+        let file_key = encode_key(&TrackedStateKey {
+            schema_key: "schema".to_string(),
+            file_id: Some("file".to_string()),
+            entity_id: EntityIdentity::single("entity"),
+        });
+
+        assert_ne!(null_key, file_key);
+        assert_eq!(
+            decode_key(&null_key).expect("null key"),
+            TrackedStateKey {
+                schema_key: "schema".to_string(),
+                file_id: None,
+                entity_id: EntityIdentity::single("entity"),
+            }
+        );
+        assert_eq!(
+            decode_key(&file_key).expect("file key"),
+            TrackedStateKey {
+                schema_key: "schema".to_string(),
+                file_id: Some("file".to_string()),
+                entity_id: EntityIdentity::single("entity"),
+            }
+        );
+    }
+
+    #[test]
+    fn key_codec_encodes_composite_identity_as_string_tuple_parts() {
+        let key = TrackedStateKey {
+            schema_key: "schema".to_string(),
+            file_id: None,
+            entity_id: EntityIdentity {
+                parts: vec![
+                    "namespace".to_string(),
+                    "true".to_string(),
+                    "42".to_string(),
+                ],
+            },
+        };
+
+        let encoded = encode_key(&key);
+
+        assert_eq!(decode_key(&encoded).expect("key should decode"), key);
+    }
+
+    #[test]
+    fn key_codec_decodes_entity_suffix_with_trusted_prefix() {
+        let key = TrackedStateKey {
+            schema_key: "schema".to_string(),
+            file_id: Some("file".to_string()),
+            entity_id: EntityIdentity {
+                parts: vec!["namespace".to_string(), "id".to_string()],
+            },
+        };
+        let encoded = encode_key(&key);
+        let prefix = encode_schema_file_prefix("schema", Some("file"));
+
+        assert_eq!(
+            decode_key_with_trusted_prefix(&encoded, "schema", Some("file"), prefix.len())
+                .expect("key suffix should decode"),
+            key
+        );
+    }
+
+    #[test]
+    fn key_codec_rejects_non_string_identity_part_tags() {
+        let mut encoded = encode_key(&TrackedStateKey {
+            schema_key: "schema".to_string(),
+            file_id: None,
+            entity_id: EntityIdentity {
+                parts: vec!["true".to_string()],
+            },
+        });
+        let schema_key_len = "schema".len();
+        let file_scope_offset = 4 + schema_key_len;
+        let entity_tag_offset = file_scope_offset + 1;
+        encoded[entity_tag_offset] = 2;
+
+        let error = decode_key(&encoded).expect_err("non-string identity tag should reject");
+        assert!(error
+            .to_string()
+            .contains("invalid entity identity part tag 2"));
+    }
+
+    #[test]
+    fn key_codec_preserves_tuple_prefix_ordering() {
+        let prefix = encode_key(&TrackedStateKey {
+            schema_key: "schema".to_string(),
+            file_id: None,
+            entity_id: EntityIdentity {
+                parts: vec!["a".to_string()],
+            },
+        });
+        let extended = encode_key(&TrackedStateKey {
+            schema_key: "schema".to_string(),
+            file_id: None,
+            entity_id: EntityIdentity {
+                parts: vec!["a".to_string(), "b".to_string()],
+            },
+        });
+
+        assert!(prefix < extended);
+    }
+
+    #[test]
+    fn value_codec_roundtrips_locator_value() {
+        let value = TrackedStateIndexValue {
+            change_locator: ChangeLocator {
+                source_commit_id: "commit".to_string(),
+                source_pack_id: 7,
+                source_ordinal: 11,
+                change_id: "change".to_string(),
+            },
+            deleted: false,
+            snapshot_ref: Some(JsonRef::from_hash_bytes([1; 32])),
+            metadata_ref: Some(JsonRef::from_hash_bytes([2; 32])),
+            created_at: "2026-01-01T00:00:00Z".to_string(),
+            updated_at: "2026-01-02T00:00:00Z".to_string(),
+        };
+
+        let encoded = encode_value(&value);
+        assert_eq!(decode_value(&encoded).expect("value"), value);
+    }
+
+    #[test]
+    fn value_codec_roundtrips_second_locator_value() {
+        let value = TrackedStateIndexValue {
+            change_locator: ChangeLocator {
+                source_commit_id: "other-commit".to_string(),
+                source_pack_id: 0,
+                source_ordinal: 1,
+                change_id: "other-change".to_string(),
+            },
+            deleted: true,
+            snapshot_ref: None,
+            metadata_ref: None,
+            created_at: "2026-01-01T00:00:00Z".to_string(),
+            updated_at: "2026-01-02T00:00:00Z".to_string(),
+        };
+
+        let encoded = encode_value(&value);
+        assert_eq!(decode_value(&encoded).expect("value"), value);
+    }
+
+    #[test]
+    fn value_codec_compacts_matching_timestamps() {
+        let mut compact = TrackedStateIndexValue {
+            change_locator: ChangeLocator {
+                source_commit_id: "commit".to_string(),
+                source_pack_id: 0,
+                source_ordinal: 1,
+                change_id: "change".to_string(),
+            },
+            deleted: false,
+            snapshot_ref: None,
+            metadata_ref: None,
+            created_at: "2026-01-01T00:00:00Z".to_string(),
+            updated_at: "2026-01-01T00:00:00Z".to_string(),
+        };
+        let compact_len = encode_value(&compact).len();
+        assert_eq!(
+            decode_value(&encode_value(&compact)).expect("value"),
+            compact
+        );
+
+        compact.updated_at = "2026-01-02T00:00:00Z".to_string();
+        let distinct_len = encode_value(&compact).len();
+
+        assert!(compact_len < distinct_len);
+        assert_eq!(
+            distinct_len - compact_len,
+            sized_bytes_len(compact.updated_at.as_bytes())
+        );
+    }
+
+    #[test]
+    fn delta_pack_ref_encoder_roundtrips_entries() {
+        let entity_id = EntityIdentity {
+            parts: vec!["entity-a".to_string()],
+        };
+        let snapshot_ref = JsonRef::from_hash_bytes([1; 32]);
+        let metadata_ref = JsonRef::from_hash_bytes([2; 32]);
+        let live_change = crate::commit_store::ChangeRef {
+            id: "commit-a:change-live",
+            entity_id: &entity_id,
+            schema_key: "schema",
+            file_id: Some("file-a"),
+            snapshot_ref: Some(&snapshot_ref),
+            metadata_ref: Some(&metadata_ref),
+            created_at: "2026-01-01T00:00:00Z",
+        };
+        let tombstone_change = crate::commit_store::ChangeRef {
+            id: "change-deleted",
+            entity_id: &entity_id,
+            schema_key: "schema",
+            file_id: None,
+            snapshot_ref: None,
+            metadata_ref: None,
+            created_at: "2026-01-01T00:00:00Z",
+        };
+        let live_locator = crate::commit_store::ChangeLocatorRef {
+            source_commit_id: "commit-a",
+            source_pack_id: 3,
+            source_ordinal: 5,
+            change_id: "commit-a:change-live",
+        };
+        let tombstone_locator = crate::commit_store::ChangeLocatorRef {
+            source_commit_id: "source-commit",
+            source_pack_id: 3,
+            source_ordinal: 6,
+            change_id: "commit-a:borrowed",
+        };
+        let encoded = encode_delta_pack_refs(
+            "commit-a",
+            &[
+                TrackedStateDeltaRef {
+                    change: live_change,
+                    locator: live_locator,
+                    created_at: "2026-01-01T00:00:00Z",
+                    updated_at: "2026-01-02T00:00:00Z",
+                },
+                TrackedStateDeltaRef {
+                    change: tombstone_change,
+                    locator: tombstone_locator,
+                    created_at: "2026-01-03T00:00:00Z",
+                    updated_at: "2026-01-04T00:00:00Z",
+                },
+            ],
+        )
+        .expect("delta pack should encode");
+
+        let mut cursor = 5usize;
+        assert_eq!(
+            read_var_sized_string(&encoded, &mut cursor, "delta pack commit_id")
+                .expect("commit id should decode"),
+            "commit-a"
+        );
+        assert_eq!(
+            read_var_u32(&encoded, &mut cursor, "delta key prefix count")
+                .expect("prefix count should decode"),
+            2
+        );
+
+        let (decoded_commit_id, decoded) =
+            decode_delta_pack(&encoded, None).expect("delta pack should decode");
+
+        assert_eq!(decoded_commit_id, "commit-a");
+        assert_eq!(
+            decoded,
+            vec![
+                TrackedStateDeltaEntry {
+                    key: TrackedStateKey {
+                        schema_key: "schema".to_string(),
+                        file_id: Some("file-a".to_string()),
+                        entity_id: entity_id.clone(),
+                    },
+                    value: TrackedStateIndexValue {
+                        change_locator: ChangeLocator {
+                            source_commit_id: "commit-a".to_string(),
+                            source_pack_id: 3,
+                            source_ordinal: 5,
+                            change_id: "commit-a:change-live".to_string(),
+                        },
+                        deleted: false,
+                        snapshot_ref: Some(snapshot_ref),
+                        metadata_ref: Some(metadata_ref),
+                        created_at: "2026-01-01T00:00:00Z".to_string(),
+                        updated_at: "2026-01-02T00:00:00Z".to_string(),
+                    },
+                },
+                TrackedStateDeltaEntry {
+                    key: TrackedStateKey {
+                        schema_key: "schema".to_string(),
+                        file_id: None,
+                        entity_id,
+                    },
+                    value: TrackedStateIndexValue {
+                        change_locator: ChangeLocator {
+                            source_commit_id: "source-commit".to_string(),
+                            source_pack_id: 3,
+                            source_ordinal: 6,
+                            change_id: "commit-a:borrowed".to_string(),
+                        },
+                        deleted: true,
+                        snapshot_ref: None,
+                        metadata_ref: None,
+                        created_at: "2026-01-03T00:00:00Z".to_string(),
+                        updated_at: "2026-01-04T00:00:00Z".to_string(),
+                    },
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn delta_pack_ref_encoder_roundtrips_mixed_json_pack_indexes() {
+        let entity_id = EntityIdentity::single("entity-a");
+        let snapshot_ref = JsonRef::from_hash_bytes([1; 32]);
+        let metadata_ref = JsonRef::from_hash_bytes([2; 32]);
+        let change = crate::commit_store::ChangeRef {
+            id: "commit-a:change-live",
+            entity_id: &entity_id,
+            schema_key: "schema",
+            file_id: Some("file-a"),
+            snapshot_ref: Some(&snapshot_ref),
+            metadata_ref: Some(&metadata_ref),
+            created_at: "2026-01-01T00:00:00Z",
+        };
+        let locator = crate::commit_store::ChangeLocatorRef {
+            source_commit_id: "commit-a",
+            source_pack_id: 0,
+            source_ordinal: 0,
+            change_id: "commit-a:change-live",
+        };
+        let delta = TrackedStateDeltaRef {
+            change,
+            locator,
+            created_at: "2026-01-01T00:00:00Z",
+            updated_at: "2026-01-01T00:00:00Z",
+        };
+        let mut pack_indexes = HashMap::new();
+        pack_indexes.insert(*snapshot_ref.as_hash_array(), 1);
+        let pack_refs = vec![JsonRef::from_hash_bytes([9; 32]), snapshot_ref];
+
+        let inline = encode_delta_pack_refs("commit-a", &[delta]).expect("inline delta pack");
+        assert!(!delta_pack_uses_json_pack_indexes(&inline).expect("inline mode should peek"));
+        let empty_indexes = HashMap::new();
+        let empty_index_pack = encode_delta_pack_refs_with_json_pack_indexes(
+            "commit-a",
+            &[delta],
+            Some(&empty_indexes),
+        )
+        .expect("empty-index delta pack");
+        assert_eq!(empty_index_pack, inline);
+        assert!(!delta_pack_uses_json_pack_indexes(&empty_index_pack)
+            .expect("empty index mode should peek"));
+        decode_delta_pack(&empty_index_pack, None).expect("empty index pack should decode inline");
+
+        let mixed = encode_delta_pack_refs_with_json_pack_indexes(
+            "commit-a",
+            &[delta],
+            Some(&pack_indexes),
+        )
+        .expect("mixed delta pack");
+        assert!(delta_pack_uses_json_pack_indexes(&mixed).expect("mixed mode should peek"));
+
+        assert!(
+            mixed.len() < inline.len(),
+            "pack-index refs should be smaller than inline refs"
+        );
+        assert!(decode_delta_pack(&mixed, None)
+            .expect_err("mixed refs require JSON pack refs")
+            .to_string()
+            .contains("needs JSON pack refs"));
+        let (_, decoded) =
+            decode_delta_pack(&mixed, Some(&pack_refs)).expect("mixed delta pack should decode");
+        assert_eq!(decoded[0].value.snapshot_ref, Some(snapshot_ref));
+        assert_eq!(decoded[0].value.metadata_ref, Some(metadata_ref));
+    }
+
+    #[test]
+    fn delta_pack_stream_decoder_rejects_trailing_entry_bytes() {
+        let entity_id = EntityIdentity::single("entity");
+        let change = crate::commit_store::ChangeRef {
+            id: "commit-a:change-0",
+            entity_id: &entity_id,
+            schema_key: "schema",
+            file_id: None,
+            snapshot_ref: None,
+            metadata_ref: None,
+            created_at: "2026-01-01T00:00:00Z",
+        };
+        let locator = crate::commit_store::ChangeLocatorRef {
+            source_commit_id: "commit-a",
+            source_pack_id: 0,
+            source_ordinal: 0,
+            change_id: "commit-a:change-0",
+        };
+        let mut encoded = encode_delta_pack_refs(
+            "commit-a",
+            &[TrackedStateDeltaRef {
+                change,
+                locator,
+                created_at: "2026-01-01T00:00:00Z",
+                updated_at: "2026-01-01T00:00:00Z",
+            }],
+        )
+        .expect("delta pack should encode");
+
+        let mut cursor = 5usize;
+        let _ = read_var_sized_string(&encoded, &mut cursor, "delta pack commit_id")
+            .expect("commit id should decode");
+        assert_eq!(
+            read_var_u32(&encoded, &mut cursor, "delta key prefix count")
+                .expect("prefix count should decode"),
+            1
+        );
+        let _ =
+            decode_delta_key_prefix(&encoded, &mut cursor).expect("delta key prefix should decode");
+        encoded[cursor] = 0;
+
+        let error =
+            decode_delta_pack(&encoded, None).expect_err("trailing entry bytes should reject");
+        assert!(
+            error.to_string().contains("trailing bytes"),
+            "error should mention trailing bytes: {error}"
+        );
+    }
+
+    #[test]
+    fn delta_pack_rejects_overlong_varint() {
+        let mut encoded = Vec::new();
+        encoded.extend_from_slice(b"LXTD");
+        encoded.push(DELTA_PACK_VERSION);
+        encoded.extend_from_slice(&[0x80, 0x80, 0x80, 0x80, 0x80]);
+
+        let error = decode_delta_pack(&encoded, None).expect_err("overlong varint should reject");
+        assert!(
+            error.to_string().contains("varint exceeds u32"),
+            "error should mention overlong varint: {error}"
+        );
+    }
+
+    #[test]
+    fn delta_pack_rejects_varint_above_u32() {
+        let mut encoded = Vec::new();
+        encoded.extend_from_slice(b"LXTD");
+        encoded.push(DELTA_PACK_VERSION);
+        encoded.extend_from_slice(&[0xff, 0xff, 0xff, 0xff, 0x1f]);
+
+        let error = decode_delta_pack(&encoded, None).expect_err("too-large varint should reject");
+        assert!(
+            error.to_string().contains("varint exceeds u32"),
+            "error should mention oversized varint: {error}"
+        );
+    }
+
+    #[test]
+    fn delta_pack_rejects_non_canonical_varint() {
+        let mut encoded = Vec::new();
+        encoded.extend_from_slice(b"LXTD");
+        encoded.push(DELTA_PACK_VERSION);
+        encoded.extend_from_slice(&[0x80, 0x00]);
+
+        let error =
+            decode_delta_pack(&encoded, None).expect_err("non-canonical varint should reject");
+        assert!(
+            error.to_string().contains("non-canonical varint"),
+            "error should mention non-canonical varint: {error}"
+        );
+    }
+
+    #[test]
+    fn delta_key_decoder_rejects_out_of_bounds_prefix_index() {
+        let mut encoded_key = Vec::new();
+        push_var_u32(&mut encoded_key, 1, "delta key prefix index").expect("prefix index");
+        push_var_entity_identity(&mut encoded_key, &EntityIdentity::single("entity"))
+            .expect("entity identity");
+
+        let mut cursor = 0usize;
+        let err = decode_delta_key(
+            &encoded_key,
+            &mut cursor,
+            &[DeltaKeyPrefix {
+                schema_key: "schema".to_string(),
+                file_id: None,
+            }],
+        )
+        .expect_err("out-of-bounds prefix index should reject");
+
+        assert!(err
+            .to_string()
+            .contains("tracked-state delta key prefix index 1 is out of bounds"));
+    }
+
+    #[test]
+    fn encoded_value_len_matches_encoded_value_bytes() {
+        let values = [
+            TrackedStateIndexValue {
+                change_locator: ChangeLocator {
+                    source_commit_id: "commit".to_string(),
+                    source_pack_id: 0,
+                    source_ordinal: 0,
+                    change_id: "change".to_string(),
+                },
+                deleted: false,
+                snapshot_ref: None,
+                metadata_ref: None,
+                created_at: "2026-01-01T00:00:00Z".to_string(),
+                updated_at: "2026-01-02T00:00:00Z".to_string(),
+            },
+            TrackedStateIndexValue {
+                change_locator: ChangeLocator {
+                    source_commit_id: "commit".to_string(),
+                    source_pack_id: 1,
+                    source_ordinal: 2,
+                    change_id: "change-2".to_string(),
+                },
+                deleted: true,
+                snapshot_ref: Some(JsonRef::from_hash_bytes([3; 32])),
+                metadata_ref: None,
+                created_at: "2026-01-01T00:00:00Z".to_string(),
+                updated_at: "2026-01-02T00:00:00Z".to_string(),
+            },
+            TrackedStateIndexValue {
+                change_locator: ChangeLocator {
+                    source_commit_id: "other".to_string(),
+                    source_pack_id: 4,
+                    source_ordinal: 8,
+                    change_id: "change-3".to_string(),
+                },
+                deleted: false,
+                snapshot_ref: None,
+                metadata_ref: Some(JsonRef::from_hash_bytes([4; 32])),
+                created_at: "2026-01-01T00:00:00Z".to_string(),
+                updated_at: "2026-01-02T00:00:00Z".to_string(),
+            },
+        ];
+
+        for value in values {
+            assert_eq!(encoded_value_len(&value), encode_value(&value).len());
+        }
+    }
+
+    #[test]
+    fn leaf_node_codec_uses_indexable_offset_table() {
+        let entries = vec![
+            EncodedLeafEntry {
+                key: b"alpha".to_vec(),
+                value: b"one".to_vec(),
+            },
+            EncodedLeafEntry {
+                key: b"bravo".to_vec(),
+                value: b"two-two".to_vec(),
+            },
+        ];
+
+        let encoded = encode_leaf_node(&entries);
+        assert_eq!(encoded[0], NODE_KIND_LEAF);
+        assert_eq!(encoded[1], NODE_VERSION);
+        assert_eq!(&encoded[2..6], 2u32.to_be_bytes().as_slice());
+        assert_eq!(&encoded[6..10], 0u32.to_be_bytes().as_slice());
+
+        let DecodedNodeRef::Leaf(leaf) = decode_node_ref(&encoded).expect("leaf ref") else {
+            panic!("expected leaf node");
+        };
+        assert_eq!(leaf.len(), 2);
+        assert_eq!(leaf.key(1).expect("second key"), Some(b"bravo".as_slice()));
+        let second = leaf
+            .entry(1)
+            .expect("second entry")
+            .expect("second entry exists");
+        assert_eq!(second.key, b"bravo");
+        assert_eq!(second.value, b"two-two");
+
+        let DecodedNode::Leaf(owned) = decode_node(&encoded).expect("owned leaf") else {
+            panic!("expected owned leaf node");
+        };
+        assert_eq!(owned.entries(), entries.as_slice());
+    }
+
+    #[test]
+    fn leaf_node_codec_roundtrips_empty_leaf() {
+        let encoded = encode_leaf_node(&[]);
+        assert_eq!(encoded.len(), 10);
+
+        let DecodedNodeRef::Leaf(leaf) = decode_node_ref(&encoded).expect("leaf ref") else {
+            panic!("expected leaf node");
+        };
+        assert_eq!(leaf.len(), 0);
+        assert!(leaf.entry(0).expect("missing entry").is_none());
+    }
+
+    #[test]
+    fn leaf_node_codec_rejects_malformed_offsets() {
+        let entries = vec![
+            EncodedLeafEntry {
+                key: b"alpha".to_vec(),
+                value: b"one".to_vec(),
+            },
+            EncodedLeafEntry {
+                key: b"bravo".to_vec(),
+                value: b"two".to_vec(),
+            },
+        ];
+        let encoded = encode_leaf_node(&entries);
+
+        let mut non_zero_first = encoded.clone();
+        non_zero_first[6..10].copy_from_slice(&1u32.to_be_bytes());
+        assert!(decode_node_ref(&non_zero_first)
+            .expect_err("non-zero first offset should reject")
+            .to_string()
+            .contains("offset table must start at zero"));
+
+        let mut non_monotonic = encoded.clone();
+        non_monotonic[10..14].copy_from_slice(&100u32.to_be_bytes());
+        assert!(decode_node_ref(&non_monotonic)
+            .expect_err("non-monotonic offsets should reject")
+            .to_string()
+            .contains("offsets must be monotonic"));
+
+        let mut short_coverage = encoded;
+        let payload_len = short_coverage.len() - 18;
+        short_coverage[14..18].copy_from_slice(&((payload_len - 1) as u32).to_be_bytes());
+        assert!(decode_node_ref(&short_coverage)
+            .expect_err("short offset coverage should reject")
+            .to_string()
+            .contains("offset table does not cover full payload"));
+    }
+
+    #[test]
+    fn content_hash_is_blake3() {
+        assert_eq!(hash_bytes(b"abc"), *blake3::hash(b"abc").as_bytes());
+    }
+
+    #[test]
+    fn boundary_decisions_are_xxh3_based_and_deterministic() {
+        let left = boundary_trigger(b"key", 0, 4096, 128, 4096);
+        let right = boundary_trigger(b"key", 0, 4096, 128, 4096);
+        assert_eq!(left, right);
+    }
+}