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

package/dist-engine-src/src/sql2/filesystem_predicates.rs

@@ -0,0 +1,159 @@
+use datafusion::common::tree_node::{Transformed, TreeNode};
+use datafusion::common::{DataFusionError, Result, ScalarValue};
+use datafusion::logical_expr::expr::{Between, InList};
+use datafusion::logical_expr::{BinaryExpr, Expr, Operator};
+
+use crate::common::{normalize_directory_path, ParsedFilePath};
+use crate::LixError;
+
+use super::error::lix_error_to_datafusion_error;
+
+#[derive(Debug, Clone, Copy)]
+pub(crate) enum FilesystemPathKind {
+    File,
+    Directory,
+}
+
+pub(crate) fn canonicalize_filesystem_path_filters(
+    filters: &[Expr],
+    kind: FilesystemPathKind,
+) -> Result<Vec<Expr>> {
+    filters
+        .iter()
+        .cloned()
+        .map(|filter| canonicalize_filesystem_path_filter(filter, kind))
+        .collect()
+}
+
+fn canonicalize_filesystem_path_filter(expr: Expr, kind: FilesystemPathKind) -> Result<Expr> {
+    expr.transform(|expr| canonicalize_filesystem_path_expr(expr, kind))
+        .map(|transformed| transformed.data)
+}
+
+fn canonicalize_filesystem_path_expr(
+    expr: Expr,
+    kind: FilesystemPathKind,
+) -> Result<Transformed<Expr>> {
+    match expr {
+        Expr::BinaryExpr(binary_expr) if is_path_comparison_operator(binary_expr.op) => {
+            canonicalize_path_binary_expr(binary_expr, kind)
+        }
+        Expr::InList(in_list) if is_path_column(&in_list.expr) => {
+            canonicalize_path_in_list(in_list, kind)
+        }
+        Expr::Between(between) if is_path_column(&between.expr) => {
+            canonicalize_path_between(between, kind)
+        }
+        _ => Ok(Transformed::no(expr)),
+    }
+}
+
+fn canonicalize_path_binary_expr(
+    binary_expr: BinaryExpr,
+    kind: FilesystemPathKind,
+) -> Result<Transformed<Expr>> {
+    let BinaryExpr { left, op, right } = binary_expr;
+    let left_is_path = is_path_column(&left);
+    let right_is_path = is_path_column(&right);
+
+    let left = if right_is_path {
+        Box::new(canonicalize_path_literal_expr(*left, kind)?)
+    } else {
+        left
+    };
+    let right = if left_is_path {
+        Box::new(canonicalize_path_literal_expr(*right, kind)?)
+    } else {
+        right
+    };
+
+    Ok(Transformed::yes(Expr::BinaryExpr(BinaryExpr::new(
+        left, op, right,
+    ))))
+}
+
+fn canonicalize_path_in_list(
+    in_list: InList,
+    kind: FilesystemPathKind,
+) -> Result<Transformed<Expr>> {
+    let list = in_list
+        .list
+        .into_iter()
+        .map(|expr| canonicalize_path_literal_expr(expr, kind))
+        .collect::<Result<Vec<_>>>()?;
+    Ok(Transformed::yes(Expr::InList(InList::new(
+        in_list.expr,
+        list,
+        in_list.negated,
+    ))))
+}
+
+fn canonicalize_path_between(
+    between: Between,
+    kind: FilesystemPathKind,
+) -> Result<Transformed<Expr>> {
+    Ok(Transformed::yes(Expr::Between(Between {
+        expr: between.expr,
+        negated: between.negated,
+        low: Box::new(canonicalize_path_literal_expr(*between.low, kind)?),
+        high: Box::new(canonicalize_path_literal_expr(*between.high, kind)?),
+    })))
+}
+
+fn canonicalize_path_literal_expr(expr: Expr, kind: FilesystemPathKind) -> Result<Expr> {
+    let Expr::Literal(literal, metadata) = expr else {
+        return Err(unsupported_dynamic_path_predicate_error(expr));
+    };
+
+    match literal {
+        ScalarValue::Utf8(Some(value))
+        | ScalarValue::Utf8View(Some(value))
+        | ScalarValue::LargeUtf8(Some(value)) => {
+            let normalized = canonicalize_path_value(&value, kind)?;
+            Ok(Expr::Literal(ScalarValue::Utf8(Some(normalized)), metadata))
+        }
+        _ => Ok(Expr::Literal(literal, metadata)),
+    }
+}
+
+fn canonicalize_path_value(value: &str, kind: FilesystemPathKind) -> Result<String> {
+    match kind {
+        FilesystemPathKind::File => ParsedFilePath::try_from_path(value)
+            .map(|parsed| parsed.normalized_path.to_string())
+            .map_err(lix_error_to_datafusion_error),
+        FilesystemPathKind::Directory => {
+            normalize_directory_path(value).map_err(lix_error_to_datafusion_error)
+        }
+    }
+}
+
+fn is_path_column(expr: &Expr) -> bool {
+    matches!(expr, Expr::Column(column) if column.name == "path")
+}
+
+fn is_path_comparison_operator(op: Operator) -> bool {
+    matches!(
+        op,
+        Operator::Eq
+            | Operator::NotEq
+            | Operator::Lt
+            | Operator::LtEq
+            | Operator::Gt
+            | Operator::GtEq
+    )
+}
+
+fn unsupported_dynamic_path_predicate_error(expr: Expr) -> DataFusionError {
+    lix_error_to_datafusion_error(
+        LixError::new(
+            LixError::CODE_UNSUPPORTED_SQL,
+            format!(
+                "filesystem path predicates only support literal path values; found expression {expr:?}"
+            ),
+        )
+        .with_hint(
+            "Compare lix_file.path or lix_directory.path to a string literal or bound parameter. \
+             Computed path expressions are not supported until path canonicalization can run at evaluation time.",
+        ),
+    )
+}

package/dist-engine-src/src/sql2/filesystem_visibility.rs

@@ -0,0 +1,383 @@
+#![allow(dead_code)]
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+
+use serde::Deserialize;
+
+use crate::live_state::MaterializedLiveStateRow;
+use crate::live_state::{LiveStateFilter, LiveStateReader, LiveStateScanRequest};
+use crate::LixError;
+
+use super::filesystem_planner::{
+    FilesystemRowContext, BLOB_REF_SCHEMA_KEY, DIRECTORY_DESCRIPTOR_SCHEMA_KEY,
+    FILE_DESCRIPTOR_SCHEMA_KEY,
+};
+
+/// Execution-visible filesystem metadata decoded from live-state rows.
+///
+/// The helper intentionally depends only on `LiveStateReader`. In engine
+/// write execution that context may include staged rows, so filesystem planning
+/// sees pending writes without reaching into write-execution internals.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub(crate) struct VisibleFilesystem {
+    pub(crate) directories_by_id: BTreeMap<String, VisibleDirectory>,
+    pub(crate) directory_children_by_parent_id: BTreeMap<Option<String>, BTreeSet<String>>,
+    pub(crate) files_by_directory_id: BTreeMap<Option<String>, BTreeMap<String, VisibleFile>>,
+    pub(crate) blob_refs_by_file_id: BTreeMap<String, VisibleBlobRef>,
+}
+
+impl VisibleFilesystem {
+    /// Loads filesystem rows for a single version from execution-visible live
+    /// state and builds lookup indexes used by filesystem write planning.
+    pub(crate) async fn load(
+        live_state: Arc<dyn LiveStateReader>,
+        version_id: &str,
+    ) -> Result<Self, LixError> {
+        let rows = live_state
+            .scan_rows(&LiveStateScanRequest {
+                filter: LiveStateFilter {
+                    schema_keys: vec![
+                        DIRECTORY_DESCRIPTOR_SCHEMA_KEY.to_string(),
+                        FILE_DESCRIPTOR_SCHEMA_KEY.to_string(),
+                        BLOB_REF_SCHEMA_KEY.to_string(),
+                    ],
+                    version_ids: vec![version_id.to_string()],
+                    ..LiveStateFilter::default()
+                },
+                ..LiveStateScanRequest::default()
+            })
+            .await?;
+        Self::from_live_rows(rows)
+    }
+
+    /// Builds filesystem lookup indexes from rows that are already known to be
+    /// transaction-visible.
+    pub(crate) fn from_live_rows(rows: Vec<MaterializedLiveStateRow>) -> Result<Self, LixError> {
+        let mut visible = Self::default();
+
+        for row in rows {
+            let Some(snapshot_content) = row.snapshot_content.as_deref() else {
+                continue;
+            };
+            match row.schema_key.as_str() {
+                DIRECTORY_DESCRIPTOR_SCHEMA_KEY => {
+                    let snapshot: DirectoryDescriptorSnapshot =
+                        serde_json::from_str(snapshot_content).map_err(|error| {
+                            LixError::new(
+                                "LIX_ERROR_UNKNOWN",
+                                format!("invalid lix_directory_descriptor snapshot JSON: {error}"),
+                            )
+                        })?;
+                    let directory = VisibleDirectory {
+                        id: snapshot.id,
+                        parent_id: snapshot.parent_id,
+                        name: snapshot.name,
+                        hidden: snapshot.hidden.unwrap_or(false),
+                        context: filesystem_row_context(&row)?,
+                    };
+                    visible
+                        .directory_children_by_parent_id
+                        .entry(directory.parent_id.clone())
+                        .or_default()
+                        .insert(directory.id.clone());
+                    visible
+                        .directories_by_id
+                        .insert(directory.id.clone(), directory);
+                }
+                FILE_DESCRIPTOR_SCHEMA_KEY => {
+                    let snapshot: FileDescriptorSnapshot = serde_json::from_str(snapshot_content)
+                        .map_err(|error| {
+                        LixError::new(
+                            "LIX_ERROR_UNKNOWN",
+                            format!("invalid lix_file_descriptor snapshot JSON: {error}"),
+                        )
+                    })?;
+                    let file = VisibleFile {
+                        id: snapshot.id,
+                        directory_id: snapshot.directory_id,
+                        name: snapshot.name,
+                        hidden: snapshot.hidden,
+                        context: filesystem_row_context(&row)?,
+                    };
+                    visible
+                        .files_by_directory_id
+                        .entry(file.directory_id.clone())
+                        .or_default()
+                        .insert(file.id.clone(), file);
+                }
+                BLOB_REF_SCHEMA_KEY => {
+                    let snapshot: BlobRefSnapshot = serde_json::from_str(snapshot_content)
+                        .map_err(|error| {
+                            LixError::new(
+                                "LIX_ERROR_UNKNOWN",
+                                format!("invalid lix_binary_blob_ref snapshot JSON: {error}"),
+                            )
+                        })?;
+                    visible.blob_refs_by_file_id.insert(
+                        snapshot.id.clone(),
+                        VisibleBlobRef {
+                            file_id: snapshot.id,
+                            blob_hash: snapshot.blob_hash,
+                            size_bytes: snapshot.size_bytes,
+                            context: filesystem_row_context(&row)?,
+                        },
+                    );
+                }
+                _ => {}
+            }
+        }
+
+        Ok(visible)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct VisibleDirectory {
+    pub(crate) id: String,
+    pub(crate) parent_id: Option<String>,
+    pub(crate) name: String,
+    pub(crate) hidden: bool,
+    pub(crate) context: FilesystemRowContext,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct VisibleFile {
+    pub(crate) id: String,
+    pub(crate) directory_id: Option<String>,
+    pub(crate) name: String,
+    pub(crate) hidden: bool,
+    pub(crate) context: FilesystemRowContext,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct VisibleBlobRef {
+    pub(crate) file_id: String,
+    pub(crate) blob_hash: String,
+    pub(crate) size_bytes: Option<u64>,
+    pub(crate) context: FilesystemRowContext,
+}
+
+#[derive(Debug, Deserialize)]
+struct DirectoryDescriptorSnapshot {
+    id: String,
+    parent_id: Option<String>,
+    name: String,
+    hidden: Option<bool>,
+}
+
+#[derive(Debug, Deserialize)]
+struct FileDescriptorSnapshot {
+    id: String,
+    directory_id: Option<String>,
+    name: String,
+    hidden: bool,
+}
+
+#[derive(Debug, Deserialize)]
+struct BlobRefSnapshot {
+    id: String,
+    blob_hash: String,
+    size_bytes: Option<u64>,
+}
+
+fn filesystem_row_context(
+    row: &MaterializedLiveStateRow,
+) -> Result<FilesystemRowContext, LixError> {
+    Ok(FilesystemRowContext {
+        version_id: row.version_id.clone(),
+        global: row.global,
+        untracked: row.untracked,
+        file_id: row.file_id.clone(),
+        metadata: row
+            .metadata
+            .as_deref()
+            .map(|metadata| {
+                crate::parse_row_metadata_value(metadata, "filesystem row metadata").and_then(
+                    |metadata| {
+                        crate::transaction::types::TransactionJson::from_value(
+                            metadata,
+                            "filesystem row metadata",
+                        )
+                    },
+                )
+            })
+            .transpose()?,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use async_trait::async_trait;
+
+    use crate::live_state::MaterializedLiveStateRow;
+    use crate::live_state::{LiveStateReader, LiveStateRowRequest, LiveStateScanRequest};
+    use crate::LixError;
+
+    use super::{
+        VisibleFilesystem, BLOB_REF_SCHEMA_KEY, DIRECTORY_DESCRIPTOR_SCHEMA_KEY,
+        FILE_DESCRIPTOR_SCHEMA_KEY,
+    };
+
+    #[tokio::test]
+    async fn nested_directories_resolve_correctly() {
+        let filesystem = VisibleFilesystem::load(
+            live_state(vec![
+                directory_row(
+                    "dir-docs",
+                    r#"{"id":"dir-docs","parent_id":null,"name":"docs","hidden":false}"#,
+                ),
+                directory_row(
+                    "dir-guides",
+                    r#"{"id":"dir-guides","parent_id":"dir-docs","name":"guides","hidden":false}"#,
+                ),
+            ]),
+            "version-a",
+        )
+        .await
+        .expect("visible filesystem should load");
+
+        assert_eq!(
+            filesystem
+                .directories_by_id
+                .get("dir-guides")
+                .and_then(|directory| directory.parent_id.as_deref()),
+            Some("dir-docs")
+        );
+        assert!(filesystem
+            .directory_children_by_parent_id
+            .get(&None)
+            .is_some_and(|children| children.contains("dir-docs")));
+        assert!(filesystem
+            .directory_children_by_parent_id
+            .get(&Some("dir-docs".to_string()))
+            .is_some_and(|children| children.contains("dir-guides")));
+    }
+
+    #[tokio::test]
+    async fn files_attach_to_directory_ids() {
+        let filesystem = VisibleFilesystem::load(
+            live_state(vec![file_row(
+                "file-readme",
+                r#"{"id":"file-readme","directory_id":"dir-guides","name":"readme.md","hidden":false}"#,
+            )]),
+            "version-a",
+        )
+        .await
+        .expect("visible filesystem should load");
+
+        let files = filesystem
+            .files_by_directory_id
+            .get(&Some("dir-guides".to_string()))
+            .expect("directory should have attached files");
+        let file = files
+            .get("file-readme")
+            .expect("file should be indexed by id inside directory");
+        assert_eq!(file.name, "readme.md");
+    }
+
+    #[tokio::test]
+    async fn blob_refs_attach_to_file_ids() {
+        let filesystem = VisibleFilesystem::load(
+            live_state(vec![blob_ref_row(
+                "file-readme",
+                r#"{"id":"file-readme","blob_hash":"abc123","size_bytes":5}"#,
+            )]),
+            "version-a",
+        )
+        .await
+        .expect("visible filesystem should load");
+
+        let blob_ref = filesystem
+            .blob_refs_by_file_id
+            .get("file-readme")
+            .expect("blob ref should be indexed by file id");
+        assert_eq!(blob_ref.blob_hash, "abc123");
+        assert_eq!(blob_ref.size_bytes, Some(5));
+    }
+
+    fn live_state(rows: Vec<MaterializedLiveStateRow>) -> std::sync::Arc<dyn LiveStateReader> {
+        std::sync::Arc::new(RowsLiveStateReader { rows })
+    }
+
+    struct RowsLiveStateReader {
+        rows: Vec<MaterializedLiveStateRow>,
+    }
+
+    #[async_trait]
+    impl LiveStateReader for RowsLiveStateReader {
+        async fn scan_rows(
+            &self,
+            request: &LiveStateScanRequest,
+        ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
+            Ok(self
+                .rows
+                .iter()
+                .filter(|row| {
+                    (request.filter.schema_keys.is_empty()
+                        || request.filter.schema_keys.contains(&row.schema_key))
+                        && (request.filter.version_ids.is_empty()
+                            || request.filter.version_ids.contains(&row.version_id))
+                })
+                .cloned()
+                .collect())
+        }
+
+        async fn load_row(
+            &self,
+            _request: &LiveStateRowRequest,
+        ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
+            Ok(None)
+        }
+    }
+
+    fn directory_row(entity_id: &str, snapshot_content: &str) -> MaterializedLiveStateRow {
+        live_row(
+            entity_id,
+            DIRECTORY_DESCRIPTOR_SCHEMA_KEY,
+            None,
+            snapshot_content,
+        )
+    }
+
+    fn file_row(entity_id: &str, snapshot_content: &str) -> MaterializedLiveStateRow {
+        live_row(
+            entity_id,
+            FILE_DESCRIPTOR_SCHEMA_KEY,
+            None,
+            snapshot_content,
+        )
+    }
+
+    fn blob_ref_row(entity_id: &str, snapshot_content: &str) -> MaterializedLiveStateRow {
+        live_row(
+            entity_id,
+            BLOB_REF_SCHEMA_KEY,
+            Some(entity_id.to_string()),
+            snapshot_content,
+        )
+    }
+
+    fn live_row(
+        entity_id: &str,
+        schema_key: &str,
+        file_id: Option<String>,
+        snapshot_content: &str,
+    ) -> MaterializedLiveStateRow {
+        MaterializedLiveStateRow {
+            entity_id: crate::entity_identity::EntityIdentity::single(entity_id),
+            schema_key: schema_key.to_string(),
+            file_id,
+            snapshot_content: Some(snapshot_content.to_string()),
+            metadata: None,
+            deleted: false,
+            version_id: "version-a".to_string(),
+            change_id: Some(format!("change-{entity_id}")),
+            commit_id: Some(format!("commit-{entity_id}")),
+            global: false,
+            untracked: false,
+            created_at: "2026-04-23T00:00:00Z".to_string(),
+            updated_at: "2026-04-23T01:00:00Z".to_string(),
+        }
+    }
+}

package/dist-engine-src/src/sql2/history_projection.rs

@@ -0,0 +1,56 @@
+use serde_json::Value as JsonValue;
+
+use crate::entity_identity::EntityIdentity;
+use crate::LixError;
+
+/// Shared projection contract for typed history views.
+///
+/// On tombstone rows (`snapshot_content IS NULL`), identity columns survive by
+/// projecting from canonical entity identity. Non-identity columns must remain
+/// NULL because there is no snapshot to project payload from.
+pub(crate) enum HistoryIdentityProjection<'a> {
+    PrimaryKeyPaths(&'a [Vec<String>]),
+    SingleColumn { column: &'a str },
+}
+
+pub(crate) fn tombstone_identity_column_value(
+    column_name: &str,
+    entity_id: &str,
+    projection: HistoryIdentityProjection<'_>,
+) -> Result<Option<JsonValue>, LixError> {
+    match projection {
+        HistoryIdentityProjection::SingleColumn { column } => {
+            if column_name == column {
+                Ok(Some(JsonValue::String(entity_id.to_string())))
+            } else {
+                Ok(None)
+            }
+        }
+        HistoryIdentityProjection::PrimaryKeyPaths(primary_key_paths) => {
+            primary_key_tombstone_value(column_name, entity_id, primary_key_paths)
+        }
+    }
+}
+
+fn primary_key_tombstone_value(
+    column_name: &str,
+    entity_id: &str,
+    primary_key_paths: &[Vec<String>],
+) -> Result<Option<JsonValue>, LixError> {
+    let Some(part_index) = primary_key_paths
+        .iter()
+        .position(|path| path.as_slice() == [column_name])
+    else {
+        return Ok(None);
+    };
+
+    let identity = EntityIdentity::from_json_array_text(entity_id).map_err(|error| {
+        LixError::unknown(format!(
+            "failed to decode history tombstone entity identity: {error}"
+        ))
+    })?;
+    Ok(identity
+        .parts
+        .get(part_index)
+        .map(|part| JsonValue::String(part.clone())))
+}