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

package/dist-engine-src/src/session/merge/version.rs

@@ -1,7 +1,7 @@
-use serde_json::json;
+use serde_json::{json, Value as JsonValue};
 
-use crate::transaction::types::StageWrite;
-use crate::version::VersionRefReader;
+use crate::transaction::types::TransactionWrite;
+use crate::version::{VersionLifecycle, VersionOperation, VersionReferenceRole};
 use crate::LixError;
 
 use super::analysis::{analyze, MergeCommits, MergeOutcome};
@@ -67,7 +67,7 @@ pub struct MergeVersionPreview {
 pub struct MergeConflict {
     pub kind: MergeConflictKind,
     pub schema_key: String,
-    pub entity_id: String,
+    pub entity_id: JsonValue,
     pub file_id: Option<String>,
     pub target: MergeConflictSide,
     pub source: MergeConflictSide,
@@ -117,26 +117,21 @@ impl SessionContext {
 
                 let (target_head, source_head) = {
                     let reader = transaction.version_ref_reader();
-                    let target_head = reader
-                        .load_head_commit_id(&active_version_id)
-                        .await?
-                        .ok_or_else(|| {
-                            LixError::version_not_found(
-                                active_version_id.clone(),
-                                "merge_version_preview",
-                                "target",
-                            )
-                        })?;
-                    let source_head = reader
-                        .load_head_commit_id(&source_version_id)
-                        .await?
-                        .ok_or_else(|| {
-                            LixError::version_not_found(
-                                source_version_id.clone(),
-                                "merge_version_preview",
-                                "source",
-                            )
-                        })?;
+                    let lifecycle = VersionLifecycle::new(&reader);
+                    let target_head = lifecycle
+                        .require_existing_commit_id(
+                            &active_version_id,
+                            VersionOperation::MergeVersionPreview,
+                            VersionReferenceRole::Target,
+                        )
+                        .await?;
+                    let source_head = lifecycle
+                        .require_existing_commit_id(
+                            &source_version_id,
+                            VersionOperation::MergeVersionPreview,
+                            VersionReferenceRole::Source,
+                        )
+                        .await?;
                     (target_head, source_head)
                 };
 
@@ -189,26 +184,21 @@ impl SessionContext {
 
                 let (target_head, source_head) = {
                     let reader = transaction.version_ref_reader();
-                    let target_head = reader
-                        .load_head_commit_id(&active_version_id)
-                        .await?
-                        .ok_or_else(|| {
-                            LixError::version_not_found(
-                                active_version_id.clone(),
-                                "merge_version",
-                                "target",
-                            )
-                        })?;
-                    let source_head = reader
-                        .load_head_commit_id(&source_version_id)
-                        .await?
-                        .ok_or_else(|| {
-                            LixError::version_not_found(
-                                source_version_id.clone(),
-                                "merge_version",
-                                "source",
-                            )
-                        })?;
+                    let lifecycle = VersionLifecycle::new(&reader);
+                    let target_head = lifecycle
+                        .require_existing_commit_id(
+                            &active_version_id,
+                            VersionOperation::MergeVersion,
+                            VersionReferenceRole::Target,
+                        )
+                        .await?;
+                    let source_head = lifecycle
+                        .require_existing_commit_id(
+                            &source_version_id,
+                            VersionOperation::MergeVersion,
+                            VersionReferenceRole::Source,
+                        )
+                        .await?;
                     (target_head, source_head)
                 };
 
@@ -300,7 +290,7 @@ impl SessionContext {
                 }
 
                 transaction
-                    .stage_write(StageWrite::AdoptedChanges {
+                    .stage_write(TransactionWrite::AdoptedChanges {
                         changes: adopted_changes,
                     })
                     .await?;

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

@@ -1,17 +1,18 @@
-//! Engine2 session boundary.
+//! Engine session boundary.
 //!
-//! Transaction invariant:
-//! any engine2 operation that may write must enter through
-//! `SessionContext::with_write_transaction`. Reads that influence writes are
-//! only available from the transaction capability. Session APIs must not
-//! open `Transaction` directly or use session-level read helpers inside write
-//! flows.
+//! Transaction invariant: a session has one execution lease. Parent-handle
+//! calls use it for implicit single-statement execution; explicit transactions
+//! hold it until commit or rollback. Session APIs must not open `Transaction`
+//! directly or use session-level read helpers inside write flows.
 
 mod context;
 mod create_version;
 mod execute;
 mod merge;
+#[cfg(feature = "storage-benches")]
+pub mod optimization9_sql2_bench;
 mod switch_version;
+mod transaction;
 
 pub use context::SessionContext;
 pub(crate) use context::{SessionMode, WORKSPACE_VERSION_KEY};
@@ -23,3 +24,4 @@ pub use merge::{
     MergeVersionReceipt,
 };
 pub use switch_version::{SwitchVersionOptions, SwitchVersionReceipt};
+pub use transaction::SessionTransaction;

package/dist-engine-src/src/session/optimization9_sql2_bench.rs

@@ -0,0 +1,100 @@
+use crate::functions::FunctionContext;
+use crate::session::context::{SessionContext, SessionSqlExecutionContext};
+use crate::sql2::{self, SqlLogicalPlan};
+use crate::storage::StorageReadScope;
+use crate::transaction::open_transaction;
+use crate::{LixError, SqlQueryResult, Value};
+
+/// Opaque read plan used by the Optimization 9 SQL2 diagnostic benchmark.
+///
+/// This module is gated behind `storage-benches` and exists only to split SQL2
+/// planning cost from SQL2 execution cost without widening the normal session
+/// API.
+pub struct PreparedReadPlan {
+    plan: SqlLogicalPlan,
+    read_scope:
+        StorageReadScope<Box<dyn crate::storage::StorageReadTransaction + Send + Sync + 'static>>,
+    runtime_functions: FunctionContext,
+}
+
+pub async fn plan_read_only(session: &SessionContext, sql: &str) -> Result<(), LixError> {
+    let prepared = prepare_read_plan(session, sql).await?;
+    drop(prepared.plan);
+    drop(prepared.runtime_functions);
+    prepared.read_scope.rollback().await
+}
+
+pub async fn plan_write_only(session: &SessionContext, sql: &str) -> Result<(), LixError> {
+    session.ensure_open()?;
+    let opened = open_transaction(
+        &session.mode,
+        session.storage.clone(),
+        std::sync::Arc::clone(&session.live_state),
+        std::sync::Arc::clone(&session.tracked_state),
+        std::sync::Arc::clone(&session.binary_cas),
+        std::sync::Arc::clone(&session.commit_store),
+        std::sync::Arc::clone(&session.version_ctx),
+        std::sync::Arc::clone(&session.catalog_context),
+    )
+    .await?;
+    let mut transaction = opened.transaction;
+    let runtime_functions = opened.runtime_functions;
+    let plan = sql2::create_write_logical_plan(&mut transaction, sql).await?;
+    drop(plan);
+    drop(runtime_functions);
+    transaction.rollback().await
+}
+
+pub async fn prepare_read_plan(
+    session: &SessionContext,
+    sql: &str,
+) -> Result<PreparedReadPlan, LixError> {
+    session.ensure_open()?;
+    let read_scope = StorageReadScope::new(session.storage.begin_read_transaction().await?);
+    let mut read_store = read_scope.store();
+    let live_state: std::sync::Arc<dyn crate::live_state::LiveStateReader> =
+        std::sync::Arc::new(session.live_state.reader(read_store.clone()));
+    let runtime_functions = FunctionContext::prepare(live_state.as_ref()).await?;
+    let functions = runtime_functions.provider();
+    let active_version_id = session
+        .active_version_id_from_reader(&mut read_store)
+        .await?;
+    let visible_schemas = session
+        .catalog_context
+        .schema_jsons_for_sql_read_planning(live_state.as_ref(), &active_version_id)
+        .await?;
+    let ctx = SessionSqlExecutionContext {
+        active_version_id: &active_version_id,
+        read_store,
+        live_state: std::sync::Arc::clone(&session.live_state),
+        binary_cas: std::sync::Arc::clone(&session.binary_cas),
+        commit_store: std::sync::Arc::clone(&session.commit_store),
+        version_ctx: std::sync::Arc::clone(&session.version_ctx),
+        visible_schemas,
+        functions: functions.clone(),
+    };
+    let plan = sql2::create_logical_plan(&ctx, sql).await?;
+    drop(ctx);
+    drop(live_state);
+
+    Ok(PreparedReadPlan {
+        plan,
+        read_scope,
+        runtime_functions,
+    })
+}
+
+pub async fn execute_read_plan(
+    prepared: PreparedReadPlan,
+    params: &[Value],
+) -> Result<SqlQueryResult, LixError> {
+    let PreparedReadPlan {
+        plan,
+        read_scope,
+        runtime_functions,
+    } = prepared;
+    let result = sql2::execute_logical_plan(plan, params).await;
+    read_scope.rollback().await?;
+    drop(runtime_functions);
+    result
+}

package/dist-engine-src/src/session/switch_version.rs

@@ -2,15 +2,14 @@ use std::sync::Arc;
 
 use serde_json::json;
 
-use crate::transaction::types::StageRow;
-use crate::version::VersionRefReader;
+use crate::transaction::types::{TransactionJson, TransactionWriteRow};
+use crate::version::{VersionLifecycle, VersionOperation, VersionReferenceRole};
 use crate::LixError;
 use crate::GLOBAL_VERSION_ID;
 
 use super::context::{SessionContext, SessionMode, WORKSPACE_VERSION_KEY};
 
 const KEY_VALUE_SCHEMA_KEY: &str = "lix_key_value";
-const KEY_VALUE_SCHEMA_VERSION: &str = "1";
 
 /// Options for switching a session to another version.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -40,17 +39,16 @@ impl SessionContext {
         let next_mode = self
             .with_write_transaction(|transaction| {
                 Box::pin(async move {
-                    let head = {
+                    {
                         let reader = transaction.version_ref_reader();
-                        reader.load_head_commit_id(&version_id).await?
+                        VersionLifecycle::new(&reader)
+                            .require_existing_commit_id(
+                                &version_id,
+                                VersionOperation::SwitchVersion,
+                                VersionReferenceRole::Target,
+                            )
+                            .await?
                     };
-                    if head.is_none() {
-                        return Err(LixError::version_not_found(
-                            version_id.clone(),
-                            "switch_version",
-                            "target",
-                        ));
-                    }
 
                     match current_mode {
                         SessionMode::Pinned { .. } => Ok(SessionMode::Pinned {
@@ -73,10 +71,11 @@ impl SessionContext {
             Arc::clone(&self.live_state),
             Arc::clone(&self.tracked_state),
             Arc::clone(&self.binary_cas),
-            Arc::clone(&self.changelog),
+            Arc::clone(&self.commit_store),
             Arc::clone(&self.version_ctx),
-            Arc::clone(&self.schema_registry),
+            Arc::clone(&self.catalog_context),
             self.closed_flag(),
+            self.active_transaction_flag(),
         );
         Ok((
             session,
@@ -87,20 +86,19 @@ impl SessionContext {
     }
 }
 
-fn workspace_version_stage_row(version_id: &str) -> Result<StageRow, LixError> {
-    Ok(StageRow {
+fn workspace_version_stage_row(version_id: &str) -> Result<TransactionWriteRow, LixError> {
+    Ok(TransactionWriteRow {
         entity_id: Some(crate::entity_identity::EntityIdentity::single(
             WORKSPACE_VERSION_KEY,
         )),
         schema_key: KEY_VALUE_SCHEMA_KEY.to_string(),
         file_id: None,
-        snapshot_content: Some(encode_snapshot(json!({
+        snapshot: Some(TransactionJson::from_value_unchecked(json!({
             "key": WORKSPACE_VERSION_KEY,
             "value": version_id,
-        }))?),
+        }))),
         metadata: None,
         origin: None,
-        schema_version: KEY_VALUE_SCHEMA_VERSION.to_string(),
         created_at: None,
         updated_at: None,
         global: true,
@@ -110,12 +108,3 @@ fn workspace_version_stage_row(version_id: &str) -> Result<StageRow, LixError> {
         version_id: GLOBAL_VERSION_ID.to_string(),
     })
 }
-
-fn encode_snapshot(value: serde_json::Value) -> Result<String, LixError> {
-    serde_json::to_string(&value).map_err(|error| {
-        LixError::new(
-            "LIX_ERROR_UNKNOWN",
-            format!("engine2 switch_version snapshot serialization failed: {error}"),
-        )
-    })
-}

package/dist-engine-src/src/session/transaction.rs

@@ -0,0 +1,76 @@
+use std::sync::Arc;
+
+use crate::functions::FunctionContext;
+use crate::transaction::{open_transaction, Transaction};
+use crate::LixError;
+
+use super::context::SessionTransactionGuard;
+use super::SessionContext;
+
+pub struct SessionTransaction {
+    pub(super) transaction: Option<Transaction>,
+    pub(super) runtime_functions: FunctionContext,
+    _transaction_guard: SessionTransactionGuard,
+}
+
+impl SessionContext {
+    pub async fn begin_transaction(&self) -> Result<SessionTransaction, LixError> {
+        self.ensure_open()?;
+        let transaction_guard = self.reserve_session_transaction()?;
+        let opened = match open_transaction(
+            &self.mode,
+            self.storage.clone(),
+            Arc::clone(&self.live_state),
+            Arc::clone(&self.tracked_state),
+            Arc::clone(&self.binary_cas),
+            Arc::clone(&self.commit_store),
+            Arc::clone(&self.version_ctx),
+            Arc::clone(&self.catalog_context),
+        )
+        .await
+        {
+            Ok(opened) => opened,
+            Err(error) => {
+                return Err(error);
+            }
+        };
+        Ok(SessionTransaction {
+            transaction: Some(opened.transaction),
+            runtime_functions: opened.runtime_functions,
+            _transaction_guard: transaction_guard,
+        })
+    }
+}
+
+impl SessionTransaction {
+    pub(super) fn transaction_mut(&mut self) -> Result<&mut Transaction, LixError> {
+        self.transaction
+            .as_mut()
+            .ok_or_else(|| transaction_state_error("Lix transaction is closed"))
+    }
+
+    pub async fn commit(mut self) -> Result<(), LixError> {
+        let transaction = self
+            .transaction
+            .take()
+            .ok_or_else(|| transaction_state_error("Lix transaction is closed"))?;
+        let result = transaction
+            .commit(&self.runtime_functions)
+            .await
+            .map(|_| ());
+        result
+    }
+
+    pub async fn rollback(mut self) -> Result<(), LixError> {
+        let transaction = self
+            .transaction
+            .take()
+            .ok_or_else(|| transaction_state_error("Lix transaction is closed"))?;
+        let result = transaction.rollback().await;
+        result
+    }
+}
+
+pub(crate) fn transaction_state_error(message: impl Into<String>) -> LixError {
+    LixError::new("LIX_INVALID_TRANSACTION_STATE", message)
+}

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

@@ -18,17 +18,18 @@ use datafusion::physical_plan::{
 };
 use futures_util::stream;
 
-use crate::changelog::{materialize_change, ChangelogScanRequest, MaterializedCanonicalChange};
+use crate::commit_store::ChangeScanRequest;
 use crate::serialize_row_metadata;
 use crate::LixError;
 
 use super::record_batch::record_batch_with_row_count;
 use super::result_metadata::json_field;
-use super::SqlChangelogQuerySource;
+use super::SqlCommitStoreQuerySource;
+use crate::commit_store::{materialize_change, MaterializedChange};
 
 pub(crate) async fn register_lix_change_provider(
     session: &datafusion::prelude::SessionContext,
-    query_source: SqlChangelogQuerySource,
+    query_source: SqlCommitStoreQuerySource,
 ) -> Result<(), LixError> {
     session
         .register_table("lix_change", Arc::new(LixChangeProvider::new(query_source)))
@@ -38,7 +39,7 @@ pub(crate) async fn register_lix_change_provider(
 
 struct LixChangeProvider {
     schema: SchemaRef,
-    query_source: SqlChangelogQuerySource,
+    query_source: SqlCommitStoreQuerySource,
 }
 
 impl std::fmt::Debug for LixChangeProvider {
@@ -48,7 +49,7 @@ impl std::fmt::Debug for LixChangeProvider {
 }
 
 impl LixChangeProvider {
-    fn new(query_source: SqlChangelogQuerySource) -> Self {
+    fn new(query_source: SqlCommitStoreQuerySource) -> Self {
         Self {
             schema: lix_change_schema(),
             query_source,
@@ -97,7 +98,7 @@ impl TableProvider for LixChangeProvider {
 }
 
 struct LixChangeScanExec {
-    query_source: SqlChangelogQuerySource,
+    query_source: SqlCommitStoreQuerySource,
     schema: SchemaRef,
     projection: Option<Vec<usize>>,
     limit: Option<usize>,
@@ -112,7 +113,7 @@ impl std::fmt::Debug for LixChangeScanExec {
 
 impl LixChangeScanExec {
     fn new(
-        query_source: SqlChangelogQuerySource,
+        query_source: SqlCommitStoreQuerySource,
         schema: SchemaRef,
         projection: Option<Vec<usize>>,
         limit: Option<usize>,
@@ -191,8 +192,8 @@ impl ExecutionPlan for LixChangeScanExec {
         let stream = stream::once(async move {
             let mut json_reader = query_source.json_reader;
             let canonical_changes = query_source
-                .changelog_reader
-                .scan_changes(&ChangelogScanRequest { limit })
+                .commit_store_reader
+                .scan_changes(&ChangeScanRequest { limit })
                 .await
                 .map_err(lix_error_to_datafusion_error)?;
             let mut changes = Vec::with_capacity(canonical_changes.len());
@@ -214,7 +215,6 @@ enum ChangeColumn {
     Id,
     EntityId,
     SchemaKey,
-    SchemaVersion,
     FileId,
     Metadata,
     CreatedAt,
@@ -224,9 +224,8 @@ enum ChangeColumn {
 fn lix_change_schema() -> SchemaRef {
     Arc::new(Schema::new(vec![
         Field::new("id", DataType::Utf8, false),
-        Field::new("entity_id", DataType::Utf8, false),
+        json_field("entity_id", false),
         Field::new("schema_key", DataType::Utf8, false),
-        Field::new("schema_version", DataType::Utf8, false),
         Field::new("file_id", DataType::Utf8, true),
         json_field("metadata", true),
         Field::new("created_at", DataType::Utf8, false),
@@ -239,7 +238,6 @@ fn change_projection_for_scan(projection: Option<&Vec<usize>>) -> Vec<ChangeColu
         ChangeColumn::Id,
         ChangeColumn::EntityId,
         ChangeColumn::SchemaKey,
-        ChangeColumn::SchemaVersion,
         ChangeColumn::FileId,
         ChangeColumn::Metadata,
         ChangeColumn::CreatedAt,
@@ -262,7 +260,7 @@ fn projected_schema(schema: &SchemaRef, projection: Option<&Vec<usize>>) -> Sche
 
 fn change_record_batch(
     projection: &[ChangeColumn],
-    changes: &[MaterializedCanonicalChange],
+    changes: &[MaterializedChange],
 ) -> Result<RecordBatch> {
     let arrays = projection
         .iter()
@@ -274,7 +272,7 @@ fn change_record_batch(
                     .map(|row| {
                         Some(
                             row.entity_id
-                                .as_string()
+                                .as_json_array_text()
                                 .expect("canonical change entity identity should project"),
                         )
                     })
@@ -283,9 +281,6 @@ fn change_record_batch(
             ChangeColumn::SchemaKey => {
                 string_array(changes.iter().map(|row| Some(row.schema_key.as_str())))
             }
-            ChangeColumn::SchemaVersion => {
-                string_array(changes.iter().map(|row| Some(row.schema_version.as_str())))
-            }
             ChangeColumn::FileId => string_array(changes.iter().map(|row| row.file_id.as_deref())),
             ChangeColumn::Metadata => Arc::new(StringArray::from(
                 changes
@@ -312,9 +307,8 @@ fn change_schema(projection: &[ChangeColumn]) -> SchemaRef {
             .iter()
             .map(|column| match column {
                 ChangeColumn::Id => Field::new("id", DataType::Utf8, false),
-                ChangeColumn::EntityId => Field::new("entity_id", DataType::Utf8, false),
+                ChangeColumn::EntityId => json_field("entity_id", false),
                 ChangeColumn::SchemaKey => Field::new("schema_key", DataType::Utf8, false),
-                ChangeColumn::SchemaVersion => Field::new("schema_version", DataType::Utf8, false),
                 ChangeColumn::FileId => Field::new("file_id", DataType::Utf8, true),
                 ChangeColumn::Metadata => json_field("metadata", true),
                 ChangeColumn::CreatedAt => Field::new("created_at", DataType::Utf8, false),