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

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

@@ -0,0 +1,494 @@
+use crate::entity_identity::EntityIdentity;
+use crate::tracked_state::tree_types::TrackedStateTreeScanRequest;
+use crate::tracked_state::{TrackedStateFilter, TrackedStateRow, TrackedStateStoreReader};
+use crate::LixError;
+
+/// Filter for comparing two tracked-state commit roots.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub(crate) struct TrackedStateDiffRequest {
+    pub(crate) filter: TrackedStateFilter,
+}
+
+/// Changed tracked-state rows between two commit roots.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub(crate) struct TrackedStateDiff {
+    pub(crate) entries: Vec<TrackedStateDiffEntry>,
+}
+
+/// One changed identity between two commit roots.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct TrackedStateDiffEntry {
+    pub(crate) identity: TrackedStateDiffIdentity,
+    pub(crate) kind: TrackedStateDiffKind,
+    /// Raw row in the left root.
+    ///
+    /// This can be a tombstone. Callers that need user-visible semantics
+    /// should use `visible_before()` instead of inspecting this directly.
+    pub(crate) before: Option<TrackedStateRow>,
+    /// Raw row in the right root.
+    ///
+    /// This can be a tombstone. Keeping the raw tombstone is what lets merge
+    /// apply deletes without reloading the source root.
+    pub(crate) after: Option<TrackedStateRow>,
+}
+
+/// Root-local tracked-state identity.
+///
+/// Entity identity used by merge/diff logic.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub(crate) struct TrackedStateDiffIdentity {
+    pub(crate) schema_key: String,
+    pub(crate) entity_id: EntityIdentity,
+    pub(crate) file_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum TrackedStateDiffKind {
+    Added,
+    Modified,
+    Removed,
+}
+
+/// Diffs two tracked-state commit roots.
+///
+pub(crate) async fn diff_commits<S>(
+    reader: &mut TrackedStateStoreReader<S>,
+    left_commit_id: &str,
+    right_commit_id: &str,
+    request: &TrackedStateDiffRequest,
+) -> Result<TrackedStateDiff, LixError>
+where
+    S: crate::storage::StorageReader,
+{
+    let scan_request = scan_request_for_diff(request);
+    let mut entries = Vec::new();
+    for tree_entry in reader
+        .diff_tree_entries_at_commits(left_commit_id, right_commit_id, &scan_request)
+        .await?
+    {
+        let before = match tree_entry.before {
+            Some((key, value)) => Some(reader.materialize_tree_value(key, value).await?),
+            None => None,
+        };
+        let after = match tree_entry.after {
+            Some((key, value)) => Some(reader.materialize_tree_value(key, value).await?),
+            None => None,
+        };
+        let identity = match before.as_ref().or(after.as_ref()) {
+            Some(row) => TrackedStateDiffIdentity::from_row(row)?,
+            None => continue,
+        };
+        let Some(entry) = classify_diff(identity, before, after) else {
+            continue;
+        };
+        entries.push(entry);
+    }
+
+    Ok(TrackedStateDiff { entries })
+}
+
+fn scan_request_for_diff(request: &TrackedStateDiffRequest) -> TrackedStateTreeScanRequest {
+    let mut filter = request.filter.clone();
+    filter.include_tombstones = true;
+    TrackedStateTreeScanRequest {
+        schema_keys: filter.schema_keys,
+        entity_ids: filter.entity_ids,
+        file_ids: filter.file_ids,
+        include_tombstones: filter.include_tombstones,
+        limit: None,
+    }
+}
+
+fn classify_diff(
+    identity: TrackedStateDiffIdentity,
+    before: Option<TrackedStateRow>,
+    after: Option<TrackedStateRow>,
+) -> Option<TrackedStateDiffEntry> {
+    match (is_live_row(before.as_ref()), is_live_row(after.as_ref())) {
+        (None, None) => None,
+        (None, Some(_)) => Some(TrackedStateDiffEntry {
+            identity,
+            kind: TrackedStateDiffKind::Added,
+            before,
+            after,
+        }),
+        (Some(_), None) => Some(TrackedStateDiffEntry {
+            identity,
+            kind: TrackedStateDiffKind::Removed,
+            before,
+            after,
+        }),
+        (Some(before), Some(after)) if tracked_row_payload_eq(before, after) => None,
+        (Some(_), Some(_)) => Some(TrackedStateDiffEntry {
+            identity,
+            kind: TrackedStateDiffKind::Modified,
+            before,
+            after,
+        }),
+    }
+}
+
+fn is_live_row(row: Option<&TrackedStateRow>) -> Option<&TrackedStateRow> {
+    row.filter(|row| row.snapshot_content.is_some())
+}
+
+fn tracked_row_payload_eq(left: &TrackedStateRow, right: &TrackedStateRow) -> bool {
+    left.snapshot_content == right.snapshot_content
+        && left.metadata == right.metadata
+        && left.schema_version == right.schema_version
+}
+
+impl TrackedStateDiffIdentity {
+    fn from_row(row: &TrackedStateRow) -> Result<Self, LixError> {
+        Ok(Self {
+            schema_key: row.schema_key.clone(),
+            entity_id: row.entity_id.clone(),
+            file_id: row.file_id.clone(),
+        })
+    }
+}
+
+impl TrackedStateDiffEntry {
+    #[cfg(test)]
+    pub(crate) fn before_is_live(&self) -> bool {
+        self.visible_before().is_some()
+    }
+
+    #[cfg(test)]
+    pub(crate) fn after_is_live(&self) -> bool {
+        self.visible_after().is_some()
+    }
+
+    #[cfg(test)]
+    pub(crate) fn visible_before(&self) -> Option<&TrackedStateRow> {
+        self.before
+            .as_ref()
+            .filter(|row| row.snapshot_content.is_some())
+    }
+
+    #[cfg(test)]
+    pub(crate) fn visible_after(&self) -> Option<&TrackedStateRow> {
+        self.after
+            .as_ref()
+            .filter(|row| row.snapshot_content.is_some())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use super::*;
+    use crate::backend::testing::UnitTestBackend;
+    use crate::json_store::JsonStoreContext;
+    use crate::storage::{StorageContext, StorageWriteSet, StorageWriteTransaction};
+    use crate::tracked_state::TrackedStateContext;
+    use crate::NullableKeyFilter;
+
+    #[tokio::test]
+    async fn diff_commits_reports_added_rows() {
+        let (storage, tracked_state) = seed_roots(&[], &[row("entity-a", None, "after")]).await;
+
+        let diff = diff(storage.clone(), &tracked_state).await;
+
+        assert_eq!(
+            kinds(&diff),
+            vec![("entity-a".to_string(), TrackedStateDiffKind::Added)]
+        );
+        assert!(diff.entries[0].before.is_none());
+        assert_eq!(
+            diff.entries[0]
+                .after
+                .as_ref()
+                .map(|row| row.change_id.as_str()),
+            Some("after")
+        );
+        assert!(!diff.entries[0].before_is_live());
+        assert!(diff.entries[0].after_is_live());
+    }
+
+    #[tokio::test]
+    async fn diff_commits_reports_removed_rows_when_right_side_is_absent() {
+        let (storage, tracked_state) = seed_roots(&[row("entity-a", None, "before")], &[]).await;
+
+        let diff = diff(storage.clone(), &tracked_state).await;
+
+        assert_eq!(
+            kinds(&diff),
+            vec![("entity-a".to_string(), TrackedStateDiffKind::Removed)]
+        );
+        assert_eq!(
+            diff.entries[0]
+                .before
+                .as_ref()
+                .map(|row| row.change_id.as_str()),
+            Some("before")
+        );
+        assert!(diff.entries[0].after.is_none());
+        assert!(diff.entries[0].before_is_live());
+        assert!(!diff.entries[0].after_is_live());
+    }
+
+    #[tokio::test]
+    async fn diff_commits_reports_removed_rows_when_right_side_is_tombstone() {
+        let (storage, tracked_state) = seed_roots(
+            &[row("entity-a", None, "before")],
+            &[tombstone("entity-a", None, "delete")],
+        )
+        .await;
+
+        let diff = diff(storage.clone(), &tracked_state).await;
+
+        assert_eq!(
+            kinds(&diff),
+            vec![("entity-a".to_string(), TrackedStateDiffKind::Removed)]
+        );
+        let entry = &diff.entries[0];
+        assert_eq!(
+            entry.after.as_ref().map(|row| row.change_id.as_str()),
+            Some("delete")
+        );
+        assert!(
+            entry
+                .after
+                .as_ref()
+                .is_some_and(|row| row.snapshot_content.is_none()),
+            "removed diff should preserve the right-side tombstone for merge"
+        );
+        assert!(entry.before_is_live());
+        assert!(!entry.after_is_live());
+    }
+
+    #[tokio::test]
+    async fn diff_commits_reports_added_rows_when_left_side_is_tombstone() {
+        let (storage, tracked_state) = seed_roots(
+            &[tombstone("entity-a", None, "delete")],
+            &[row("entity-a", None, "after")],
+        )
+        .await;
+
+        let diff = diff(storage.clone(), &tracked_state).await;
+
+        assert_eq!(
+            kinds(&diff),
+            vec![("entity-a".to_string(), TrackedStateDiffKind::Added)]
+        );
+        let entry = &diff.entries[0];
+        assert_eq!(
+            entry.before.as_ref().map(|row| row.change_id.as_str()),
+            Some("delete")
+        );
+        assert!(
+            entry
+                .before
+                .as_ref()
+                .is_some_and(|row| row.snapshot_content.is_none()),
+            "added diff should preserve the left-side tombstone for merge"
+        );
+        assert!(!entry.before_is_live());
+        assert!(entry.after_is_live());
+    }
+
+    #[tokio::test]
+    async fn diff_commits_reports_modified_rows_for_changed_payload() {
+        let (storage, tracked_state) = seed_roots(
+            &[row_with_value("entity-a", None, "before", "one")],
+            &[row_with_value("entity-a", None, "after", "two")],
+        )
+        .await;
+
+        let diff = diff(storage.clone(), &tracked_state).await;
+
+        assert_eq!(
+            kinds(&diff),
+            vec![("entity-a".to_string(), TrackedStateDiffKind::Modified)]
+        );
+        assert!(diff.entries[0].before_is_live());
+        assert!(diff.entries[0].after_is_live());
+    }
+
+    #[tokio::test]
+    async fn diff_commits_omits_unchanged_rows_even_when_metadata_differs_only_by_commit() {
+        let (storage, tracked_state) = seed_roots(
+            &[row_with_value("entity-a", None, "before", "same")],
+            &[row_with_value("entity-a", None, "after", "same")],
+        )
+        .await;
+
+        let diff = diff(storage.clone(), &tracked_state).await;
+
+        assert!(diff.entries.is_empty());
+    }
+
+    #[tokio::test]
+    async fn diff_commits_distinguishes_same_entity_with_different_file_id() {
+        let (storage, tracked_state) = seed_roots(
+            &[row("entity-a", Some("file-a"), "before-a")],
+            &[
+                row("entity-a", Some("file-a"), "before-a"),
+                row("entity-a", Some("file-b"), "after-b"),
+            ],
+        )
+        .await;
+
+        let diff = diff(storage.clone(), &tracked_state).await;
+
+        assert_eq!(diff.entries.len(), 1);
+        assert_eq!(diff.entries[0].identity.file_id.as_deref(), Some("file-b"));
+        assert_eq!(diff.entries[0].kind, TrackedStateDiffKind::Added);
+    }
+
+    #[tokio::test]
+    async fn diff_commits_filters_by_schema_entity_and_file_id() {
+        let (storage, tracked_state) = seed_roots(
+            &[],
+            &[
+                row_with_schema("entity-a", Some("file-a"), "schema-a", "change-a"),
+                row_with_schema("entity-b", Some("file-b"), "schema-b", "change-b"),
+            ],
+        )
+        .await;
+        let mut reader = tracked_state.reader(storage.clone());
+        let diff = reader
+            .diff_commits(
+                "left",
+                "right",
+                &TrackedStateDiffRequest {
+                    filter: TrackedStateFilter {
+                        schema_keys: vec!["schema-b".to_string()],
+                        entity_ids: vec![crate::entity_identity::EntityIdentity::single(
+                            "entity-b",
+                        )],
+                        file_ids: vec![NullableKeyFilter::Value("file-b".to_string())],
+                        ..Default::default()
+                    },
+                },
+            )
+            .await
+            .expect("diff should load");
+
+        assert_eq!(
+            kinds(&diff),
+            vec![("entity-b".to_string(), TrackedStateDiffKind::Added)]
+        );
+    }
+
+    async fn diff(
+        storage: StorageContext,
+        tracked_state: &TrackedStateContext,
+    ) -> TrackedStateDiff {
+        tracked_state
+            .reader(storage)
+            .diff_commits("left", "right", &TrackedStateDiffRequest::default())
+            .await
+            .expect("diff should load")
+    }
+
+    async fn seed_roots(
+        left_rows: &[TrackedStateRow],
+        right_rows: &[TrackedStateRow],
+    ) -> (StorageContext, TrackedStateContext) {
+        let backend = Arc::new(UnitTestBackend::new());
+        let storage = StorageContext::new(backend.clone());
+        let tracked_state = TrackedStateContext::new();
+        let mut tx = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+        write_root_for_test(tx.as_mut(), &tracked_state, "left", None, left_rows)
+            .await
+            .expect("left root should write");
+        write_root_for_test(tx.as_mut(), &tracked_state, "right", None, right_rows)
+            .await
+            .expect("right root should write");
+        tx.commit().await.expect("transaction should commit");
+        (storage, tracked_state)
+    }
+
+    async fn write_root_for_test(
+        tx: &mut dyn StorageWriteTransaction,
+        tracked_state: &TrackedStateContext,
+        commit_id: &str,
+        parent_commit_id: Option<&str>,
+        rows: &[TrackedStateRow],
+    ) -> Result<(), LixError> {
+        let mut writes = StorageWriteSet::new();
+        {
+            let mut json_writer = JsonStoreContext::new().writer();
+            tracked_state
+                .writer()
+                .stage_root(
+                    tx,
+                    &mut writes,
+                    &mut json_writer,
+                    commit_id,
+                    parent_commit_id,
+                    rows,
+                )
+                .await?;
+        }
+        writes.apply(tx).await?;
+        Ok(())
+    }
+
+    fn kinds(diff: &TrackedStateDiff) -> Vec<(String, TrackedStateDiffKind)> {
+        diff.entries
+            .iter()
+            .map(|entry| {
+                (
+                    entry.identity.entity_id.as_string().expect("identity"),
+                    entry.kind,
+                )
+            })
+            .collect()
+    }
+
+    fn tombstone(entity_id: &str, file_id: Option<&str>, change_id: &str) -> TrackedStateRow {
+        let mut row = row(entity_id, file_id, change_id);
+        row.snapshot_content = None;
+        row
+    }
+
+    fn row(entity_id: &str, file_id: Option<&str>, change_id: &str) -> TrackedStateRow {
+        row_with_schema(entity_id, file_id, "test_schema", change_id)
+    }
+
+    fn row_with_schema(
+        entity_id: &str,
+        file_id: Option<&str>,
+        schema_key: &str,
+        change_id: &str,
+    ) -> TrackedStateRow {
+        row_with_schema_and_value(entity_id, file_id, schema_key, change_id, "value")
+    }
+
+    fn row_with_value(
+        entity_id: &str,
+        file_id: Option<&str>,
+        change_id: &str,
+        value: &str,
+    ) -> TrackedStateRow {
+        row_with_schema_and_value(entity_id, file_id, "test_schema", change_id, value)
+    }
+
+    fn row_with_schema_and_value(
+        entity_id: &str,
+        file_id: Option<&str>,
+        schema_key: &str,
+        change_id: &str,
+        value: &str,
+    ) -> TrackedStateRow {
+        TrackedStateRow {
+            entity_id: EntityIdentity::single(entity_id),
+            schema_key: schema_key.to_string(),
+            file_id: file_id.map(str::to_string),
+            snapshot_content: Some(format!("{{\"value\":\"{value}\"}}")),
+            metadata: None,
+            schema_version: "1".to_string(),
+            created_at: "2026-01-01T00:00:00Z".to_string(),
+            updated_at: "2026-01-01T00:00:00Z".to_string(),
+            change_id: change_id.to_string(),
+            commit_id: change_id.replace("change", "commit"),
+        }
+    }
+}

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

@@ -0,0 +1,141 @@
+use crate::json_store::{JsonRef, JsonStoreReader, JsonStoreWriter};
+use crate::storage::{StorageReader, StorageWriteSet};
+use crate::tracked_state::tree_types::{TrackedStateKey, TrackedStateValue};
+use crate::tracked_state::TrackedStateRow;
+use crate::{serialize_row_metadata, validate_row_metadata, LixError, RowMetadata};
+
+pub(crate) fn canonicalize_materialized_row(
+    writes: &mut StorageWriteSet,
+    json_writer: &mut JsonStoreWriter,
+    row: &TrackedStateRow,
+) -> Result<TrackedStateValue, LixError> {
+    let snapshot_ref = stage_optional_json(writes, json_writer, row.snapshot_content.as_deref())?;
+    let metadata_ref = stage_optional_metadata(writes, json_writer, row.metadata.as_ref())?;
+    Ok(TrackedStateValue::from_row_refs(
+        row,
+        snapshot_ref,
+        metadata_ref,
+    ))
+}
+
+pub(crate) async fn materialize_value<S>(
+    json_reader: &mut JsonStoreReader<S>,
+    key: TrackedStateKey,
+    value: TrackedStateValue,
+    projection: &TrackedMaterializationProjection,
+) -> Result<TrackedStateRow, LixError>
+where
+    S: StorageReader,
+{
+    let snapshot_content = if projection.snapshot_content {
+        load_optional_json(json_reader, value.snapshot_ref.as_ref(), "snapshot_ref").await?
+    } else {
+        None
+    };
+    let metadata = if projection.metadata {
+        load_optional_metadata(json_reader, value.metadata_ref.as_ref()).await?
+    } else {
+        None
+    };
+    Ok(value.into_materialized_row(key, snapshot_content, metadata))
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct TrackedMaterializationProjection {
+    pub(crate) snapshot_content: bool,
+    pub(crate) metadata: bool,
+}
+
+impl TrackedMaterializationProjection {
+    pub(crate) fn full() -> Self {
+        Self {
+            snapshot_content: true,
+            metadata: true,
+        }
+    }
+
+    pub(crate) fn from_columns(columns: &[String]) -> Self {
+        if columns.is_empty() {
+            return Self::full();
+        }
+        Self {
+            snapshot_content: columns.iter().any(|column| column == "snapshot_content"),
+            metadata: columns.iter().any(|column| column == "metadata"),
+        }
+    }
+}
+
+fn stage_optional_json(
+    writes: &mut StorageWriteSet,
+    json_writer: &mut JsonStoreWriter,
+    value: Option<&str>,
+) -> Result<Option<JsonRef>, LixError> {
+    let Some(value) = value else {
+        return Ok(None);
+    };
+    json_writer.stage_bytes(writes, value.as_bytes()).map(Some)
+}
+
+fn stage_optional_metadata(
+    writes: &mut StorageWriteSet,
+    json_writer: &mut JsonStoreWriter,
+    value: Option<&RowMetadata>,
+) -> Result<Option<JsonRef>, LixError> {
+    let Some(value) = value else {
+        return Ok(None);
+    };
+    let serialized = serialize_row_metadata(value);
+    json_writer
+        .stage_bytes(writes, serialized.as_bytes())
+        .map(Some)
+}
+
+async fn load_optional_metadata<S>(
+    json_reader: &mut JsonStoreReader<S>,
+    json_ref: Option<&JsonRef>,
+) -> Result<Option<RowMetadata>, LixError>
+where
+    S: StorageReader,
+{
+    let Some(json) = load_optional_json(json_reader, json_ref, "metadata_ref").await? else {
+        return Ok(None);
+    };
+    let metadata = serde_json::from_str::<RowMetadata>(&json).map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_INVALID_JSON",
+            format!("tracked_state metadata_ref is invalid JSON: {error}"),
+        )
+    })?;
+    validate_row_metadata(metadata, "tracked_state metadata_ref").map(Some)
+}
+
+async fn load_optional_json<S>(
+    json_reader: &mut JsonStoreReader<S>,
+    json_ref: Option<&JsonRef>,
+    field: &str,
+) -> Result<Option<String>, LixError>
+where
+    S: StorageReader,
+{
+    let Some(json_ref) = json_ref else {
+        return Ok(None);
+    };
+    let bytes = json_reader.load_bytes(json_ref).await?.ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!(
+                "tracked_state {field} '{}' is missing from json_store",
+                json_ref.to_hex()
+            ),
+        )
+    })?;
+    String::from_utf8(bytes).map(Some).map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!(
+                "tracked_state {field} '{}' is not valid UTF-8 JSON bytes: {error}",
+                json_ref.to_hex()
+            ),
+        )
+    })
+}