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

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

@@ -1,61 +1,53 @@
 use std::collections::{BTreeMap, BTreeSet};
 
 use crate::tracked_state::{
-    MaterializedTrackedStateRow, TrackedStateDiff, TrackedStateDiffEntry, TrackedStateDiffIdentity,
+    TrackedStateDiff, TrackedStateDiffEntry, TrackedStateDiffIdentity, TrackedStateDiffRow,
 };
 use crate::LixError;
 
 /// Planned tracked-state merge result.
 ///
-/// This is intentionally a pure planner. It does not know about versions,
+/// This is intentionally a pure planner. It does not know about branches,
 /// sessions, changelog writes, or live-state overlays. Callers provide two
 /// diffs from the same merge base:
 ///
-/// - `base -> target`: what the destination version changed.
-/// - `base -> source`: what the incoming version changed.
+/// - `base -> target`: what the destination branch changed.
+/// - `base -> source`: what the incoming branch changed.
 ///
-/// The planner returns source-side patches that can be applied to the target
-/// root plus first-class conflicts for identities changed differently on both
-/// sides.
+/// The planner returns source-side picks plus first-class conflicts for
+/// identities changed differently on both sides.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub(crate) struct TrackedStateMergePlan {
-    pub(crate) patches: Vec<TrackedStateMergePatch>,
+    pub(crate) picks: Vec<TrackedStateMergePick>,
     pub(crate) conflicts: Vec<TrackedStateMergeConflict>,
 }
 
-/// One source-side patch to apply to the target root.
+/// One source-side change selected for the merge result.
 ///
-/// Merge patches are expressed as canonical change adoption, not as new row
-/// writes. The projected row carries the target-root materialization shape,
-/// including tombstones, while `change_id` preserves the source canonical
-/// change identity.
+/// Merge picks describe source-side state that will be selected into
+/// the target root. The selected row carries the target-root materialization
+/// shape, including tombstones.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) enum TrackedStateMergePatch {
-    Adopt {
-        identity: TrackedStateDiffIdentity,
-        change_id: String,
-        projected_row: MaterializedTrackedStateRow,
-    },
+pub(crate) struct TrackedStateMergePick {
+    pub(crate) identity: TrackedStateDiffIdentity,
+    pub(crate) change_id: String,
+    pub(crate) selected_row: TrackedStateDiffRow,
 }
 
-impl TrackedStateMergePatch {
+impl TrackedStateMergePick {
     #[cfg(test)]
     pub(crate) fn identity(&self) -> &TrackedStateDiffIdentity {
-        match self {
-            Self::Adopt { identity, .. } => identity,
-        }
+        &self.identity
     }
 
-    pub(crate) fn change_id(&self) -> &str {
-        match self {
-            Self::Adopt { change_id, .. } => change_id,
-        }
+    #[cfg(test)]
+    pub(crate) fn source_change_id(&self) -> &str {
+        &self.change_id
     }
 
-    pub(crate) fn projected_row(&self) -> &MaterializedTrackedStateRow {
-        match self {
-            Self::Adopt { projected_row, .. } => projected_row,
-        }
+    #[cfg(test)]
+    pub(crate) fn source_row(&self) -> &TrackedStateDiffRow {
+        &self.selected_row
     }
 }
 
@@ -70,7 +62,7 @@ pub(crate) struct TrackedStateMergeConflict {
 /// Plans a three-way tracked-state merge from two base-relative diffs.
 ///
 /// This follows the same shape as prolly-tree merge systems: compare
-/// `base -> target` and `base -> source` by identity, emit source-only patches
+/// `base -> target` and `base -> source` by identity, emit source-only picks
 /// for the target root, ignore target-only changes, collapse convergent
 /// changes, and report divergent same-identity changes as conflicts.
 pub(crate) fn plan_merge(
@@ -94,11 +86,10 @@ pub(crate) fn plan_merge(
             (None, None) => {}
             (Some(_target), None) => {
                 // Target already changed this identity. Source did not, so
-                // there is nothing to apply.
+                // there is nothing to pick.
             }
             (None, Some(source)) => {
-                plan.patches
-                    .push(adopt_source_change_patch(identity, source)?);
+                plan.picks.push(source_change_pick(identity, source)?);
             }
             (Some(target), Some(source)) if same_final_state(target, source) => {
                 // Both sides reached the same visible state. Keep target to
@@ -122,13 +113,16 @@ fn diff_by_identity(
 ) -> Result<BTreeMap<TrackedStateDiffIdentity, &TrackedStateDiffEntry>, LixError> {
     let mut entries = BTreeMap::new();
     for entry in &diff.entries {
+        if entry.identity.schema_key == "lix_commit" {
+            continue;
+        }
         if entries.insert(entry.identity.clone(), entry).is_some() {
             return Err(LixError::new(
                 "LIX_ERROR_UNKNOWN",
                 format!(
                     "tracked-state merge received duplicate diff entry for schema '{}' entity '{}'",
                     entry.identity.schema_key,
-                    entry.identity.entity_id.as_json_array_text()?
+                    entry.identity.entity_pk.as_json_array_text()?
                 ),
             ));
         }
@@ -136,24 +130,24 @@ fn diff_by_identity(
     Ok(entries)
 }
 
-fn adopt_source_change_patch(
+fn source_change_pick(
     identity: TrackedStateDiffIdentity,
     entry: &TrackedStateDiffEntry,
-) -> Result<TrackedStateMergePatch, LixError> {
+) -> Result<TrackedStateMergePick, LixError> {
     let Some(row) = entry.after.clone() else {
         return Err(LixError::new(
             "LIX_ERROR_UNKNOWN",
             format!(
-                "tracked-state merge cannot apply source removal for schema '{}' entity '{}' without a tombstone row",
+                "tracked-state merge cannot pick source removal for schema '{}' entity '{}' without a tombstone row",
                 entry.identity.schema_key,
-                entry.identity.entity_id.as_json_array_text()?
+                entry.identity.entity_pk.as_json_array_text()?
             ),
         ));
     };
-    Ok(TrackedStateMergePatch::Adopt {
+    Ok(TrackedStateMergePick {
         identity,
         change_id: row.change_id.clone(),
-        projected_row: row,
+        selected_row: row,
     })
 }
 
@@ -168,21 +162,19 @@ fn same_final_state(target: &TrackedStateDiffEntry, source: &TrackedStateDiffEnt
     }
 }
 
-fn row_is_live(row: &MaterializedTrackedStateRow) -> bool {
-    row.snapshot_content.is_some()
+fn row_is_live(row: &TrackedStateDiffRow) -> bool {
+    !row.deleted
 }
 
-fn tracked_row_payload_eq(
-    left: &MaterializedTrackedStateRow,
-    right: &MaterializedTrackedStateRow,
-) -> bool {
-    left.snapshot_content == right.snapshot_content && left.metadata == right.metadata
+fn tracked_row_payload_eq(left: &TrackedStateDiffRow, right: &TrackedStateDiffRow) -> bool {
+    left.snapshot_ref == right.snapshot_ref && left.metadata_ref == right.metadata_ref
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::entity_identity::EntityIdentity;
+    use crate::entity_pk::EntityPk;
+    use crate::json_store::JsonRef;
     use crate::tracked_state::TrackedStateDiffKind;
 
     #[test]
@@ -198,7 +190,7 @@ mod tests {
         )
         .expect("merge should plan");
 
-        assert_eq!(patch_ids(&plan), vec!["entity-a"]);
+        assert_eq!(pick_ids(&plan), vec!["entity-a"]);
         assert!(plan.conflicts.is_empty());
     }
 
@@ -215,12 +207,9 @@ mod tests {
         )
         .expect("merge should plan");
 
-        assert_eq!(patch_ids(&plan), vec!["entity-a"]);
-        assert_eq!(
-            plan.patches[0].projected_row().snapshot_content.as_deref(),
-            Some("{\"value\":\"source\"}")
-        );
-        assert_eq!(plan.patches[0].change_id(), "source");
+        assert_eq!(pick_ids(&plan), vec!["entity-a"]);
+        assert!(plan.picks[0].source_row().snapshot_ref.is_some());
+        assert_eq!(plan.picks[0].source_change_id(), "source");
     }
 
     #[test]
@@ -236,9 +225,9 @@ mod tests {
         )
         .expect("merge should plan");
 
-        assert_eq!(patch_ids(&plan), vec!["entity-a"]);
-        assert_eq!(plan.patches[0].projected_row().snapshot_content, None);
-        assert_eq!(plan.patches[0].change_id(), "source-delete");
+        assert_eq!(pick_ids(&plan), vec!["entity-a"]);
+        assert!(plan.picks[0].source_row().deleted);
+        assert_eq!(plan.picks[0].source_change_id(), "source-delete");
     }
 
     #[test]
@@ -254,7 +243,7 @@ mod tests {
         )
         .expect("merge should plan");
 
-        assert!(plan.patches.is_empty());
+        assert!(plan.picks.is_empty());
         assert!(plan.conflicts.is_empty());
     }
 
@@ -275,7 +264,7 @@ mod tests {
 
         let plan = plan_merge(&diff(vec![target]), &diff(vec![source])).expect("merge should plan");
 
-        assert!(plan.patches.is_empty());
+        assert!(plan.picks.is_empty());
         assert!(plan.conflicts.is_empty());
     }
 
@@ -296,7 +285,7 @@ mod tests {
 
         let plan = plan_merge(&diff(vec![target]), &diff(vec![source])).expect("merge should plan");
 
-        assert!(plan.patches.is_empty());
+        assert!(plan.picks.is_empty());
         assert!(plan.conflicts.is_empty());
     }
 
@@ -317,7 +306,7 @@ mod tests {
 
         let plan = plan_merge(&diff(vec![target]), &diff(vec![source])).expect("merge should plan");
 
-        assert!(plan.patches.is_empty());
+        assert!(plan.picks.is_empty());
         assert_eq!(conflict_ids(&plan), vec!["entity-a"]);
     }
 
@@ -378,7 +367,7 @@ mod tests {
     }
 
     #[test]
-    fn patch_and_conflict_order_is_deterministic_by_identity() {
+    fn pick_and_conflict_order_is_deterministic_by_identity() {
         let target = diff(vec![entry(
             "entity-b",
             TrackedStateDiffKind::Modified,
@@ -408,7 +397,7 @@ mod tests {
 
         let plan = plan_merge(&target, &source).expect("merge should plan");
 
-        assert_eq!(patch_ids(&plan), vec!["entity-a", "entity-c"]);
+        assert_eq!(pick_ids(&plan), vec!["entity-a", "entity-c"]);
         assert_eq!(conflict_ids(&plan), vec!["entity-b"]);
     }
 
@@ -417,15 +406,15 @@ mod tests {
     }
 
     fn entry(
-        entity_id: &str,
+        entity_pk: &str,
         kind: TrackedStateDiffKind,
-        before: Option<MaterializedTrackedStateRow>,
-        after: Option<MaterializedTrackedStateRow>,
+        before: Option<TrackedStateDiffRow>,
+        after: Option<TrackedStateDiffRow>,
     ) -> TrackedStateDiffEntry {
         TrackedStateDiffEntry {
             identity: TrackedStateDiffIdentity {
                 schema_key: "test_schema".to_string(),
-                entity_id: EntityIdentity::single(entity_id),
+                entity_pk: EntityPk::single(entity_pk),
                 file_id: None,
             },
             kind,
@@ -434,13 +423,13 @@ mod tests {
         }
     }
 
-    fn patch_ids(plan: &TrackedStateMergePlan) -> Vec<String> {
-        plan.patches
+    fn pick_ids(plan: &TrackedStateMergePlan) -> Vec<String> {
+        plan.picks
             .iter()
             .map(|entry| {
                 entry
                     .identity()
-                    .entity_id
+                    .entity_pk
                     .as_single_string_owned()
                     .expect("identity")
             })
@@ -453,36 +442,33 @@ mod tests {
             .map(|entry| {
                 entry
                     .identity
-                    .entity_id
+                    .entity_pk
                     .as_single_string_owned()
                     .expect("identity")
             })
             .collect()
     }
 
-    fn tombstone(entity_id: &str, change_id: &str) -> MaterializedTrackedStateRow {
-        let mut row = row(entity_id, change_id);
-        row.snapshot_content = None;
+    fn tombstone(entity_pk: &str, change_id: &str) -> TrackedStateDiffRow {
+        let mut row = row(entity_pk, change_id);
+        row.snapshot_ref = None;
         row.deleted = true;
         row
     }
 
-    fn row(entity_id: &str, change_id: &str) -> MaterializedTrackedStateRow {
-        row_with_value(entity_id, change_id, "value")
+    fn row(entity_pk: &str, change_id: &str) -> TrackedStateDiffRow {
+        row_with_value(entity_pk, change_id, "value")
     }
 
-    fn row_with_value(
-        entity_id: &str,
-        change_id: &str,
-        value: &str,
-    ) -> MaterializedTrackedStateRow {
-        MaterializedTrackedStateRow {
-            entity_id: EntityIdentity::single(entity_id),
+    fn row_with_value(entity_pk: &str, change_id: &str, value: &str) -> TrackedStateDiffRow {
+        let snapshot = format!("{{\"value\":\"{value}\"}}");
+        TrackedStateDiffRow {
+            entity_pk: EntityPk::single(entity_pk),
             schema_key: "test_schema".to_string(),
             file_id: None,
-            snapshot_content: Some(format!("{{\"value\":\"{value}\"}}")),
-            metadata: None,
             deleted: false,
+            snapshot_ref: Some(JsonRef::for_content(snapshot.as_bytes())),
+            metadata_ref: None,
             created_at: "2026-01-01T00:00:00Z".to_string(),
             updated_at: "2026-01-01T00:00:00Z".to_string(),
             change_id: change_id.to_string(),

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

@@ -1,32 +1,35 @@
-mod by_file_index;
+#[cfg(feature = "storage-benches")]
+mod bench_support;
 mod codec;
+mod commit_root_rebuild;
 mod context;
 mod diff;
-mod materialization;
-mod materializer;
 mod merge;
+mod row_materialization;
 mod storage;
 mod tree;
 mod types;
 
-#[allow(unused_imports)]
-pub(crate) use context::{
-    TrackedStateContext, TrackedStateMaterializer, TrackedStateStoreReader, TrackedStateWriter,
-};
-#[allow(unused_imports)]
+pub(crate) use context::{TrackedStateContext, TrackedStateStoreReader};
 pub(crate) use diff::{
     TrackedStateDiff, TrackedStateDiffEntry, TrackedStateDiffIdentity, TrackedStateDiffKind,
-    TrackedStateDiffRequest,
+    TrackedStateDiffRequest, TrackedStateDiffRow,
 };
-pub(crate) use materialization::{materialize_index_entries, TrackedMaterializationProjection};
-#[allow(unused_imports)]
 pub(crate) use merge::{
-    plan_merge, TrackedStateMergeConflict, TrackedStateMergePatch, TrackedStateMergePlan,
+    plan_merge, TrackedStateMergeConflict, TrackedStateMergePick, TrackedStateMergePlan,
+};
+pub(crate) use row_materialization::{
+    materialize_rows_from_index_entries, TrackedRowMaterialization,
 };
-pub(crate) use storage::{load_delta_pack, DeltaJsonPackIndexesRef};
-#[allow(unused_imports)]
+#[cfg(feature = "storage-benches")]
+pub(crate) use storage::{TRACKED_STATE_COMMIT_ROOT_SPACE, TRACKED_STATE_TREE_CHUNK_SPACE};
+#[cfg(any(test, feature = "storage-benches"))]
+pub(crate) use types::TrackedStateKey;
 pub(crate) use types::{
-    MaterializedTrackedStateRow, TrackedStateDeltaRef, TrackedStateFilter,
-    TrackedStateIndexValueRef, TrackedStateKeyRef, TrackedStateProjection, TrackedStateRowRequest,
+    MaterializedTrackedStateRow, TrackedStateDeltaRef, TrackedStateFilter, TrackedStateReadColumns,
     TrackedStateScanRequest,
 };
+#[cfg(feature = "storage-benches")]
+pub mod bench {
+    pub use super::bench_support::*;
+}