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

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

@@ -1,32 +1,38 @@
-use std::collections::BTreeSet;
+use std::collections::{BTreeMap, BTreeSet};
 use std::sync::Arc;
 
 use async_trait::async_trait;
 use serde_json::Value as JsonValue;
 
 use crate::binary_cas::{BinaryCasContext, BlobBytesBatch, BlobHash};
-use crate::changelog::ChangelogContext;
+use crate::catalog::CatalogContext;
 use crate::commit_graph::{CommitGraphContext, CommitGraphStoreReader};
+use crate::commit_store::CommitStoreContext;
+use crate::domain::Domain;
 use crate::entity_identity::EntityIdentity;
 use crate::functions::{FunctionContext, FunctionProviderHandle};
-use crate::json_store::JsonStoreContext;
 use crate::live_state::{
-    LiveStateContext, LiveStateRow, LiveStateRowRequest, LiveStateScanRequest,
+    LiveStateContext, LiveStateRowRequest, LiveStateScanRequest, MaterializedLiveStateRow,
 };
-use crate::schema_registry::SchemaRegistry;
 use crate::session::{SessionMode, WORKSPACE_VERSION_KEY};
 use crate::sql2::SqlWriteExecutionContext;
 use crate::storage::{StorageContext, StorageWriteSet, StorageWriteTransaction};
 use crate::tracked_state::{TrackedStateContext, TrackedStateStoreReader};
 use crate::transaction::commit;
 use crate::transaction::live_state_overlay::overlay_scan_rows;
-use crate::transaction::normalization::normalize_stage_row;
+use crate::transaction::normalization::{
+    normalize_transaction_write_row, remember_pending_registered_schema,
+    NormalizedTransactionWriteRow, REGISTERED_SCHEMA_KEY,
+};
+use crate::transaction::prepare_version_ref_row;
 use crate::transaction::schema_resolver::TransactionSchemaResolver;
-use crate::transaction::staging::{StagedWriteSet, TransactionStagedWrites};
+use crate::transaction::staging::{PreparedWriteSet, TransactionWriteBuffer};
 use crate::transaction::types::{
-    StageFileData, StageRow, StageWrite, StageWriteMode, StageWriteOutcome,
+    stage_json_from_value, PreparedAdoptedStateRow, PreparedRowFacts, PreparedStateRow,
+    PreparedTransactionWrite, TransactionAdoptedChange, TransactionFileData, TransactionJson,
+    TransactionWrite, TransactionWriteMode, TransactionWriteOutcome, TransactionWriteRow,
 };
-use crate::transaction::validation::{validate_staged_writes, TransactionValidationInput};
+use crate::transaction::validation::{validate_prepared_writes, TransactionValidationInput};
 use crate::version::{VersionContext, VersionRefReader};
 use crate::GLOBAL_VERSION_ID;
 use crate::{LixError, NullableKeyFilter};
@@ -34,14 +40,14 @@ use crate::{LixError, NullableKeyFilter};
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub(crate) struct TransactionCommitOutcome;
 
-/// One execution-scoped transaction capability for engine2 write paths.
+/// One execution-scoped transaction capability for engine write paths.
 ///
 /// This is intentionally not a session-wide kitchen sink. It owns the backend
 /// write transaction for one `SessionContext::execute(...)` call and projects
-/// staged SQL writes back into the SQL DAG through an engine2-local live-state
+/// accepted SQL/provider writes back into the SQL DAG through an engine-local live-state
 /// overlay.
 ///
-/// Transaction invariant: this is the capability for engine2 operations
+/// Transaction invariant: this is the capability for engine operations
 /// that may write. Write-relevant reads must be exposed from this transaction,
 /// after the backend write transaction has begun, rather than from session-level
 /// helpers.
@@ -50,10 +56,10 @@ pub(crate) struct Transaction {
     live_state: Arc<LiveStateContext>,
     tracked_state: Arc<TrackedStateContext>,
     binary_cas: Arc<BinaryCasContext>,
-    changelog: Arc<ChangelogContext>,
+    commit_store: Arc<CommitStoreContext>,
     version_ctx: Arc<VersionContext>,
     schema_resolver: TransactionSchemaResolver,
-    staged_writes: Arc<TransactionStagedWrites>,
+    staged_writes: Arc<TransactionWriteBuffer>,
     storage_transaction: Box<dyn StorageWriteTransaction + Send + Sync + 'static>,
     visible_schemas: Vec<JsonValue>,
     functions: FunctionProviderHandle,
@@ -68,9 +74,9 @@ impl Transaction {
         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<OpenTransaction, LixError> {
         let mut storage_transaction = storage.begin_write_transaction().await?;
         let setup_result = async {
@@ -88,8 +94,17 @@ impl Transaction {
             let functions = runtime_functions.provider();
             let visible_schemas = {
                 let visible_live_state = live_state.reader(storage_transaction.as_mut());
-                schema_registry
-                    .visible_schemas(&visible_live_state, &active_version_id)
+                catalog_context
+                    .schema_jsons_for_sql_read_planning(&visible_live_state, &active_version_id)
+                    .await?
+            };
+            let schema_facts = {
+                let visible_live_state = live_state.reader(storage_transaction.as_mut());
+                catalog_context
+                    .schema_facts_for_domain(
+                        &visible_live_state,
+                        &Domain::schema_catalog(active_version_id.clone(), true),
+                    )
                     .await?
             };
             Ok::<_, LixError>((
@@ -97,28 +112,31 @@ impl Transaction {
                 runtime_functions,
                 functions,
                 visible_schemas,
+                schema_facts,
             ))
         }
         .await;
-        let (active_version_id, runtime_functions, functions, visible_schemas) = match setup_result
-        {
-            Ok(result) => result,
-            Err(error) => {
-                let _ = storage_transaction.rollback().await;
-                return Err(error);
-            }
-        };
-        let mut schema_resolver = TransactionSchemaResolver::new(schema_registry);
-        schema_resolver
-            .remember_visible_schemas(active_version_id.clone(), visible_schemas.clone())?;
-        let staged_writes = Arc::new(TransactionStagedWrites::new(functions.clone()));
+        let (active_version_id, runtime_functions, functions, visible_schemas, schema_facts) =
+            match setup_result {
+                Ok(result) => result,
+                Err(error) => {
+                    let _ = storage_transaction.rollback().await;
+                    return Err(error);
+                }
+            };
+        let mut schema_resolver = TransactionSchemaResolver::new(catalog_context);
+        schema_resolver.remember_schema_facts(
+            &Domain::schema_catalog(active_version_id.clone(), true),
+            schema_facts,
+        );
+        let staged_writes = Arc::new(TransactionWriteBuffer::new(functions.clone()));
         Ok(OpenTransaction {
             transaction: Self {
                 active_version_id,
                 live_state,
                 tracked_state,
                 binary_cas,
-                changelog,
+                commit_store,
                 version_ctx,
                 schema_resolver,
                 staged_writes,
@@ -130,34 +148,36 @@ impl Transaction {
         })
     }
 
-    /// Commits staged writes, runtime function state, and the backend transaction.
+    /// Commits prepared writes, runtime function state, and the backend transaction.
     ///
-    /// Commit owns the execution boundary: provider-staged rows become
-    /// changelog facts, `lix_commit` rows, version-ref updates, and visible
-    /// live_state rows before the backend transaction is committed.
+    /// Commit owns the execution boundary: prepared rows become commit-store
+    /// facts, version-ref updates, and visible live_state rows before the
+    /// backend transaction is committed.
     pub(crate) async fn commit(
         mut self,
         runtime_functions: &FunctionContext,
     ) -> Result<TransactionCommitOutcome, LixError> {
-        let staged_writes = match self.staged_writes.drain() {
-            Ok(staged_writes) => staged_writes,
+        let prepared_writes = match self.staged_writes.drain() {
+            Ok(prepared_writes) => prepared_writes,
             Err(error) => {
                 let _ = self.storage_transaction.rollback().await;
                 return Err(error);
             }
         };
-        if let Err(error) = self.validate_staged_writes_by_version(&staged_writes).await {
+        if let Err(error) = self
+            .validate_prepared_writes_by_version(&prepared_writes)
+            .await
+        {
             let _ = self.storage_transaction.rollback().await;
             return Err(error);
         }
-        if let Err(error) = commit::commit_staged_writes(
+        if let Err(error) = commit::commit_prepared_writes(
             &self.binary_cas,
-            &self.changelog,
-            &self.live_state,
+            &self.commit_store,
             self.version_ctx.as_ref(),
             Some(runtime_functions),
             self.storage_transaction.as_mut(),
-            staged_writes,
+            prepared_writes,
         )
         .await
         {
@@ -181,75 +201,226 @@ impl Transaction {
     /// Stages one decoded write batch into this transaction.
     ///
     /// This is the programmatic write entrypoint used by non-SQL APIs. The
-    /// transaction still owns hydration from `StageRow` into `StagedStateRow`,
-    /// so generated timestamps, change ids, commit ids, and commit membership
-    /// stay in one place.
+    /// transaction still owns preparation from `TransactionWriteRow` into
+    /// `PreparedStateRow`, so generated timestamps, change ids, commit ids, and
+    /// commit membership stay in one place.
     #[allow(dead_code)]
     pub(crate) async fn stage_write(
         &mut self,
-        write: StageWrite,
-    ) -> Result<StageWriteOutcome, LixError> {
-        require_valid_stage_write_storage_scopes(&write)?;
-        self.require_existing_stage_write_version_ids(&write)
+        write: TransactionWrite,
+    ) -> Result<TransactionWriteOutcome, LixError> {
+        require_valid_transaction_write_storage_scopes(&write)?;
+        #[cfg(feature = "storage-benches")]
+        {
+            crate::storage_bench::record_transaction_rows_staged(transaction_write_row_count(
+                &write,
+            ));
+            crate::storage_bench::record_transaction_untracked_rows(
+                transaction_write_untracked_row_count(&write),
+            );
+        }
+        self.require_existing_transaction_write_version_ids(&write)
             .await?;
-        let write = self.normalize_stage_write(write).await?;
+        let write = self.prepare_transaction_write(write).await?;
         self.staged_writes.stage_write(write)
     }
 
-    async fn normalize_stage_write(&mut self, write: StageWrite) -> Result<StageWrite, LixError> {
+    async fn prepare_transaction_write(
+        &mut self,
+        write: TransactionWrite,
+    ) -> Result<PreparedTransactionWrite, LixError> {
         Ok(match write {
-            StageWrite::Rows { mode, rows } => StageWrite::Rows {
+            TransactionWrite::Rows { mode, rows } => PreparedTransactionWrite::Rows {
                 mode,
-                rows: self.normalize_stage_rows(rows).await?,
+                rows: self.prepare_transaction_rows(rows).await?,
             },
-            StageWrite::RowsWithFileData {
+            TransactionWrite::RowsWithFileData {
                 mode,
                 rows,
                 file_data,
                 count,
-            } => StageWrite::RowsWithFileData {
+            } => PreparedTransactionWrite::RowsWithFileData {
                 mode,
-                rows: self.normalize_stage_rows(rows).await?,
+                rows: self.prepare_transaction_rows(rows).await?,
                 file_data,
                 count,
             },
-            StageWrite::AdoptedChanges { changes } => StageWrite::AdoptedChanges { changes },
+            TransactionWrite::AdoptedChanges { changes } => {
+                PreparedTransactionWrite::AdoptedChanges {
+                    rows: self.prepare_adopted_changes(changes).await?,
+                }
+            }
         })
     }
 
-    async fn normalize_stage_rows(
+    async fn prepare_transaction_rows(
         &mut self,
-        rows: Vec<StageRow>,
-    ) -> Result<Vec<StageRow>, LixError> {
-        let mut normalized_rows = Vec::with_capacity(rows.len());
-        for row in rows {
-            let version_id = row.schema_scope_version_id().to_string();
-            let staged = self.staged_writes.staging_overlay()?;
-            let live_state = self.live_state.reader(self.storage_transaction.as_mut());
+        rows: Vec<TransactionWriteRow>,
+    ) -> Result<Vec<PreparedStateRow>, LixError> {
+        let row_count = rows.len();
+        let staged = self.staged_writes.staging_overlay()?;
+        let live_state = self.live_state.reader(self.storage_transaction.as_mut());
+        let mut rows_by_scope = BTreeMap::<Domain, Vec<(usize, TransactionWriteRow)>>::new();
+        for (index, row) in rows.into_iter().enumerate() {
+            rows_by_scope
+                .entry(Domain::schema_catalog(
+                    row.schema_scope_version_id().to_string(),
+                    row.untracked,
+                ))
+                .or_default()
+                .push((index, row));
+        }
+
+        let mut prepared_rows = Vec::with_capacity(row_count);
+        prepared_rows.resize_with(row_count, || None);
+        for (domain, rows) in rows_by_scope {
+            let functions = self.functions.clone();
             let catalog = self
                 .schema_resolver
-                .catalog_for_row_normalization(&live_state, staged, &version_id)
+                .catalog_for_row_normalization(&live_state, &staged, &domain)
                 .await?;
-            let row = normalize_stage_row(row, catalog, self.functions.clone())?;
-            normalized_rows.push(row);
+            for (_, row) in &rows {
+                if row.schema_key != REGISTERED_SCHEMA_KEY {
+                    continue;
+                }
+                if row.file_id.is_some() {
+                    return Err(LixError::new(
+                        LixError::CODE_SCHEMA_DEFINITION,
+                        "lix_registered_schema rows must not be scoped to a file",
+                    )
+                    .with_hint("Schema definitions are scoped by version and durability only; write them with null file_id."));
+                }
+                remember_pending_registered_schema(
+                    row.snapshot.as_ref().map(TransactionJson::value),
+                    Domain::schema_catalog(
+                        row.schema_scope_version_id().to_string(),
+                        row.untracked,
+                    ),
+                    catalog,
+                )?;
+            }
+            let normalized_rows = rows
+                .into_iter()
+                .map(|(index, row)| {
+                    normalize_transaction_write_row(row, catalog, functions.clone())
+                        .map(|row| (index, row))
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            for (index, row) in normalized_rows {
+                prepared_rows[index] = Some(prepare_state_row(row, &functions)?);
+            }
         }
-        Ok(normalized_rows)
+        Ok(prepared_rows
+            .into_iter()
+            .map(|row| {
+                row.expect("every row should be prepared exactly once by schema scope grouping")
+            })
+            .collect())
     }
 
-    async fn validate_staged_writes_by_version(
+    async fn prepare_adopted_changes(
         &mut self,
-        staged_writes: &StagedWriteSet,
+        changes: Vec<TransactionAdoptedChange>,
+    ) -> Result<Vec<PreparedAdoptedStateRow>, LixError> {
+        let change_count = changes.len();
+        let staged = self.staged_writes.staging_overlay()?;
+        let live_state = self.live_state.reader(self.storage_transaction.as_mut());
+        let mut changes_by_scope =
+            BTreeMap::<Domain, Vec<(usize, TransactionAdoptedChange)>>::new();
+        for (index, change) in changes.into_iter().enumerate() {
+            let schema_scope_version_id = if change.version_id == GLOBAL_VERSION_ID {
+                GLOBAL_VERSION_ID
+            } else {
+                change.version_id.as_str()
+            };
+            changes_by_scope
+                .entry(Domain::schema_catalog(
+                    schema_scope_version_id.to_string(),
+                    false,
+                ))
+                .or_default()
+                .push((index, change));
+        }
+
+        let mut prepared_rows = Vec::with_capacity(change_count);
+        prepared_rows.resize_with(change_count, || None);
+        for (domain, changes) in changes_by_scope {
+            let catalog = self
+                .schema_resolver
+                .catalog_for_row_normalization(&live_state, &staged, &domain)
+                .await?;
+            for (_, change) in &changes {
+                let row = &change.projected_row;
+                if row.schema_key != REGISTERED_SCHEMA_KEY {
+                    continue;
+                }
+                if row.file_id.is_some() {
+                    return Err(LixError::new(
+                        LixError::CODE_SCHEMA_DEFINITION,
+                        "lix_registered_schema rows must not be scoped to a file",
+                    )
+                    .with_hint("Schema definitions are scoped by version and durability only; write them with null file_id."));
+                }
+                remember_adopted_registered_schema(
+                    Domain::schema_catalog(change.version_id.clone(), false),
+                    row.snapshot_content.as_deref(),
+                    catalog,
+                )?;
+            }
+            let mut planned_changes = Vec::with_capacity(changes.len());
+            for (index, change) in changes {
+                let row = &change.projected_row;
+                let Some((schema_plan_id, _)) = catalog.plan_for_key(&row.schema_key) else {
+                    return Err(LixError::new(
+                        LixError::CODE_SCHEMA_DEFINITION,
+                        format!(
+                            "schema '{}' is not visible to this transaction",
+                            row.schema_key
+                        ),
+                    ));
+                };
+                if row.schema_key == REGISTERED_SCHEMA_KEY {
+                    if row.file_id.is_some() {
+                        return Err(LixError::new(
+                            LixError::CODE_SCHEMA_DEFINITION,
+                            "lix_registered_schema rows must not be scoped to a file",
+                        )
+                        .with_hint("Schema definitions are scoped by version and durability only; write them with null file_id."));
+                    }
+                    remember_adopted_registered_schema(
+                        Domain::schema_catalog(change.version_id.clone(), false),
+                        row.snapshot_content.as_deref(),
+                        catalog,
+                    )?;
+                }
+                planned_changes.push((index, change, schema_plan_id));
+            }
+            for (index, change, schema_plan_id) in planned_changes {
+                prepared_rows[index] = Some(prepare_adopted_state_row(change, schema_plan_id)?);
+            }
+        }
+        Ok(prepared_rows
+            .into_iter()
+            .map(|row| row.expect("every adopted row should be prepared exactly once"))
+            .collect())
+    }
+
+    async fn validate_prepared_writes_by_version(
+        &mut self,
+        prepared_writes: &PreparedWriteSet,
     ) -> Result<(), LixError> {
-        for version_id in staged_write_validation_version_ids(staged_writes) {
-            let version_staged_writes =
-                staged_write_set_for_schema_scope(staged_writes, &version_id);
+        let validation_index = prepared_writes.validation_index();
+        for scope in validation_index.schema_scopes() {
+            #[cfg(feature = "storage-benches")]
+            crate::storage_bench::record_transaction_validation_version();
+            let version_prepared_writes = validation_index.validation_set_for_schema_scope(scope);
             let live_state = self.live_state.reader(self.storage_transaction.as_mut());
             let schema_catalog = self
                 .schema_resolver
-                .catalog_for_validation(&live_state, staged_writes, &version_id)
+                .catalog_for_validation(&live_state, scope)
                 .await?;
-            validate_staged_writes(TransactionValidationInput::new(
-                &version_staged_writes,
+            validate_prepared_writes(TransactionValidationInput::new(
+                &version_prepared_writes,
                 &schema_catalog,
                 &live_state,
             ))
@@ -262,20 +433,20 @@ impl Transaction {
     #[allow(dead_code)]
     pub(crate) async fn stage_rows(
         &mut self,
-        rows: Vec<StageRow>,
-    ) -> Result<StageWriteOutcome, LixError> {
-        self.stage_write(StageWrite::Rows {
-            mode: StageWriteMode::Replace,
+        rows: Vec<TransactionWriteRow>,
+    ) -> Result<TransactionWriteOutcome, LixError> {
+        self.stage_write(TransactionWrite::Rows {
+            mode: TransactionWriteMode::Replace,
             rows,
         })
         .await
     }
 
-    async fn require_existing_stage_write_version_ids(
+    async fn require_existing_transaction_write_version_ids(
         &mut self,
-        write: &StageWrite,
+        write: &TransactionWrite,
     ) -> Result<(), LixError> {
-        let version_ids = stage_write_version_ids(write);
+        let version_ids = transaction_write_version_ids(write);
         let reader = self
             .version_ctx
             .ref_reader(self.storage_transaction.as_mut());
@@ -329,18 +500,9 @@ impl Transaction {
     ) -> Result<(), LixError> {
         let timestamp = self.functions.call_timestamp();
         let mut writes = StorageWriteSet::new();
-        let canonical_row = {
-            let mut json_writer = JsonStoreContext::new().writer();
-            self.version_ctx.canonical_ref_row(
-                &mut writes,
-                &mut json_writer,
-                version_id,
-                commit_id,
-                &timestamp,
-            )?
-        };
+        let canonical_row = prepare_version_ref_row(version_id, commit_id, &timestamp)?;
         self.version_ctx
-            .stage_canonical_ref_rows(&mut writes, &[canonical_row])?;
+            .stage_canonical_ref_rows(&mut writes, &[canonical_row.row])?;
         writes
             .apply(&mut self.storage_transaction.as_mut())
             .await
@@ -375,11 +537,129 @@ impl Transaction {
     pub(crate) fn commit_graph_reader(
         &mut self,
     ) -> CommitGraphStoreReader<&mut dyn StorageWriteTransaction> {
-        CommitGraphContext::new(self.changelog.as_ref().clone())
-            .reader(self.storage_transaction.as_mut())
+        CommitGraphContext::new().reader(self.storage_transaction.as_mut())
     }
 }
 
+fn prepare_state_row(
+    normalized: NormalizedTransactionWriteRow,
+    functions: &FunctionProviderHandle,
+) -> Result<PreparedStateRow, LixError> {
+    let NormalizedTransactionWriteRow {
+        row,
+        snapshot,
+        schema_plan_id,
+        facts,
+    } = normalized;
+    let updated_at = row.updated_at.unwrap_or_else(|| functions.call_timestamp());
+    let snapshot = snapshot
+        .map(|value| stage_json_from_value(value, "prepared row snapshot_content"))
+        .transpose()?;
+    let metadata = row
+        .metadata
+        .map(|value| stage_json_from_value(value, "prepared row metadata"))
+        .transpose()?;
+    Ok(PreparedStateRow {
+        schema_plan_id,
+        facts,
+        entity_id: row.entity_id.ok_or_else(|| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                "normalized transaction write row is missing entity_id",
+            )
+        })?,
+        schema_key: row.schema_key,
+        file_id: row.file_id,
+        snapshot,
+        metadata,
+        origin: row.origin,
+        created_at: row.created_at.unwrap_or_else(|| updated_at.clone()),
+        updated_at,
+        global: row.global,
+        change_id: if row.untracked {
+            row.change_id
+        } else {
+            Some(row.change_id.unwrap_or_else(|| functions.call_uuid_v7()))
+        },
+        commit_id: row.commit_id,
+        untracked: row.untracked,
+        version_id: row.version_id,
+    })
+}
+
+fn remember_adopted_registered_schema(
+    domain: Domain,
+    snapshot_content: Option<&str>,
+    catalog: &mut crate::catalog::CatalogSnapshot,
+) -> Result<(), LixError> {
+    let snapshot = snapshot_content
+        .map(|value| {
+            serde_json::from_str::<JsonValue>(value).map_err(|error| {
+                LixError::new(
+                    LixError::CODE_UNKNOWN,
+                    format!("adopted registered schema snapshot_content is invalid JSON: {error}"),
+                )
+            })
+        })
+        .transpose()?;
+    remember_pending_registered_schema(snapshot.as_ref(), domain, catalog)
+}
+
+fn prepare_adopted_state_row(
+    change: TransactionAdoptedChange,
+    schema_plan_id: crate::catalog::SchemaPlanId,
+) -> Result<PreparedAdoptedStateRow, LixError> {
+    if change.change_id != change.projected_row.change_id {
+        return Err(LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            format!(
+                "adopted change '{}' does not match projected row change_id '{}'",
+                change.change_id, change.projected_row.change_id
+            ),
+        ));
+    }
+    let row = change.projected_row;
+    let snapshot = row
+        .snapshot_content
+        .as_deref()
+        .map(|value| stage_materialized_json_text(value, "adopted row snapshot_content"))
+        .transpose()?;
+    let metadata = row
+        .metadata
+        .as_deref()
+        .map(|value| stage_materialized_json_text(value, "adopted row metadata"))
+        .transpose()?;
+    Ok(PreparedAdoptedStateRow {
+        schema_plan_id,
+        facts: PreparedRowFacts::default(),
+        entity_id: row.entity_id,
+        schema_key: row.schema_key,
+        file_id: row.file_id,
+        snapshot,
+        metadata,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        global: change.version_id == GLOBAL_VERSION_ID,
+        change_id: change.change_id,
+        commit_id: String::new(),
+        version_id: change.version_id,
+    })
+}
+
+fn stage_materialized_json_text(
+    value: &str,
+    context: &str,
+) -> Result<crate::transaction::types::StageJson, LixError> {
+    let parsed = serde_json::from_str::<serde_json::Value>(value).map_err(|error| {
+        LixError::new(
+            LixError::CODE_UNKNOWN,
+            format!("{context} is invalid JSON: {error}"),
+        )
+    })?;
+    let prepared = TransactionJson::from_value(parsed, context)?;
+    stage_json_from_value(prepared, context)
+}
+
 pub(crate) struct OpenTransaction {
     pub(crate) transaction: Transaction,
     pub(crate) runtime_functions: FunctionContext,
@@ -391,9 +671,9 @@ pub(crate) async fn open_transaction(
     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<OpenTransaction, LixError> {
     Transaction::open(
         mode,
@@ -401,9 +681,9 @@ pub(crate) async fn open_transaction(
         live_state,
         tracked_state,
         binary_cas,
-        changelog,
+        commit_store,
         version_ctx,
-        schema_registry,
+        catalog_context,
     )
     .await
 }
@@ -432,7 +712,7 @@ impl SqlWriteExecutionContext for Transaction {
     async fn scan_live_state(
         &mut self,
         request: &LiveStateScanRequest,
-    ) -> Result<Vec<LiveStateRow>, LixError> {
+    ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
         let staged = self.staged_writes.staging_overlay()?;
         let base = self.live_state.reader(self.storage_transaction.as_mut());
         overlay_scan_rows(&base, &staged, request).await
@@ -445,115 +725,67 @@ impl SqlWriteExecutionContext for Transaction {
             .await
     }
 
-    async fn stage_write(&mut self, write: StageWrite) -> Result<StageWriteOutcome, LixError> {
+    async fn stage_write(
+        &mut self,
+        write: TransactionWrite,
+    ) -> Result<TransactionWriteOutcome, LixError> {
         Transaction::stage_write(self, write).await
     }
 }
 
-fn stage_write_version_ids(write: &StageWrite) -> BTreeSet<String> {
+fn transaction_write_version_ids(write: &TransactionWrite) -> BTreeSet<String> {
     match write {
-        StageWrite::Rows { rows, .. } => stage_row_version_ids(rows),
-        StageWrite::RowsWithFileData {
+        TransactionWrite::Rows { rows, .. } => transaction_write_row_version_ids(rows),
+        TransactionWrite::RowsWithFileData {
             rows, file_data, ..
-        } => stage_row_version_ids(rows)
+        } => transaction_write_row_version_ids(rows)
             .into_iter()
             .chain(stage_file_data_version_ids(file_data))
             .collect(),
-        StageWrite::AdoptedChanges { changes } => changes
+        TransactionWrite::AdoptedChanges { changes } => changes
             .iter()
             .map(|change| change.version_id.clone())
             .collect(),
     }
 }
 
-fn staged_write_validation_version_ids(staged_writes: &StagedWriteSet) -> BTreeSet<String> {
-    staged_writes
-        .state_rows
-        .iter()
-        .map(|row| row.schema_scope_version_id().to_string())
-        .chain(
-            staged_writes
-                .adopted_rows
-                .iter()
-                .map(|row| row.schema_scope_version_id().to_string()),
-        )
-        .collect()
+#[cfg(feature = "storage-benches")]
+fn transaction_write_row_count(write: &TransactionWrite) -> usize {
+    match write {
+        TransactionWrite::Rows { rows, .. } => rows.len(),
+        TransactionWrite::RowsWithFileData { rows, .. } => rows.len(),
+        TransactionWrite::AdoptedChanges { changes } => changes.len(),
+    }
 }
 
-fn staged_write_set_for_schema_scope(
-    staged_writes: &StagedWriteSet,
-    schema_scope_version_id: &str,
-) -> StagedWriteSet {
-    StagedWriteSet {
-        state_rows: staged_writes
-            .state_rows
-            .iter()
-            .filter(|row| row.schema_scope_version_id() == schema_scope_version_id)
-            .cloned()
-            .collect(),
-        adopted_rows: staged_writes
-            .adopted_rows
-            .iter()
-            .filter(|row| row.schema_scope_version_id() == schema_scope_version_id)
-            .cloned()
-            .collect(),
-        insert_identities: staged_writes
-            .insert_identities
-            .iter()
-            .filter(|(identity, _)| {
-                let identity_schema_scope = if identity.version_id == GLOBAL_VERSION_ID {
-                    GLOBAL_VERSION_ID
-                } else {
-                    identity.version_id.as_str()
-                };
-                identity_schema_scope == schema_scope_version_id
-            })
-            .map(|(identity, origin)| (identity.clone(), origin.clone()))
-            .collect(),
-        commit_members_by_version: staged_writes
-            .commit_members_by_version
-            .iter()
-            .filter(|(member_version_id, _)| {
-                let member_schema_scope = if member_version_id.as_str() == GLOBAL_VERSION_ID {
-                    GLOBAL_VERSION_ID
-                } else {
-                    member_version_id.as_str()
-                };
-                member_schema_scope == schema_scope_version_id
-            })
-            .map(|(member_version_id, members)| (member_version_id.clone(), members.clone()))
-            .collect(),
-        extra_commit_parents_by_version: staged_writes
-            .extra_commit_parents_by_version
-            .iter()
-            .filter(|(parent_version_id, _)| parent_version_id.as_str() == schema_scope_version_id)
-            .map(|(parent_version_id, parents)| (parent_version_id.clone(), parents.clone()))
-            .collect(),
-        file_data_writes: staged_writes
-            .file_data_writes
-            .iter()
-            .filter(|write| {
-                let write_schema_scope = if write.version_id == GLOBAL_VERSION_ID {
-                    GLOBAL_VERSION_ID
-                } else {
-                    write.version_id.as_str()
-                };
-                write_schema_scope == schema_scope_version_id
-            })
-            .cloned()
-            .collect(),
+#[cfg(feature = "storage-benches")]
+fn transaction_write_untracked_row_count(write: &TransactionWrite) -> usize {
+    match write {
+        TransactionWrite::Rows { rows, .. } => rows.iter().filter(|row| row.untracked).count(),
+        TransactionWrite::RowsWithFileData { rows, .. } => {
+            rows.iter().filter(|row| row.untracked).count()
+        }
+        TransactionWrite::AdoptedChanges { .. } => 0,
     }
 }
 
-fn require_valid_stage_write_storage_scopes(write: &StageWrite) -> Result<(), LixError> {
+fn require_valid_transaction_write_storage_scopes(
+    write: &TransactionWrite,
+) -> Result<(), LixError> {
     match write {
-        StageWrite::Rows { rows, .. } => require_valid_stage_row_storage_scopes(rows),
-        StageWrite::RowsWithFileData { rows, .. } => require_valid_stage_row_storage_scopes(rows),
-        StageWrite::AdoptedChanges { .. } => Ok(()),
+        TransactionWrite::Rows { rows, .. } => {
+            require_valid_transaction_write_row_storage_scopes(rows)
+        }
+        TransactionWrite::RowsWithFileData { rows, .. } => {
+            require_valid_transaction_write_row_storage_scopes(rows)
+        }
+        TransactionWrite::AdoptedChanges { .. } => Ok(()),
     }
 }
 
-fn require_valid_stage_row_storage_scopes(rows: &[StageRow]) -> Result<(), LixError> {
+fn require_valid_transaction_write_row_storage_scopes(
+    rows: &[TransactionWriteRow],
+) -> Result<(), LixError> {
     for row in rows {
         require_valid_storage_scope(row.version_id.as_str(), row.global)?;
     }
@@ -570,11 +802,11 @@ fn require_valid_storage_scope(version_id: &str, global: bool) -> Result<(), Lix
     Ok(())
 }
 
-fn stage_row_version_ids(rows: &[StageRow]) -> BTreeSet<String> {
+fn transaction_write_row_version_ids(rows: &[TransactionWriteRow]) -> BTreeSet<String> {
     rows.iter().map(|row| row.version_id.clone()).collect()
 }
 
-fn stage_file_data_version_ids(file_data: &[StageFileData]) -> BTreeSet<String> {
+fn stage_file_data_version_ids(file_data: &[TransactionFileData]) -> BTreeSet<String> {
     file_data
         .iter()
         .map(|write| write.version_id.clone())
@@ -662,8 +894,9 @@ mod tests {
 
     use super::*;
     use crate::backend::testing::UnitTestBackend;
-    use crate::changelog::ChangelogScanRequest;
+    use crate::commit_store::{ChangeScanRequest, CommitStoreContext};
     use crate::tracked_state::{TrackedStateRowRequest, TrackedStateScanRequest};
+    use crate::transaction::types::TransactionJson;
     use crate::untracked_state::{UntrackedStateContext, UntrackedStateRowRequest};
     use crate::version::VersionContext;
     use crate::Backend;
@@ -674,20 +907,23 @@ mod tests {
         LiveStateContext::new(
             crate::tracked_state::TrackedStateContext::new(),
             crate::untracked_state::UntrackedStateContext::new(),
-            crate::commit_graph::CommitGraphContext::new(crate::changelog::ChangelogContext::new()),
+            crate::commit_graph::CommitGraphContext::new(),
         )
     }
 
+    const SCHEMA_FIXTURE_COMMIT_ID: &str = "schema-fixture-commit";
+
     #[tokio::test]
     async fn stage_rows_routes_tracked_and_untracked_rows_without_sql() {
         let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
         let storage = StorageContext::new(Arc::clone(&backend));
         let live_state = Arc::new(live_state_context());
-        seed_visible_schema_rows(storage.clone(), &live_state).await;
+        seed_visible_schema_rows(storage.clone()).await;
         let binary_cas = Arc::new(BinaryCasContext::new());
-        let changelog = Arc::new(ChangelogContext::new());
+        let changelog = Arc::new(CommitStoreContext::new());
+        let commit_store = Arc::new(CommitStoreContext::new());
         let version_ctx = Arc::new(VersionContext::new(Arc::new(UntrackedStateContext::new())));
-        let schema_registry = Arc::new(SchemaRegistry::new());
+        let catalog_context = Arc::new(CatalogContext::new());
         let opened = open_transaction(
             &SessionMode::Pinned {
                 version_id: GLOBAL_VERSION_ID.to_string(),
@@ -696,9 +932,9 @@ mod tests {
             Arc::clone(&live_state),
             Arc::new(crate::tracked_state::TrackedStateContext::new()),
             Arc::clone(&binary_cas),
-            Arc::clone(&changelog),
+            Arc::clone(&commit_store),
             Arc::clone(&version_ctx),
-            Arc::clone(&schema_registry),
+            Arc::clone(&catalog_context),
         )
         .await
         .expect("transaction should open");
@@ -719,20 +955,25 @@ mod tests {
 
         let changes = changelog
             .reader(storage.clone())
-            .scan_changes(&ChangelogScanRequest::default())
+            .scan_changes(&ChangeScanRequest::default())
             .await
             .expect("changelog should scan");
         assert!(
-            changes
-                .iter()
-                .any(|change| change.entity_id.as_string().as_deref() == Ok("tracked-programmatic")),
+            changes.iter().any(|change| change
+                .record
+                .entity_id
+                .as_single_string_owned()
+                .as_deref()
+                == Ok("tracked-programmatic")),
             "tracked staged row should be appended to changelog"
         );
         assert!(
-            !changes
-                .iter()
-                .any(|change| change.entity_id.as_string().as_deref()
-                    == Ok("untracked-programmatic")),
+            !changes.iter().any(|change| change
+                .record
+                .entity_id
+                .as_single_string_owned()
+                .as_deref()
+                == Ok("untracked-programmatic")),
             "untracked staged row must not be appended to changelog"
         );
 
@@ -745,18 +986,20 @@ mod tests {
 
         let tracked_row = crate::tracked_state::TrackedStateContext::new()
             .reader(storage.clone())
-            .load_row_at_commit(
+            .load_rows_at_commit(
                 &head_commit_id,
-                &TrackedStateRowRequest {
+                &[TrackedStateRowRequest {
                     schema_key: "lix_key_value".to_string(),
                     entity_id: crate::entity_identity::EntityIdentity::single(
                         "tracked-programmatic",
                     ),
                     file_id: NullableKeyFilter::Null,
-                },
+                }],
             )
             .await
             .expect("tracked state should load")
+            .pop()
+            .flatten()
             .expect("tracked row should be present in tracked state");
         assert_eq!(tracked_row.commit_id, head_commit_id);
         assert_eq!(
@@ -803,7 +1046,8 @@ mod tests {
         assert!(
             tracked_rows
                 .iter()
-                .all(|row| row.entity_id.as_string().as_deref() != Ok("untracked-programmatic")),
+                .all(|row| row.entity_id.as_single_string_owned().as_deref()
+                    != Ok("untracked-programmatic")),
             "untracked staged rows should not be written into tracked state"
         );
     }
@@ -813,11 +1057,12 @@ mod tests {
         let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
         let storage = StorageContext::new(Arc::clone(&backend));
         let live_state = Arc::new(live_state_context());
-        seed_visible_schema_rows(storage.clone(), &live_state).await;
+        seed_visible_schema_rows(storage.clone()).await;
         let binary_cas = Arc::new(BinaryCasContext::new());
-        let changelog = Arc::new(ChangelogContext::new());
+        let changelog = Arc::new(CommitStoreContext::new());
+        let commit_store = Arc::new(CommitStoreContext::new());
         let version_ctx = Arc::new(VersionContext::new(Arc::new(UntrackedStateContext::new())));
-        let schema_registry = Arc::new(SchemaRegistry::new());
+        let catalog_context = Arc::new(CatalogContext::new());
         let opened = open_transaction(
             &SessionMode::Pinned {
                 version_id: GLOBAL_VERSION_ID.to_string(),
@@ -826,9 +1071,9 @@ mod tests {
             Arc::clone(&live_state),
             Arc::new(crate::tracked_state::TrackedStateContext::new()),
             Arc::clone(&binary_cas),
-            Arc::clone(&changelog),
+            Arc::clone(&commit_store),
             Arc::clone(&version_ctx),
-            Arc::clone(&schema_registry),
+            Arc::clone(&catalog_context),
         )
         .await
         .expect("transaction should open");
@@ -836,7 +1081,9 @@ mod tests {
         let runtime_functions = opened.runtime_functions;
 
         let mut invalid_row = key_value_stage_row("invalid-programmatic", "invalid", false);
-        invalid_row.snapshot_content = Some("{\"key\":\"invalid-programmatic\"}".to_string());
+        invalid_row.snapshot = Some(TransactionJson::from_value_for_test(
+            json!({"key": "invalid-programmatic"}),
+        ));
         transaction
             .stage_rows(vec![invalid_row])
             .await
@@ -853,11 +1100,16 @@ mod tests {
 
         let changes = changelog
             .reader(storage.clone())
-            .scan_changes(&ChangelogScanRequest::default())
+            .scan_changes(&ChangeScanRequest::default())
             .await
             .expect("changelog should scan after failed commit");
         assert!(
-            changes.is_empty(),
+            changes.iter().all(|change| change
+                .record
+                .entity_id
+                .as_single_string_owned()
+                .as_deref()
+                != Ok("invalid-programmatic")),
             "validation failure must happen before changelog persistence"
         );
         let head = version_ctx
@@ -866,8 +1118,9 @@ mod tests {
             .await
             .expect("version ref should load after failed commit");
         assert_eq!(
-            head, None,
-            "validation failure must happen before version-ref persistence"
+            head.as_deref(),
+            Some(SCHEMA_FIXTURE_COMMIT_ID),
+            "validation failure must not advance the version ref"
         );
     }
 
@@ -879,7 +1132,7 @@ mod tests {
             open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("invalid-metadata", "value", false);
-        row.metadata = Some(json!("not-an-object"));
+        row.metadata = Some(TransactionJson::from_value_for_test(json!("not-an-object")));
         transaction
             .stage_rows(vec![row])
             .await
@@ -900,6 +1153,7 @@ mod tests {
             &live_state,
             &changelog,
             &version_ref,
+            "invalid-metadata",
         )
         .await;
     }
@@ -928,7 +1182,7 @@ mod tests {
         assert!(
             error
                 .message
-                .contains("schema 'missing_schema' version '1' is not visible"),
+                .contains("schema 'missing_schema' is not visible"),
             "error should explain missing schema visibility: {error:?}"
         );
     }
@@ -991,35 +1245,6 @@ mod tests {
         );
     }
 
-    #[tokio::test]
-    async fn stage_rows_rejects_unknown_schema_version_without_sql() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let (
-            _live_state,
-            _binary_cas,
-            _changelog,
-            _version_ref,
-            _runtime_functions,
-            mut transaction,
-        ) = open_test_transaction(&backend).await;
-
-        let mut row = key_value_stage_row("unknown-version", "value", false);
-        row.schema_version = "999".to_string();
-
-        let error = transaction
-            .stage_rows(vec![row])
-            .await
-            .expect_err("unknown schema version should be rejected while staging");
-
-        assert_eq!(error.code, LixError::CODE_SCHEMA_DEFINITION);
-        assert!(
-            error
-                .message
-                .contains("schema 'lix_key_value' version '999' is not visible"),
-            "error should explain missing schema version visibility: {error:?}"
-        );
-    }
-
     #[tokio::test]
     async fn stage_rows_rejects_invalid_snapshot_json_without_sql() {
         let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
@@ -1033,17 +1258,17 @@ mod tests {
         ) = open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("invalid-json", "value", false);
-        row.snapshot_content = Some("{".to_string());
+        row.snapshot = Some(TransactionJson::from_value_for_test(json!("not-an-object")));
 
         let error = transaction
             .stage_rows(vec![row])
             .await
-            .expect_err("invalid JSON should be rejected while staging");
+            .expect_err("non-object snapshot should be rejected while staging");
 
         assert_eq!(error.code, LixError::CODE_SCHEMA_VALIDATION);
         assert!(
-            error.message.contains("invalid JSON"),
-            "error should explain invalid JSON: {error:?}"
+            error.message.contains("must be a JSON object"),
+            "error should explain invalid snapshot shape: {error:?}"
         );
     }
 
@@ -1055,7 +1280,9 @@ mod tests {
             open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("schema-mismatch", "value", false);
-        row.snapshot_content = Some(r#"{"key":"schema-mismatch"}"#.to_string());
+        row.snapshot = Some(TransactionJson::from_value_for_test(
+            json!({"key": "schema-mismatch"}),
+        ));
         transaction
             .stage_rows(vec![row])
             .await
@@ -1076,6 +1303,7 @@ mod tests {
             &live_state,
             &changelog,
             &version_ref,
+            "schema-mismatch",
         )
         .await;
     }
@@ -1094,14 +1322,18 @@ mod tests {
 
         let mut row = key_value_stage_row("malformed-registered-schema", "value", false);
         row.schema_key = "lix_registered_schema".to_string();
-        row.snapshot_content = Some(
-            json!({
-                "value": {
-                    "x-lix-key": "malformed_registered_schema"
-                }
-            })
-            .to_string(),
-        );
+        row.snapshot = Some(TransactionJson::from_value_for_test(json!({
+            "value": {
+                "x-lix-key": "malformed_registered_schema",
+                "x-lix-primary-key": ["id"],
+                "type": "object",
+                "properties": {
+                    "id": { "type": "string" }
+                },
+                "required": ["id"],
+                "additionalProperties": false
+            }
+        })));
         row.entity_id = None;
 
         let error = transaction
@@ -1109,10 +1341,9 @@ mod tests {
             .await
             .expect_err("malformed registered schema should be rejected while staging");
 
-        assert_eq!(error.code, LixError::CODE_SCHEMA_VALIDATION);
+        assert_eq!(error.code, LixError::CODE_SCHEMA_DEFINITION);
         assert!(
-            error.message.contains("x-lix-version")
-                || error.message.contains("primary-key pointer"),
+            error.message.contains("x-lix-primary-key"),
             "error should explain malformed registered schema: {error:?}"
         );
     }
@@ -1151,18 +1382,19 @@ mod tests {
     ) -> (
         Arc<LiveStateContext>,
         Arc<BinaryCasContext>,
-        Arc<ChangelogContext>,
+        Arc<CommitStoreContext>,
         Arc<VersionContext>,
         FunctionContext,
         Transaction,
     ) {
         let storage = StorageContext::new(Arc::clone(backend));
         let live_state = Arc::new(live_state_context());
-        seed_visible_schema_rows(storage.clone(), &live_state).await;
+        seed_visible_schema_rows(storage.clone()).await;
         let binary_cas = Arc::new(BinaryCasContext::new());
-        let changelog = Arc::new(ChangelogContext::new());
+        let changelog = Arc::new(CommitStoreContext::new());
+        let commit_store = Arc::new(CommitStoreContext::new());
         let version_ctx = Arc::new(VersionContext::new(Arc::new(UntrackedStateContext::new())));
-        let schema_registry = Arc::new(SchemaRegistry::new());
+        let catalog_context = Arc::new(CatalogContext::new());
         let opened = open_transaction(
             &SessionMode::Pinned {
                 version_id: GLOBAL_VERSION_ID.to_string(),
@@ -1171,9 +1403,9 @@ mod tests {
             Arc::clone(&live_state),
             Arc::new(crate::tracked_state::TrackedStateContext::new()),
             Arc::clone(&binary_cas),
-            Arc::clone(&changelog),
+            Arc::clone(&commit_store),
             Arc::clone(&version_ctx),
-            schema_registry,
+            catalog_context,
         )
         .await
         .expect("transaction should open");
@@ -1190,46 +1422,52 @@ mod tests {
         )
     }
 
-    async fn seed_visible_schema_rows(storage: StorageContext, live_state: &LiveStateContext) {
+    async fn seed_visible_schema_rows(storage: StorageContext) {
+        let mut writes = StorageWriteSet::new();
         let rows = crate::schema::seed_schema_definitions()
             .into_iter()
             .map(|schema| {
                 let key = crate::schema::schema_key_from_definition(schema)
                     .expect("seed schema key should derive");
-                LiveStateRow {
-                    entity_id: crate::schema::registered_schema_entity_id(
-                        &key.schema_key,
-                        &key.schema_version,
-                    )
-                    .expect("registered schema identity should derive"),
+                let snapshot_content = json!({ "value": schema }).to_string();
+                crate::tracked_state::MaterializedTrackedStateRow {
+                    entity_id: crate::schema::registered_schema_entity_id(&key.schema_key)
+                        .expect("registered schema identity should derive"),
                     schema_key: "lix_registered_schema".to_string(),
                     file_id: None,
-                    version_id: GLOBAL_VERSION_ID.to_string(),
-                    schema_version: "1".to_string(),
-                    snapshot_content: Some(json!({ "value": schema }).to_string()),
+                    snapshot_content: Some(snapshot_content),
                     metadata: None,
+                    deleted: false,
                     created_at: "1970-01-01T00:00:00.000Z".to_string(),
                     updated_at: "1970-01-01T00:00:00.000Z".to_string(),
-                    change_id: None,
-                    commit_id: None,
-                    untracked: true,
-                    global: true,
+                    change_id: format!("schema-fixture-{}", key.schema_key),
+                    commit_id: SCHEMA_FIXTURE_COMMIT_ID.to_string(),
                 }
             })
             .collect::<Vec<_>>();
+        let version_ref_row = prepare_version_ref_row(
+            GLOBAL_VERSION_ID,
+            SCHEMA_FIXTURE_COMMIT_ID,
+            "1970-01-01T00:00:00.000Z",
+        )
+        .expect("schema fixture version ref should stage");
         let mut storage_transaction = storage
             .begin_write_transaction()
             .await
             .expect("schema fixture transaction should open");
-        let mut writes = StorageWriteSet::new();
-        let mut json_writer = JsonStoreContext::new().writer();
-        {
-            let mut writer = live_state.writer(storage_transaction.as_mut());
-            writer
-                .stage_rows(&mut writes, &mut json_writer, &rows)
-                .await
-                .expect("schema fixture rows should stage");
-        }
+        crate::test_support::stage_tracked_root_from_materialized(
+            storage_transaction.as_mut(),
+            &crate::tracked_state::TrackedStateContext::new(),
+            SCHEMA_FIXTURE_COMMIT_ID,
+            None,
+            &rows,
+        )
+        .await
+        .expect("schema fixture rows should stage");
+        crate::untracked_state::UntrackedStateContext::new()
+            .writer(&mut writes)
+            .stage_rows([version_ref_row.row.as_ref()])
+            .expect("schema fixture version ref should stage");
         writes
             .apply(&mut storage_transaction.as_mut())
             .await
@@ -1243,16 +1481,22 @@ mod tests {
     async fn assert_no_persistence_after_validation_failure(
         storage: StorageContext,
         live_state: &LiveStateContext,
-        changelog: &ChangelogContext,
+        changelog: &CommitStoreContext,
         version_ctx: &VersionContext,
+        rejected_entity_id: &str,
     ) {
         let changes = changelog
             .reader(storage.clone())
-            .scan_changes(&ChangelogScanRequest::default())
+            .scan_changes(&ChangeScanRequest::default())
             .await
             .expect("changelog should scan after failed commit");
         assert!(
-            changes.is_empty(),
+            changes.iter().all(|change| change
+                .record
+                .entity_id
+                .as_single_string_owned()
+                .as_deref()
+                != Ok(rejected_entity_id)),
             "validation failure must happen before changelog persistence"
         );
         let head = version_ctx
@@ -1261,15 +1505,16 @@ mod tests {
             .await
             .expect("version ref should load after failed commit");
         assert_eq!(
-            head, None,
-            "validation failure must happen before version-ref persistence"
+            head.as_deref(),
+            Some(SCHEMA_FIXTURE_COMMIT_ID),
+            "validation failure must not advance the version ref"
         );
         let row = live_state
             .reader(storage)
             .load_row(&crate::live_state::LiveStateRowRequest {
                 schema_key: "lix_key_value".to_string(),
                 version_id: GLOBAL_VERSION_ID.to_string(),
-                entity_id: crate::entity_identity::EntityIdentity::single("schema-mismatch"),
+                entity_id: crate::entity_identity::EntityIdentity::single(rejected_entity_id),
                 file_id: NullableKeyFilter::Null,
             })
             .await
@@ -1280,21 +1525,17 @@ mod tests {
         );
     }
 
-    fn key_value_stage_row(key: &str, value: &str, untracked: bool) -> StageRow {
-        StageRow {
+    fn key_value_stage_row(key: &str, value: &str, untracked: bool) -> TransactionWriteRow {
+        TransactionWriteRow {
             entity_id: Some(crate::entity_identity::EntityIdentity::single(key)),
             schema_key: "lix_key_value".to_string(),
             file_id: None,
-            snapshot_content: Some(
-                json!({
-                    "key": key,
-                    "value": value,
-                })
-                .to_string(),
-            ),
+            snapshot: Some(TransactionJson::from_value_for_test(json!({
+                "key": key,
+                "value": value,
+            }))),
             metadata: None,
             origin: None,
-            schema_version: "1".to_string(),
             created_at: None,
             updated_at: None,
             global: true,