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

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

@@ -6,23 +6,27 @@ 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};
 
+use super::transaction::transaction_state_error;
+
 pub(crate) const WORKSPACE_VERSION_KEY: &str = "lix_workspace_version_id";
 
 #[derive(Clone)]
@@ -31,16 +35,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
-/// through `SessionContext::with_write_transaction`. Reads that influence writes
-/// are only available from that transaction capability, not from session-level
-/// helpers.
+/// services. Parent-handle `execute(...)` runs as an implicit single-statement
+/// transaction. Explicit transactions hold the session execution lease until
+/// commit or rollback, so all SQL during that window must run through the
+/// transaction handle.
 #[derive(Clone)]
 pub struct SessionContext {
     pub(super) mode: SessionMode,
@@ -48,10 +49,11 @@ 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>,
+    active_transaction: Arc<AtomicBool>,
 }
 
 impl SessionContext {
@@ -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,10 @@ impl SessionContext {
             live_state,
             tracked_state,
             binary_cas,
-            changelog,
+            commit_store,
             version_ctx,
-            schema_registry,
+            catalog_context,
+            Arc::new(AtomicBool::new(false)),
             Arc::new(AtomicBool::new(false)),
         )
     }
@@ -131,10 +134,11 @@ 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>,
+        active_transaction: Arc<AtomicBool>,
     ) -> Self {
         Self {
             mode,
@@ -142,10 +146,11 @@ impl SessionContext {
             live_state,
             tracked_state,
             binary_cas,
-            changelog,
+            commit_store,
             version_ctx,
-            schema_registry,
+            catalog_context,
             closed,
+            active_transaction,
         }
     }
 
@@ -164,6 +169,10 @@ impl SessionContext {
         Arc::clone(&self.closed)
     }
 
+    pub(crate) fn active_transaction_flag(&self) -> Arc<AtomicBool> {
+        Arc::clone(&self.active_transaction)
+    }
+
     pub(crate) fn ensure_open(&self) -> Result<(), LixError> {
         if self.is_closed() {
             return Err(closed_error());
@@ -256,18 +265,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)
     }
@@ -279,15 +284,25 @@ impl SessionContext {
         ) -> Pin<Box<dyn Future<Output = Result<T, LixError>> + 'tx>>,
     {
         self.ensure_open()?;
+        let _transaction_guard = self.reserve_session_transaction()?;
+        self.with_write_transaction_reserved(f).await
+    }
+
+    pub(crate) async fn with_write_transaction_reserved<T, F>(&self, f: F) -> Result<T, LixError>
+    where
+        F: for<'tx> FnOnce(
+            &'tx mut Transaction,
+        ) -> Pin<Box<dyn Future<Output = Result<T, LixError>> + 'tx>>,
+    {
         let opened = 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.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;
@@ -304,6 +319,19 @@ impl SessionContext {
             }
         }
     }
+
+    pub(super) fn reserve_session_transaction(&self) -> Result<SessionTransactionGuard, LixError> {
+        let active_transaction = self.active_transaction_flag();
+        if active_transaction
+            .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+            .is_err()
+        {
+            return Err(transaction_state_error(
+                "Lix handle has an active transaction; use the transaction handle for reads and writes until it is committed or rolled back",
+            ));
+        }
+        Ok(SessionTransactionGuard { active_transaction })
+    }
 }
 
 fn closed_error() -> LixError {
@@ -311,6 +339,16 @@ fn closed_error() -> LixError {
         .with_hint("Open a new Lix handle before calling this method.")
 }
 
+pub(super) struct SessionTransactionGuard {
+    active_transaction: Arc<AtomicBool>,
+}
+
+impl Drop for SessionTransactionGuard {
+    fn drop(&mut self) {
+        self.active_transaction.store(false, Ordering::SeqCst);
+    }
+}
+
 /// Read-only SQL execution context derived from a session.
 ///
 /// Write statements re-plan against `Transaction`; this context intentionally
@@ -321,7 +359,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 +374,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,14 @@
 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};
+use super::transaction::SessionTransaction;
 
-/// 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 +251,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.
@@ -291,29 +291,40 @@ impl SessionContext {
     /// 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)?;
+        let _transaction_guard = self.reserve_session_transaction()?;
+        let statement = sql2::parse_statement(sql)?;
+        let kind = sql2::classify_datafusion_statement(&statement);
         if kind == sql2::SqlStatementKind::Write {
-            let sql = sql.to_string();
+            let sql_for_error = sql.to_string();
             let params = params.to_vec();
             return self
-                .with_write_transaction(|transaction| {
+                .with_write_transaction_reserved(|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 tx_plan =
+                            sql2::create_write_logical_plan_from_parsed(transaction, statement)
+                                .await?;
                         let result = sql2::execute_logical_plan(tx_plan, &params).await?;
                         let affected_rows = affected_rows_from_query_result(result)?;
                         Ok(ExecuteResult::from_rows_affected(affected_rows))
                     })
                 })
-                .await;
+                .await
+                .map_err(|error| normalize_sql_surface_error(error, &sql_for_error));
+        }
+        if kind == sql2::SqlStatementKind::Other {
+            return Err(LixError::new(
+                LixError::CODE_UNSUPPORTED_SQL,
+                "SQL statement is not supported by Lix SQL",
+            ));
         }
 
         let read_scope = StorageReadScope::new(self.storage.begin_read_transaction().await?);
@@ -325,21 +336,21 @@ 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(),
             };
 
-            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);
@@ -352,7 +363,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)
@@ -370,23 +381,106 @@ impl SessionContext {
         &self,
         runtime_functions: &FunctionContext,
     ) -> 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?;
+        if writes.is_empty() {
+            return Ok(());
         }
+        let mut transaction = self.storage.begin_write_transaction().await?;
+        writes.apply(&mut transaction.as_mut()).await?;
         transaction.commit().await
     }
 }
 
+impl SessionTransaction {
+    /// 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 statement = sql2::parse_statement(sql)?;
+        let kind = sql2::classify_datafusion_statement(&statement);
+        let transaction = self.transaction_mut()?;
+        match kind {
+            sql2::SqlStatementKind::Write => {
+                execute_transaction_write(transaction, statement, params)
+                    .await
+                    .map_err(|error| normalize_sql_surface_error(error, sql))
+            }
+            sql2::SqlStatementKind::Read => {
+                let plan = sql2::create_transaction_read_logical_plan_from_parsed(
+                    transaction,
+                    sql,
+                    statement,
+                )
+                .await
+                .map_err(|error| normalize_sql_surface_error(error, sql))?;
+                let result = sql2::execute_logical_plan(plan, params)
+                    .await
+                    .map_err(|error| normalize_sql_surface_error(error, sql))?;
+                Ok(ExecuteResult::from_sql_query_result(result))
+            }
+            sql2::SqlStatementKind::Other => Err(LixError::new(
+                LixError::CODE_UNSUPPORTED_SQL,
+                "SQL statement is not supported by Lix SQL",
+            )),
+        }
+    }
+}
+
+async fn execute_transaction_write(
+    transaction: &mut crate::transaction::Transaction,
+    statement: datafusion::sql::parser::Statement,
+    params: &[Value],
+) -> Result<ExecuteResult, LixError> {
+    let tx_plan = sql2::create_write_logical_plan_from_parsed(transaction, statement).await?;
+    let result = sql2::execute_logical_plan(tx_plan, params).await?;
+    let affected_rows = affected_rows_from_query_result(result)?;
+    Ok(ExecuteResult::from_rows_affected(affected_rows))
+}
+
+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()?
                 ),
             ));
         };