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

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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,75 @@
+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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,222 @@
+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

@@ -0,0 +1,223 @@
+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)
+        }
+    }
+}