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

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

@@ -1,44 +1,54 @@
 use std::collections::{BTreeMap, BTreeSet};
+use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::Arc;
 
 use async_trait::async_trait;
 use serde_json::Value as JsonValue;
 
 use crate::binary_cas::{BinaryCasContext, BlobBytesBatch, BlobHash};
+use crate::branch::{BranchContext, BranchRefReader};
 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::entity_pk::EntityPk;
 use crate::functions::{FunctionContext, FunctionProviderHandle};
+use crate::live_state::overlay_scan_rows;
 use crate::live_state::{
     LiveStateContext, LiveStateRowRequest, LiveStateScanRequest, MaterializedLiveStateRow,
 };
-use crate::session::{SessionMode, WORKSPACE_VERSION_KEY};
+use crate::session::{SessionMode, WORKSPACE_BRANCH_KEY};
 use crate::sql2::SqlWriteExecutionContext;
-use crate::storage::{StorageContext, StorageWriteSet, StorageWriteTransaction};
+use crate::sql2::{
+    ChangelogQuerySource, HistoryQuerySource, SqlChangelogQuerySource, SqlExecutionContext,
+    SqlHistoryQuerySource,
+};
+use crate::storage::{
+    InMemoryStorageBackend, StorageBackend, StorageReadOptions, StorageWriteOptions,
+    StorageWriteSetStats,
+};
+use crate::storage::{StorageContext, StorageRead, StorageReadScope, StorageWriteSet};
 use crate::tracked_state::{TrackedStateContext, TrackedStateStoreReader};
 use crate::transaction::commit;
-use crate::transaction::live_state_overlay::overlay_scan_rows;
 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::prepare_branch_ref_row;
 use crate::transaction::schema_resolver::TransactionSchemaResolver;
 use crate::transaction::staging::{PreparedWriteSet, TransactionWriteBuffer};
 use crate::transaction::types::{
-    stage_json_from_value, PreparedAdoptedStateRow, PreparedRowFacts, PreparedStateRow,
-    PreparedTransactionWrite, TransactionAdoptedChange, TransactionFileData, TransactionJson,
-    TransactionWrite, TransactionWriteMode, TransactionWriteOutcome, TransactionWriteRow,
+    stage_json_from_value, PreparedStateRow, PreparedTransactionWrite, StagedCommitChangeRef,
+    TransactionFileData, TransactionJson, TransactionWrite, TransactionWriteMode,
+    TransactionWriteOutcome, TransactionWriteRow,
 };
 use crate::transaction::validation::{validate_prepared_writes, TransactionValidationInput};
-use crate::version::{VersionContext, VersionRefReader};
-use crate::GLOBAL_VERSION_ID;
+use crate::GLOBAL_BRANCH_ID;
 use crate::{LixError, NullableKeyFilter};
 
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
-pub(crate) struct TransactionCommitOutcome;
+pub(crate) struct TransactionCommitOutcome {
+    pub(crate) storage_stats: StorageWriteSetStats,
+}
 
 /// One execution-scoped transaction capability for engine write paths.
 ///
@@ -51,98 +61,233 @@ pub(crate) struct TransactionCommitOutcome;
 /// 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.
-pub(crate) struct Transaction {
-    active_version_id: String,
+pub(crate) struct Transaction<B: StorageBackend = InMemoryStorageBackend> {
+    active_branch_id: String,
     live_state: Arc<LiveStateContext>,
     tracked_state: Arc<TrackedStateContext>,
     binary_cas: Arc<BinaryCasContext>,
-    commit_store: Arc<CommitStoreContext>,
-    version_ctx: Arc<VersionContext>,
+    branch_ctx: Arc<BranchContext>,
+    catalog_context: Arc<CatalogContext>,
     schema_resolver: TransactionSchemaResolver,
     staged_writes: Arc<TransactionWriteBuffer>,
-    storage_transaction: Box<dyn StorageWriteTransaction + Send + Sync + 'static>,
-    visible_schemas: Vec<JsonValue>,
+    staged_storage_writes: StorageWriteSet,
+    storage: StorageContext<B>,
+    sql_schema_cache: SqlSchemaCache,
     functions: FunctionProviderHandle,
+    commit_boundary: Option<TransactionCommitBoundary>,
+}
+
+#[derive(Default)]
+struct SqlSchemaCache {
+    visible_schemas: Option<Vec<JsonValue>>,
+}
+
+impl SqlSchemaCache {
+    fn is_prepared(&self) -> bool {
+        self.visible_schemas.is_some()
+    }
+
+    fn prepare(&mut self, visible_schemas: Vec<JsonValue>) {
+        self.visible_schemas = Some(visible_schemas);
+    }
+
+    fn visible_schemas(&self) -> Result<&[JsonValue], LixError> {
+        self.visible_schemas.as_deref().ok_or_else(|| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "SQL visible schemas were requested before SQL transaction context preparation",
+            )
+        })
+    }
+}
+
+#[derive(Clone)]
+pub(crate) struct TransactionCommitBoundary {
+    state: CommitBoundaryState,
+    pre_commit_check: Arc<dyn Fn() -> Result<(), LixError> + Send + Sync>,
+}
+
+impl TransactionCommitBoundary {
+    pub(crate) fn new(
+        state: CommitBoundaryState,
+        pre_commit_check: Arc<dyn Fn() -> Result<(), LixError> + Send + Sync>,
+    ) -> Self {
+        Self {
+            state,
+            pre_commit_check,
+        }
+    }
+
+    fn begin(&self) -> CommitBoundaryGuard {
+        self.state.begin()
+    }
+
+    fn check(&self) -> Result<(), LixError> {
+        (self.pre_commit_check)()
+    }
+
+    fn commit<T>(&self, commit: impl FnOnce() -> Result<T, LixError>) -> Result<T, LixError> {
+        let _gate = self.state.lock_durable_commit();
+        self.check()?;
+        commit()
+    }
+}
+
+#[derive(Clone)]
+pub(crate) struct CommitBoundaryState {
+    active_count: Arc<AtomicUsize>,
+    durable_commit_gate: Arc<std::sync::Mutex<()>>,
+    watch: tokio::sync::watch::Sender<usize>,
+}
+
+impl CommitBoundaryState {
+    pub(crate) fn new() -> Self {
+        let (watch, _) = tokio::sync::watch::channel(0);
+        Self {
+            active_count: Arc::new(AtomicUsize::new(0)),
+            durable_commit_gate: Arc::new(std::sync::Mutex::new(())),
+            watch,
+        }
+    }
+
+    pub(crate) fn begin(&self) -> CommitBoundaryGuard {
+        let previous = self.active_count.fetch_add(1, Ordering::SeqCst);
+        self.watch.send_replace(previous + 1);
+        CommitBoundaryGuard {
+            state: self.clone(),
+        }
+    }
+
+    pub(crate) fn active_count(&self) -> usize {
+        self.active_count.load(Ordering::SeqCst)
+    }
+
+    pub(crate) fn is_active(&self) -> bool {
+        self.active_count() > 0
+    }
+
+    pub(crate) fn subscribe(&self) -> tokio::sync::watch::Receiver<usize> {
+        self.watch.subscribe()
+    }
+
+    pub(crate) fn lock_durable_commit(&self) -> std::sync::MutexGuard<'_, ()> {
+        self.durable_commit_gate
+            .lock()
+            .expect("commit boundary durable commit gate should not poison")
+    }
+
+    pub(crate) fn try_lock_durable_commit(&self) -> Option<std::sync::MutexGuard<'_, ()>> {
+        match self.durable_commit_gate.try_lock() {
+            Ok(guard) => Some(guard),
+            Err(std::sync::TryLockError::WouldBlock) => None,
+            Err(std::sync::TryLockError::Poisoned(_)) => {
+                panic!("commit boundary durable commit gate should not poison")
+            }
+        }
+    }
 }
 
-impl Transaction {
+pub(crate) struct CommitBoundaryGuard {
+    state: CommitBoundaryState,
+}
+
+impl Drop for CommitBoundaryGuard {
+    fn drop(&mut self) {
+        let remaining = self.state.active_count.fetch_sub(1, Ordering::SeqCst) - 1;
+        self.state.watch.send_replace(remaining);
+    }
+}
+
+pub(crate) fn begin_commit_boundary(
+    boundary: Option<&TransactionCommitBoundary>,
+) -> Option<CommitBoundaryGuard> {
+    let boundary = boundary?;
+    Some(boundary.begin())
+}
+
+fn check_commit_boundary(boundary: Option<&TransactionCommitBoundary>) -> Result<(), LixError> {
+    if let Some(boundary) = boundary {
+        boundary.check()?;
+    }
+    Ok(())
+}
+
+pub(crate) fn commit_at_boundary<T>(
+    boundary: Option<&TransactionCommitBoundary>,
+    commit: impl FnOnce() -> Result<T, LixError>,
+) -> Result<T, LixError> {
+    match boundary {
+        Some(boundary) => boundary.commit(commit),
+        None => commit(),
+    }
+}
+
+impl<B> Transaction<B>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
     /// Opens a backend write transaction and creates an execution-scoped
     /// staging area for SQL/provider hooks.
     async fn open(
         mode: &SessionMode,
-        storage: StorageContext,
+        storage: StorageContext<B>,
         live_state: Arc<LiveStateContext>,
         tracked_state: Arc<TrackedStateContext>,
         binary_cas: Arc<BinaryCasContext>,
-        commit_store: Arc<CommitStoreContext>,
-        version_ctx: Arc<VersionContext>,
+        branch_ctx: Arc<BranchContext>,
         catalog_context: Arc<CatalogContext>,
-    ) -> Result<OpenTransaction, LixError> {
-        let mut storage_transaction = storage.begin_write_transaction().await?;
+    ) -> Result<OpenTransaction<B>, LixError> {
+        let read = storage.begin_read(StorageReadOptions::default())?;
         let setup_result = async {
-            let active_version_id = resolve_active_version_id(
-                mode,
-                live_state.as_ref(),
-                version_ctx.as_ref(),
-                storage_transaction.as_mut(),
-            )
-            .await?;
+            let active_branch_id =
+                resolve_active_branch_id(mode, live_state.as_ref(), branch_ctx.as_ref(), &read)
+                    .await?;
             let runtime_functions = {
-                let runtime_live_state = live_state.reader(storage_transaction.as_mut());
+                let runtime_live_state = live_state.reader(&read);
                 FunctionContext::prepare(&runtime_live_state).await?
             };
             let functions = runtime_functions.provider();
-            let visible_schemas = {
-                let visible_live_state = live_state.reader(storage_transaction.as_mut());
-                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());
+                let visible_live_state = live_state.reader(&read);
                 catalog_context
                     .schema_facts_for_domain(
                         &visible_live_state,
-                        &Domain::schema_catalog(active_version_id.clone(), true),
+                        &Domain::schema_catalog(active_branch_id.clone(), true),
                     )
                     .await?
             };
-            Ok::<_, LixError>((
-                active_version_id,
-                runtime_functions,
-                functions,
-                visible_schemas,
-                schema_facts,
-            ))
+            Ok::<_, LixError>((active_branch_id, runtime_functions, functions, schema_facts))
         }
         .await;
-        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);
+        let (active_branch_id, runtime_functions, functions, schema_facts) = match setup_result {
+            Ok(result) => result,
+            Err(error) => {
+                return Err(error);
+            }
+        };
+        let mut schema_resolver = TransactionSchemaResolver::new(Arc::clone(&catalog_context));
         schema_resolver.remember_schema_facts(
-            &Domain::schema_catalog(active_version_id.clone(), true),
+            &Domain::schema_catalog(active_branch_id.clone(), true),
             schema_facts,
         );
         let staged_writes = Arc::new(TransactionWriteBuffer::new(functions.clone()));
         Ok(OpenTransaction {
             transaction: Self {
-                active_version_id,
+                active_branch_id,
                 live_state,
                 tracked_state,
                 binary_cas,
-                commit_store,
-                version_ctx,
+                branch_ctx,
+                catalog_context,
                 schema_resolver,
                 staged_writes,
-                storage_transaction,
-                visible_schemas,
+                staged_storage_writes: StorageWriteSet::new(),
+                storage,
+                sql_schema_cache: SqlSchemaCache::default(),
                 functions,
+                commit_boundary: None,
             },
             runtime_functions,
         })
@@ -150,42 +295,57 @@ impl Transaction {
 
     /// Commits prepared writes, runtime function state, and the backend transaction.
     ///
-    /// Commit owns the execution boundary: prepared rows become commit-store
-    /// facts, version-ref updates, and visible live_state rows before the
+    /// Commit owns the execution boundary: prepared rows become changelog
+    /// facts, branch-ref updates, and visible live_state rows before the
     /// backend transaction is committed.
+    #[allow(dead_code)]
     pub(crate) async fn commit(
-        mut self,
+        self,
         runtime_functions: &FunctionContext,
     ) -> Result<TransactionCommitOutcome, LixError> {
-        let prepared_writes = match self.staged_writes.drain() {
+        let mut transaction = self;
+        let commit_boundary = transaction.commit_boundary.clone();
+        let prepared_writes = match transaction.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_prepared_writes_by_version(&prepared_writes)
+        let _commit_guard = begin_commit_boundary(commit_boundary.as_ref());
+        check_commit_boundary(commit_boundary.as_ref())?;
+        if let Err(error) = transaction
+            .validate_prepared_writes_by_branch(&prepared_writes)
             .await
         {
-            let _ = self.storage_transaction.rollback().await;
             return Err(error);
         }
-        if let Err(error) = commit::commit_prepared_writes(
-            &self.binary_cas,
-            &self.commit_store,
-            self.version_ctx.as_ref(),
+        let mut read = transaction
+            .storage
+            .begin_read(StorageReadOptions::default())?;
+        let mut writes = match commit::commit_prepared_writes(
+            &transaction.binary_cas,
+            transaction.branch_ctx.as_ref(),
             Some(runtime_functions),
-            self.storage_transaction.as_mut(),
+            &mut read,
             prepared_writes,
         )
         .await
         {
-            let _ = self.storage_transaction.rollback().await;
-            return Err(error);
-        }
-        self.storage_transaction.commit().await?;
-        Ok(TransactionCommitOutcome::default())
+            Ok(writes) => writes,
+            Err(error) => return Err(error),
+        };
+        writes.extend(transaction.staged_storage_writes);
+        let storage_stats = commit_at_boundary(commit_boundary.as_ref(), || {
+            let (_commit, stats) = transaction
+                .storage
+                .commit_write_set(writes, StorageWriteOptions::default())?;
+            Ok(stats)
+        })?;
+        Ok(TransactionCommitOutcome { storage_stats })
+    }
+
+    pub(crate) fn attach_commit_boundary(&mut self, boundary: TransactionCommitBoundary) {
+        self.commit_boundary = Some(boundary);
     }
 
     /// Rolls back the backend transaction.
@@ -195,7 +355,7 @@ impl Transaction {
     /// rely on.
     #[allow(dead_code)]
     pub(crate) async fn rollback(self) -> Result<(), LixError> {
-        self.storage_transaction.rollback().await
+        Ok(())
     }
 
     /// Stages one decoded write batch into this transaction.
@@ -203,7 +363,7 @@ impl Transaction {
     /// This is the programmatic write entrypoint used by non-SQL APIs. The
     /// transaction still owns preparation from `TransactionWriteRow` into
     /// `PreparedStateRow`, so generated timestamps, change ids, commit ids, and
-    /// commit membership stay in one place.
+    /// commit change refs stay in one place.
     #[allow(dead_code)]
     pub(crate) async fn stage_write(
         &mut self,
@@ -219,7 +379,7 @@ impl Transaction {
                 transaction_write_untracked_row_count(&write),
             );
         }
-        self.require_existing_transaction_write_version_ids(&write)
+        self.require_existing_transaction_write_branch_ids(&write)
             .await?;
         let write = self.prepare_transaction_write(write).await?;
         self.staged_writes.stage_write(write)
@@ -245,11 +405,6 @@ impl Transaction {
                 file_data,
                 count,
             },
-            TransactionWrite::AdoptedChanges { changes } => {
-                PreparedTransactionWrite::AdoptedChanges {
-                    rows: self.prepare_adopted_changes(changes).await?,
-                }
-            }
         })
     }
 
@@ -259,12 +414,13 @@ impl Transaction {
     ) -> 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 read = self.storage.begin_read(StorageReadOptions::default())?;
+        let live_state = self.live_state.reader(&read);
         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.schema_scope_branch_id().to_string(),
                     row.untracked,
                 ))
                 .or_default()
@@ -288,14 +444,11 @@ impl Transaction {
                         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."));
+                    .with_hint("Schema definitions are scoped by branch 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,
-                    ),
+                    Domain::schema_catalog(row.schema_scope_branch_id().to_string(), row.untracked),
                     catalog,
                 )?;
             }
@@ -318,109 +471,23 @@ impl Transaction {
             .collect())
     }
 
-    async fn prepare_adopted_changes(
-        &mut self,
-        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(
+    async fn validate_prepared_writes_by_branch(
         &mut self,
         prepared_writes: &PreparedWriteSet,
     ) -> Result<(), LixError> {
         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());
+            crate::storage_bench::record_transaction_validation_branch();
+            let branch_prepared_writes = validation_index.validation_set_for_schema_scope(scope);
+            let read = self.storage.begin_read(StorageReadOptions::default())?;
+            let live_state = self.live_state.reader(&read);
             let schema_catalog = self
                 .schema_resolver
                 .catalog_for_validation(&live_state, scope)
                 .await?;
             validate_prepared_writes(TransactionValidationInput::new(
-                &version_prepared_writes,
+                &branch_prepared_writes,
                 &schema_catalog,
                 &live_state,
             ))
@@ -442,21 +509,20 @@ impl Transaction {
         .await
     }
 
-    async fn require_existing_transaction_write_version_ids(
+    async fn require_existing_transaction_write_branch_ids(
         &mut self,
         write: &TransactionWrite,
     ) -> Result<(), LixError> {
-        let version_ids = transaction_write_version_ids(write);
-        let reader = self
-            .version_ctx
-            .ref_reader(self.storage_transaction.as_mut());
-        for version_id in version_ids {
-            if version_id == GLOBAL_VERSION_ID {
+        let branch_ids = transaction_write_branch_ids(write);
+        let read = self.storage.begin_read(StorageReadOptions::default())?;
+        let reader = self.branch_ctx.ref_reader(&read);
+        for branch_id in branch_ids {
+            if branch_id == GLOBAL_BRANCH_ID {
                 continue;
             }
-            if reader.load_head_commit_id(&version_id).await?.is_none() {
-                return Err(LixError::version_not_found(
-                    version_id,
+            if reader.load_head_commit_id(&branch_id).await?.is_none() {
+                return Err(LixError::branch_not_found(
+                    branch_id,
                     "stage_write",
                     "target",
                 ));
@@ -465,9 +531,9 @@ impl Transaction {
         Ok(())
     }
 
-    /// Returns the active version resolved inside this write transaction.
-    pub(crate) fn active_version_id(&self) -> &str {
-        &self.active_version_id
+    /// Returns the active branch resolved inside this write transaction.
+    pub(crate) fn active_branch_id(&self) -> &str {
+        &self.active_branch_id
     }
 
     /// Returns this transaction's prepared runtime functions.
@@ -475,69 +541,216 @@ impl Transaction {
         self.functions.clone()
     }
 
-    /// Adds an extra parent to the commit generated for `version_id`.
-    ///
-    /// Merge uses this to preserve source-branch ancestry. Ordinary writes do
-    /// not call this because commit finalization already parents to the
-    /// version's previous head.
-    pub(crate) fn add_commit_parent(
+    pub(crate) async fn sql_read_execution_context(
+        &mut self,
+    ) -> Result<TransactionSqlReadExecutionContext<B::Read<'_>>, LixError> {
+        self.prepare_sql_visible_schemas().await?;
+        self.sql_read_execution_context_from_cached_schemas()
+    }
+
+    fn sql_read_execution_context_from_cached_schemas(
         &self,
-        version_id: String,
-        parent_commit_id: String,
-    ) -> Result<(), LixError> {
-        self.staged_writes
-            .add_commit_parent(version_id, parent_commit_id)
+    ) -> Result<TransactionSqlReadExecutionContext<B::Read<'_>>, LixError> {
+        let read_store = self.storage.begin_read(StorageReadOptions::default())?;
+        let staged = self.staged_writes.staging_overlay()?;
+        Ok(TransactionSqlReadExecutionContext {
+            active_branch_id: self.active_branch_id.clone(),
+            read_store,
+            live_state: Arc::clone(&self.live_state),
+            binary_cas: Arc::clone(&self.binary_cas),
+            branch_ctx: Arc::clone(&self.branch_ctx),
+            visible_schemas: self.cached_visible_schemas()?.to_vec(),
+            functions: self.functions.clone(),
+            staged,
+        })
     }
 
-    /// Advances a version ref without staging tracked rows.
+    pub(crate) async fn prepare_sql_visible_schemas(&mut self) -> Result<(), LixError> {
+        if self.sql_schema_cache.is_prepared() {
+            return Ok(());
+        }
+        let read = self.storage.begin_read(StorageReadOptions::default())?;
+        let live_state = self.live_state.reader(&read);
+        let visible_schemas = self
+            .catalog_context
+            .schema_jsons_for_sql_read_planning(&live_state, &self.active_branch_id)
+            .await?;
+        self.sql_schema_cache.prepare(visible_schemas);
+        Ok(())
+    }
+
+    fn cached_visible_schemas(&self) -> Result<&[JsonValue], LixError> {
+        self.sql_schema_cache.visible_schemas()
+    }
+
+    /// Advances a branch ref without staging tracked rows.
     ///
     /// Fast-forward merges use this path because the commit graph already
     /// contains the source head; the target ref only needs to move to it.
-    pub(crate) async fn advance_version_ref(
+    pub(crate) async fn advance_branch_ref(
         &mut self,
-        version_id: &str,
+        branch_id: &str,
         commit_id: &str,
     ) -> Result<(), LixError> {
         let timestamp = self.functions.call_timestamp();
-        let mut writes = StorageWriteSet::new();
-        let canonical_row = prepare_version_ref_row(version_id, commit_id, &timestamp)?;
-        self.version_ctx
-            .stage_canonical_ref_rows(&mut writes, &[canonical_row.row])?;
-        writes
-            .apply(&mut self.storage_transaction.as_mut())
-            .await
-            .map(|_| ())
+        let canonical_row = prepare_branch_ref_row(branch_id, commit_id, &timestamp)?;
+        self.branch_ctx
+            .stage_canonical_ref_rows(&mut self.staged_storage_writes, &[canonical_row.row])
     }
 
-    /// Returns the commit id currently staged for `version_id`, if tracked rows
-    /// have been staged for that version.
-    pub(crate) fn staged_commit_id(&self, version_id: &str) -> Result<Option<String>, LixError> {
-        self.staged_writes.staged_commit_id(version_id)
-    }
-
-    /// Stages a commit for `version_id` even if no tracked rows changed.
-    pub(crate) fn stage_empty_commit(&self, version_id: String) -> Result<String, LixError> {
-        self.staged_writes.stage_empty_commit(version_id)
+    pub(crate) fn stage_merge_commit(
+        &self,
+        branch_id: String,
+        source_parent_commit_id: String,
+        selected_changes: impl IntoIterator<Item = StagedCommitChangeRef>,
+    ) -> Result<String, LixError> {
+        let commit_id = self
+            .staged_writes
+            .stage_selected_commit_change_refs(branch_id.clone(), selected_changes)?;
+        self.staged_writes
+            .add_commit_parent(branch_id, source_parent_commit_id)?;
+        Ok(commit_id)
     }
 
-    /// Creates a version-ref reader scoped to this write transaction.
-    pub(crate) fn version_ref_reader(&mut self) -> impl VersionRefReader + '_ {
-        self.version_ctx
-            .ref_reader(self.storage_transaction.as_mut())
+    /// Creates a branch-ref reader scoped to this write transaction.
+    pub(crate) fn branch_ref_reader(&mut self) -> impl BranchRefReader + '_ {
+        let read = self
+            .storage
+            .begin_read(StorageReadOptions::default())
+            .expect("open transaction read scope");
+        self.branch_ctx.ref_reader(read)
     }
 
     /// Creates a tracked-state reader scoped to this write transaction.
     pub(crate) fn tracked_state_reader(
         &mut self,
-    ) -> TrackedStateStoreReader<&mut dyn StorageWriteTransaction> {
-        self.tracked_state.reader(self.storage_transaction.as_mut())
+    ) -> TrackedStateStoreReader<StorageReadScope<B::Read<'_>>> {
+        let read = self
+            .storage
+            .begin_read(StorageReadOptions::default())
+            .expect("open transaction read scope");
+        self.tracked_state.reader(read)
     }
 
     /// Creates a commit-graph reader scoped to this write transaction.
     pub(crate) fn commit_graph_reader(
         &mut self,
-    ) -> CommitGraphStoreReader<&mut dyn StorageWriteTransaction> {
-        CommitGraphContext::new().reader(self.storage_transaction.as_mut())
+    ) -> CommitGraphStoreReader<StorageReadScope<B::Read<'_>>> {
+        let read = self
+            .storage
+            .begin_read(StorageReadOptions::default())
+            .expect("open transaction read scope");
+        CommitGraphContext::new().reader(read)
+    }
+}
+
+pub(crate) struct TransactionSqlReadExecutionContext<R> {
+    active_branch_id: String,
+    read_store: StorageReadScope<R>,
+    live_state: Arc<LiveStateContext>,
+    binary_cas: Arc<BinaryCasContext>,
+    branch_ctx: Arc<BranchContext>,
+    visible_schemas: Vec<JsonValue>,
+    functions: FunctionProviderHandle,
+    staged: crate::transaction::staging::PreparedStateRowOverlay,
+}
+
+impl<R> TransactionSqlReadExecutionContext<R>
+where
+    R: crate::storage::StorageBackendRead,
+{
+    pub(crate) fn close(self) -> Result<(), LixError> {
+        self.read_store.close().map_err(Into::into)
+    }
+}
+
+impl<R> SqlExecutionContext for TransactionSqlReadExecutionContext<R>
+where
+    R: crate::storage::StorageBackendRead + Clone + Send + Sync + 'static,
+{
+    type ReadStore = StorageReadScope<R>;
+
+    fn active_branch_id(&self) -> &str {
+        &self.active_branch_id
+    }
+
+    fn live_state(&self) -> Arc<dyn crate::live_state::LiveStateReader> {
+        Arc::new(TransactionReadLiveStateReader {
+            base: self.live_state.reader(self.read_store.clone()),
+            staged: self.staged.clone(),
+        })
+    }
+
+    fn functions(&self) -> FunctionProviderHandle {
+        self.functions.clone()
+    }
+
+    fn history_query_source(&self) -> SqlHistoryQuerySource<Self::ReadStore> {
+        HistoryQuerySource {
+            json_reader: crate::json_store::JsonStoreContext::new().reader(self.read_store.store()),
+        }
+    }
+
+    fn changelog_query_source(&self) -> SqlChangelogQuerySource<Self::ReadStore> {
+        ChangelogQuerySource {
+            store: self.read_store.clone(),
+            json_reader: crate::json_store::JsonStoreContext::new().reader(self.read_store.store()),
+        }
+    }
+
+    fn commit_graph(&self) -> Box<dyn crate::commit_graph::CommitGraphReader> {
+        Box::new(CommitGraphContext::new().reader(self.read_store.clone()))
+    }
+
+    fn branch_ref(&self) -> Arc<dyn BranchRefReader> {
+        Arc::new(self.branch_ctx.ref_reader(self.read_store.clone()))
+    }
+
+    fn blob_reader(&self) -> Arc<dyn crate::binary_cas::BlobDataReader> {
+        Arc::new(self.binary_cas.reader(self.read_store.clone()))
+    }
+
+    fn list_visible_schemas(&self) -> Result<Vec<JsonValue>, LixError> {
+        Ok(self.visible_schemas.clone())
+    }
+}
+
+struct TransactionReadLiveStateReader<R> {
+    base: crate::live_state::LiveStateStoreReader<StorageReadScope<R>>,
+    staged: crate::transaction::staging::PreparedStateRowOverlay,
+}
+
+#[async_trait]
+impl<R> crate::live_state::LiveStateReader for TransactionReadLiveStateReader<R>
+where
+    R: crate::storage::StorageBackendRead + Clone + Send + Sync,
+{
+    async fn scan_rows(
+        &self,
+        request: &LiveStateScanRequest,
+    ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
+        overlay_scan_rows(&self.base, &self.staged, request).await
+    }
+
+    async fn load_row(
+        &self,
+        request: &LiveStateRowRequest,
+    ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
+        Ok(self
+            .scan_rows(&LiveStateScanRequest {
+                filter: crate::live_state::LiveStateFilter {
+                    schema_keys: vec![request.schema_key.clone()],
+                    entity_pks: vec![request.entity_pk.clone()],
+                    branch_ids: vec![request.branch_id.clone()],
+                    file_ids: vec![request.file_id.clone()],
+                    ..Default::default()
+                },
+                limit: Some(1),
+                ..Default::default()
+            })
+            .await?
+            .into_iter()
+            .next())
     }
 }
 
@@ -562,10 +775,10 @@ fn prepare_state_row(
     Ok(PreparedStateRow {
         schema_plan_id,
         facts,
-        entity_id: row.entity_id.ok_or_else(|| {
+        entity_pk: row.entity_pk.ok_or_else(|| {
             LixError::new(
                 "LIX_ERROR_UNKNOWN",
-                "normalized transaction write row is missing entity_id",
+                "normalized transaction write row is missing entity_pk",
             )
         })?,
         schema_key: row.schema_key,
@@ -583,115 +796,50 @@ fn prepare_state_row(
         },
         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,
+        branch_id: row.branch_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) struct OpenTransaction<B: StorageBackend = InMemoryStorageBackend> {
+    pub(crate) transaction: Transaction<B>,
     pub(crate) runtime_functions: FunctionContext,
 }
 
-pub(crate) async fn open_transaction(
+pub(crate) async fn open_transaction<B>(
     mode: &SessionMode,
-    storage: StorageContext,
+    storage: StorageContext<B>,
     live_state: Arc<LiveStateContext>,
     tracked_state: Arc<TrackedStateContext>,
     binary_cas: Arc<BinaryCasContext>,
-    commit_store: Arc<CommitStoreContext>,
-    version_ctx: Arc<VersionContext>,
+    branch_ctx: Arc<BranchContext>,
     catalog_context: Arc<CatalogContext>,
-) -> Result<OpenTransaction, LixError> {
+) -> Result<OpenTransaction<B>, LixError>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
     Transaction::open(
         mode,
         storage,
         live_state,
         tracked_state,
         binary_cas,
-        commit_store,
-        version_ctx,
+        branch_ctx,
         catalog_context,
     )
     .await
 }
 
 #[async_trait]
-impl SqlWriteExecutionContext for Transaction {
-    fn active_version_id(&self) -> &str {
-        &self.active_version_id
+impl<B> SqlWriteExecutionContext for Transaction<B>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    fn active_branch_id(&self) -> &str {
+        &self.active_branch_id
     }
 
     fn functions(&self) -> FunctionProviderHandle {
@@ -699,14 +847,12 @@ impl SqlWriteExecutionContext for Transaction {
     }
 
     fn list_visible_schemas(&self) -> Result<Vec<JsonValue>, LixError> {
-        Ok(self.visible_schemas.clone())
+        Ok(self.cached_visible_schemas()?.to_vec())
     }
 
     async fn load_bytes_many(&mut self, hashes: &[BlobHash]) -> Result<BlobBytesBatch, LixError> {
-        self.binary_cas
-            .reader(self.storage_transaction.as_mut())
-            .load_bytes_many(hashes)
-            .await
+        let read = self.storage.begin_read(StorageReadOptions::default())?;
+        self.binary_cas.reader(&read).load_bytes_many(hashes).await
     }
 
     async fn scan_live_state(
@@ -714,15 +860,19 @@ impl SqlWriteExecutionContext for Transaction {
         request: &LiveStateScanRequest,
     ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
         let staged = self.staged_writes.staging_overlay()?;
-        let base = self.live_state.reader(self.storage_transaction.as_mut());
+        let read = self.storage.begin_read(StorageReadOptions::default())?;
+        let base = self.live_state.reader(&read);
         overlay_scan_rows(&base, &staged, request).await
     }
 
-    async fn load_version_head(&mut self, version_id: &str) -> Result<Option<String>, LixError> {
-        self.version_ctx
-            .ref_reader(self.storage_transaction.as_mut())
-            .load_head_commit_id(version_id)
-            .await
+    async fn load_branch_head(&mut self, branch_id: &str) -> Result<Option<String>, LixError> {
+        let read = self.storage.begin_read(StorageReadOptions::default())?;
+        let result = self
+            .branch_ctx
+            .ref_reader(&read)
+            .load_head_commit_id(branch_id)
+            .await;
+        result
     }
 
     async fn stage_write(
@@ -733,18 +883,14 @@ impl SqlWriteExecutionContext for Transaction {
     }
 }
 
-fn transaction_write_version_ids(write: &TransactionWrite) -> BTreeSet<String> {
+fn transaction_write_branch_ids(write: &TransactionWrite) -> BTreeSet<String> {
     match write {
-        TransactionWrite::Rows { rows, .. } => transaction_write_row_version_ids(rows),
+        TransactionWrite::Rows { rows, .. } => transaction_write_row_branch_ids(rows),
         TransactionWrite::RowsWithFileData {
             rows, file_data, ..
-        } => transaction_write_row_version_ids(rows)
+        } => transaction_write_row_branch_ids(rows)
             .into_iter()
-            .chain(stage_file_data_version_ids(file_data))
-            .collect(),
-        TransactionWrite::AdoptedChanges { changes } => changes
-            .iter()
-            .map(|change| change.version_id.clone())
+            .chain(stage_file_data_branch_ids(file_data))
             .collect(),
     }
 }
@@ -754,7 +900,6 @@ 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(),
     }
 }
 
@@ -765,7 +910,6 @@ fn transaction_write_untracked_row_count(write: &TransactionWrite) -> usize {
         TransactionWrite::RowsWithFileData { rows, .. } => {
             rows.iter().filter(|row| row.untracked).count()
         }
-        TransactionWrite::AdoptedChanges { .. } => 0,
     }
 }
 
@@ -779,7 +923,6 @@ fn require_valid_transaction_write_storage_scopes(
         TransactionWrite::RowsWithFileData { rows, .. } => {
             require_valid_transaction_write_row_storage_scopes(rows)
         }
-        TransactionWrite::AdoptedChanges { .. } => Ok(()),
     }
 }
 
@@ -787,103 +930,101 @@ 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)?;
+        require_valid_storage_scope(row.branch_id.as_str(), row.global)?;
     }
     Ok(())
 }
 
-fn require_valid_storage_scope(version_id: &str, global: bool) -> Result<(), LixError> {
-    if global != (version_id == GLOBAL_VERSION_ID) {
+fn require_valid_storage_scope(branch_id: &str, global: bool) -> Result<(), LixError> {
+    if global != (branch_id == GLOBAL_BRANCH_ID) {
         return Err(LixError::new(
             LixError::CODE_INVALID_STORAGE_SCOPE,
-            format!("invalid storage scope: version_id='{version_id}', global={global}"),
+            format!("invalid storage scope: branch_id='{branch_id}', global={global}"),
         ));
     }
     Ok(())
 }
 
-fn transaction_write_row_version_ids(rows: &[TransactionWriteRow]) -> BTreeSet<String> {
-    rows.iter().map(|row| row.version_id.clone()).collect()
+fn transaction_write_row_branch_ids(rows: &[TransactionWriteRow]) -> BTreeSet<String> {
+    rows.iter().map(|row| row.branch_id.clone()).collect()
 }
 
-fn stage_file_data_version_ids(file_data: &[TransactionFileData]) -> BTreeSet<String> {
+fn stage_file_data_branch_ids(file_data: &[TransactionFileData]) -> BTreeSet<String> {
     file_data
         .iter()
-        .map(|write| write.version_id.clone())
+        .map(|write| write.branch_id.clone())
         .collect()
 }
 
-async fn resolve_active_version_id(
+async fn resolve_active_branch_id(
     mode: &SessionMode,
     live_state: &LiveStateContext,
-    version_ctx: &VersionContext,
-    transaction: &mut dyn StorageWriteTransaction,
+    branch_ctx: &BranchContext,
+    read: &(impl StorageRead + Send + Sync + ?Sized),
 ) -> Result<String, LixError> {
     match mode {
-        SessionMode::Pinned { version_id } => Ok(version_id.clone()),
-        SessionMode::Workspace => {
-            load_workspace_version_id(live_state, version_ctx, transaction).await
-        }
+        SessionMode::Pinned { branch_id } => Ok(branch_id.clone()),
+        SessionMode::Workspace => load_workspace_branch_id(live_state, branch_ctx, read).await,
     }
 }
 
-async fn load_workspace_version_id(
+async fn load_workspace_branch_id(
     live_state: &LiveStateContext,
-    version_ctx: &VersionContext,
-    transaction: &mut dyn StorageWriteTransaction,
+    branch_ctx: &BranchContext,
+    read: &(impl StorageRead + Send + Sync + ?Sized),
 ) -> Result<String, LixError> {
     let row = live_state
-        .reader(&mut *transaction)
+        .reader(read)
         .load_row(&LiveStateRowRequest {
             schema_key: "lix_key_value".to_string(),
-            version_id: GLOBAL_VERSION_ID.to_string(),
-            entity_id: EntityIdentity::single(WORKSPACE_VERSION_KEY),
+            branch_id: GLOBAL_BRANCH_ID.to_string(),
+            entity_pk: EntityPk::single(WORKSPACE_BRANCH_KEY),
             file_id: NullableKeyFilter::Null,
         })
         .await?
         .ok_or_else(|| {
             LixError::new(
                 "LIX_ERROR_UNKNOWN",
-                "workspace version selector is missing lix_key_value:lix_workspace_version_id",
+                "workspace branch selector is missing lix_key_value:lix_workspace_branch_id",
             )
         })?;
     let snapshot_content = row.snapshot_content.as_deref().ok_or_else(|| {
         LixError::new(
             "LIX_ERROR_UNKNOWN",
-            "workspace version selector is missing snapshot_content",
+            "workspace branch selector is missing snapshot_content",
         )
     })?;
     let snapshot = serde_json::from_str::<JsonValue>(snapshot_content).map_err(|error| {
         LixError::new(
             "LIX_ERROR_UNKNOWN",
-            format!("workspace version selector snapshot is invalid JSON: {error}"),
+            format!("workspace branch selector snapshot is invalid JSON: {error}"),
         )
     })?;
-    let version_id = snapshot
+    let branch_id = snapshot
         .get("value")
         .and_then(JsonValue::as_str)
         .filter(|value| !value.is_empty())
         .ok_or_else(|| {
             LixError::new(
                 "LIX_ERROR_UNKNOWN",
-                "workspace version selector value must be a non-empty string",
+                "workspace branch selector value must be a non-empty string",
             )
         })?
         .to_string();
 
-    let head = version_ctx
-        .ref_reader(&mut *transaction)
-        .load_head_commit_id(&version_id)
+    let head = branch_ctx
+        .ref_reader(read)
+        .load_head_commit_id(&branch_id)
         .await?;
     if head.is_none() {
-        return Err(LixError::version_not_found(
-            version_id,
-            "load_workspace_version_id",
+        return Err(LixError::branch_not_found(
+            branch_id,
+            "load_workspace_branch_id",
             "workspace_selector",
         ));
     }
 
-    Ok(version_id)
+    Ok(branch_id)
 }
 
 #[cfg(test)]
@@ -893,15 +1034,14 @@ mod tests {
     use serde_json::json;
 
     use super::*;
-    use crate::backend::testing::UnitTestBackend;
-    use crate::commit_store::{ChangeScanRequest, CommitStoreContext};
-    use crate::tracked_state::{TrackedStateRowRequest, TrackedStateScanRequest};
+    use crate::branch::BranchContext;
+    use crate::changelog::ChangelogReader;
+    use crate::storage::{InMemoryStorageBackend, StorageReadOptions};
+    use crate::tracked_state::{TrackedStateKey, TrackedStateScanRequest};
     use crate::transaction::types::TransactionJson;
     use crate::untracked_state::{UntrackedStateContext, UntrackedStateRowRequest};
-    use crate::version::VersionContext;
-    use crate::Backend;
     use crate::NullableKeyFilter;
-    use crate::GLOBAL_VERSION_ID;
+    use crate::GLOBAL_BRANCH_ID;
 
     fn live_state_context() -> LiveStateContext {
         LiveStateContext::new(
@@ -915,25 +1055,23 @@ mod tests {
 
     #[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 backend = InMemoryStorageBackend::new();
+        let storage = StorageContext::new(backend.clone());
         let live_state = Arc::new(live_state_context());
         seed_visible_schema_rows(storage.clone()).await;
         let binary_cas = Arc::new(BinaryCasContext::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 tracked_state = Arc::new(crate::tracked_state::TrackedStateContext::new());
+        let branch_ctx = Arc::new(BranchContext::new(Arc::new(UntrackedStateContext::new())));
         let catalog_context = Arc::new(CatalogContext::new());
         let opened = open_transaction(
             &SessionMode::Pinned {
-                version_id: GLOBAL_VERSION_ID.to_string(),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
             },
             storage.clone(),
             Arc::clone(&live_state),
-            Arc::new(crate::tracked_state::TrackedStateContext::new()),
+            Arc::clone(&tracked_state),
             Arc::clone(&binary_cas),
-            Arc::clone(&commit_store),
-            Arc::clone(&version_ctx),
+            Arc::clone(&branch_ctx),
             Arc::clone(&catalog_context),
         )
         .await
@@ -953,47 +1091,70 @@ mod tests {
             .await
             .expect("transaction should commit");
 
-        let changes = changelog
-            .reader(storage.clone())
-            .scan_changes(&ChangeScanRequest::default())
+        let tracked_row = live_state
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
+            .load_row(&LiveStateRowRequest {
+                schema_key: "lix_key_value".to_string(),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single("tracked-programmatic"),
+                file_id: NullableKeyFilter::Null,
+            })
             .await
-            .expect("changelog should scan");
-        assert!(
-            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"
+            .expect("tracked row should load")
+            .expect("tracked row should exist");
+        let tracked_change_id = tracked_row
+            .change_id
+            .as_ref()
+            .expect("tracked row should have a change id")
+            .clone();
+        let mut changelog_reader = crate::changelog::ChangelogContext::new().reader(
+            storage
+                .begin_read(StorageReadOptions::default())
+                .expect("read should open"),
         );
+        let changes = changelog_reader
+            .load_changes(crate::changelog::ChangeLoadRequest {
+                change_ids: &[tracked_change_id],
+            })
+            .await
+            .expect("changelog should load tracked change");
         assert!(
-            !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"
+            matches!(
+                changes.entries.as_slice(),
+                [Some(change)]
+                    if change.entity_pk.as_single_string_owned().as_deref()
+                        == Ok("tracked-programmatic")
+            ),
+            "tracked staged row should be appended to changelog"
         );
 
-        let head_commit_id = version_ctx
-            .ref_reader(storage.clone())
-            .load_head_commit_id(GLOBAL_VERSION_ID)
+        let head_commit_id = branch_ctx
+            .ref_reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
+            .load_head_commit_id(GLOBAL_BRANCH_ID)
             .await
-            .expect("version ref should load")
-            .expect("tracked commit should advance the global version ref");
+            .expect("branch ref should load")
+            .expect("tracked commit should advance the global branch ref");
 
         let tracked_row = crate::tracked_state::TrackedStateContext::new()
-            .reader(storage.clone())
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .load_rows_at_commit(
                 &head_commit_id,
-                &[TrackedStateRowRequest {
+                &[TrackedStateKey {
                     schema_key: "lix_key_value".to_string(),
-                    entity_id: crate::entity_identity::EntityIdentity::single(
-                        "tracked-programmatic",
-                    ),
-                    file_id: NullableKeyFilter::Null,
+                    entity_pk: crate::entity_pk::EntityPk::single("tracked-programmatic"),
+                    file_id: None,
                 }],
             )
             .await
@@ -1008,11 +1169,15 @@ mod tests {
         );
 
         let untracked_row = crate::untracked_state::UntrackedStateContext::new()
-            .reader(storage.clone())
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .load_row(&UntrackedStateRowRequest {
                 schema_key: "lix_key_value".to_string(),
-                version_id: GLOBAL_VERSION_ID.to_string(),
-                entity_id: crate::entity_identity::EntityIdentity::single("untracked-programmatic"),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single("untracked-programmatic"),
                 file_id: NullableKeyFilter::Null,
             })
             .await
@@ -1024,11 +1189,15 @@ mod tests {
         );
 
         let live_untracked_row = live_state
-            .reader(storage.clone())
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .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("untracked-programmatic"),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single("untracked-programmatic"),
                 file_id: NullableKeyFilter::Null,
             })
             .await
@@ -1036,17 +1205,21 @@ mod tests {
             .expect("untracked row should be visible through live state");
         assert!(live_untracked_row.untracked);
         assert!(live_untracked_row.global);
-        assert_eq!(live_untracked_row.version_id, GLOBAL_VERSION_ID);
+        assert_eq!(live_untracked_row.branch_id, GLOBAL_BRANCH_ID);
 
         let tracked_rows = crate::tracked_state::TrackedStateContext::new()
-            .reader(storage.clone())
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .scan_rows_at_commit(&head_commit_id, &TrackedStateScanRequest::default())
             .await
             .expect("tracked state should scan");
         assert!(
             tracked_rows
                 .iter()
-                .all(|row| row.entity_id.as_single_string_owned().as_deref()
+                .all(|row| row.entity_pk.as_single_string_owned().as_deref()
                     != Ok("untracked-programmatic")),
             "untracked staged rows should not be written into tracked state"
         );
@@ -1054,25 +1227,22 @@ mod tests {
 
     #[tokio::test]
     async fn commit_validates_staged_rows_before_persistence() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let backend = InMemoryStorageBackend::new();
+        let storage = StorageContext::new(backend.clone());
         let live_state = Arc::new(live_state_context());
         seed_visible_schema_rows(storage.clone()).await;
         let binary_cas = Arc::new(BinaryCasContext::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 branch_ctx = Arc::new(BranchContext::new(Arc::new(UntrackedStateContext::new())));
         let catalog_context = Arc::new(CatalogContext::new());
         let opened = open_transaction(
             &SessionMode::Pinned {
-                version_id: GLOBAL_VERSION_ID.to_string(),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
             },
             storage.clone(),
             Arc::clone(&live_state),
             Arc::new(crate::tracked_state::TrackedStateContext::new()),
             Arc::clone(&binary_cas),
-            Arc::clone(&commit_store),
-            Arc::clone(&version_ctx),
+            Arc::clone(&branch_ctx),
             Arc::clone(&catalog_context),
         )
         .await
@@ -1098,37 +1268,27 @@ mod tests {
             "validation error should explain the rejected schema data: {error:?}"
         );
 
-        let changes = changelog
-            .reader(storage.clone())
-            .scan_changes(&ChangeScanRequest::default())
-            .await
-            .expect("changelog should scan after failed commit");
-        assert!(
-            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
-            .ref_reader(storage.clone())
-            .load_head_commit_id(GLOBAL_VERSION_ID)
+        let head = branch_ctx
+            .ref_reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
+            .load_head_commit_id(GLOBAL_BRANCH_ID)
             .await
-            .expect("version ref should load after failed commit");
+            .expect("branch ref should load after failed commit");
         assert_eq!(
             head.as_deref(),
             Some(SCHEMA_FIXTURE_COMMIT_ID),
-            "validation failure must not advance the version ref"
+            "validation failure must not advance the branch ref"
         );
     }
 
     #[tokio::test]
     async fn commit_rejects_non_object_metadata_without_sql() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
-        let (live_state, _binary_cas, changelog, version_ref, runtime_functions, mut transaction) =
+        let backend = InMemoryStorageBackend::new();
+        let storage = StorageContext::new(backend.clone());
+        let (live_state, _binary_cas, branch_ref, runtime_functions, mut transaction) =
             open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("invalid-metadata", "value", false);
@@ -1151,8 +1311,7 @@ mod tests {
         assert_no_persistence_after_validation_failure(
             storage.clone(),
             &live_state,
-            &changelog,
-            &version_ref,
+            &branch_ref,
             "invalid-metadata",
         )
         .await;
@@ -1160,15 +1319,9 @@ mod tests {
 
     #[tokio::test]
     async fn stage_rows_rejects_unknown_schema_key_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 backend = InMemoryStorageBackend::new();
+        let (_live_state, _binary_cas, _branch_ref, _runtime_functions, mut transaction) =
+            open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("unknown-schema", "value", false);
         row.schema_key = "missing_schema".to_string();
@@ -1188,49 +1341,37 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn stage_rows_rejects_missing_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("ghost-version-row", "value", false);
-        row.version_id = "ghost-version".to_string();
+    async fn stage_rows_rejects_missing_branch_without_sql() {
+        let backend = InMemoryStorageBackend::new();
+        let (_live_state, _binary_cas, _branch_ref, _runtime_functions, mut transaction) =
+            open_test_transaction(&backend).await;
+
+        let mut row = key_value_stage_row("ghost-branch-row", "value", false);
+        row.branch_id = "ghost-branch".to_string();
         row.global = false;
 
         let error = transaction
             .stage_rows(vec![row])
             .await
-            .expect_err("missing version should be rejected before staging");
+            .expect_err("missing branch should be rejected before staging");
 
-        assert_eq!(error.code, LixError::CODE_VERSION_NOT_FOUND);
+        assert_eq!(error.code, LixError::CODE_BRANCH_NOT_FOUND);
         assert!(
             error
                 .message
-                .contains("version 'ghost-version' was not found"),
-            "error should explain missing version: {error:?}"
+                .contains("branch 'ghost-branch' was not found"),
+            "error should explain missing branch: {error:?}"
         );
     }
 
     #[tokio::test]
     async fn stage_rows_rejects_invalid_storage_scope_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 backend = InMemoryStorageBackend::new();
+        let (_live_state, _binary_cas, _branch_ref, _runtime_functions, mut transaction) =
+            open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("invalid-storage-scope", "value", false);
-        row.version_id = GLOBAL_VERSION_ID.to_string();
+        row.branch_id = GLOBAL_BRANCH_ID.to_string();
         row.global = false;
 
         let error = transaction
@@ -1240,22 +1381,16 @@ mod tests {
 
         assert_eq!(error.code, LixError::CODE_INVALID_STORAGE_SCOPE);
         assert!(
-            error.message.contains("version_id='global', global=false"),
+            error.message.contains("branch_id='global', global=false"),
             "error should explain invalid storage scope: {error:?}"
         );
     }
 
     #[tokio::test]
     async fn stage_rows_rejects_invalid_snapshot_json_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 backend = InMemoryStorageBackend::new();
+        let (_live_state, _binary_cas, _branch_ref, _runtime_functions, mut transaction) =
+            open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("invalid-json", "value", false);
         row.snapshot = Some(TransactionJson::from_value_for_test(json!("not-an-object")));
@@ -1274,9 +1409,9 @@ mod tests {
 
     #[tokio::test]
     async fn commit_rejects_snapshot_that_violates_json_schema_without_sql() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
-        let (live_state, _binary_cas, changelog, version_ref, runtime_functions, mut transaction) =
+        let backend = InMemoryStorageBackend::new();
+        let storage = StorageContext::new(backend.clone());
+        let (live_state, _binary_cas, branch_ref, runtime_functions, mut transaction) =
             open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("schema-mismatch", "value", false);
@@ -1301,8 +1436,7 @@ mod tests {
         assert_no_persistence_after_validation_failure(
             storage.clone(),
             &live_state,
-            &changelog,
-            &version_ref,
+            &branch_ref,
             "schema-mismatch",
         )
         .await;
@@ -1310,15 +1444,9 @@ mod tests {
 
     #[tokio::test]
     async fn stage_rows_rejects_malformed_registered_schema_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 backend = InMemoryStorageBackend::new();
+        let (_live_state, _binary_cas, _branch_ref, _runtime_functions, mut transaction) =
+            open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("malformed-registered-schema", "value", false);
         row.schema_key = "lix_registered_schema".to_string();
@@ -1334,7 +1462,7 @@ mod tests {
                 "additionalProperties": false
             }
         })));
-        row.entity_id = None;
+        row.entity_pk = None;
 
         let error = transaction
             .stage_rows(vec![row])
@@ -1349,62 +1477,52 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn stage_rows_rejects_primary_key_entity_id_mismatch_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;
+    async fn stage_rows_rejects_primary_key_entity_pk_mismatch_without_sql() {
+        let backend = InMemoryStorageBackend::new();
+        let (_live_state, _binary_cas, _branch_ref, _runtime_functions, mut transaction) =
+            open_test_transaction(&backend).await;
 
         let mut row = key_value_stage_row("right-id", "value", false);
-        row.entity_id = Some(crate::entity_identity::EntityIdentity::single("wrong-id"));
+        row.entity_pk = Some(crate::entity_pk::EntityPk::single("wrong-id"));
 
         let error = transaction
             .stage_rows(vec![row])
             .await
-            .expect_err("entity id mismatch should be rejected while staging");
+            .expect_err("entity pk mismatch should be rejected while staging");
 
         assert_eq!(error.code, LixError::CODE_SCHEMA_VALIDATION);
         assert!(
             error
                 .message
-                .contains("does not match x-lix-primary-key derived entity_id"),
-            "error should explain entity id mismatch: {error:?}"
+                .contains("does not match x-lix-primary-key derived entity_pk"),
+            "error should explain entity pk mismatch: {error:?}"
         );
     }
 
     async fn open_test_transaction(
-        backend: &Arc<dyn Backend + Send + Sync>,
+        backend: &InMemoryStorageBackend,
     ) -> (
         Arc<LiveStateContext>,
         Arc<BinaryCasContext>,
-        Arc<CommitStoreContext>,
-        Arc<VersionContext>,
+        Arc<BranchContext>,
         FunctionContext,
         Transaction,
     ) {
-        let storage = StorageContext::new(Arc::clone(backend));
+        let storage = StorageContext::new(backend.clone());
         let live_state = Arc::new(live_state_context());
         seed_visible_schema_rows(storage.clone()).await;
         let binary_cas = Arc::new(BinaryCasContext::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 branch_ctx = Arc::new(BranchContext::new(Arc::new(UntrackedStateContext::new())));
         let catalog_context = Arc::new(CatalogContext::new());
         let opened = open_transaction(
             &SessionMode::Pinned {
-                version_id: GLOBAL_VERSION_ID.to_string(),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
             },
             storage,
             Arc::clone(&live_state),
             Arc::new(crate::tracked_state::TrackedStateContext::new()),
             Arc::clone(&binary_cas),
-            Arc::clone(&commit_store),
-            Arc::clone(&version_ctx),
+            Arc::clone(&branch_ctx),
             catalog_context,
         )
         .await
@@ -1415,8 +1533,7 @@ mod tests {
         (
             live_state,
             binary_cas,
-            changelog,
-            version_ctx,
+            branch_ctx,
             runtime_functions,
             transaction,
         )
@@ -1431,7 +1548,7 @@ mod tests {
                     .expect("seed schema key 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)
+                    entity_pk: crate::schema::registered_schema_entity_pk(&key.schema_key)
                         .expect("registered schema identity should derive"),
                     schema_key: "lix_registered_schema".to_string(),
                     file_id: None,
@@ -1445,18 +1562,18 @@ mod tests {
                 }
             })
             .collect::<Vec<_>>();
-        let version_ref_row = prepare_version_ref_row(
-            GLOBAL_VERSION_ID,
+        let branch_ref_row = prepare_branch_ref_row(
+            GLOBAL_BRANCH_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");
+        .expect("schema fixture branch ref should stage");
+        let mut read = storage
+            .begin_read(crate::storage::StorageReadOptions::default())
+            .expect("schema fixture read should open");
         crate::test_support::stage_tracked_root_from_materialized(
-            storage_transaction.as_mut(),
+            &mut read,
+            &mut writes,
             &crate::tracked_state::TrackedStateContext::new(),
             SCHEMA_FIXTURE_COMMIT_ID,
             None,
@@ -1466,55 +1583,43 @@ mod tests {
         .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
-            .expect("schema fixture rows should apply");
-        storage_transaction
-            .commit()
-            .await
+            .stage_rows([branch_ref_row.row.as_ref()])
+            .expect("schema fixture branch ref should stage");
+        storage
+            .commit_write_set(writes, crate::storage::StorageWriteOptions::default())
             .expect("schema fixture transaction should commit");
     }
 
     async fn assert_no_persistence_after_validation_failure(
         storage: StorageContext,
         live_state: &LiveStateContext,
-        changelog: &CommitStoreContext,
-        version_ctx: &VersionContext,
-        rejected_entity_id: &str,
+        branch_ctx: &BranchContext,
+        rejected_entity_pk: &str,
     ) {
-        let changes = changelog
-            .reader(storage.clone())
-            .scan_changes(&ChangeScanRequest::default())
-            .await
-            .expect("changelog should scan after failed commit");
-        assert!(
-            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
-            .ref_reader(storage.clone())
-            .load_head_commit_id(GLOBAL_VERSION_ID)
+        let head = branch_ctx
+            .ref_reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
+            .load_head_commit_id(GLOBAL_BRANCH_ID)
             .await
-            .expect("version ref should load after failed commit");
+            .expect("branch ref should load after failed commit");
         assert_eq!(
             head.as_deref(),
             Some(SCHEMA_FIXTURE_COMMIT_ID),
-            "validation failure must not advance the version ref"
+            "validation failure must not advance the branch ref"
         );
         let row = live_state
-            .reader(storage)
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .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(rejected_entity_id),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single(rejected_entity_pk),
                 file_id: NullableKeyFilter::Null,
             })
             .await
@@ -1527,7 +1632,7 @@ mod tests {
 
     fn key_value_stage_row(key: &str, value: &str, untracked: bool) -> TransactionWriteRow {
         TransactionWriteRow {
-            entity_id: Some(crate::entity_identity::EntityIdentity::single(key)),
+            entity_pk: Some(crate::entity_pk::EntityPk::single(key)),
             schema_key: "lix_key_value".to_string(),
             file_id: None,
             snapshot: Some(TransactionJson::from_value_for_test(json!({
@@ -1542,7 +1647,7 @@ mod tests {
             change_id: None,
             commit_id: None,
             untracked,
-            version_id: GLOBAL_VERSION_ID.to_string(),
+            branch_id: GLOBAL_BRANCH_ID.to_string(),
         }
     }
 }