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

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

@@ -6,20 +6,22 @@ use std::sync::Arc;
 use serde_json::Value as JsonValue;
 
 use crate::binary_cas::{BinaryCasContext, BlobDataReader};
-use crate::changelog::ChangelogContext;
+use crate::catalog::CatalogContext;
 use crate::commit_graph::{CommitGraphContext, CommitGraphReader};
+use crate::commit_store::CommitStoreContext;
 use crate::entity_identity::EntityIdentity;
 use crate::functions::FunctionProviderHandle;
 use crate::json_store::JsonStoreContext;
 use crate::live_state::{LiveStateContext, LiveStateReader, LiveStateRowRequest};
-use crate::schema_registry::SchemaRegistry;
-use crate::sql2::{ChangelogQuerySource, SqlChangelogQuerySource, SqlExecutionContext};
+use crate::sql2::{CommitStoreQuerySource, SqlCommitStoreQuerySource, SqlExecutionContext};
 use crate::storage::{
     ScopedStorageReader, StorageContext, StorageReadScope, StorageReadTransaction, StorageReader,
 };
 use crate::tracked_state::TrackedStateContext;
 use crate::transaction::{open_transaction, Transaction};
-use crate::version::{VersionContext, VersionRefReader};
+use crate::version::{
+    VersionContext, VersionLifecycle, VersionOperation, VersionRefReader, VersionReferenceRole,
+};
 use crate::GLOBAL_VERSION_ID;
 use crate::{LixError, NullableKeyFilter};
 
@@ -31,13 +33,13 @@ pub(crate) enum SessionMode {
     Workspace,
 }
 
-/// Session-context state for engine2 execution.
+/// Session-context state for engine execution.
 ///
 /// A session context pins the active version selector and shared execution
 /// services. Each call to `execute(...)` projects this state into a read-only
 /// SQL context or a transaction-owned write context.
 ///
-/// Write transaction invariant: any engine2 operation that may write must enter
+/// Write transaction invariant: any engine operation that may write must enter
 /// through `SessionContext::with_write_transaction`. Reads that influence writes
 /// are only available from that transaction capability, not from session-level
 /// helpers.
@@ -48,9 +50,9 @@ pub struct SessionContext {
     pub(super) live_state: Arc<LiveStateContext>,
     pub(super) tracked_state: Arc<TrackedStateContext>,
     pub(super) binary_cas: Arc<BinaryCasContext>,
-    pub(super) changelog: Arc<ChangelogContext>,
+    pub(super) commit_store: Arc<CommitStoreContext>,
     pub(super) version_ctx: Arc<VersionContext>,
-    pub(super) schema_registry: Arc<SchemaRegistry>,
+    pub(super) catalog_context: Arc<CatalogContext>,
     closed: Arc<AtomicBool>,
 }
 
@@ -60,9 +62,9 @@ impl SessionContext {
         live_state: Arc<LiveStateContext>,
         tracked_state: Arc<TrackedStateContext>,
         binary_cas: Arc<BinaryCasContext>,
-        changelog: Arc<ChangelogContext>,
+        commit_store: Arc<CommitStoreContext>,
         version_ctx: Arc<VersionContext>,
-        schema_registry: Arc<SchemaRegistry>,
+        catalog_context: Arc<CatalogContext>,
     ) -> Result<Self, LixError> {
         let session = Self::new(
             SessionMode::Workspace,
@@ -70,9 +72,9 @@ impl SessionContext {
             live_state,
             tracked_state,
             binary_cas,
-            changelog,
+            commit_store,
             version_ctx,
-            schema_registry,
+            catalog_context,
         );
         session.active_version_id().await?;
         Ok(session)
@@ -84,9 +86,9 @@ impl SessionContext {
         live_state: Arc<LiveStateContext>,
         tracked_state: Arc<TrackedStateContext>,
         binary_cas: Arc<BinaryCasContext>,
-        changelog: Arc<ChangelogContext>,
+        commit_store: Arc<CommitStoreContext>,
         version_ctx: Arc<VersionContext>,
-        schema_registry: Arc<SchemaRegistry>,
+        catalog_context: Arc<CatalogContext>,
     ) -> Result<Self, LixError> {
         Ok(Self::new(
             SessionMode::Pinned {
@@ -96,9 +98,9 @@ impl SessionContext {
             live_state,
             tracked_state,
             binary_cas,
-            changelog,
+            commit_store,
             version_ctx,
-            schema_registry,
+            catalog_context,
         ))
     }
 
@@ -108,9 +110,9 @@ impl SessionContext {
         live_state: Arc<LiveStateContext>,
         tracked_state: Arc<TrackedStateContext>,
         binary_cas: Arc<BinaryCasContext>,
-        changelog: Arc<ChangelogContext>,
+        commit_store: Arc<CommitStoreContext>,
         version_ctx: Arc<VersionContext>,
-        schema_registry: Arc<SchemaRegistry>,
+        catalog_context: Arc<CatalogContext>,
     ) -> Self {
         Self::new_with_closed(
             mode,
@@ -118,9 +120,9 @@ impl SessionContext {
             live_state,
             tracked_state,
             binary_cas,
-            changelog,
+            commit_store,
             version_ctx,
-            schema_registry,
+            catalog_context,
             Arc::new(AtomicBool::new(false)),
         )
     }
@@ -131,9 +133,9 @@ impl SessionContext {
         live_state: Arc<LiveStateContext>,
         tracked_state: Arc<TrackedStateContext>,
         binary_cas: Arc<BinaryCasContext>,
-        changelog: Arc<ChangelogContext>,
+        commit_store: Arc<CommitStoreContext>,
         version_ctx: Arc<VersionContext>,
-        schema_registry: Arc<SchemaRegistry>,
+        catalog_context: Arc<CatalogContext>,
         closed: Arc<AtomicBool>,
     ) -> Self {
         Self {
@@ -142,9 +144,9 @@ impl SessionContext {
             live_state,
             tracked_state,
             binary_cas,
-            changelog,
+            commit_store,
             version_ctx,
-            schema_registry,
+            catalog_context,
             closed,
         }
     }
@@ -256,18 +258,14 @@ impl SessionContext {
             })?
             .to_string();
 
-        let head = self
-            .version_ctx
-            .ref_reader(&mut *reader)
-            .load_head_commit_id(&version_id)
+        let version_ref = self.version_ctx.ref_reader(&mut *reader);
+        VersionLifecycle::new(&version_ref)
+            .require_existing_ref(
+                &version_id,
+                VersionOperation::LoadWorkspaceSelector,
+                VersionReferenceRole::WorkspaceSelector,
+            )
             .await?;
-        if head.is_none() {
-            return Err(LixError::version_not_found(
-                version_id,
-                "load_workspace_version_id",
-                "workspace_selector",
-            ));
-        }
 
         Ok(version_id)
     }
@@ -285,9 +283,9 @@ 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),
         )
         .await?;
         let mut transaction = opened.transaction;
@@ -321,7 +319,7 @@ pub(super) struct SessionSqlExecutionContext<'a> {
         ScopedStorageReader<Box<dyn StorageReadTransaction + Send + Sync + 'static>>,
     pub(super) live_state: Arc<LiveStateContext>,
     pub(super) binary_cas: Arc<BinaryCasContext>,
-    pub(super) changelog: Arc<ChangelogContext>,
+    pub(super) commit_store: Arc<CommitStoreContext>,
     pub(super) version_ctx: Arc<VersionContext>,
     pub(super) visible_schemas: Vec<JsonValue>,
     pub(super) functions: FunctionProviderHandle,
@@ -336,16 +334,16 @@ impl SqlExecutionContext for SessionSqlExecutionContext<'_> {
         Arc::new(self.live_state.reader(self.read_store.clone())) as Arc<dyn LiveStateReader>
     }
 
-    fn changelog_query_source(&self) -> SqlChangelogQuerySource {
+    fn commit_store_query_source(&self) -> SqlCommitStoreQuerySource {
         let read_scope = StorageReadScope::new(self.read_store.clone());
-        ChangelogQuerySource {
-            changelog_reader: Arc::new(self.changelog.reader(read_scope.store())),
+        CommitStoreQuerySource {
+            commit_store_reader: Arc::new(self.commit_store.reader(read_scope.store())),
             json_reader: JsonStoreContext::new().reader(read_scope.store()),
         }
     }
 
     fn commit_graph(&self) -> Box<dyn CommitGraphReader> {
-        Box::new(CommitGraphContext::new(ChangelogContext::new()).reader(self.read_store.clone()))
+        Box::new(CommitGraphContext::new().reader(self.read_store.clone()))
     }
 
     fn version_ref(&self) -> Arc<dyn VersionRefReader> {

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

@@ -1,5 +1,8 @@
-use crate::transaction::types::{StageWrite, StageWriteMode};
-use crate::version::{version_descriptor_stage_row, version_ref_stage_row, VersionRefReader};
+use crate::transaction::types::{TransactionWrite, TransactionWriteMode};
+use crate::version::{
+    version_descriptor_stage_row, version_ref_stage_row, VersionLifecycle, VersionOperation,
+    VersionReferenceRole,
+};
 use crate::LixError;
 
 use super::context::SessionContext;
@@ -7,7 +10,7 @@ use super::context::SessionContext;
 /// Options for creating a new version from the session's active version.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreateVersionOptions {
-    /// Optional caller-provided version id. If omitted, engine2 generates one.
+    /// Optional caller-provided version id. If omitted, engine generates one.
     pub id: Option<String>,
     /// User-facing version name.
     pub name: String,
@@ -41,25 +44,30 @@ impl SessionContext {
                     .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();
+                    VersionLifecycle::require_existing_commit(
+                        &mut commit_graph,
+                        &from_commit_id,
+                        VersionOperation::CreateVersion,
+                        VersionReferenceRole::CommitSource,
+                    )
+                    .await?;
                     from_commit_id
                 } else {
                     let active_version_id = transaction.active_version_id().to_string();
                     let reader = transaction.version_ref_reader();
-                    reader
-                        .load_head_commit_id(&active_version_id)
+                    VersionLifecycle::new(&reader)
+                        .require_existing_commit_id(
+                            &active_version_id,
+                            VersionOperation::CreateVersion,
+                            VersionReferenceRole::Source,
+                        )
                         .await?
-                        .ok_or_else(|| {
-                            LixError::version_not_found(
-                                active_version_id.clone(),
-                                "create_version",
-                                "source",
-                            )
-                        })?
                 };
 
                 transaction
-                    .stage_write(StageWrite::Rows {
-                        mode: StageWriteMode::Insert,
+                    .stage_write(TransactionWrite::Rows {
+                        mode: TransactionWriteMode::Insert,
                         rows: vec![
                             version_descriptor_stage_row(&version_id, &options.name, false),
                             version_ref_stage_row(&version_id, &source_head),

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

@@ -1,14 +1,13 @@
 use std::sync::Arc;
 
 use crate::functions::FunctionContext;
-use crate::json_store::JsonStoreContext;
 use crate::sql2;
 use crate::storage::{StorageReadScope, StorageWriteSet};
 use crate::{LixError, LixNotice, SqlQueryResult, Value};
 
 use super::context::{SessionContext, SessionSqlExecutionContext};
 
-/// Result of executing one SQL statement through engine2.
+/// Result of executing one SQL statement through engine.
 ///
 /// Column names live once at the result-set level. Individual rows only own
 /// values, which keeps the public API row-oriented without copying schema
@@ -251,7 +250,7 @@ fn value_type_error(expected: &str, actual: &Value) -> LixError {
     )
 }
 
-/// Borrowed row view with access to the result-set column names.
+/// Zero-copy row view with access to the result-set column names.
 ///
 /// This is the ergonomic path for callers that want `row.get("column")`
 /// without storing column metadata on every owned row.
@@ -300,6 +299,7 @@ impl SessionContext {
         let kind = sql2::classify_statement(sql)?;
         if kind == sql2::SqlStatementKind::Write {
             let sql = sql.to_string();
+            let sql_for_error = sql.clone();
             let params = params.to_vec();
             return self
                 .with_write_transaction(|transaction| {
@@ -313,7 +313,8 @@ impl SessionContext {
                         Ok(ExecuteResult::from_rows_affected(affected_rows))
                     })
                 })
-                .await;
+                .await
+                .map_err(|error| normalize_sql_surface_error(error, &sql_for_error));
         }
 
         let read_scope = StorageReadScope::new(self.storage.begin_read_transaction().await?);
@@ -325,15 +326,15 @@ impl SessionContext {
             let functions = runtime_functions.provider();
             let active_version_id = self.active_version_id_from_reader(&mut read_store).await?;
             let visible_schemas = self
-                .schema_registry
-                .visible_schemas(live_state.as_ref(), &active_version_id)
+                .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: Arc::clone(&self.live_state),
                 binary_cas: Arc::clone(&self.binary_cas),
-                changelog: Arc::clone(&self.changelog),
+                commit_store: Arc::clone(&self.commit_store),
                 version_ctx: Arc::clone(&self.version_ctx),
                 visible_schemas,
                 functions: functions.clone(),
@@ -352,7 +353,7 @@ impl SessionContext {
             }
             Err(error) => {
                 let _ = read_scope.rollback().await;
-                return Err(error);
+                return Err(normalize_sql_surface_error(error, sql));
             }
         };
         self.persist_runtime_functions_if_needed(&runtime_functions)
@@ -372,13 +373,8 @@ impl SessionContext {
     ) -> Result<(), LixError> {
         let mut transaction = self.storage.begin_write_transaction().await?;
         let mut writes = StorageWriteSet::new();
-        let mut json_writer = JsonStoreContext::new().writer();
         runtime_functions
-            .stage_persist_if_needed(
-                &mut self.live_state.writer(transaction.as_mut()),
-                &mut writes,
-                &mut json_writer,
-            )
+            .stage_persist_if_needed(&mut writes)
             .await?;
         if !writes.is_empty() {
             writes.apply(&mut transaction.as_mut()).await?;
@@ -387,6 +383,41 @@ impl SessionContext {
     }
 }
 
+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 {
+            code: LixError::CODE_INVALID_PARAM.to_string(),
+            ..error
+        };
+    }
+    if error.code == LixError::CODE_INVALID_JSON_PATH
+        && error
+            .message
+            .to_ascii_lowercase()
+            .contains("uses variadic path segments")
+    {
+        return LixError {
+            code: LixError::CODE_INVALID_PARAM.to_string(),
+            ..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
+}
+
+fn sql_uses_public_filesystem_path_surface(sql: &str) -> bool {
+    let lower = sql.to_ascii_lowercase();
+    (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);

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

@@ -1,10 +1,10 @@
 use crate::tracked_state::TrackedStateMergePlan;
-use crate::transaction::types::StageAdoptedChange;
+use crate::transaction::types::TransactionAdoptedChange;
 
 pub(crate) fn adopted_changes_from_merge_plan(
     plan: &TrackedStateMergePlan,
     target_version_id: &str,
-) -> Vec<StageAdoptedChange> {
+) -> Vec<TransactionAdoptedChange> {
     plan.patches
         .iter()
         .map(|patch| stage_adopted_change_from_patch(patch, target_version_id))
@@ -14,8 +14,8 @@ pub(crate) fn adopted_changes_from_merge_plan(
 fn stage_adopted_change_from_patch(
     patch: &crate::tracked_state::TrackedStateMergePatch,
     target_version_id: &str,
-) -> StageAdoptedChange {
-    StageAdoptedChange {
+) -> TransactionAdoptedChange {
+    TransactionAdoptedChange {
         version_id: target_version_id.to_string(),
         change_id: patch.change_id().to_string(),
         projected_row: patch.projected_row().clone(),

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

@@ -2,12 +2,13 @@ use crate::tracked_state::{
     TrackedStateDiffEntry, TrackedStateDiffKind, TrackedStateMergeConflict, TrackedStateMergePlan,
 };
 use crate::LixError;
+use serde_json::Value as JsonValue;
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct MergeConflict {
     pub(crate) kind: MergeConflictKind,
     pub(crate) schema_key: String,
-    pub(crate) entity_id: String,
+    pub(crate) entity_id: JsonValue,
     pub(crate) file_id: Option<String>,
     pub(crate) target: MergeConflictSide,
     pub(crate) source: MergeConflictSide,
@@ -42,7 +43,7 @@ fn conflict_from_tracked(conflict: &TrackedStateMergeConflict) -> Result<MergeCo
     Ok(MergeConflict {
         kind: MergeConflictKind::SameEntityChanged,
         schema_key: conflict.identity.schema_key.clone(),
-        entity_id: conflict.identity.entity_id.as_string()?,
+        entity_id: conflict.identity.entity_id.as_json_array_value()?,
         file_id: conflict.identity.file_id.clone(),
         target: conflict_side_from_diff_entry(&conflict.target),
         source: conflict_side_from_diff_entry(&conflict.source),

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

@@ -36,7 +36,7 @@ pub(crate) fn stats_from_plan(
                 format!(
                     "merge analysis could not find source diff entry for adopted schema '{}' entity '{}'",
                     identity.schema_key,
-                    identity.entity_id.as_string()?
+                    identity.entity_id.as_json_array_text()?
                 ),
             ));
         };

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,7 +1,7 @@
-//! Engine2 session boundary.
+//! Engine session boundary.
 //!
 //! Transaction invariant:
-//! any engine2 operation that may write must enter through
+//! any engine 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
@@ -11,6 +11,8 @@ mod context;
 mod create_version;
 mod execute;
 mod merge;
+#[cfg(feature = "storage-benches")]
+pub mod optimization9_sql2_bench;
 mod switch_version;
 
 pub use context::SessionContext;