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

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

@@ -0,0 +1,94 @@
+use crate::branch::{
+    branch_descriptor_stage_row, branch_ref_stage_row, BranchLifecycle, BranchOperation,
+    BranchReferenceRole,
+};
+use crate::storage::StorageBackend;
+use crate::transaction::types::{TransactionWrite, TransactionWriteMode};
+use crate::LixError;
+
+use super::context::SessionContext;
+
+/// Options for creating a new branch from the session's active branch.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CreateBranchOptions {
+    /// Optional caller-provided branch id. If omitted, engine generates one.
+    pub id: Option<String>,
+    /// User-facing branch name.
+    pub name: String,
+    /// Optional commit id for the new branch head. If omitted, the current
+    /// active branch head is used.
+    pub from_commit_id: Option<String>,
+}
+
+/// Receipt returned after creating a branch.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CreateBranchReceipt {
+    pub id: String,
+    pub name: String,
+    pub hidden: bool,
+    pub commit_id: String,
+}
+
+impl<B> SessionContext<B>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    /// Creates a new branch from this session's current branch head.
+    ///
+    /// Branch descriptors are tracked global facts so every branch agrees on
+    /// which branches exist. Branch refs are untracked global moving pointers,
+    /// so creating a ref does not add another changelog fact.
+    pub async fn create_branch(
+        &self,
+        options: CreateBranchOptions,
+    ) -> Result<CreateBranchReceipt, LixError> {
+        self.with_write_transaction(|transaction| {
+            Box::pin(async move {
+                let branch_id = options
+                    .id
+                    .unwrap_or_else(|| transaction.functions().call_uuid_v7());
+                let source_head = if let Some(from_commit_id) = options.from_commit_id {
+                    let mut commit_graph = transaction.commit_graph_reader();
+                    BranchLifecycle::require_existing_commit(
+                        &mut commit_graph,
+                        &from_commit_id,
+                        BranchOperation::CreateBranch,
+                        BranchReferenceRole::CommitSource,
+                    )
+                    .await?;
+                    from_commit_id
+                } else {
+                    let active_branch_id = transaction.active_branch_id().to_string();
+                    let reader = transaction.branch_ref_reader();
+                    BranchLifecycle::new(&reader)
+                        .require_existing_commit_id(
+                            &active_branch_id,
+                            BranchOperation::CreateBranch,
+                            BranchReferenceRole::Source,
+                        )
+                        .await?
+                };
+
+                transaction
+                    .stage_write(TransactionWrite::Rows {
+                        mode: TransactionWriteMode::Insert,
+                        rows: vec![
+                            branch_descriptor_stage_row(&branch_id, &options.name, false),
+                            branch_ref_stage_row(&branch_id, &source_head),
+                        ],
+                    })
+                    .await?;
+
+                Ok(CreateBranchReceipt {
+                    id: branch_id,
+                    name: options.name,
+                    hidden: false,
+                    commit_id: source_head,
+                })
+            })
+        })
+        .await
+    }
+}

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

@@ -2,10 +2,12 @@ use std::sync::Arc;
 
 use crate::functions::FunctionContext;
 use crate::sql2;
-use crate::storage::{StorageReadScope, StorageWriteSet};
+use crate::storage::{StorageBackend, StorageReadOptions, StorageWriteOptions, StorageWriteSet};
+use crate::transaction::{begin_commit_boundary, commit_at_boundary};
 use crate::{LixError, LixNotice, SqlQueryResult, Value};
 
-use super::context::{SessionContext, SessionSqlExecutionContext};
+use super::context::{SessionContext, SessionSqlExecutionContext, SessionWriteAccess};
+use super::transaction::SessionTransaction;
 
 /// Result of executing one SQL statement through engine.
 ///
@@ -286,30 +288,38 @@ impl RowRef<'_> {
     }
 }
 
-impl SessionContext {
+impl<B> SessionContext<B>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
     /// Executes one DataFusion SQL statement against this Lix session.
     ///
     /// The SQL dialect is DataFusion SQL, not SQLite SQL. Positional
-    /// placeholders use `$1`, `$2`, and so on. SQLite-specific catalog tables
+    /// placeholders use `?` or `$1`, `$2`, and so on. SQLite-specific catalog tables
     /// and transaction statements such as `sqlite_master`, `BEGIN`, and
     /// `COMMIT` are not part of this contract; use `information_schema` for
     /// catalog inspection. Lix owns transaction boundaries for each statement.
     pub async fn execute(&self, sql: &str, params: &[Value]) -> Result<ExecuteResult, LixError> {
         self.ensure_open()?;
-        let kind = sql2::classify_statement(sql)?;
-        if kind == sql2::SqlStatementKind::Write {
-            let sql = sql.to_string();
-            let sql_for_error = sql.clone();
+        let statement = sql2::parse_statement(sql)?;
+        if sql2::bind_statement_route(&statement)? == sql2::BoundStatementRoute::Write {
+            let write_access = self.begin_session_write_access().await?;
+            let sql_for_error = sql.to_string();
             let params = params.to_vec();
             return self
-                .with_write_transaction(|transaction| {
+                .with_write_transaction_reserved(write_access, |transaction| {
                     Box::pin(async move {
                         // Re-plan against the transaction-backed write
                         // session so provider hooks read and stage through the
                         // transaction-owned SQL write context.
-                        let tx_plan = sql2::create_write_logical_plan(transaction, &sql).await?;
-                        let result = sql2::execute_logical_plan(tx_plan, &params).await?;
-                        let affected_rows = affected_rows_from_query_result(result)?;
+                        transaction.prepare_sql_visible_schemas().await?;
+                        let tx_plan =
+                            sql2::create_write_logical_plan_from_parsed(transaction, statement)
+                                .await?;
+                        let affected_rows =
+                            sql2::execute_write_logical_plan(transaction, tx_plan, &params).await?;
                         Ok(ExecuteResult::from_rows_affected(affected_rows))
                     })
                 })
@@ -317,30 +327,39 @@ impl SessionContext {
                 .map_err(|error| normalize_sql_surface_error(error, &sql_for_error));
         }
 
-        let read_scope = StorageReadScope::new(self.storage.begin_read_transaction().await?);
+        let runtime_write_access = if sql2::statement_has_durable_runtime_function(&statement) {
+            Some(self.begin_session_write_access().await?)
+        } else {
+            None
+        };
+        let _operation_guard = if runtime_write_access.is_some() {
+            None
+        } else {
+            Some(self.begin_session_operation()?)
+        };
+        let read_scope = self.storage.begin_read(StorageReadOptions::default())?;
         let read_result = async {
             let mut read_store = read_scope.store();
             let live_state: Arc<dyn crate::live_state::LiveStateReader> =
                 Arc::new(self.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 = self.active_version_id_from_reader(&mut read_store).await?;
+            let active_branch_id = self.active_branch_id_from_reader(&mut read_store).await?;
             let visible_schemas = self
                 .catalog_context
-                .schema_jsons_for_sql_read_planning(live_state.as_ref(), &active_version_id)
+                .schema_jsons_for_sql_read_planning(live_state.as_ref(), &active_branch_id)
                 .await?;
             let ctx = SessionSqlExecutionContext {
-                active_version_id: &active_version_id,
+                active_branch_id: &active_branch_id,
                 read_store,
                 live_state: Arc::clone(&self.live_state),
                 binary_cas: Arc::clone(&self.binary_cas),
-                commit_store: Arc::clone(&self.commit_store),
-                version_ctx: Arc::clone(&self.version_ctx),
+                branch_ctx: Arc::clone(&self.branch_ctx),
                 visible_schemas,
                 functions: functions.clone(),
             };
 
-            let plan = sql2::create_logical_plan(&ctx, sql).await?;
+            let plan = sql2::create_logical_plan_from_parsed(&ctx, sql, statement).await?;
             let result = sql2::execute_logical_plan(plan, params).await?;
             drop(ctx);
             drop(live_state);
@@ -348,19 +367,55 @@ impl SessionContext {
         };
         let (runtime_functions, result) = match read_result.await {
             Ok(result) => {
-                read_scope.rollback().await?;
+                read_scope.close()?;
                 result
             }
             Err(error) => {
-                let _ = read_scope.rollback().await;
+                let _ = read_scope.close();
                 return Err(normalize_sql_surface_error(error, sql));
             }
         };
-        self.persist_runtime_functions_if_needed(&runtime_functions)
+        self.persist_runtime_functions_if_needed(&runtime_functions, runtime_write_access.as_ref())
             .await?;
         Ok(ExecuteResult::from_sql_query_result(result))
     }
 
+    #[cfg(test)]
+    pub(crate) async fn execute_with_write_executor_mode(
+        &self,
+        sql: &str,
+        params: &[Value],
+        mode: sql2::WriteExecutorMode,
+    ) -> Result<ExecuteResult, LixError> {
+        self.ensure_open()?;
+        let statement = sql2::parse_statement(sql)?;
+        if sql2::bind_statement_route(&statement)? == sql2::BoundStatementRoute::Write {
+            let write_access = self.begin_session_write_access().await?;
+            let sql_for_error = sql.to_string();
+            let params = params.to_vec();
+            return self
+                .with_write_transaction_reserved(write_access, |transaction| {
+                    Box::pin(async move {
+                        transaction.prepare_sql_visible_schemas().await?;
+                        let tx_plan =
+                            sql2::create_write_logical_plan_from_parsed(transaction, statement)
+                                .await?;
+                        let affected_rows = sql2::execute_write_logical_plan_with_mode(
+                            transaction,
+                            tx_plan,
+                            &params,
+                            mode,
+                        )
+                        .await?;
+                        Ok(ExecuteResult::from_rows_affected(affected_rows))
+                    })
+                })
+                .await
+                .map_err(|error| normalize_sql_surface_error(error, &sql_for_error));
+        }
+        self.execute(sql, params).await
+    }
+
     /// Persists execution-scoped runtime function state after a successful read.
     ///
     /// Reads do not otherwise own a write transaction, but SQL functions such as
@@ -370,19 +425,198 @@ impl SessionContext {
     async fn persist_runtime_functions_if_needed(
         &self,
         runtime_functions: &FunctionContext,
+        runtime_write_access: Option<&SessionWriteAccess>,
     ) -> Result<(), LixError> {
-        let mut transaction = self.storage.begin_write_transaction().await?;
         let mut writes = StorageWriteSet::new();
         runtime_functions
             .stage_persist_if_needed(&mut writes)
             .await?;
-        if !writes.is_empty() {
-            writes.apply(&mut transaction.as_mut()).await?;
+        if writes.is_empty() {
+            return Ok(());
+        }
+        if runtime_write_access.is_none() {
+            return Err(LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "runtime function state changed without reserved write access",
+            ));
         }
-        transaction.commit().await
+        let commit_boundary = self.transaction_commit_boundary();
+        let _commit_guard = begin_commit_boundary(Some(&commit_boundary));
+        commit_at_boundary(Some(&commit_boundary), || {
+            self.storage
+                .commit_write_set(writes, StorageWriteOptions::default())?;
+            Ok(())
+        })?;
+        Ok(())
     }
 }
 
+impl<B> SessionTransaction<B>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    /// Executes one SQL statement inside this transaction.
+    ///
+    /// Write statements are staged until `commit()`. Read statements use the
+    /// transaction overlay, so they can observe writes staged by earlier calls
+    /// on this transaction handle.
+    pub async fn execute(
+        &mut self,
+        sql: &str,
+        params: &[Value],
+    ) -> Result<ExecuteResult, LixError> {
+        let _operation_guard = self.begin_session_operation()?;
+        let statement = sql2::parse_statement(sql)?;
+        let transaction = self.transaction_mut()?;
+        match sql2::bind_statement_route(&statement)? {
+            sql2::BoundStatementRoute::Write => {
+                execute_transaction_write_auto(transaction, statement, params)
+                    .await
+                    .map_err(|error| normalize_sql_surface_error(error, sql))
+            }
+            sql2::BoundStatementRoute::Read => {
+                let read_ctx = transaction.sql_read_execution_context().await?;
+                let read_result = async {
+                    let plan = sql2::create_transaction_read_logical_plan_from_parsed(
+                        &read_ctx,
+                        transaction,
+                        sql,
+                        statement,
+                    )
+                    .await?;
+                    sql2::execute_logical_plan(plan, params).await
+                }
+                .await;
+                let close_result = read_ctx.close();
+                let result = match read_result {
+                    Ok(result) => {
+                        close_result?;
+                        result
+                    }
+                    Err(error) => {
+                        let _ = close_result;
+                        return Err(normalize_sql_surface_error(error, sql));
+                    }
+                };
+                Ok(ExecuteResult::from_sql_query_result(result))
+            }
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) async fn execute_with_write_executor_mode(
+        &mut self,
+        sql: &str,
+        params: &[Value],
+        mode: sql2::WriteExecutorMode,
+    ) -> Result<ExecuteResult, LixError> {
+        let _operation_guard = self.begin_session_operation()?;
+        let statement = sql2::parse_statement(sql)?;
+        let transaction = self.transaction_mut()?;
+        match sql2::bind_statement_route(&statement)? {
+            sql2::BoundStatementRoute::Write => {
+                execute_transaction_write_with_mode(transaction, statement, params, mode)
+                    .await
+                    .map_err(|error| normalize_sql_surface_error(error, sql))
+            }
+            sql2::BoundStatementRoute::Read => self.execute(sql, params).await,
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) async fn execute_with_write_executor_mode_and_trace(
+        &mut self,
+        sql: &str,
+        params: &[Value],
+        mode: sql2::WriteExecutorMode,
+    ) -> Result<(ExecuteResult, Option<sql2::WriteExecutorPath>), LixError> {
+        let _operation_guard = self.begin_session_operation()?;
+        let statement = sql2::parse_statement(sql)?;
+        let transaction = self.transaction_mut()?;
+        match sql2::bind_statement_route(&statement)? {
+            sql2::BoundStatementRoute::Write => {
+                execute_transaction_write_with_mode_and_trace(transaction, statement, params, mode)
+                    .await
+                    .map_err(|error| normalize_sql_surface_error(error, sql))
+            }
+            sql2::BoundStatementRoute::Read => {
+                self.execute(sql, params).await.map(|result| (result, None))
+            }
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) async fn scan_live_state_for_test(
+        &mut self,
+        request: &crate::live_state::LiveStateScanRequest,
+    ) -> Result<Vec<crate::live_state::MaterializedLiveStateRow>, LixError> {
+        let _operation_guard = self.begin_session_operation()?;
+        let transaction = self.transaction_mut()?;
+        <crate::transaction::Transaction<B> as sql2::SqlWriteExecutionContext>::scan_live_state(
+            transaction,
+            request,
+        )
+        .await
+    }
+}
+
+async fn execute_transaction_write_auto<B>(
+    transaction: &mut crate::transaction::Transaction<B>,
+    statement: datafusion::sql::parser::Statement,
+    params: &[Value],
+) -> Result<ExecuteResult, LixError>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    transaction.prepare_sql_visible_schemas().await?;
+    let tx_plan = sql2::create_write_logical_plan_from_parsed(transaction, statement).await?;
+    let affected_rows = sql2::execute_write_logical_plan(transaction, tx_plan, params).await?;
+    Ok(ExecuteResult::from_rows_affected(affected_rows))
+}
+
+#[cfg(test)]
+async fn execute_transaction_write_with_mode<B>(
+    transaction: &mut crate::transaction::Transaction<B>,
+    statement: datafusion::sql::parser::Statement,
+    params: &[Value],
+    mode: sql2::WriteExecutorMode,
+) -> Result<ExecuteResult, LixError>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    transaction.prepare_sql_visible_schemas().await?;
+    let tx_plan = sql2::create_write_logical_plan_from_parsed(transaction, statement).await?;
+    let affected_rows =
+        sql2::execute_write_logical_plan_with_mode(transaction, tx_plan, params, mode).await?;
+    Ok(ExecuteResult::from_rows_affected(affected_rows))
+}
+
+#[cfg(test)]
+async fn execute_transaction_write_with_mode_and_trace<B>(
+    transaction: &mut crate::transaction::Transaction<B>,
+    statement: datafusion::sql::parser::Statement,
+    params: &[Value],
+    mode: sql2::WriteExecutorMode,
+) -> Result<(ExecuteResult, Option<sql2::WriteExecutorPath>), LixError>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    transaction.prepare_sql_visible_schemas().await?;
+    let tx_plan = sql2::create_write_logical_plan_from_parsed(transaction, statement).await?;
+    let (affected_rows, path) =
+        sql2::execute_write_logical_plan_with_mode_and_trace(transaction, tx_plan, params, mode)
+            .await?;
+    Ok((ExecuteResult::from_rows_affected(affected_rows), Some(path)))
+}
+
 fn normalize_sql_surface_error(error: LixError, sql: &str) -> LixError {
     if error.code.starts_with("LIX_ERROR_PATH_") && sql_uses_public_filesystem_path_surface(sql) {
         return LixError {
@@ -401,15 +635,6 @@ fn normalize_sql_surface_error(error: LixError, sql: &str) -> LixError {
             ..error
         };
     }
-    if error.code == LixError::CODE_FOREIGN_KEY {
-        let lower = error.message.to_ascii_lowercase();
-        if lower.contains("schema 'lix_version_ref'") && lower.contains("target 'lix_commit.") {
-            return LixError {
-                code: LixError::CODE_VERSION_NOT_FOUND.to_string(),
-                ..error
-            };
-        }
-    }
     error
 }
 
@@ -418,28 +643,6 @@ fn sql_uses_public_filesystem_path_surface(sql: &str) -> bool {
     (lower.contains("lix_file") || lower.contains("lix_directory")) && lower.contains("path")
 }
 
-fn affected_rows_from_query_result(result: SqlQueryResult) -> Result<u64, LixError> {
-    let Some(first_row) = result.rows.first() else {
-        return Ok(0);
-    };
-    let Some(first_value) = first_row.first() else {
-        return Ok(0);
-    };
-    match first_value {
-        Value::Integer(value) if *value >= 0 => Ok(*value as u64),
-        Value::Text(value) => value.parse::<u64>().map_err(|error| {
-            LixError::new(
-                "LIX_ERROR_UNKNOWN",
-                format!("failed to parse affected row count from SQL result: {error}"),
-            )
-        }),
-        other => Err(LixError::new(
-            "LIX_ERROR_UNKNOWN",
-            format!("expected affected row count, got {other:?}"),
-        )),
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

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

@@ -1,4 +1,4 @@
-use crate::storage::StorageReader;
+use crate::storage::StorageRead;
 use crate::tracked_state::{
     plan_merge, TrackedStateDiff, TrackedStateDiffRequest, TrackedStateMergePlan,
     TrackedStateStoreReader,
@@ -44,7 +44,7 @@ pub(crate) async fn analyze<S>(
     commits: MergeCommits,
 ) -> Result<MergeAnalysis, LixError>
 where
-    S: StorageReader,
+    S: StorageRead + Send + Sync,
 {
     let request = TrackedStateDiffRequest::default();
     let source_diff = reader
@@ -56,7 +56,13 @@ where
         TrackedStateDiff::default()
     } else {
         reader
-            .diff_commits(&commits.base_commit_id, &commits.target_commit_id, &request)
+            .diff_commits_with_validation(
+                &commits.base_commit_id,
+                &commits.target_commit_id,
+                &request,
+                false,
+                true,
+            )
             .await?
     };