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

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

@@ -1,21 +1,49 @@
+use std::collections::HashMap;
+
 use xxhash_rust::xxh3::xxh3_64_with_seed;
 
-use crate::entity_identity::{EntityIdentity, EntityIdentityPart};
+use crate::commit_store::ChangeLocator;
+use crate::entity_identity::EntityIdentity;
 use crate::json_store::JsonRef;
-use crate::tracked_state::tree_types::{
-    TrackedStateKey, TrackedStateValue, TRACKED_STATE_HASH_BYTES,
+use crate::tracked_state::types::{
+    TrackedStateDeltaEntry, TrackedStateDeltaRef, TrackedStateIndexValue,
+    TrackedStateIndexValueRef, TrackedStateKey, TrackedStateKeyRef, TRACKED_STATE_HASH_BYTES,
 };
 use crate::LixError;
 
-const NODE_VERSION: u8 = 1;
-const VALUE_VERSION: u8 = 2;
+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;
-const ENTITY_IDENTITY_BOOL: u8 = 2;
-const ENTITY_IDENTITY_NUMBER: u8 = 3;
+
+#[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 {
@@ -23,6 +51,21 @@ pub(crate) struct EncodedLeafEntry {
     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],
@@ -37,12 +80,37 @@ pub(crate) struct ChildSummary {
     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>,
@@ -54,6 +122,50 @@ impl DecodedLeafNode {
     }
 }
 
+#[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>,
@@ -70,17 +182,29 @@ pub(crate) fn hash_bytes(bytes: &[u8]) -> [u8; TRACKED_STATE_HASH_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();
-    push_sized_bytes(&mut out, key.schema_key.as_bytes());
-    match &key.file_id {
+    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(&mut out, file_id.as_bytes());
+            push_sized_bytes(out, file_id.as_bytes());
         }
         None => out.push(0),
     }
-    push_entity_identity(&mut out, &key.entity_id);
-    out
+    push_entity_identity(out, key.entity_id);
 }
 
 pub(crate) fn encode_schema_key_prefix(schema_key: &str) -> Vec<u8> {
@@ -128,137 +252,573 @@ pub(crate) fn decode_key(bytes: &[u8]) -> Result<TrackedStateKey, LixError> {
     })
 }
 
-pub(crate) fn encode_value(value: &TrackedStateValue) -> Vec<u8> {
+/// 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();
-    out.push(VALUE_VERSION);
-    push_optional_json_ref(&mut out, value.snapshot_ref.as_ref());
-    push_optional_json_ref(&mut out, value.metadata_ref.as_ref());
-    push_sized_bytes(&mut out, value.schema_version.as_bytes());
-    push_sized_bytes(&mut out, value.created_at.as_bytes());
-    push_sized_bytes(&mut out, value.updated_at.as_bytes());
-    push_sized_bytes(&mut out, value.change_id.as_bytes());
-    push_sized_bytes(&mut out, value.commit_id.as_bytes());
-    out.push(u8::from(value.deleted));
+    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: &TrackedStateValue) -> usize {
-    1 + optional_json_ref_len(value.snapshot_ref.as_ref())
+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())
-        + sized_bytes_len(value.schema_version.as_bytes())
-        + sized_bytes_len(value.created_at.as_bytes())
-        + sized_bytes_len(value.updated_at.as_bytes())
-        + sized_bytes_len(value.change_id.as_bytes())
-        + sized_bytes_len(value.commit_id.as_bytes())
-        + 1
 }
 
-pub(crate) fn decode_value(bytes: &[u8]) -> Result<TrackedStateValue, LixError> {
+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 version = read_u8(bytes, &mut cursor, "value version")?;
+    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")?;
-    let schema_version = read_sized_string(bytes, &mut cursor, "schema_version")?;
-    let created_at = read_sized_string(bytes, &mut cursor, "created_at")?;
-    let updated_at = read_sized_string(bytes, &mut cursor, "updated_at")?;
-    let change_id = read_sized_string(bytes, &mut cursor, "change_id")?;
-    let commit_id = read_sized_string(bytes, &mut cursor, "commit_id")?;
-    let deleted = match read_u8(bytes, &mut cursor, "deleted")? {
-        0 => false,
-        1 => true,
-        other => {
-            return Err(LixError::new(
-                "LIX_ERROR_UNKNOWN",
-                format!("tracked-state tree value has invalid deleted byte {other}"),
-            ))
-        }
-    };
     if cursor != bytes.len() {
         return Err(LixError::new(
             "LIX_ERROR_UNKNOWN",
             "tracked-state tree value decode found trailing bytes",
         ));
     }
-    Ok(TrackedStateValue {
+    Ok(TrackedStateIndexValue {
+        change_locator: ChangeLocator {
+            source_commit_id,
+            source_pack_id,
+            source_ordinal,
+            change_id,
+        },
+        deleted,
         snapshot_ref,
         metadata_ref,
-        schema_version,
         created_at,
         updated_at,
-        change_id,
-        commit_id,
-        deleted,
     })
 }
 
-#[cfg(test)]
-fn sized_bytes_len(bytes: &[u8]) -> usize {
-    4 + bytes.len()
+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 push_optional_json_ref(out: &mut Vec<u8>, value: Option<&JsonRef>) {
-    match value {
-        Some(value) => {
+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);
-            out.extend_from_slice(value.as_hash_bytes());
+            push_var_sized_bytes(out, file_id.as_bytes(), "delta key prefix file_id")?;
         }
         None => out.push(0),
     }
+    Ok(())
 }
 
-#[cfg(test)]
-fn optional_json_ref_len(value: Option<&JsonRef>) -> usize {
-    match value {
-        Some(_) => 1 + TRACKED_STATE_HASH_BYTES,
-        None => 1,
+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(())
 }
 
-fn read_optional_json_ref(
+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,
-    field: &str,
-) -> Result<Option<JsonRef>, LixError> {
-    match read_u8(bytes, cursor, field)? {
-        0 => Ok(None),
-        1 => {
-            let hash = read_fixed_hash(bytes, cursor, field)?;
-            Ok(Some(JsonRef::from_hash_bytes(hash)))
+    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 tree value has invalid {field} presence byte {other}"),
+            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 out, &entry.key);
-        push_sized_bytes(&mut out, &entry.value);
+        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);
+        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());
     }
@@ -266,6 +826,28 @@ pub(crate) fn encode_internal_node(children: &[ChildSummary]) -> Vec<u8> {
 }
 
 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")?;
@@ -278,14 +860,8 @@ pub(crate) fn decode_node(bytes: &[u8]) -> Result<DecodedNode, LixError> {
     let count = read_u32(bytes, &mut cursor, "entry count")?;
     let node = match kind {
         NODE_KIND_LEAF => {
-            let mut entries = Vec::with_capacity(count);
-            for _ in 0..count {
-                entries.push(EncodedLeafEntry {
-                    key: read_sized_bytes(bytes, &mut cursor, "leaf key")?,
-                    value: read_sized_bytes(bytes, &mut cursor, "leaf value")?,
-                });
-            }
-            DecodedNode::Leaf(DecodedLeafNode { entries })
+            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);
@@ -301,7 +877,7 @@ pub(crate) fn decode_node(bytes: &[u8]) -> Result<DecodedNode, LixError> {
                     subtree_count,
                 });
             }
-            DecodedNode::Internal(DecodedInternalNode { children })
+            DecodedNodeRef::Internal(DecodedInternalNode { children })
         }
         other => {
             return Err(LixError::new(
@@ -319,6 +895,50 @@ pub(crate) fn decode_node(bytes: &[u8]) -> Result<DecodedNode, LixError> {
     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>,
@@ -384,20 +1004,8 @@ fn push_entity_identity(out: &mut Vec<u8>, identity: &EntityIdentity) {
         "tracked-state key entity identity must contain at least one part"
     );
     for part in &identity.parts {
-        match part {
-            EntityIdentityPart::String(value) => {
-                out.push(ENTITY_IDENTITY_STRING);
-                push_sized_bytes(out, value.as_bytes());
-            }
-            EntityIdentityPart::Bool(value) => {
-                out.push(ENTITY_IDENTITY_BOOL);
-                out.push(u8::from(*value));
-            }
-            EntityIdentityPart::Number(value) => {
-                out.push(ENTITY_IDENTITY_NUMBER);
-                push_sized_bytes(out, value.as_bytes());
-            }
-        }
+        out.push(ENTITY_IDENTITY_STRING);
+        push_sized_bytes(out, part.as_bytes());
     }
     out.push(ENTITY_IDENTITY_END);
 }
@@ -409,33 +1017,11 @@ fn read_entity_identity(bytes: &[u8], cursor: &mut usize) -> Result<EntityIdenti
         match tag {
             ENTITY_IDENTITY_END => break,
             ENTITY_IDENTITY_STRING => {
-                parts.push(EntityIdentityPart::String(read_sized_string(
+                parts.push(read_sized_string(
                     bytes,
                     cursor,
                     "entity identity string part",
-                )?));
-            }
-            ENTITY_IDENTITY_BOOL => {
-                let value = match read_u8(bytes, cursor, "entity identity bool part")? {
-                    0 => false,
-                    1 => true,
-                    other => {
-                        return Err(LixError::new(
-                            "LIX_ERROR_UNKNOWN",
-                            format!(
-                            "tracked-state tree key has invalid entity identity bool byte {other}"
-                        ),
-                        ))
-                    }
-                };
-                parts.push(EntityIdentityPart::Bool(value));
-            }
-            ENTITY_IDENTITY_NUMBER => {
-                parts.push(EntityIdentityPart::Number(read_sized_string(
-                    bytes,
-                    cursor,
-                    "entity identity number part",
-                )?));
+                )?);
             }
             other => {
                 return Err(LixError::new(
@@ -459,6 +1045,180 @@ fn push_sized_bytes(out: &mut Vec<u8>, bytes: &[u8]) {
     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());
 }
@@ -481,6 +1241,14 @@ fn read_sized_bytes(
     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(
@@ -495,7 +1263,61 @@ fn read_sized_bytes(
         )
     })?;
     *cursor = end;
-    Ok(slice.to_vec())
+    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(
@@ -516,6 +1338,51 @@ fn read_fixed_hash(
     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(
@@ -527,6 +1394,35 @@ fn read_u8(bytes: &[u8], cursor: &mut usize, field_name: &str) -> Result<u8, Lix
     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(|| {
@@ -592,15 +1488,15 @@ mod tests {
     }
 
     #[test]
-    fn key_codec_encodes_composite_identity_as_typed_tuple_parts() {
+    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![
-                    EntityIdentityPart::String("namespace".to_string()),
-                    EntityIdentityPart::Bool(true),
-                    EntityIdentityPart::Number("42".to_string()),
+                    "namespace".to_string(),
+                    "true".to_string(),
+                    "42".to_string(),
                 ],
             },
         };
@@ -608,32 +1504,45 @@ mod tests {
         let encoded = encode_key(&key);
 
         assert_eq!(decode_key(&encoded).expect("key should decode"), key);
-        assert!(
-            !encoded
-                .windows(b"pk:v1:".len())
-                .any(|window| window == b"pk:v1:"),
-            "tracked-state keys should not store the SQL entity_id projection"
-        );
     }
 
     #[test]
-    fn key_codec_distinguishes_typed_identity_parts() {
-        let string_true = encode_key(&TrackedStateKey {
+    fn key_codec_decodes_entity_suffix_with_trusted_prefix() {
+        let key = TrackedStateKey {
             schema_key: "schema".to_string(),
-            file_id: None,
+            file_id: Some("file".to_string()),
             entity_id: EntityIdentity {
-                parts: vec![EntityIdentityPart::String("true".to_string())],
+                parts: vec!["namespace".to_string(), "id".to_string()],
             },
-        });
-        let bool_true = encode_key(&TrackedStateKey {
+        };
+        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![EntityIdentityPart::Bool(true)],
+                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;
 
-        assert_ne!(string_true, bool_true);
+        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]
@@ -642,17 +1551,14 @@ mod tests {
             schema_key: "schema".to_string(),
             file_id: None,
             entity_id: EntityIdentity {
-                parts: vec![EntityIdentityPart::String("a".to_string())],
+                parts: vec!["a".to_string()],
             },
         });
         let extended = encode_key(&TrackedStateKey {
             schema_key: "schema".to_string(),
             file_id: None,
             entity_id: EntityIdentity {
-                parts: vec![
-                    EntityIdentityPart::String("a".to_string()),
-                    EntityIdentityPart::String("b".to_string()),
-                ],
+                parts: vec!["a".to_string(), "b".to_string()],
             },
         });
 
@@ -660,16 +1566,19 @@ mod tests {
     }
 
     #[test]
-    fn value_codec_roundtrips_tombstone_value() {
-        let value = TrackedStateValue {
-            snapshot_ref: None,
-            metadata_ref: Some(JsonRef::from_hash_bytes([1; 32])),
-            schema_version: "1".to_string(),
+    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(),
-            change_id: "change".to_string(),
-            commit_id: "commit".to_string(),
-            deleted: true,
         };
 
         let encoded = encode_value(&value);
@@ -677,54 +1586,397 @@ mod tests {
     }
 
     #[test]
-    fn value_codec_roundtrips_snapshot_ref() {
-        let value = TrackedStateValue {
-            snapshot_ref: Some(JsonRef::from_hash_bytes([2; 32])),
+    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,
-            schema_version: "1".to_string(),
             created_at: "2026-01-01T00:00:00Z".to_string(),
             updated_at: "2026-01-02T00:00:00Z".to_string(),
-            change_id: "change".to_string(),
-            commit_id: "commit".to_string(),
-            deleted: false,
         };
 
         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 = [
-            TrackedStateValue {
+            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,
-                schema_version: "1".to_string(),
                 created_at: "2026-01-01T00:00:00Z".to_string(),
                 updated_at: "2026-01-02T00:00:00Z".to_string(),
-                change_id: "change".to_string(),
-                commit_id: "commit".to_string(),
-                deleted: true,
             },
-            TrackedStateValue {
+            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: Some(JsonRef::from_hash_bytes([4; 32])),
-                schema_version: "1".to_string(),
+                metadata_ref: None,
                 created_at: "2026-01-01T00:00:00Z".to_string(),
                 updated_at: "2026-01-02T00:00:00Z".to_string(),
-                change_id: "change".to_string(),
-                commit_id: "commit".to_string(),
-                deleted: false,
             },
-            TrackedStateValue {
-                snapshot_ref: Some(JsonRef::from_hash_bytes([5; 32])),
-                metadata_ref: None,
-                schema_version: "1".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(),
-                change_id: "change".to_string(),
-                commit_id: "commit".to_string(),
-                deleted: false,
             },
         ];
 
@@ -733,6 +1985,92 @@ mod tests {
         }
     }
 
+    #[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());