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

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

@@ -0,0 +1,122 @@
+use crate::changelog::ChangeRecord;
+use crate::entity_pk::EntityPk;
+use crate::json_store::{JsonLoadRequestRef, JsonReadScopeRef, JsonRef, JsonStoreReader};
+use crate::storage::StorageRead;
+use crate::{parse_row_metadata, LixError};
+
+/// Read-boundary view of a changelog change with JSON refs resolved.
+///
+/// `lix_change` materializes direct durable `changelog.change` facts and
+/// derived `lix_commit` changes from `changelog.commit`. History surfaces
+/// materialize reachability-aware commit-graph changes, while traversal context
+/// stays outside this row shape.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct MaterializedChange {
+    pub(crate) id: String,
+    pub(crate) entity_pk: EntityPk,
+    pub(crate) schema_key: String,
+    pub(crate) file_id: Option<String>,
+    pub(crate) snapshot_content: Option<String>,
+    pub(crate) metadata: Option<String>,
+    pub(crate) created_at: String,
+}
+
+pub(crate) async fn materialize_located_history_change<S>(
+    json_reader: &mut JsonStoreReader<S>,
+    change: crate::commit_graph::CommitGraphChange,
+) -> Result<MaterializedChange, LixError>
+where
+    S: StorageRead,
+{
+    materialize_commit_graph_change(json_reader, change).await
+}
+
+pub(crate) async fn materialize_changelog_change_record<S>(
+    json_reader: &mut JsonStoreReader<S>,
+    change: ChangeRecord,
+) -> Result<MaterializedChange, LixError>
+where
+    S: StorageRead,
+{
+    materialize_commit_graph_change(
+        json_reader,
+        crate::commit_graph::CommitGraphChange {
+            id: change.change_id,
+            entity_pk: change.entity_pk,
+            schema_key: change.schema_key,
+            file_id: change.file_id,
+            snapshot_ref: change.snapshot_ref,
+            metadata_ref: change.metadata_ref,
+            created_at: change.created_at,
+        },
+    )
+    .await
+}
+
+pub(crate) async fn materialize_commit_graph_change<S>(
+    json_reader: &mut JsonStoreReader<S>,
+    change: crate::commit_graph::CommitGraphChange,
+) -> Result<MaterializedChange, LixError>
+where
+    S: StorageRead,
+{
+    let snapshot_content = load_optional_changelog_json_text(
+        json_reader,
+        change.snapshot_ref.as_ref(),
+        "snapshot_ref",
+    )
+    .await?;
+    let metadata = match load_optional_changelog_json_text(
+        json_reader,
+        change.metadata_ref.as_ref(),
+        "metadata_ref",
+    )
+    .await?
+    {
+        Some(value) => Some(parse_row_metadata(&value, "changelog change metadata_ref")?),
+        None => None,
+    };
+    Ok(MaterializedChange {
+        id: change.id,
+        entity_pk: change.entity_pk,
+        schema_key: change.schema_key,
+        file_id: change.file_id,
+        snapshot_content,
+        metadata,
+        created_at: change.created_at,
+    })
+}
+
+async fn load_optional_changelog_json_text<S>(
+    json_reader: &mut JsonStoreReader<S>,
+    json_ref: Option<&JsonRef>,
+    field: &str,
+) -> Result<Option<String>, LixError>
+where
+    S: StorageRead,
+{
+    let Some(json_ref) = json_ref else {
+        return Ok(None);
+    };
+    let batch = json_reader
+        .load_bytes_many(JsonLoadRequestRef {
+            refs: std::slice::from_ref(json_ref),
+            scope: JsonReadScopeRef::OutOfBand,
+        })
+        .await?;
+    let Some(bytes) = batch.into_values().into_iter().next().flatten() else {
+        return Err(LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            format!(
+                "changelog change {field} '{}' is missing",
+                json_ref.to_hex()
+            ),
+        ));
+    };
+    String::from_utf8(bytes).map(Some).map_err(|error| {
+        LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            format!("changelog change {field} is not UTF-8 JSON: {error}"),
+        )
+    })
+}

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

@@ -6,28 +6,31 @@ use serde_json::Value as JsonValue;
 use tokio::sync::Mutex;
 
 use crate::binary_cas::{BlobBytesBatch, BlobDataReader, BlobHash};
+use crate::branch::{BranchHead, BranchRefReader};
 use crate::commit_graph::CommitGraphReader;
-use crate::commit_store::CommitStoreReader;
 use crate::functions::FunctionProviderHandle;
 use crate::json_store::JsonStoreReader;
 use crate::live_state::{
     LiveStateFilter, LiveStateReader, LiveStateRowRequest, LiveStateScanRequest,
     MaterializedLiveStateRow,
 };
-use crate::storage::{ScopedStorageReader, StorageReadTransaction};
+use crate::storage::StorageRead;
 use crate::transaction::types::{TransactionWrite, TransactionWriteOutcome};
-use crate::version::{VersionHead, VersionRefReader};
 use crate::LixError;
 
-pub(crate) type SqlReadStore =
-    ScopedStorageReader<Box<dyn StorageReadTransaction + Send + Sync + 'static>>;
-pub(crate) type SqlCommitStoreQuerySource = CommitStoreQuerySource<SqlReadStore>;
-pub(crate) type SqlJsonReader = JsonStoreReader<ScopedStorageReader<SqlReadStore>>;
+pub(crate) type SqlChangelogQuerySource<S> = ChangelogQuerySource<S>;
+pub(crate) type SqlHistoryQuerySource<S> = HistoryQuerySource<S>;
+pub(crate) type SqlJsonReader<S> = JsonStoreReader<S>;
 
 #[derive(Clone)]
-pub(crate) struct CommitStoreQuerySource<S> {
-    pub(crate) commit_store_reader: Arc<CommitStoreReader<ScopedStorageReader<S>>>,
-    pub(crate) json_reader: JsonStoreReader<ScopedStorageReader<S>>,
+pub(crate) struct HistoryQuerySource<S> {
+    pub(crate) json_reader: JsonStoreReader<S>,
+}
+
+#[derive(Clone)]
+pub(crate) struct ChangelogQuerySource<S> {
+    pub(crate) store: S,
+    pub(crate) json_reader: JsonStoreReader<S>,
 }
 
 /// Read-only execution boundary for `sql2::execute_sql(...)`.
@@ -41,12 +44,15 @@ pub(crate) struct CommitStoreQuerySource<S> {
 /// sources.
 #[allow(dead_code)]
 pub(crate) trait SqlExecutionContext {
-    fn active_version_id(&self) -> &str;
+    type ReadStore: StorageRead + Clone + Send + Sync + 'static;
+
+    fn active_branch_id(&self) -> &str;
     fn live_state(&self) -> Arc<dyn LiveStateReader>;
     fn functions(&self) -> FunctionProviderHandle;
-    fn commit_store_query_source(&self) -> SqlCommitStoreQuerySource;
+    fn history_query_source(&self) -> SqlHistoryQuerySource<Self::ReadStore>;
+    fn changelog_query_source(&self) -> SqlChangelogQuerySource<Self::ReadStore>;
     fn commit_graph(&self) -> Box<dyn CommitGraphReader>;
-    fn version_ref(&self) -> Arc<dyn VersionRefReader>;
+    fn branch_ref(&self) -> Arc<dyn BranchRefReader>;
     fn blob_reader(&self) -> Arc<dyn BlobDataReader>;
     fn list_visible_schemas(&self) -> Result<Vec<JsonValue>, LixError>;
 }
@@ -60,7 +66,7 @@ pub(crate) trait SqlExecutionContext {
 #[async_trait]
 #[allow(dead_code)]
 pub(crate) trait SqlWriteExecutionContext {
-    fn active_version_id(&self) -> &str;
+    fn active_branch_id(&self) -> &str;
     fn functions(&self) -> FunctionProviderHandle;
     fn list_visible_schemas(&self) -> Result<Vec<JsonValue>, LixError>;
 
@@ -71,7 +77,7 @@ pub(crate) trait SqlWriteExecutionContext {
         request: &LiveStateScanRequest,
     ) -> Result<Vec<MaterializedLiveStateRow>, LixError>;
 
-    async fn load_version_head(&mut self, version_id: &str) -> Result<Option<String>, LixError>;
+    async fn load_branch_head(&mut self, branch_id: &str) -> Result<Option<String>, LixError>;
 
     async fn stage_write(
         &mut self,
@@ -120,8 +126,8 @@ impl SqlWriteContext {
         unsafe { self.ptr.0.as_ref().list_visible_schemas() }
     }
 
-    pub(crate) fn active_version_id(&self) -> String {
-        unsafe { self.ptr.0.as_ref().active_version_id().to_string() }
+    pub(crate) fn active_branch_id(&self) -> String {
+        unsafe { self.ptr.0.as_ref().active_branch_id().to_string() }
     }
 
     pub(crate) async fn scan_live_state(
@@ -156,9 +162,9 @@ impl SqlWriteContext {
         }
     }
 
-    pub(crate) async fn load_version_head(
+    pub(crate) async fn load_branch_head(
         &self,
-        version_id: &str,
+        branch_id: &str,
     ) -> Result<Option<String>, LixError> {
         let _guard = self.gate.lock().await;
         unsafe {
@@ -167,7 +173,7 @@ impl SqlWriteContext {
                 .as_ptr()
                 .as_mut()
                 .unwrap()
-                .load_version_head(version_id)
+                .load_branch_head(branch_id)
                 .await
         }
     }
@@ -266,8 +272,8 @@ impl LiveStateReader for WriteContextLiveStateReader {
             .scan_live_state(&LiveStateScanRequest {
                 filter: LiveStateFilter {
                     schema_keys: vec![request.schema_key.clone()],
-                    entity_ids: vec![request.entity_id.clone()],
-                    version_ids: vec![request.version_id.clone()],
+                    entity_pks: vec![request.entity_pk.clone()],
+                    branch_ids: vec![request.branch_id.clone()],
                     file_ids: vec![request.file_id.clone()],
                     ..LiveStateFilter::default()
                 },
@@ -279,30 +285,30 @@ impl LiveStateReader for WriteContextLiveStateReader {
     }
 }
 
-pub(crate) struct WriteContextVersionRefReader {
+pub(crate) struct WriteContextBranchRefReader {
     ctx: SqlWriteContext,
 }
 
-impl WriteContextVersionRefReader {
+impl WriteContextBranchRefReader {
     pub(crate) fn new(ctx: SqlWriteContext) -> Self {
         Self { ctx }
     }
 }
 
 #[async_trait]
-impl VersionRefReader for WriteContextVersionRefReader {
-    async fn load_head(&self, version_id: &str) -> Result<Option<VersionHead>, LixError> {
+impl BranchRefReader for WriteContextBranchRefReader {
+    async fn load_head(&self, branch_id: &str) -> Result<Option<BranchHead>, LixError> {
         Ok(self
             .ctx
-            .load_version_head(version_id)
+            .load_branch_head(branch_id)
             .await?
-            .map(|commit_id| VersionHead {
-                version_id: version_id.to_string(),
+            .map(|commit_id| BranchHead {
+                branch_id: branch_id.to_string(),
                 commit_id,
             }))
     }
 
-    async fn scan_heads(&self) -> Result<Vec<VersionHead>, LixError> {
+    async fn scan_heads(&self) -> Result<Vec<BranchHead>, LixError> {
         Err(LixError::new(
             "LIX_ERROR_UNKNOWN",
             "scan_heads is not available through sql2 write context",

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

@@ -59,7 +59,7 @@ fn classify_datafusion_error(error: &DataFusionError) -> LixError {
 
     if looks_like_unsupported_dialect(&lower) {
         return LixError::new(LixError::CODE_DIALECT_UNSUPPORTED, message)
-            .with_hint("Lix SQL uses DataFusion syntax. Use lix_json_get(...) or lix_json_get_text(...) for JSON access, and numbered placeholders like $1, $2, ...");
+            .with_hint("Lix SQL uses DataFusion syntax. Use lix_json_get(...) or lix_json_get_text(...) for JSON access, and placeholders like ?, ? or $1, $2, ...");
     }
 
     if looks_like_unsupported_runtime_plan(&lower) {
@@ -76,9 +76,8 @@ fn classify_datafusion_error(error: &DataFusionError) -> LixError {
         || lower.contains("placeholder")
         || lower.contains("bind")
     {
-        return LixError::new(LixError::CODE_PARSE_ERROR, message).with_hint(
-            "Use numbered placeholders like $1, $2, ...; '?' placeholders are not supported.",
-        );
+        return LixError::new(LixError::CODE_PARSE_ERROR, message)
+            .with_hint("Use placeholders like ?, ? or numbered placeholders like $1, $2, ...");
     }
 
     if lower.contains("requires start_commit_id")
@@ -86,7 +85,7 @@ fn classify_datafusion_error(error: &DataFusionError) -> LixError {
         || lower.contains("history table")
     {
         return LixError::new(LixError::CODE_HISTORY_FILTER_REQUIRED, message)
-            .with_hint("Add a commit/version range predicate before querying history tables.");
+            .with_hint("Add a commit/branch range predicate before querying history tables.");
     }
 
     if lower.contains("table not found")