@lix-js/sdk 0.6.0-preview.4 → 0.6.0

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

@@ -1,15 +0,0 @@
-mod context;
-mod overlay;
-mod reader;
-mod types;
-mod visibility;
-
-#[allow(unused_imports)]
-pub(crate) use context::{LiveStateContext, LiveStateStoreReader};
-#[allow(unused_imports)]
-pub(crate) use reader::LiveStateReader;
-#[allow(unused_imports)]
-pub(crate) use types::{
-    Bound, LiveStateFilter, LiveStateProjection, LiveStateRowIdentity, LiveStateRowRequest,
-    LiveStateScanRequest, MaterializedLiveStateRow, ScanConstraint, ScanField, ScanOperator,
-};

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

@@ -1,75 +0,0 @@
-use std::collections::BTreeMap;
-
-use crate::live_state::{LiveStateRowIdentity, MaterializedLiveStateRow};
-
-/// Applies the local untracked overlay to tracked live-state rows.
-///
-/// The visible live-state contract is "latest local untracked row wins" for
-/// the same version/schema/entity/file identity. This keeps SQL providers from
-/// knowing whether a visible row came from tracked changelog projection or from
-/// local untracked state.
-pub(crate) fn overlay_untracked_rows(
-    tracked_rows: Vec<MaterializedLiveStateRow>,
-    untracked_rows: Vec<MaterializedLiveStateRow>,
-) -> Vec<MaterializedLiveStateRow> {
-    let mut rows_by_identity = BTreeMap::new();
-
-    for row in tracked_rows {
-        rows_by_identity.insert(LiveStateRowIdentity::from_row(&row), row);
-    }
-    for row in untracked_rows {
-        rows_by_identity.insert(LiveStateRowIdentity::from_row(&row), row);
-    }
-
-    rows_by_identity.into_values().collect()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn untracked_row_wins_for_same_identity() {
-        let tracked = live_row("tracked", false, Some("change-tracked"));
-        let untracked = live_row("untracked", true, None);
-
-        let rows = overlay_untracked_rows(vec![tracked], vec![untracked]);
-
-        assert_eq!(rows.len(), 1);
-        assert_eq!(
-            rows[0].snapshot_content.as_deref(),
-            Some("{\"value\":\"untracked\"}")
-        );
-        assert!(rows[0].untracked);
-        assert_eq!(rows[0].change_id, None);
-    }
-
-    #[test]
-    fn different_identities_are_preserved() {
-        let tracked = live_row("tracked", false, Some("change-tracked"));
-        let mut untracked = live_row("untracked", true, None);
-        untracked.entity_id = crate::entity_identity::EntityIdentity::single("other");
-
-        let rows = overlay_untracked_rows(vec![tracked], vec![untracked]);
-
-        assert_eq!(rows.len(), 2);
-    }
-
-    fn live_row(value: &str, untracked: bool, change_id: Option<&str>) -> MaterializedLiveStateRow {
-        MaterializedLiveStateRow {
-            entity_id: crate::entity_identity::EntityIdentity::single("entity"),
-            schema_key: "schema".to_string(),
-            file_id: None,
-            snapshot_content: Some(format!("{{\"value\":\"{value}\"}}")),
-            metadata: None,
-            deleted: false,
-            created_at: "2026-01-01T00:00:00Z".to_string(),
-            updated_at: "2026-01-01T00:00:00Z".to_string(),
-            global: true,
-            change_id: change_id.map(str::to_string),
-            commit_id: None,
-            untracked,
-            version_id: "global".to_string(),
-        }
-    }
-}

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

@@ -1,23 +0,0 @@
-use async_trait::async_trait;
-
-use crate::live_state::MaterializedLiveStateRow;
-use crate::live_state::{LiveStateRowRequest, LiveStateScanRequest};
-use crate::LixError;
-
-/// Minimal engine read model for transaction planning and SQL providers.
-///
-/// Engine only needs visible state-row reads here. Changelog freshness/catch-up
-/// should be added at this boundary later instead of leaking projection internals
-/// into sessions or SQL providers.
-#[async_trait]
-pub(crate) trait LiveStateReader: Send + Sync {
-    async fn scan_rows(
-        &self,
-        request: &LiveStateScanRequest,
-    ) -> Result<Vec<MaterializedLiveStateRow>, LixError>;
-
-    async fn load_row(
-        &self,
-        request: &LiveStateRowRequest,
-    ) -> Result<Option<MaterializedLiveStateRow>, LixError>;
-}

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

@@ -1,222 +0,0 @@
-use crate::entity_identity::EntityIdentity;
-use crate::tracked_state::MaterializedTrackedStateRow;
-use crate::untracked_state::{
-    MaterializedUntrackedStateRow, UntrackedStateFilter, UntrackedStateRowRequest,
-};
-use crate::{NullableKeyFilter, Value};
-
-/// Durable row visible through live_state reads.
-///
-/// Unlike provider write rows, live-state rows are fully hydrated facts. Missing
-/// generated fields should be caught before this type is constructed.
-#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
-pub(crate) struct MaterializedLiveStateRow {
-    pub(crate) entity_id: EntityIdentity,
-    pub(crate) schema_key: String,
-    pub(crate) file_id: Option<String>,
-    pub(crate) snapshot_content: Option<String>,
-    pub(crate) metadata: Option<String>,
-    pub(crate) deleted: bool,
-    pub(crate) created_at: String,
-    pub(crate) updated_at: String,
-    pub(crate) global: bool,
-    pub(crate) change_id: Option<String>,
-    pub(crate) commit_id: Option<String>,
-    pub(crate) untracked: bool,
-    pub(crate) version_id: String,
-}
-
-impl From<MaterializedUntrackedStateRow> for MaterializedLiveStateRow {
-    fn from(row: MaterializedUntrackedStateRow) -> Self {
-        MaterializedLiveStateRow {
-            entity_id: row.entity_id,
-            schema_key: row.schema_key,
-            file_id: row.file_id,
-            snapshot_content: row.snapshot_content,
-            metadata: row.metadata,
-            deleted: row.deleted,
-            created_at: row.created_at,
-            updated_at: row.updated_at,
-            global: row.global,
-            change_id: None,
-            commit_id: None,
-            untracked: true,
-            version_id: row.version_id,
-        }
-    }
-}
-
-impl TryFrom<&MaterializedLiveStateRow> for MaterializedTrackedStateRow {
-    type Error = crate::LixError;
-
-    fn try_from(row: &MaterializedLiveStateRow) -> Result<Self, Self::Error> {
-        if row.untracked {
-            return Err(crate::LixError::new(
-                "LIX_ERROR_UNKNOWN",
-                "tracked_state cannot store untracked live-state rows",
-            ));
-        }
-        let Some(change_id) = row.change_id.clone() else {
-            return Err(crate::LixError::new(
-                "LIX_ERROR_UNKNOWN",
-                "tracked_state rows require change_id",
-            ));
-        };
-        let Some(commit_id) = row.commit_id.clone() else {
-            return Err(crate::LixError::new(
-                "LIX_ERROR_UNKNOWN",
-                "tracked_state rows require commit_id",
-            ));
-        };
-
-        Ok(MaterializedTrackedStateRow {
-            entity_id: row.entity_id.clone(),
-            schema_key: row.schema_key.clone(),
-            file_id: row.file_id.clone(),
-            snapshot_content: row.snapshot_content.clone(),
-            metadata: row.metadata.clone(),
-            deleted: row.deleted,
-            created_at: row.created_at.clone(),
-            updated_at: row.updated_at.clone(),
-            change_id,
-            commit_id,
-        })
-    }
-}
-
-impl From<&MaterializedLiveStateRow> for MaterializedUntrackedStateRow {
-    fn from(row: &MaterializedLiveStateRow) -> Self {
-        MaterializedUntrackedStateRow {
-            entity_id: row.entity_id.clone(),
-            schema_key: row.schema_key.clone(),
-            file_id: row.file_id.clone(),
-            snapshot_content: row.snapshot_content.clone(),
-            metadata: row.metadata.clone(),
-            deleted: row.deleted,
-            created_at: row.created_at.clone(),
-            updated_at: row.updated_at.clone(),
-            global: row.global,
-            version_id: row.version_id.clone(),
-        }
-    }
-}
-
-/// Which indexed field a live-state scan constraint applies to.
-#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
-pub(crate) enum ScanField {
-    EntityId,
-    FileId,
-}
-
-/// Inclusive or exclusive range bound.
-#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
-pub(crate) struct Bound {
-    pub(crate) value: Value,
-    pub(crate) inclusive: bool,
-}
-
-/// SQL-free structured scan constraint.
-#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
-pub(crate) struct ScanConstraint {
-    pub(crate) field: ScanField,
-    pub(crate) operator: ScanOperator,
-}
-
-/// Structured scan operator aligned with the current planner/storage split.
-#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
-pub(crate) enum ScanOperator {
-    Eq(Value),
-    In(Vec<Value>),
-    Range {
-        lower: Option<Bound>,
-        upper: Option<Bound>,
-    },
-}
-
-/// Identity-centered filter for visible live entities.
-#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, Default)]
-pub(crate) struct LiveStateFilter {
-    #[serde(default)]
-    pub(crate) schema_keys: Vec<String>,
-    #[serde(default)]
-    pub(crate) entity_ids: Vec<EntityIdentity>,
-    #[serde(default)]
-    pub(crate) version_ids: Vec<String>,
-    #[serde(default)]
-    pub(crate) file_ids: Vec<NullableKeyFilter<String>>,
-    #[serde(default)]
-    pub(crate) untracked: Option<bool>,
-    #[serde(default)]
-    pub(crate) constraints: Vec<ScanConstraint>,
-    #[serde(default)]
-    pub(crate) include_tombstones: bool,
-}
-
-impl From<LiveStateFilter> for UntrackedStateFilter {
-    fn from(filter: LiveStateFilter) -> Self {
-        Self {
-            schema_keys: filter.schema_keys,
-            entity_ids: filter.entity_ids,
-            version_ids: filter.version_ids,
-            file_ids: filter.file_ids,
-        }
-    }
-}
-
-/// Requested property set for a live-state scan.
-#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, Default)]
-pub(crate) struct LiveStateProjection {
-    #[serde(default)]
-    pub(crate) columns: Vec<String>,
-}
-
-/// First-principles scan request for engine-owned reads.
-#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, Default)]
-pub(crate) struct LiveStateScanRequest {
-    #[serde(default)]
-    pub(crate) filter: LiveStateFilter,
-    #[serde(default)]
-    pub(crate) projection: LiveStateProjection,
-    #[serde(default)]
-    pub(crate) limit: Option<usize>,
-}
-
-/// Point lookup request for one visible live-state row.
-#[derive(Debug, Clone, PartialEq)]
-pub(crate) struct LiveStateRowRequest {
-    pub(crate) schema_key: String,
-    pub(crate) version_id: String,
-    pub(crate) entity_id: EntityIdentity,
-    pub(crate) file_id: NullableKeyFilter<String>,
-}
-
-impl From<&LiveStateRowRequest> for UntrackedStateRowRequest {
-    fn from(request: &LiveStateRowRequest) -> Self {
-        Self {
-            schema_key: request.schema_key.clone(),
-            version_id: request.version_id.clone(),
-            entity_id: request.entity_id.clone(),
-            file_id: request.file_id.clone(),
-        }
-    }
-}
-
-/// Stable visible-row identity used for overlay composition.
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
-pub(crate) struct LiveStateRowIdentity {
-    pub(crate) version_id: String,
-    pub(crate) schema_key: String,
-    pub(crate) entity_id: EntityIdentity,
-    pub(crate) file_id: Option<String>,
-}
-
-impl LiveStateRowIdentity {
-    pub(crate) fn from_row(row: &MaterializedLiveStateRow) -> Self {
-        Self {
-            version_id: row.version_id.clone(),
-            schema_key: row.schema_key.clone(),
-            entity_id: row.entity_id.clone(),
-            file_id: row.file_id.clone(),
-        }
-    }
-}

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

@@ -1,223 +0,0 @@
-use std::collections::BTreeMap;
-
-use crate::live_state::{LiveStateRowIdentity, MaterializedLiveStateRow};
-use crate::GLOBAL_VERSION_ID;
-
-/// Expands a version-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() {
-        return Vec::new();
-    }
-
-    let mut expanded = version_ids.to_vec();
-    if version_ids
-        .iter()
-        .any(|version_id| version_id != GLOBAL_VERSION_ID)
-        && !expanded
-            .iter()
-            .any(|version_id| version_id == GLOBAL_VERSION_ID)
-    {
-        expanded.push(GLOBAL_VERSION_ID.to_string());
-    }
-    expanded
-}
-
-/// 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
-/// 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(
-    rows: Vec<MaterializedLiveStateRow>,
-    requested_version_ids: &[String],
-    include_tombstones: bool,
-) -> Vec<MaterializedLiveStateRow> {
-    let mut rows = project_global_rows_into_requested_versions(rows, requested_version_ids);
-    if !include_tombstones {
-        rows.retain(|row| !row.deleted);
-    }
-    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 project_global_rows_into_requested_versions(
-    rows: Vec<MaterializedLiveStateRow>,
-    requested_version_ids: &[String],
-) -> Vec<MaterializedLiveStateRow> {
-    if requested_version_ids.is_empty() {
-        return rows;
-    }
-
-    let mut rows_by_identity = BTreeMap::<LiveStateRowIdentity, MaterializedLiveStateRow>::new();
-    for requested_version_id in requested_version_ids {
-        for row in &rows {
-            if row.version_id == GLOBAL_VERSION_ID {
-                let mut projected = row.clone();
-                projected.version_id = requested_version_id.clone();
-                rows_by_identity.insert(LiveStateRowIdentity::from_row(&projected), projected);
-            }
-        }
-        for row in rows
-            .iter()
-            .filter(|row| row.version_id == *requested_version_id)
-        {
-            rows_by_identity.insert(LiveStateRowIdentity::from_row(row), row.clone());
-        }
-    }
-
-    rows_by_identity.into_values().collect()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn expands_requested_version_with_global_candidates() {
-        assert_eq!(
-            expanded_version_ids(&["version-a".to_string()]),
-            vec!["version-a".to_string(), "global".to_string()]
-        );
-        assert_eq!(
-            expanded_version_ids(&["global".to_string()]),
-            vec!["global".to_string()]
-        );
-    }
-
-    #[test]
-    fn scan_projects_global_row_into_requested_version() {
-        let rows = resolve_scan_rows(
-            vec![row_at(
-                "global",
-                "global-value",
-                true,
-                Some("change-global"),
-            )],
-            &["version-a".to_string()],
-            false,
-        );
-
-        assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].version_id, "version-a");
-        assert!(rows[0].global);
-        assert_eq!(
-            rows[0].snapshot_content.as_deref(),
-            Some("{\"value\":\"global-value\"}")
-        );
-    }
-
-    #[test]
-    fn scan_prefers_requested_version_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")),
-            ],
-            &["version-a".to_string()],
-            false,
-        );
-
-        assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].version_id, "version-a");
-        assert!(!rows[0].global);
-        assert_eq!(
-            rows[0].snapshot_content.as_deref(),
-            Some("{\"value\":\"version-value\"}")
-        );
-    }
-
-    #[test]
-    fn version_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")),
-            ],
-            &["version-a".to_string()],
-            false,
-        );
-
-        assert!(rows.is_empty());
-    }
-
-    #[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")),
-            ],
-            &["version-a".to_string()],
-            true,
-        );
-
-        assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].version_id, "version-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",
-        );
-
-        assert_eq!(row.version_id, "version-a");
-        assert!(row.global);
-    }
-
-    fn row_at(
-        version_id: &str,
-        value: &str,
-        global: bool,
-        change_id: Option<&str>,
-    ) -> MaterializedLiveStateRow {
-        MaterializedLiveStateRow {
-            entity_id: crate::entity_identity::EntityIdentity::single("entity"),
-            schema_key: "schema".to_string(),
-            file_id: None,
-            snapshot_content: Some(format!("{{\"value\":\"{value}\"}}")),
-            metadata: None,
-            deleted: false,
-            created_at: "2026-01-01T00:00:00Z".to_string(),
-            updated_at: "2026-01-01T00:00:00Z".to_string(),
-            global,
-            change_id: change_id.map(str::to_string),
-            commit_id: Some("commit".to_string()),
-            untracked: false,
-            version_id: version_id.to_string(),
-        }
-    }
-
-    fn tombstone_at(
-        version_id: &str,
-        global: bool,
-        change_id: Option<&str>,
-    ) -> MaterializedLiveStateRow {
-        MaterializedLiveStateRow {
-            snapshot_content: None,
-            deleted: true,
-            ..row_at(version_id, "ignored", global, change_id)
-        }
-    }
-}