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

package/dist-engine-src/src/live_state/visibility.rs

@@ -1,122 +1,271 @@
 use std::collections::BTreeMap;
 
-use crate::live_state::{LiveStateRowIdentity, MaterializedLiveStateRow};
-use crate::GLOBAL_VERSION_ID;
+use crate::live_state::{
+    LiveStateReader, LiveStateRowIdentity, LiveStateScanRequest, MaterializedLiveStateRow,
+};
+use crate::LixError;
+use crate::GLOBAL_BRANCH_ID;
 
-/// Expands a version-scoped storage read so global candidates are available for
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) struct VisibilityRequest {
+    pub(crate) branch_scope: VisibilityBranchScope,
+    pub(crate) include_tombstones: bool,
+    pub(crate) limit: Option<usize>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) enum VisibilityBranchScope {
+    BranchIds { branch_ids: Vec<String> },
+}
+
+pub(crate) trait StagedLiveStateRows {
+    fn staged_rows(
+        &self,
+        request: &LiveStateScanRequest,
+    ) -> Result<Vec<MaterializedLiveStateRow>, LixError>;
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+enum OverlayTier {
+    BaseGlobal,
+    StagedGlobal,
+    BaseBranch,
+    StagedBranch,
+}
+
+/// Expands a branch-scoped storage read so global candidates are available for
 /// the visibility overlay.
-pub(crate) fn expanded_version_ids(version_ids: &[String]) -> Vec<String> {
-    if version_ids.is_empty() {
+pub(crate) fn expanded_branch_ids(branch_ids: &[String]) -> Vec<String> {
+    if branch_ids.is_empty() {
         return Vec::new();
     }
 
-    let mut expanded = version_ids.to_vec();
-    if version_ids
+    let mut expanded = branch_ids.to_vec();
+    if branch_ids
         .iter()
-        .any(|version_id| version_id != GLOBAL_VERSION_ID)
+        .any(|branch_id| branch_id != GLOBAL_BRANCH_ID)
         && !expanded
             .iter()
-            .any(|version_id| version_id == GLOBAL_VERSION_ID)
+            .any(|branch_id| branch_id == GLOBAL_BRANCH_ID)
     {
-        expanded.push(GLOBAL_VERSION_ID.to_string());
+        expanded.push(GLOBAL_BRANCH_ID.to_string());
     }
     expanded
 }
 
+pub(crate) fn resolve_visible_rows(
+    base_rows: Vec<MaterializedLiveStateRow>,
+    staged_rows: Vec<MaterializedLiveStateRow>,
+    request: &VisibilityRequest,
+) -> Vec<MaterializedLiveStateRow> {
+    let requested_branch_ids = requested_branch_ids(&request.branch_scope);
+    resolve_live_state_rows(
+        base_rows,
+        staged_rows,
+        &requested_branch_ids,
+        request.include_tombstones,
+        request.limit,
+    )
+}
+
+pub(crate) async fn overlay_scan_rows<S>(
+    base: &dyn LiveStateReader,
+    staged: &S,
+    request: &LiveStateScanRequest,
+) -> Result<Vec<MaterializedLiveStateRow>, LixError>
+where
+    S: StagedLiveStateRows + ?Sized,
+{
+    let mut candidate_request = request.clone();
+    candidate_request.limit = None;
+    candidate_request.filter.include_tombstones = true;
+    candidate_request.filter.branch_ids = expanded_branch_ids(&request.filter.branch_ids);
+    let staged_rows = staged.staged_rows(&candidate_request)?;
+    let rows = base.scan_rows(&candidate_request).await?;
+    Ok(resolve_visible_rows(
+        rows,
+        staged_rows,
+        &VisibilityRequest {
+            branch_scope: VisibilityBranchScope::BranchIds {
+                branch_ids: request.filter.branch_ids.clone(),
+            },
+            include_tombstones: request.filter.include_tombstones,
+            limit: request.limit,
+        },
+    ))
+}
+
 /// Resolves raw tracked/untracked candidates into the rows visible for a scan.
 ///
-/// Global rows are projected into each requested version scope, but keep
-/// `global = true`. Version-scoped rows win over projected global rows for the
+/// Global rows are projected into each requested branch scope, but keep
+/// `global = true`. Branch-scoped rows win over projected global rows for the
 /// same identity. Tombstones participate in winning and are filtered only after
 /// visibility is resolved. This projection is a read concern; constraint
 /// validation remains exact storage-scope local unless a validator explicitly
 /// opts into overlay semantics.
-pub(crate) fn resolve_scan_rows(
+fn resolve_scan_rows(
     rows: Vec<MaterializedLiveStateRow>,
-    requested_version_ids: &[String],
+    requested_branch_ids: &[String],
+    include_tombstones: bool,
+) -> Vec<MaterializedLiveStateRow> {
+    let mut rows = project_global_rows_into_requested_branches(rows, requested_branch_ids);
+    if !include_tombstones {
+        rows.retain(|row| !row.deleted);
+    }
+    rows
+}
+
+fn resolve_live_state_rows(
+    base_rows: Vec<MaterializedLiveStateRow>,
+    staged_rows: Vec<MaterializedLiveStateRow>,
+    requested_branch_ids: &[String],
     include_tombstones: bool,
+    limit: Option<usize>,
 ) -> Vec<MaterializedLiveStateRow> {
-    let mut rows = project_global_rows_into_requested_versions(rows, requested_version_ids);
+    let base_rows = resolve_scan_rows(base_rows, requested_branch_ids, true);
+    let staged_rows = resolve_scan_rows(staged_rows, requested_branch_ids, true);
+    let mut rows_by_identity =
+        BTreeMap::<LiveStateRowIdentity, (OverlayTier, MaterializedLiveStateRow)>::new();
+
+    for row in base_rows {
+        let tier = if row.global {
+            OverlayTier::BaseGlobal
+        } else {
+            OverlayTier::BaseBranch
+        };
+        insert_overlay_row(&mut rows_by_identity, tier, row);
+    }
+    for row in staged_rows {
+        let tier = if row.global {
+            OverlayTier::StagedGlobal
+        } else {
+            OverlayTier::StagedBranch
+        };
+        insert_overlay_row(&mut rows_by_identity, tier, row);
+    }
+
+    let mut rows = rows_by_identity
+        .into_values()
+        .map(|(_, row)| row)
+        .collect::<Vec<_>>();
     if !include_tombstones {
         rows.retain(|row| !row.deleted);
     }
+    if let Some(limit) = limit {
+        rows.truncate(limit);
+    }
     rows
 }
 
-/// Resolves a row loaded through a concrete storage version into the row visible
-/// to the requested version scope.
-pub(crate) fn project_loaded_row(
-    mut row: MaterializedLiveStateRow,
-    requested_version_id: &str,
-    matched_version_id: &str,
-) -> MaterializedLiveStateRow {
-    if row.global && requested_version_id != GLOBAL_VERSION_ID {
-        row.version_id = requested_version_id.to_string();
-    } else if matched_version_id == GLOBAL_VERSION_ID && requested_version_id != GLOBAL_VERSION_ID {
-        row.version_id = requested_version_id.to_string();
-    }
-    row
+fn requested_branch_ids(branch_scope: &VisibilityBranchScope) -> Vec<String> {
+    match branch_scope {
+        VisibilityBranchScope::BranchIds { branch_ids } => branch_ids.clone(),
+    }
 }
 
-fn project_global_rows_into_requested_versions(
+fn project_global_rows_into_requested_branches(
     rows: Vec<MaterializedLiveStateRow>,
-    requested_version_ids: &[String],
+    requested_branch_ids: &[String],
 ) -> Vec<MaterializedLiveStateRow> {
-    if requested_version_ids.is_empty() {
-        return rows;
+    if requested_branch_ids.is_empty() {
+        return dedupe_rows(rows);
     }
 
     let mut rows_by_identity = BTreeMap::<LiveStateRowIdentity, MaterializedLiveStateRow>::new();
-    for requested_version_id in requested_version_ids {
+    for requested_branch_id in requested_branch_ids {
         for row in &rows {
-            if row.version_id == GLOBAL_VERSION_ID {
+            if row.branch_id == GLOBAL_BRANCH_ID {
                 let mut projected = row.clone();
-                projected.version_id = requested_version_id.clone();
-                rows_by_identity.insert(LiveStateRowIdentity::from_row(&projected), projected);
+                projected.branch_id = requested_branch_id.clone();
+                insert_row_preferring_untracked(&mut rows_by_identity, projected);
             }
         }
+        let mut branch_rows_by_identity =
+            BTreeMap::<LiveStateRowIdentity, MaterializedLiveStateRow>::new();
         for row in rows
             .iter()
-            .filter(|row| row.version_id == *requested_version_id)
+            .filter(|row| row.branch_id == *requested_branch_id)
         {
-            rows_by_identity.insert(LiveStateRowIdentity::from_row(row), row.clone());
+            insert_row_preferring_untracked(&mut branch_rows_by_identity, row.clone());
         }
+        rows_by_identity.extend(branch_rows_by_identity);
     }
 
     rows_by_identity.into_values().collect()
 }
 
+fn dedupe_rows(rows: Vec<MaterializedLiveStateRow>) -> Vec<MaterializedLiveStateRow> {
+    let mut rows_by_identity = BTreeMap::<LiveStateRowIdentity, MaterializedLiveStateRow>::new();
+    for row in rows {
+        insert_row_preferring_untracked(&mut rows_by_identity, row);
+    }
+    rows_by_identity.into_values().collect()
+}
+
+fn insert_overlay_row(
+    rows_by_identity: &mut BTreeMap<LiveStateRowIdentity, (OverlayTier, MaterializedLiveStateRow)>,
+    tier: OverlayTier,
+    row: MaterializedLiveStateRow,
+) {
+    let identity = LiveStateRowIdentity::from_row(&row);
+    match rows_by_identity.get(&identity) {
+        Some((existing_tier, _)) if *existing_tier > tier => {}
+        Some((existing_tier, existing))
+            if *existing_tier == tier && existing.untracked && !row.untracked => {}
+        _ => {
+            rows_by_identity.insert(identity, (tier, row));
+        }
+    }
+}
+
+fn insert_row_preferring_untracked(
+    rows_by_identity: &mut BTreeMap<LiveStateRowIdentity, MaterializedLiveStateRow>,
+    row: MaterializedLiveStateRow,
+) {
+    let identity = LiveStateRowIdentity::from_row(&row);
+    match rows_by_identity.get(&identity) {
+        Some(existing) if existing.untracked && !row.untracked => {}
+        _ => {
+            rows_by_identity.insert(identity, row);
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::entity_pk::EntityPk;
+    use crate::live_state::LiveStateRowRequest;
+    use async_trait::async_trait;
 
     #[test]
-    fn expands_requested_version_with_global_candidates() {
+    fn expands_requested_branch_with_global_candidates() {
         assert_eq!(
-            expanded_version_ids(&["version-a".to_string()]),
-            vec!["version-a".to_string(), "global".to_string()]
+            expanded_branch_ids(&["branch-a".to_string()]),
+            vec!["branch-a".to_string(), "global".to_string()]
         );
         assert_eq!(
-            expanded_version_ids(&["global".to_string()]),
+            expanded_branch_ids(&["global".to_string()]),
             vec!["global".to_string()]
         );
     }
 
     #[test]
-    fn scan_projects_global_row_into_requested_version() {
+    fn committed_scan_projects_global_row_into_requested_branch() {
         let rows = resolve_scan_rows(
             vec![row_at(
                 "global",
+                "entity",
                 "global-value",
                 true,
                 Some("change-global"),
             )],
-            &["version-a".to_string()],
+            &["branch-a".to_string()],
             false,
         );
 
         assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].version_id, "version-a");
+        assert_eq!(rows[0].branch_id, "branch-a");
         assert!(rows[0].global);
         assert_eq!(
             rows[0].snapshot_content.as_deref(),
@@ -125,75 +274,327 @@ mod tests {
     }
 
     #[test]
-    fn scan_prefers_requested_version_row_over_projected_global_row() {
+    fn committed_scan_prefers_requested_branch_row_over_projected_global_row() {
         let rows = resolve_scan_rows(
             vec![
-                row_at("global", "global-value", true, Some("change-global")),
-                row_at("version-a", "version-value", false, Some("change-version")),
+                row_at(
+                    "global",
+                    "entity",
+                    "global-value",
+                    true,
+                    Some("change-global"),
+                ),
+                row_at(
+                    "branch-a",
+                    "entity",
+                    "branch-value",
+                    false,
+                    Some("change-branch"),
+                ),
             ],
-            &["version-a".to_string()],
+            &["branch-a".to_string()],
             false,
         );
 
         assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].version_id, "version-a");
+        assert_eq!(rows[0].branch_id, "branch-a");
         assert!(!rows[0].global);
         assert_eq!(
             rows[0].snapshot_content.as_deref(),
-            Some("{\"value\":\"version-value\"}")
+            Some("{\"value\":\"branch-value\"}")
         );
     }
 
     #[test]
-    fn version_tombstone_hides_global_row_after_visibility_resolution() {
+    fn empty_branch_filter_dedupes_duplicate_base_rows() {
+        let mut tracked = row_at(
+            "branch-a",
+            "entity",
+            "tracked",
+            false,
+            Some("change-tracked"),
+        );
+        tracked.untracked = false;
+        let mut untracked = row_at("branch-a", "entity", "untracked", false, None);
+        untracked.untracked = true;
+
+        let rows = resolve_scan_rows(vec![tracked, untracked], &[], false);
+
+        assert_eq!(rows.len(), 1);
+        assert!(rows[0].untracked);
+        assert_eq!(
+            rows[0].snapshot_content.as_deref(),
+            Some("{\"value\":\"untracked\"}")
+        );
+    }
+
+    #[test]
+    fn empty_branch_filter_dedupes_duplicate_base_and_staged_overlay_identity() {
+        let base = row_at("branch-a", "entity", "base", false, Some("change-base"));
+        let staged = row_at("branch-a", "entity", "staged", false, Some("change-staged"));
+
+        let rows = resolve_live_state_rows(vec![base], vec![staged], &[], false, None);
+
+        assert_eq!(rows.len(), 1);
+        assert_eq!(
+            rows[0].snapshot_content.as_deref(),
+            Some("{\"value\":\"staged\"}")
+        );
+    }
+
+    #[test]
+    fn branch_tombstone_hides_global_row_after_visibility_resolution() {
         let rows = resolve_scan_rows(
             vec![
-                row_at("global", "global-value", true, Some("change-global")),
-                tombstone_at("version-a", false, Some("change-tombstone")),
+                row_at(
+                    "global",
+                    "entity",
+                    "global-value",
+                    true,
+                    Some("change-global"),
+                ),
+                tombstone_at("branch-a", "entity", false, Some("change-tombstone")),
             ],
-            &["version-a".to_string()],
+            &["branch-a".to_string()],
             false,
         );
 
         assert!(rows.is_empty());
     }
 
+    #[test]
+    fn overlay_prefers_staged_untracked_over_staged_tracked_for_same_visible_identity() {
+        let mut tracked = row_at(
+            "branch-a",
+            "entity",
+            "tracked",
+            false,
+            Some("change-tracked"),
+        );
+        tracked.untracked = false;
+        let mut untracked = row_at("branch-a", "entity", "untracked", false, None);
+        untracked.untracked = true;
+
+        let rows = resolve_live_state_rows(
+            Vec::new(),
+            vec![untracked.clone(), tracked.clone()],
+            &["branch-a".to_string()],
+            false,
+            None,
+        );
+
+        assert_eq!(rows.len(), 1);
+        assert!(rows[0].untracked);
+        assert_eq!(
+            rows[0].snapshot_content.as_deref(),
+            Some("{\"value\":\"untracked\"}")
+        );
+
+        let rows = resolve_live_state_rows(
+            Vec::new(),
+            vec![tracked, untracked],
+            &["branch-a".to_string()],
+            false,
+            None,
+        );
+
+        assert_eq!(rows.len(), 1);
+        assert!(rows[0].untracked);
+        assert_eq!(
+            rows[0].snapshot_content.as_deref(),
+            Some("{\"value\":\"untracked\"}")
+        );
+    }
+
+    #[test]
+    fn overlay_prefers_staged_tracked_over_base_untracked_for_same_visible_identity() {
+        let mut base = row_at("branch-a", "entity", "base-untracked", false, None);
+        base.untracked = true;
+        let mut staged = row_at(
+            "branch-a",
+            "entity",
+            "staged-tracked",
+            false,
+            Some("change-staged"),
+        );
+        staged.untracked = false;
+
+        let rows = resolve_live_state_rows(
+            vec![base],
+            vec![staged],
+            &["branch-a".to_string()],
+            false,
+            None,
+        );
+
+        assert_eq!(rows.len(), 1);
+        assert!(!rows[0].untracked);
+        assert_eq!(
+            rows[0].snapshot_content.as_deref(),
+            Some("{\"value\":\"staged-tracked\"}")
+        );
+    }
+
+    #[test]
+    fn staged_global_tombstone_hides_projected_base_global_row() {
+        let mut base = row_at("branch-a", "entity", "base", true, Some("change-base"));
+        base.global = true;
+
+        let rows = resolve_live_state_rows(
+            vec![base],
+            vec![tombstone_at(
+                "global",
+                "entity",
+                true,
+                Some("change-staged"),
+            )],
+            &["branch-a".to_string()],
+            false,
+            None,
+        );
+
+        assert!(rows.is_empty());
+    }
+
+    #[test]
+    fn base_branch_tombstone_hides_staged_global_row() {
+        let base = tombstone_at("branch-a", "entity", false, Some("change-base"));
+        let staged = row_at("global", "entity", "staged", true, Some("change-staged"));
+
+        let rows = resolve_live_state_rows(
+            vec![base],
+            vec![staged],
+            &["branch-a".to_string()],
+            false,
+            None,
+        );
+
+        assert!(rows.is_empty());
+    }
+
+    #[test]
+    fn base_tracked_branch_tombstone_hides_staged_untracked_global_row() {
+        let mut base = tombstone_at("branch-a", "entity", false, Some("change-base"));
+        base.untracked = false;
+        let mut staged = row_at("global", "entity", "staged", true, None);
+        staged.untracked = true;
+
+        let rows = resolve_live_state_rows(
+            vec![base],
+            vec![staged],
+            &["branch-a".to_string()],
+            false,
+            None,
+        );
+
+        assert!(rows.is_empty());
+    }
+
+    #[test]
+    fn staged_branch_row_overrides_base_branch_tombstone() {
+        let base = tombstone_at("branch-a", "entity", false, Some("change-base"));
+        let staged = row_at("branch-a", "entity", "staged", false, Some("change-staged"));
+
+        let rows = resolve_live_state_rows(
+            vec![base],
+            vec![staged],
+            &["branch-a".to_string()],
+            false,
+            None,
+        );
+
+        assert_eq!(rows.len(), 1);
+        assert!(!rows[0].deleted);
+    }
+
     #[test]
     fn tombstone_can_be_returned_when_requested() {
         let rows = resolve_scan_rows(
             vec![
-                row_at("global", "global-value", true, Some("change-global")),
-                tombstone_at("version-a", false, Some("change-tombstone")),
+                row_at(
+                    "global",
+                    "entity",
+                    "global-value",
+                    true,
+                    Some("change-global"),
+                ),
+                tombstone_at("branch-a", "entity", false, Some("change-tombstone")),
             ],
-            &["version-a".to_string()],
+            &["branch-a".to_string()],
             true,
         );
 
         assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].version_id, "version-a");
+        assert_eq!(rows[0].branch_id, "branch-a");
         assert_eq!(rows[0].snapshot_content, None);
     }
 
     #[test]
-    fn loaded_global_row_is_projected_into_requested_version() {
-        let row = project_loaded_row(
-            row_at("global", "global-value", true, Some("change-global")),
-            "version-a",
-            "global",
+    fn resolve_visible_rows_maps_branch_scope_and_applies_limit() {
+        let request = VisibilityRequest {
+            branch_scope: VisibilityBranchScope::BranchIds {
+                branch_ids: vec!["branch-a".to_string()],
+            },
+            include_tombstones: false,
+            limit: Some(1),
+        };
+        let rows = resolve_visible_rows(
+            vec![
+                row_at("branch-a", "a", "A", false, Some("change-a")),
+                row_at("branch-a", "b", "B", false, Some("change-b")),
+            ],
+            Vec::new(),
+            &request,
         );
 
-        assert_eq!(row.version_id, "version-a");
-        assert!(row.global);
+        assert_eq!(rows.len(), 1);
+    }
+
+    #[tokio::test]
+    async fn overlay_scan_fetches_base_global_candidates_for_staged_only_branch_scope() {
+        let base = ExistingGlobalOnlyReader {
+            rows: vec![row_at(
+                "global",
+                "entity",
+                "global-value",
+                true,
+                Some("change-global"),
+            )],
+        };
+        let staged = EmptyStagedRows;
+
+        let rows = overlay_scan_rows(
+            &base,
+            &staged,
+            &LiveStateScanRequest {
+                filter: crate::live_state::LiveStateFilter {
+                    branch_ids: vec!["staged-branch".to_string()],
+                    ..Default::default()
+                },
+                ..Default::default()
+            },
+        )
+        .await
+        .expect("overlay scan should succeed");
+
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0].branch_id, "staged-branch");
+        assert!(rows[0].global);
+        assert_eq!(
+            rows[0].snapshot_content.as_deref(),
+            Some("{\"value\":\"global-value\"}")
+        );
     }
 
     fn row_at(
-        version_id: &str,
+        branch_id: &str,
+        entity_pk: &str,
         value: &str,
         global: bool,
         change_id: Option<&str>,
     ) -> MaterializedLiveStateRow {
         MaterializedLiveStateRow {
-            entity_id: crate::entity_identity::EntityIdentity::single("entity"),
+            entity_pk: EntityPk::single(entity_pk),
             schema_key: "schema".to_string(),
             file_id: None,
             snapshot_content: Some(format!("{{\"value\":\"{value}\"}}")),
@@ -205,19 +606,61 @@ mod tests {
             change_id: change_id.map(str::to_string),
             commit_id: Some("commit".to_string()),
             untracked: false,
-            version_id: version_id.to_string(),
+            branch_id: branch_id.to_string(),
         }
     }
 
     fn tombstone_at(
-        version_id: &str,
+        branch_id: &str,
+        entity_pk: &str,
         global: bool,
         change_id: Option<&str>,
     ) -> MaterializedLiveStateRow {
         MaterializedLiveStateRow {
             snapshot_content: None,
             deleted: true,
-            ..row_at(version_id, "ignored", global, change_id)
+            ..row_at(branch_id, entity_pk, "ignored", global, change_id)
+        }
+    }
+
+    struct EmptyStagedRows;
+
+    impl StagedLiveStateRows for EmptyStagedRows {
+        fn staged_rows(
+            &self,
+            _request: &LiveStateScanRequest,
+        ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
+            Ok(Vec::new())
+        }
+    }
+
+    struct ExistingGlobalOnlyReader {
+        rows: Vec<MaterializedLiveStateRow>,
+    }
+
+    #[async_trait]
+    impl LiveStateReader for ExistingGlobalOnlyReader {
+        async fn scan_rows(
+            &self,
+            request: &LiveStateScanRequest,
+        ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
+            if request
+                .filter
+                .branch_ids
+                .iter()
+                .any(|branch_id| branch_id == GLOBAL_BRANCH_ID)
+            {
+                Ok(self.rows.clone())
+            } else {
+                Ok(Vec::new())
+            }
+        }
+
+        async fn load_row(
+            &self,
+            _request: &LiveStateRowRequest,
+        ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
+            Ok(None)
         }
     }
 }