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

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

@@ -1,24 +1,24 @@
 use async_trait::async_trait;
 use tokio::sync::Mutex;
 
+use crate::branch::BRANCH_REF_SCHEMA_KEY;
 use crate::commit_graph::CommitGraphContext;
-use crate::entity_identity::EntityIdentity;
-use crate::live_state::visibility;
+use crate::entity_pk::EntityPk;
 use crate::live_state::{
-    LiveStateReader, LiveStateRowRequest, LiveStateScanRequest, MaterializedLiveStateRow,
+    expanded_branch_ids, resolve_visible_rows, LiveStateReader, LiveStateRowRequest,
+    LiveStateScanRequest, MaterializedLiveStateRow, VisibilityBranchScope, VisibilityRequest,
 };
-use crate::storage::StorageReader;
+use crate::storage::StorageRead;
 use crate::tracked_state::{
-    MaterializedTrackedStateRow, TrackedStateContext, TrackedStateFilter, TrackedStateProjection,
-    TrackedStateRowRequest, TrackedStateScanRequest,
+    MaterializedTrackedStateRow, TrackedStateContext, TrackedStateFilter, TrackedStateReadColumns,
+    TrackedStateScanRequest,
 };
 use crate::untracked_state::{
     UntrackedStateContext, UntrackedStateRowRequest, UntrackedStateScanRequest,
 };
-use crate::version::VERSION_REF_SCHEMA_KEY;
 use crate::LixError;
 use crate::NullableKeyFilter;
-use crate::GLOBAL_VERSION_ID;
+use crate::GLOBAL_BRANCH_ID;
 
 const COMMIT_SCHEMA_KEY: &str = "lix_commit";
 const COMMIT_EDGE_SCHEMA_KEY: &str = "lix_commit_edge";
@@ -50,7 +50,7 @@ impl LiveStateContext {
     /// Creates a visible live-state reader over a caller-provided KV store.
     pub(crate) fn reader<S>(&self, store: S) -> LiveStateStoreReader<S>
     where
-        S: StorageReader,
+        S: StorageRead + Send + Sync,
     {
         LiveStateStoreReader {
             store: Mutex::new(store),
@@ -71,46 +71,45 @@ pub(crate) struct LiveStateStoreReader<S> {
 
 impl<S> LiveStateStoreReader<S>
 where
-    S: StorageReader,
+    S: StorageRead + Send + Sync,
 {
     pub(crate) async fn scan_rows(
         &self,
         request: &LiveStateScanRequest,
     ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
-        let mut store = self.store.lock().await;
-        let scope = scan_scope(&mut *store, &self.untracked_state, request).await?;
+        let store = self.store.lock().await;
+        let scope = scan_scope(&*store, &self.untracked_state, request).await?;
         let derived_rows =
-            scan_commit_derived_rows(&mut *store, &self.commit_graph, request, &scope).await?;
+            scan_commit_derived_rows(&*store, &self.commit_graph, request, &scope).await?;
         let mut tracked_rows = Vec::new();
         if request.filter.untracked != Some(true) && !is_commit_derived_only_request(request) {
-            for version_id in &scope.storage_version_ids {
+            for branch_id in &scope.storage_branch_ids {
                 let Some(commit_id) =
-                    load_version_ref_commit_id(&mut *store, &self.untracked_state, version_id)
-                        .await?
+                    load_branch_ref_commit_id(&*store, &self.untracked_state, branch_id).await?
                 else {
                     continue;
                 };
                 let tracked_request = tracked_scan_request_from_live(request);
-                let source = tracked_source_from_version_id(version_id);
-                let store: &mut dyn StorageReader = &mut *store;
+                let source = tracked_source_from_branch_id(branch_id);
+                let store = &*store;
                 tracked_rows.extend(
                     self.tracked_state
                         .reader(store)
                         .scan_rows_at_commit(&commit_id, &tracked_request)
                         .await?
                         .into_iter()
-                        .map(|row| project_tracked_row(row, version_id, source)),
+                        .map(|row| project_tracked_row(row, branch_id, source)),
                 );
             }
         }
 
         let untracked_rows = if request.filter.untracked != Some(false) {
-            let store: &mut dyn StorageReader = &mut *store;
+            let store = &*store;
             self.untracked_state
                 .reader(store)
                 .scan_rows(&untracked_scan_request_from_live(
                     request,
-                    &scope.storage_version_ids,
+                    &scope.storage_branch_ids,
                 ))
                 .await?
                 .into_iter()
@@ -132,14 +131,17 @@ where
                 .chain(derived_rows)
                 .collect()
         };
-        rows = visibility::resolve_scan_rows(
+        rows = resolve_visible_rows(
             rows,
-            &scope.projection_version_ids,
-            request.filter.include_tombstones,
+            Vec::new(),
+            &VisibilityRequest {
+                branch_scope: VisibilityBranchScope::BranchIds {
+                    branch_ids: scope.projection_branch_ids.clone(),
+                },
+                include_tombstones: request.filter.include_tombstones,
+                limit: request.limit,
+            },
         );
-        if let Some(limit) = request.limit {
-            rows.truncate(limit);
-        }
         Ok(rows)
     }
 
@@ -147,95 +149,34 @@ where
         &self,
         request: &LiveStateRowRequest,
     ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
-        let mut store = self.store.lock().await;
-        if !version_ref_exists(&mut *store, &self.untracked_state, &request.version_id).await? {
-            return Ok(None);
-        }
-        if is_commit_derived_schema(&request.schema_key)
-            && request.file_id == NullableKeyFilter::Null
         {
-            let scope = LiveStateScanScope {
-                storage_version_ids: vec![request.version_id.clone()],
-                projection_version_ids: vec![request.version_id.clone()],
-            };
-            let rows = scan_commit_derived_rows(
-                &mut *store,
-                &self.commit_graph,
-                &LiveStateScanRequest {
-                    filter: crate::live_state::LiveStateFilter {
-                        schema_keys: vec![request.schema_key.clone()],
-                        entity_ids: vec![request.entity_id.clone()],
-                        version_ids: vec![request.version_id.clone()],
-                        file_ids: vec![NullableKeyFilter::Null],
-                        untracked: Some(false),
-                        include_tombstones: false,
-                        ..Default::default()
-                    },
-                    limit: Some(1),
+            let store = self.store.lock().await;
+            if !branch_ref_exists(&*store, &self.untracked_state, &request.branch_id).await? {
+                return Ok(None);
+            }
+        }
+        let rows = 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()],
+                    include_tombstones: false,
                     ..Default::default()
                 },
-                &scope,
-            )
+                limit: Some(1),
+                ..Default::default()
+            })
             .await?;
-            if let Some(row) = rows.into_iter().next() {
-                return Ok(Some(row));
-            }
-        }
-        for candidate in load_row_candidates(request) {
-            match candidate.source {
-                LiveStateLookupSource::Untracked => {
-                    let store: &mut dyn StorageReader = &mut *store;
-                    if let Some(row) = self
-                        .untracked_state
-                        .reader(store)
-                        .load_row(&untracked_row_request_from_live(
-                            request,
-                            &candidate.version_id,
-                        ))
-                        .await?
-                    {
-                        return Ok(Some(visibility::project_loaded_row(
-                            MaterializedLiveStateRow::from(row),
-                            &request.version_id,
-                            &candidate.version_id,
-                        )));
-                    }
-                }
-                LiveStateLookupSource::Tracked => {
-                    let Some(commit_id) = load_version_ref_commit_id(
-                        &mut *store,
-                        &self.untracked_state,
-                        &candidate.version_id,
-                    )
-                    .await?
-                    else {
-                        continue;
-                    };
-                    let store: &mut dyn StorageReader = &mut *store;
-                    let tracked_request = tracked_row_request_from_live(request);
-                    let mut rows = self
-                        .tracked_state
-                        .reader(store)
-                        .load_rows_at_commit(&commit_id, &[tracked_request])
-                        .await?;
-                    if let Some(row) = rows.pop().flatten() {
-                        return Ok(Some(project_tracked_row(
-                            row,
-                            &request.version_id,
-                            tracked_source_from_version_id(&candidate.version_id),
-                        )));
-                    }
-                }
-            }
-        }
-        Ok(None)
+        Ok(rows.into_iter().next())
     }
 }
 
 #[async_trait]
 impl<S> LiveStateReader for LiveStateStoreReader<S>
 where
-    S: StorageReader + Sync,
+    S: StorageRead + Send + Sync,
 {
     async fn scan_rows(
         &self,
@@ -253,7 +194,7 @@ where
 }
 
 async fn scan_commit_derived_rows(
-    store: &mut dyn StorageReader,
+    store: &(impl StorageRead + Send + Sync + ?Sized),
     commit_graph: &CommitGraphContext,
     request: &LiveStateScanRequest,
     scope: &LiveStateScanScope,
@@ -265,10 +206,10 @@ async fn scan_commit_derived_rows(
         return Ok(Vec::new());
     }
 
-    let version_ids = if scope.projection_version_ids.is_empty() {
-        vec![GLOBAL_VERSION_ID.to_string()]
+    let branch_ids = if scope.projection_branch_ids.is_empty() {
+        vec![GLOBAL_BRANCH_ID.to_string()]
     } else {
-        scope.projection_version_ids.clone()
+        scope.projection_branch_ids.clone()
     };
     let mut graph = commit_graph.reader(store);
     let commits = graph.all_commits().await?;
@@ -277,23 +218,23 @@ async fn scan_commit_derived_rows(
         schema_filter_allows(&request.filter.schema_keys, COMMIT_EDGE_SCHEMA_KEY);
 
     let mut rows = Vec::new();
-    for version_id in &version_ids {
+    for branch_id in &branch_ids {
         if include_commit {
             for commit in &commits {
-                rows.push(commit_row(commit, version_id)?);
+                rows.push(commit_row(commit, branch_id)?);
             }
         }
         if include_commit_edge {
             for edge in graph.commit_edges(&commits) {
-                rows.push(commit_edge_row(&edge, version_id)?);
+                rows.push(commit_edge_row(&edge, branch_id)?);
             }
         }
     }
 
     rows.retain(|row| {
-        (request.filter.entity_ids.is_empty() || request.filter.entity_ids.contains(&row.entity_id))
-            && (request.filter.version_ids.is_empty()
-                || request.filter.version_ids.contains(&row.version_id))
+        (request.filter.entity_pks.is_empty() || request.filter.entity_pks.contains(&row.entity_pk))
+            && (request.filter.branch_ids.is_empty()
+                || request.filter.branch_ids.contains(&row.branch_id))
     });
     Ok(rows)
 }
@@ -333,7 +274,7 @@ fn file_filter_allows_null(file_ids: &[NullableKeyFilter<String>]) -> bool {
 
 fn commit_row(
     commit: &crate::commit_graph::CommitGraphCommit,
-    version_id: &str,
+    branch_id: &str,
 ) -> Result<MaterializedLiveStateRow, LixError> {
     let snapshot_content = serde_json::to_string(&serde_json::json!({
         "id": commit.commit_id,
@@ -345,7 +286,7 @@ fn commit_row(
         )
     })?;
     Ok(MaterializedLiveStateRow {
-        entity_id: EntityIdentity::single(commit.commit_id.clone()),
+        entity_pk: EntityPk::single(commit.commit_id.clone()),
         schema_key: COMMIT_SCHEMA_KEY.to_string(),
         file_id: None,
         snapshot_content: Some(snapshot_content),
@@ -357,13 +298,13 @@ fn commit_row(
         change_id: Some(commit.change.id.clone()),
         commit_id: Some(commit.commit_id.clone()),
         untracked: false,
-        version_id: version_id.to_string(),
+        branch_id: branch_id.to_string(),
     })
 }
 
 fn commit_edge_row(
     edge: &crate::commit_graph::CommitGraphEdge,
-    version_id: &str,
+    branch_id: &str,
 ) -> Result<MaterializedLiveStateRow, LixError> {
     let snapshot_content = serde_json::to_string(&serde_json::json!({
         "parent_id": edge.parent_commit_id,
@@ -377,7 +318,7 @@ fn commit_edge_row(
         )
     })?;
     Ok(MaterializedLiveStateRow {
-        entity_id: EntityIdentity {
+        entity_pk: EntityPk {
             parts: vec![edge.parent_commit_id.clone(), edge.child_commit_id.clone()],
         },
         schema_key: COMMIT_EDGE_SCHEMA_KEY.to_string(),
@@ -391,7 +332,7 @@ fn commit_edge_row(
         change_id: None,
         commit_id: Some(edge.child_commit_id.clone()),
         untracked: false,
-        version_id: version_id.to_string(),
+        branch_id: branch_id.to_string(),
     })
 }
 
@@ -399,13 +340,13 @@ fn tracked_scan_request_from_live(request: &LiveStateScanRequest) -> TrackedStat
     TrackedStateScanRequest {
         filter: TrackedStateFilter {
             schema_keys: request.filter.schema_keys.clone(),
-            entity_ids: request.filter.entity_ids.clone(),
+            entity_pks: request.filter.entity_pks.clone(),
             file_ids: request.filter.file_ids.clone(),
-            // Scan tombstones internally so version-local tombstones can hide
+            // Scan tombstones internally so branch-local tombstones can hide
             // global fallback rows before the serving facade filters them.
             include_tombstones: true,
         },
-        projection: TrackedStateProjection {
+        read_columns: TrackedStateReadColumns {
             columns: request.projection.columns.clone(),
         },
         limit: None,
@@ -414,10 +355,10 @@ fn tracked_scan_request_from_live(request: &LiveStateScanRequest) -> TrackedStat
 
 fn untracked_scan_request_from_live(
     request: &LiveStateScanRequest,
-    version_ids: &[String],
+    branch_ids: &[String],
 ) -> UntrackedStateScanRequest {
     let mut filter: crate::untracked_state::UntrackedStateFilter = request.filter.clone().into();
-    filter.version_ids = version_ids.to_vec();
+    filter.branch_ids = branch_ids.to_vec();
     UntrackedStateScanRequest {
         filter,
         projection: crate::untracked_state::UntrackedStateProjection {
@@ -429,67 +370,67 @@ fn untracked_scan_request_from_live(
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct LiveStateScanScope {
-    storage_version_ids: Vec<String>,
-    projection_version_ids: Vec<String>,
+    storage_branch_ids: Vec<String>,
+    projection_branch_ids: Vec<String>,
 }
 
 async fn scan_scope(
-    store: &mut dyn StorageReader,
+    store: &(impl StorageRead + Send + Sync + ?Sized),
     untracked_state: &UntrackedStateContext,
     request: &LiveStateScanRequest,
 ) -> Result<LiveStateScanScope, LixError> {
-    if request.filter.version_ids.is_empty() {
+    if request.filter.branch_ids.is_empty() {
         return Ok(LiveStateScanScope {
-            storage_version_ids: all_version_ref_ids(store, untracked_state).await?,
-            projection_version_ids: Vec::new(),
+            storage_branch_ids: all_branch_ref_ids(store, untracked_state).await?,
+            projection_branch_ids: Vec::new(),
         });
     }
 
-    let mut projection_version_ids = Vec::new();
-    for version_id in &request.filter.version_ids {
-        if version_ref_exists(store, untracked_state, version_id).await? {
-            projection_version_ids.push(version_id.clone());
+    let mut projection_branch_ids = Vec::new();
+    for branch_id in &request.filter.branch_ids {
+        if branch_ref_exists(store, untracked_state, branch_id).await? {
+            projection_branch_ids.push(branch_id.clone());
         }
     }
 
-    let storage_version_ids = visibility::expanded_version_ids(&projection_version_ids);
+    let storage_branch_ids = expanded_branch_ids(&projection_branch_ids);
     Ok(LiveStateScanScope {
-        storage_version_ids,
-        projection_version_ids,
+        storage_branch_ids,
+        projection_branch_ids,
     })
 }
 
-async fn all_version_ref_ids(
-    store: &mut dyn StorageReader,
+async fn all_branch_ref_ids(
+    store: &(impl StorageRead + Send + Sync + ?Sized),
     untracked_state: &UntrackedStateContext,
 ) -> Result<Vec<String>, LixError> {
     let rows = untracked_state
         .reader(store)
         .scan_rows(&UntrackedStateScanRequest {
             filter: crate::untracked_state::UntrackedStateFilter {
-                schema_keys: vec![VERSION_REF_SCHEMA_KEY.to_string()],
-                version_ids: vec![GLOBAL_VERSION_ID.to_string()],
+                schema_keys: vec![BRANCH_REF_SCHEMA_KEY.to_string()],
+                branch_ids: vec![GLOBAL_BRANCH_ID.to_string()],
                 ..Default::default()
             },
             ..Default::default()
         })
         .await?;
     rows.into_iter()
-        .map(|row| row.entity_id.as_single_string_owned())
+        .map(|row| row.entity_pk.as_single_string_owned())
         .collect()
 }
 
-async fn load_version_ref_commit_id(
-    store: &mut dyn StorageReader,
+async fn load_branch_ref_commit_id(
+    store: &(impl StorageRead + Send + Sync + ?Sized),
     untracked_state: &UntrackedStateContext,
-    version_id: &str,
+    branch_id: &str,
 ) -> Result<Option<String>, LixError> {
     let Some(row) = untracked_state
         .reader(store)
         .load_row(&UntrackedStateRowRequest {
-            schema_key: VERSION_REF_SCHEMA_KEY.to_string(),
-            version_id: GLOBAL_VERSION_ID.to_string(),
-            entity_id: crate::entity_identity::EntityIdentity::single(version_id),
+            schema_key: BRANCH_REF_SCHEMA_KEY.to_string(),
+            branch_id: GLOBAL_BRANCH_ID.to_string(),
+            entity_pk: crate::entity_pk::EntityPk::single(branch_id),
             file_id: crate::NullableKeyFilter::Null,
         })
         .await?
@@ -503,7 +444,7 @@ async fn load_version_ref_commit_id(
         serde_json::from_str::<serde_json::Value>(snapshot_content).map_err(|error| {
             LixError::new(
                 "LIX_ERROR_UNKNOWN",
-                format!("live_state version-ref snapshot parse failed: {error}"),
+                format!("live_state branch-ref snapshot parse failed: {error}"),
             )
         })?;
     Ok(snapshot
@@ -512,39 +453,37 @@ async fn load_version_ref_commit_id(
         .map(str::to_string))
 }
 
-async fn version_ref_exists(
-    store: &mut dyn StorageReader,
+async fn branch_ref_exists(
+    store: &(impl StorageRead + Send + Sync + ?Sized),
     untracked_state: &UntrackedStateContext,
-    version_id: &str,
+    branch_id: &str,
 ) -> Result<bool, LixError> {
-    Ok(
-        load_version_ref_commit_id(store, untracked_state, version_id)
-            .await?
-            .is_some(),
-    )
+    Ok(load_branch_ref_commit_id(store, untracked_state, branch_id)
+        .await?
+        .is_some())
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum TrackedRowSource {
     Global,
-    Version,
+    Branch,
 }
 
-fn tracked_source_from_version_id(version_id: &str) -> TrackedRowSource {
-    if version_id == GLOBAL_VERSION_ID {
+fn tracked_source_from_branch_id(branch_id: &str) -> TrackedRowSource {
+    if branch_id == GLOBAL_BRANCH_ID {
         TrackedRowSource::Global
     } else {
-        TrackedRowSource::Version
+        TrackedRowSource::Branch
     }
 }
 
 fn project_tracked_row(
     row: MaterializedTrackedStateRow,
-    view_version_id: &str,
+    view_branch_id: &str,
     source: TrackedRowSource,
 ) -> MaterializedLiveStateRow {
     MaterializedLiveStateRow {
-        entity_id: row.entity_id,
+        entity_pk: row.entity_pk,
         schema_key: row.schema_key,
         file_id: row.file_id,
         snapshot_content: row.snapshot_content,
@@ -556,83 +495,18 @@ fn project_tracked_row(
         change_id: Some(row.change_id),
         commit_id: Some(row.commit_id),
         untracked: false,
-        version_id: view_version_id.to_string(),
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum LiveStateLookupSource {
-    Untracked,
-    Tracked,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct LiveStateLookupCandidate {
-    source: LiveStateLookupSource,
-    version_id: String,
-}
-
-fn load_row_candidates(request: &LiveStateRowRequest) -> Vec<LiveStateLookupCandidate> {
-    let mut candidates = vec![
-        LiveStateLookupCandidate {
-            source: LiveStateLookupSource::Untracked,
-            version_id: request.version_id.clone(),
-        },
-        LiveStateLookupCandidate {
-            source: LiveStateLookupSource::Tracked,
-            version_id: request.version_id.clone(),
-        },
-    ];
-
-    if request.version_id != GLOBAL_VERSION_ID {
-        candidates.extend([
-            LiveStateLookupCandidate {
-                source: LiveStateLookupSource::Untracked,
-                version_id: GLOBAL_VERSION_ID.to_string(),
-            },
-            LiveStateLookupCandidate {
-                source: LiveStateLookupSource::Tracked,
-                version_id: GLOBAL_VERSION_ID.to_string(),
-            },
-        ]);
-    }
-
-    candidates
-}
-
-fn untracked_row_request_from_live(
-    request: &LiveStateRowRequest,
-    version_id: &str,
-) -> crate::untracked_state::UntrackedStateRowRequest {
-    crate::untracked_state::UntrackedStateRowRequest {
-        schema_key: request.schema_key.clone(),
-        version_id: version_id.to_string(),
-        entity_id: request.entity_id.clone(),
-        file_id: request.file_id.clone(),
-    }
-}
-
-fn tracked_row_request_from_live(request: &LiveStateRowRequest) -> TrackedStateRowRequest {
-    TrackedStateRowRequest {
-        schema_key: request.schema_key.clone(),
-        entity_id: request.entity_id.clone(),
-        file_id: request.file_id.clone(),
+        branch_id: view_branch_id.to_string(),
     }
 }
 
 #[cfg(test)]
 mod tests {
-    use std::sync::Arc;
-
     use super::*;
-    use crate::backend::{testing::UnitTestBackend, Backend};
-    use crate::commit_store::{CommitDraftRef, CommitStoreContext};
-    use crate::entity_identity::EntityIdentity;
-    use crate::json_store::{
-        JsonStoreContext, JsonWritePlacementRef, NormalizedJson, NormalizedJsonRef,
-    };
+    use crate::entity_pk::EntityPk;
+    use crate::json_store::{JsonRef, JsonStoreContext, JsonWritePlacementRef, NormalizedJsonRef};
     use crate::live_state::LiveStateFilter;
-    use crate::storage::{StorageContext, StorageWriteSet, StorageWriteTransaction};
+    use crate::storage::{InMemoryStorageBackend, StorageReadOptions, StorageWriteOptions};
+    use crate::storage::{StorageContext, StorageWriteSet};
     use crate::tracked_state::{TrackedStateDeltaRef, TrackedStateScanRequest};
     use crate::untracked_state::{MaterializedUntrackedStateRow, UntrackedStateContext};
     use crate::NullableKeyFilter;
@@ -649,10 +523,11 @@ mod tests {
     }
 
     async fn write_untracked_rows_to_store(
-        store: &mut (impl StorageWriteTransaction + ?Sized),
+        storage: &StorageContext,
+        _read: &(impl crate::storage::StorageRead + Send + Sync + ?Sized),
         rows: &[MaterializedUntrackedStateRow],
     ) {
-        let mut writes = StorageWriteSet::new();
+        let mut writes = storage.new_write_set();
         let canonical_rows = rows
             .iter()
             .map(|row| crate::test_support::untracked_state_row_from_materialized(&mut writes, row))
@@ -662,51 +537,92 @@ mod tests {
             .writer(&mut writes)
             .stage_rows(canonical_rows.iter().map(|row| row.as_ref()))
             .expect("untracked rows should write");
-        writes
-            .apply(store)
-            .await
-            .expect("untracked rows should apply");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("untracked rows should commit");
     }
 
     async fn write_empty_commits_to_store(
-        store: &mut (impl StorageWriteTransaction + ?Sized),
+        storage: &StorageContext,
+        read: &(impl crate::storage::StorageRead + Send + Sync),
         commit_ids: &[&str],
     ) {
-        let mut writes = StorageWriteSet::new();
+        let mut writes = storage.new_write_set();
+        let mut json_writer = JsonStoreContext::new().writer();
+        let mut append = crate::changelog::ChangelogAppend::default();
         for commit_id in commit_ids {
             let commit_change_id = format!("{commit_id}:commit");
-            CommitStoreContext::new()
-                .writer(&mut *store, &mut writes)
-                .stage_commit_draft(
-                    CommitDraftRef {
-                        id: commit_id,
-                        change_id: &commit_change_id,
-                        parent_ids: &[],
-                        author_account_ids: &[],
-                        created_at: "1970-01-01T00:00:00.000Z",
-                    },
-                    Vec::new(),
-                    Vec::new(),
+            append.commits.push(crate::changelog::CommitRecord {
+                format_version: 1,
+                commit_id: (*commit_id).to_string(),
+                parent_commit_ids: Vec::new(),
+                change_id: commit_change_id.clone(),
+                author_account_ids: Vec::new(),
+                created_at: "1970-01-01T00:00:00.000Z".to_string(),
+            });
+            append
+                .commit_change_refs
+                .push(crate::changelog::CommitChangeRefSet {
+                    commit_id: (*commit_id).to_string(),
+                    entries: Vec::new(),
+                });
+        }
+        let mut changelog_read = read;
+        let mut writer =
+            crate::changelog::ChangelogContext::new().writer(&mut changelog_read, &mut writes);
+        crate::changelog::ChangelogWriter::stage_append(&mut writer, append)
+            .await
+            .expect("empty changelog commits should stage");
+        drop(writer);
+        for commit_id in commit_ids {
+            let snapshot_content =
+                commit_row_snapshot_content(commit_id).expect("commit snapshot should encode");
+            let snapshot_ref = JsonRef::for_content(snapshot_content.as_bytes());
+            json_writer
+                .stage_batch(
+                    &mut writes,
+                    JsonWritePlacementRef::OutOfBand,
+                    [NormalizedJsonRef::trusted_prehashed(
+                        &snapshot_content,
+                        snapshot_ref.clone(),
+                    )],
                 )
+                .expect("commit snapshot should stage");
+            let change_id = format!("{commit_id}:commit");
+            let entity_pk = EntityPk::single(*commit_id);
+            let deltas = [TrackedStateDeltaRef {
+                schema_key: COMMIT_SCHEMA_KEY,
+                file_id: None,
+                entity_pk: &entity_pk,
+                change_id: &change_id,
+                commit_id,
+                snapshot_ref: Some(&snapshot_ref),
+                metadata_ref: None,
+                deleted: false,
+                created_at: "1970-01-01T00:00:00.000Z",
+                updated_at: "1970-01-01T00:00:00.000Z",
+            }];
+            TrackedStateContext::new()
+                .writer(read, &mut writes)
+                .stage_commit_root(commit_id, None, deltas)
                 .await
-                .expect("empty commit should stage");
+                .expect("empty tracked roots should stage");
         }
-        writes
-            .apply(store)
-            .await
-            .expect("empty commits should apply");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("empty commits should commit");
     }
 
     async fn stage_materialized_live_rows(
-        store: &mut (impl StorageReader + ?Sized),
+        store: &(impl StorageRead + Send + Sync),
         writes: &mut StorageWriteSet,
-        _json_writer: &mut crate::json_store::JsonStoreWriter,
+        json_writer: &mut crate::json_store::JsonStoreWriter,
         rows: &[MaterializedLiveStateRow],
     ) -> Result<(), LixError> {
         let mut untracked_rows = Vec::new();
         let mut tracked_rows_by_commit = std::collections::BTreeMap::<
             String,
-            Vec<(crate::commit_store::Change, String, String)>,
+            Vec<(crate::changelog::ChangeRecord, String, String)>,
         >::new();
         let mut parent_by_commit = std::collections::BTreeMap::<String, Option<String>>::new();
 
@@ -732,7 +648,7 @@ mod tests {
             }
             if row.schema_key != COMMIT_SCHEMA_KEY {
                 let change = crate::test_support::tracked_change_from_materialized(&materialized)?;
-                stage_tracked_materialized_json(writes, &commit_id, &materialized)?;
+                stage_json_payloads_from_materialized(writes, json_writer, &materialized)?;
                 tracked_rows_by_commit.entry(commit_id).or_default().push((
                     change,
                     materialized.created_at,
@@ -750,69 +666,125 @@ mod tests {
                 .as_ref()
                 .map(|parent| vec![parent.clone()])
                 .unwrap_or_default();
+            let commit_created_at = rows
+                .first()
+                .map(|(change, _, _)| change.created_at.as_str())
+                .unwrap_or("1970-01-01T00:00:00.000Z")
+                .to_string();
+            let change_refs = rows
+                .iter()
+                .map(|(change, _, _)| crate::changelog::CommitChangeRef {
+                    schema_key: change.schema_key.clone(),
+                    file_id: change.file_id.clone(),
+                    entity_pk: change.entity_pk.clone(),
+                    change_id: change.change_id.clone(),
+                })
+                .collect::<Vec<_>>();
             let commit_change_id = format!("{commit_id}:commit");
-            let commit = CommitDraftRef {
-                id: &commit_id,
-                change_id: &commit_change_id,
-                parent_ids: &parent_ids,
-                author_account_ids: &[],
-                created_at: rows
-                    .first()
-                    .map(|(change, _, _)| change.created_at.as_str())
-                    .unwrap_or("1970-01-01T00:00:00.000Z"),
-            };
-            let staged = CommitStoreContext::new()
-                .writer(&mut *store, writes)
-                .stage_tracked_commit_draft(
-                    commit,
-                    rows.iter().map(|(change, _, _)| change.as_ref()).collect(),
-                    Vec::new(),
-                )
-                .await?;
-            let deltas = rows
+            let mut append = crate::changelog::ChangelogAppend::default();
+            append
+                .changes
+                .extend(rows.iter().map(|(change, _, _)| change.clone()));
+            append.commits.push(crate::changelog::CommitRecord {
+                format_version: 1,
+                commit_id: commit_id.clone(),
+                parent_commit_ids: parent_ids,
+                change_id: commit_change_id.clone(),
+                author_account_ids: Vec::new(),
+                created_at: commit_created_at.clone(),
+            });
+            append
+                .commit_change_refs
+                .push(crate::changelog::CommitChangeRefSet {
+                    commit_id: commit_id.clone(),
+                    entries: change_refs,
+                });
+            let mut changelog_read = store;
+            let mut writer =
+                crate::changelog::ChangelogContext::new().writer(&mut changelog_read, writes);
+            crate::changelog::ChangelogWriter::stage_append(&mut writer, append).await?;
+            drop(writer);
+            let snapshot_content = commit_row_snapshot_content(&commit_id)?;
+            let snapshot_ref = JsonRef::for_content(snapshot_content.as_bytes());
+            json_writer.stage_batch(
+                writes,
+                JsonWritePlacementRef::OutOfBand,
+                [NormalizedJsonRef::trusted_prehashed(
+                    &snapshot_content,
+                    snapshot_ref.clone(),
+                )],
+            )?;
+            let commit_entity_pk = EntityPk::single(&commit_id);
+            let mut deltas = rows
                 .iter()
-                .zip(&staged.authored_locators)
-                .map(
-                    |((change, created_at, updated_at), locator)| TrackedStateDeltaRef {
-                        change: change.as_ref(),
-                        locator: locator.as_ref(),
-                        created_at,
-                        updated_at,
-                    },
-                )
+                .map(|(change, created_at, updated_at)| TrackedStateDeltaRef {
+                    schema_key: &change.schema_key,
+                    file_id: change.file_id.as_deref(),
+                    entity_pk: &change.entity_pk,
+                    change_id: &change.change_id,
+                    commit_id: &commit_id,
+                    snapshot_ref: change.snapshot_ref.as_ref(),
+                    metadata_ref: change.metadata_ref.as_ref(),
+                    deleted: change.snapshot_ref.is_none(),
+                    created_at,
+                    updated_at,
+                })
                 .collect::<Vec<_>>();
+            deltas.push(TrackedStateDeltaRef {
+                schema_key: COMMIT_SCHEMA_KEY,
+                file_id: None,
+                entity_pk: &commit_entity_pk,
+                change_id: &commit_change_id,
+                commit_id: &commit_id,
+                snapshot_ref: Some(&snapshot_ref),
+                metadata_ref: None,
+                deleted: false,
+                created_at: &commit_created_at,
+                updated_at: &commit_created_at,
+            });
             TrackedStateContext::new()
-                .writer(&mut *store, writes)
-                .stage_delta(&commit_id, parent_commit_id.as_deref(), &deltas)
+                .writer(&*store, writes)
+                .stage_commit_root(&commit_id, parent_commit_id.as_deref(), deltas)
                 .await?;
         }
         Ok(())
     }
 
-    fn stage_tracked_materialized_json(
+    fn commit_row_snapshot_content(commit_id: &str) -> Result<String, LixError> {
+        serde_json::to_string(&json!({ "id": commit_id })).map_err(|error| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("failed to encode test commit snapshot: {error}"),
+            )
+        })
+    }
+
+    fn stage_json_payloads_from_materialized(
         writes: &mut StorageWriteSet,
-        commit_id: &str,
+        json_writer: &mut crate::json_store::JsonStoreWriter,
         row: &MaterializedTrackedStateRow,
     ) -> Result<(), LixError> {
-        let mut payloads = Vec::new();
         if let Some(snapshot) = row.snapshot_content.as_deref() {
-            payloads.push(NormalizedJson::from_arc_unchecked(Arc::from(snapshot)));
+            json_writer.stage_batch(
+                writes,
+                JsonWritePlacementRef::OutOfBand,
+                [NormalizedJsonRef::trusted_prehashed(
+                    snapshot,
+                    JsonRef::for_content(snapshot.as_bytes()),
+                )],
+            )?;
         }
         if let Some(metadata) = row.metadata.as_ref() {
-            payloads.push(NormalizedJson::from_arc_unchecked(Arc::from(
-                crate::serialize_row_metadata(metadata),
-            )));
+            let serialized = crate::serialize_row_metadata(metadata);
+            json_writer.stage_batch(
+                writes,
+                JsonWritePlacementRef::OutOfBand,
+                [NormalizedJsonRef::trusted_prehashed(
+                    &serialized,
+                    JsonRef::for_content(serialized.as_bytes()),
+                )],
+            )?;
         }
-        JsonStoreContext::new().writer().stage_batch(
-            writes,
-            JsonWritePlacementRef::CommitPack {
-                commit_id,
-                pack_id: 0,
-            },
-            payloads
-                .iter()
-                .map(|payload| NormalizedJsonRef::from(payload)),
-        )?;
         Ok(())
     }
 
@@ -838,20 +810,18 @@ mod tests {
 
     #[tokio::test]
     async fn live_state_overlays_untracked_rows() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
                 stage_materialized_live_rows(
-                    transaction.as_mut(),
+                    &read,
                     &mut writes,
                     &mut json_writer,
                     &[tracked_row_with_commit(
@@ -863,22 +833,21 @@ mod tests {
                 .await
                 .expect("tracked row should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked row should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-tracked"),
+                branch_ref_row("global", "commit-tracked"),
                 untracked_row("untracked-value"),
             ],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let rows = scan_selected_tab_at(&live_state, storage.clone(), "global", false)
+        let rows = scan_selected_tab_at(&live_state, &storage, "global", false)
             .await
             .expect("scan should succeed");
         assert_eq!(rows.len(), 1);
@@ -890,11 +859,15 @@ mod tests {
         assert_eq!(rows[0].change_id, None);
 
         let loaded = live_state
-            .reader(storage.clone())
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .load_row(&LiveStateRowRequest {
                 schema_key: "lix_key_value".to_string(),
-                version_id: "global".to_string(),
-                entity_id: crate::entity_identity::EntityIdentity::single("selected-tab"),
+                branch_id: "global".to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single("selected-tab"),
                 file_id: NullableKeyFilter::Null,
             })
             .await
@@ -909,20 +882,18 @@ mod tests {
 
     #[tokio::test]
     async fn tracked_row_is_visible_without_untracked_overlay() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
                 stage_materialized_live_rows(
-                    transaction.as_mut(),
+                    &read,
                     &mut writes,
                     &mut json_writer,
                     &[tracked_row_with_commit(
@@ -934,19 +905,18 @@ mod tests {
                 .await
                 .expect("tracked row should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked row should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
-            &[version_ref_row("global", "commit-tracked")],
+            &storage,
+            &read,
+            &[branch_ref_row("global", "commit-tracked")],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let loaded = load_selected_tab(&live_state, storage.clone())
+        let loaded = load_selected_tab(&live_state, &storage)
             .await
             .expect("load should succeed")
             .expect("tracked row should be visible");
@@ -960,20 +930,18 @@ mod tests {
 
     #[tokio::test]
     async fn deleting_untracked_row_reveals_tracked_row() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
                 stage_materialized_live_rows(
-                    transaction.as_mut(),
+                    &read,
                     &mut writes,
                     &mut json_writer,
                     &[tracked_row_with_commit(
@@ -985,15 +953,15 @@ mod tests {
                 .await
                 .expect("tracked row should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked row should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-tracked"),
+                branch_ref_row("global", "commit-tracked"),
                 untracked_row("untracked-value"),
             ],
         )
@@ -1001,22 +969,21 @@ mod tests {
         {
             let mut writes = StorageWriteSet::new();
             let identity = crate::untracked_state::UntrackedStateIdentity {
-                version_id: "global".to_string(),
+                branch_id: "global".to_string(),
                 schema_key: "lix_key_value".to_string(),
-                entity_id: EntityIdentity::single("selected-tab"),
+                entity_pk: EntityPk::single("selected-tab"),
                 file_id: None,
             };
             UntrackedStateContext::new()
                 .writer(&mut writes)
-                .stage_delete_rows(std::iter::once(identity.as_ref()));
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("untracked row should delete");
+                .stage_delete_rows(std::iter::once(identity.as_ref()))
+                .expect("delete identity should stage");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
-        transaction.commit().await.expect("commit should persist");
 
-        let loaded = load_selected_tab(&live_state, storage.clone())
+        let loaded = load_selected_tab(&live_state, &storage)
             .await
             .expect("load should succeed")
             .expect("tracked row should be visible again");
@@ -1029,15 +996,13 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn load_row_falls_back_to_global_tracked_row_for_requested_version() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+    async fn load_row_falls_back_to_global_tracked_row_for_requested_branch() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [tracked_row_with_commit(
                 "global-tracked",
@@ -1047,37 +1012,31 @@ mod tests {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("tracked row should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("tracked row should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked row should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("version-a", "commit-version-a"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("branch-a", "commit-branch-a"),
             ],
         )
         .await;
-        write_empty_commits_to_store(transaction.as_mut(), &["commit-version-a"]).await;
-        transaction.commit().await.expect("commit should persist");
+        write_empty_commits_to_store(&storage, &read, &["commit-branch-a"]).await;
 
-        let loaded = load_selected_tab_at(&live_state, storage.clone(), "version-a")
+        let loaded = load_selected_tab_at(&live_state, &storage, "branch-a")
             .await
             .expect("load should succeed")
-            .expect("global row should be visible for requested version");
+            .expect("global row should be visible for requested branch");
 
-        assert_eq!(loaded.version_id, "version-a");
+        assert_eq!(loaded.branch_id, "branch-a");
         assert!(loaded.global);
         assert!(!loaded.untracked);
         assert_eq!(
@@ -1088,8 +1047,7 @@ mod tests {
 
     #[tokio::test]
     async fn main_sees_global_row_by_reading_global_root_separately() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let tracked_state = TrackedStateContext::new();
         let live_state = LiveStateContext::new(
             tracked_state.clone(),
@@ -1097,10 +1055,9 @@ mod tests {
             crate::commit_graph::CommitGraphContext::new(),
         );
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [tracked_row_with_commit(
                 "global-tracked",
@@ -1110,121 +1067,105 @@ mod tests {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("global tracked row should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("global tracked row should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("global tracked row should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("main", "commit-main"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("main", "commit-main"),
             ],
         )
         .await;
-        write_empty_commits_to_store(transaction.as_mut(), &["commit-main"]).await;
-        transaction.commit().await.expect("commit should persist");
+        write_empty_commits_to_store(&storage, &read, &["commit-main"]).await;
 
-        let loaded = load_selected_tab_at(&live_state, storage.clone(), "main")
+        let loaded = load_selected_tab_at(&live_state, &storage, "main")
             .await
             .expect("load should succeed")
             .expect("global row should be projected into main");
-        assert_eq!(loaded.version_id, "main");
+        assert_eq!(loaded.branch_id, "main");
         assert!(loaded.global);
         assert_eq!(
             loaded.snapshot_content.as_deref(),
             Some("{\"value\":\"global-tracked\"}")
         );
 
-        let main_root_rows =
-            scan_tracked_root(&tracked_state, storage.clone(), "commit-main").await;
+        let main_root_rows = scan_tracked_root(&tracked_state, &storage, "commit-main").await;
         assert_eq!(
             main_root_rows.len(),
-            0,
-            "global fallback must come from the global root, not a copied main root row"
+            1,
+            "empty commit root should contain only its derived lix_commit row"
         );
+        assert_eq!(main_root_rows[0].schema_key, "lix_commit");
     }
 
     #[tokio::test]
-    async fn load_row_prefers_requested_version_over_global() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+    async fn load_row_prefers_requested_branch_over_global() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [
                 tracked_row_with_commit("global-tracked", Some("change-global"), "commit-global"),
                 tracked_row_at_with_commit(
-                    "version-a",
-                    "version-tracked",
-                    Some("change-version"),
-                    "commit-version",
+                    "branch-a",
+                    "branch-tracked",
+                    Some("change-branch"),
+                    "commit-branch",
                 ),
             ];
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("tracked rows should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("tracked rows should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("version-a", "commit-version"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("branch-a", "commit-branch"),
             ],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let loaded = load_selected_tab_at(&live_state, storage.clone(), "version-a")
+        let loaded = load_selected_tab_at(&live_state, &storage, "branch-a")
             .await
             .expect("load should succeed")
-            .expect("version row should be visible");
+            .expect("branch row should be visible");
 
-        assert_eq!(loaded.version_id, "version-a");
+        assert_eq!(loaded.branch_id, "branch-a");
         assert!(!loaded.untracked);
         assert_eq!(
             loaded.snapshot_content.as_deref(),
-            Some("{\"value\":\"version-tracked\"}")
+            Some("{\"value\":\"branch-tracked\"}")
         );
     }
 
     #[tokio::test]
     async fn main_override_hides_global_row() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [
                 tracked_row_with_commit("global-tracked", Some("change-global"), "commit-global"),
@@ -1238,36 +1179,30 @@ mod tests {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("tracked rows should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("tracked rows should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("main", "commit-main"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("main", "commit-main"),
             ],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let loaded = load_selected_tab_at(&live_state, storage.clone(), "main")
+        let loaded = load_selected_tab_at(&live_state, &storage, "main")
             .await
             .expect("load should succeed")
             .expect("main row should be visible");
 
-        assert_eq!(loaded.version_id, "main");
+        assert_eq!(loaded.branch_id, "main");
         assert!(!loaded.global);
         assert_eq!(
             loaded.snapshot_content.as_deref(),
@@ -1277,135 +1212,117 @@ mod tests {
 
     #[tokio::test]
     async fn load_row_prefers_requested_untracked_over_requested_tracked_and_global_rows() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [
                 tracked_row_with_commit("global-tracked", Some("change-global"), "commit-global"),
                 tracked_row_at_with_commit(
-                    "version-a",
-                    "version-tracked",
-                    Some("change-version"),
-                    "commit-version",
+                    "branch-a",
+                    "branch-tracked",
+                    Some("change-branch"),
+                    "commit-branch",
                 ),
             ];
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("tracked rows should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("tracked rows should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("version-a", "commit-version"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("branch-a", "commit-branch"),
                 untracked_row_at("global", "global-untracked"),
-                untracked_row_at("version-a", "version-untracked"),
+                untracked_row_at("branch-a", "branch-untracked"),
             ],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let loaded = load_selected_tab_at(&live_state, storage.clone(), "version-a")
+        let loaded = load_selected_tab_at(&live_state, &storage, "branch-a")
             .await
             .expect("load should succeed")
-            .expect("version untracked row should be visible");
+            .expect("branch untracked row should be visible");
 
-        assert_eq!(loaded.version_id, "version-a");
+        assert_eq!(loaded.branch_id, "branch-a");
         assert!(loaded.untracked);
         assert_eq!(
             loaded.snapshot_content.as_deref(),
-            Some("{\"value\":\"version-untracked\"}")
+            Some("{\"value\":\"branch-untracked\"}")
         );
     }
 
     #[tokio::test]
-    async fn scan_rows_overlays_requested_version_over_global() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+    async fn scan_rows_overlays_requested_branch_over_global() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [
                 tracked_row_with_commit("global-tracked", Some("change-global"), "commit-global"),
                 tracked_row_at_with_commit(
-                    "version-a",
-                    "version-tracked",
-                    Some("change-version"),
-                    "commit-version",
+                    "branch-a",
+                    "branch-tracked",
+                    Some("change-branch"),
+                    "commit-branch",
                 ),
             ];
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("rows should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("rows should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("version-a", "commit-version"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("branch-a", "commit-branch"),
             ],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let rows = scan_selected_tab_at(&live_state, storage.clone(), "version-a", false)
+        let rows = scan_selected_tab_at(&live_state, &storage, "branch-a", false)
             .await
             .expect("scan should succeed");
 
         assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].version_id, "version-a");
+        assert_eq!(rows[0].branch_id, "branch-a");
         assert_eq!(
             rows[0].snapshot_content.as_deref(),
-            Some("{\"value\":\"version-tracked\"}")
+            Some("{\"value\":\"branch-tracked\"}")
         );
     }
 
     #[tokio::test]
-    async fn scan_rows_projects_global_row_into_requested_version() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+    async fn scan_rows_projects_global_row_into_requested_branch() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [tracked_row_with_commit(
                 "global-tracked",
@@ -1415,37 +1332,31 @@ mod tests {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("rows should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("rows should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("version-a", "commit-version-a"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("branch-a", "commit-branch-a"),
             ],
         )
         .await;
-        write_empty_commits_to_store(transaction.as_mut(), &["commit-version-a"]).await;
-        transaction.commit().await.expect("commit should persist");
+        write_empty_commits_to_store(&storage, &read, &["commit-branch-a"]).await;
 
-        let rows = scan_selected_tab_at(&live_state, storage.clone(), "version-a", false)
+        let rows = scan_selected_tab_at(&live_state, &storage, "branch-a", false)
             .await
             .expect("scan should succeed");
 
         assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].version_id, "version-a");
+        assert_eq!(rows[0].branch_id, "branch-a");
         assert!(rows[0].global);
         assert_eq!(
             rows[0].snapshot_content.as_deref(),
@@ -1454,15 +1365,13 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn scan_rows_does_not_project_global_rows_into_missing_version() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+    async fn scan_rows_does_not_project_global_rows_into_missing_branch() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [tracked_row_with_commit(
                 "global-tracked",
@@ -1472,107 +1381,91 @@ mod tests {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("tracked row should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("tracked row should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked row should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
-            &[version_ref_row("global", "commit-global")],
+            &storage,
+            &read,
+            &[branch_ref_row("global", "commit-global")],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let rows = scan_selected_tab_at(&live_state, storage.clone(), "missing-version", false)
+        let rows = scan_selected_tab_at(&live_state, &storage, "missing-branch", false)
             .await
             .expect("scan should succeed");
 
         assert_eq!(
             rows.len(),
             0,
-            "global rows must not be projected into a missing version scope"
+            "global rows must not be projected into a missing branch scope"
         );
     }
 
     #[tokio::test]
     async fn winning_tombstone_hides_row_unless_tombstones_are_included() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [
                 tracked_row_with_commit("global-tracked", Some("change-global"), "commit-global"),
                 tombstone_tracked_row_at_with_commit(
-                    "version-a",
+                    "branch-a",
                     Some("change-tombstone"),
-                    "commit-version",
+                    "commit-branch",
                 ),
             ];
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("rows should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("rows should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("version-a", "commit-version"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("branch-a", "commit-branch"),
             ],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let hidden = scan_selected_tab_at(&live_state, storage.clone(), "version-a", false)
+        let hidden = scan_selected_tab_at(&live_state, &storage, "branch-a", false)
             .await
             .expect("scan should succeed");
         assert_eq!(hidden.len(), 0);
 
-        let with_tombstone = scan_selected_tab_at(&live_state, storage.clone(), "version-a", true)
+        let with_tombstone = scan_selected_tab_at(&live_state, &storage, "branch-a", true)
             .await
             .expect("scan should succeed");
         assert_eq!(with_tombstone.len(), 1);
-        assert_eq!(with_tombstone[0].version_id, "version-a");
+        assert_eq!(with_tombstone[0].branch_id, "branch-a");
         assert_eq!(with_tombstone[0].snapshot_content, None);
     }
 
     #[tokio::test]
     async fn main_tombstone_hides_global_row() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         {
             let rows = [
                 tracked_row_with_commit("global-tracked", Some("change-global"), "commit-global"),
@@ -1585,149 +1478,111 @@ mod tests {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("tracked rows should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("tracked rows should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
+            &storage,
+            &read,
             &[
-                version_ref_row("global", "commit-global"),
-                version_ref_row("main", "commit-main"),
+                branch_ref_row("global", "commit-global"),
+                branch_ref_row("main", "commit-main"),
             ],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let hidden = scan_selected_tab_at(&live_state, storage.clone(), "main", false)
+        let hidden = scan_selected_tab_at(&live_state, &storage, "main", false)
             .await
             .expect("scan should succeed");
         assert_eq!(hidden.len(), 0);
 
-        let tombstones = scan_selected_tab_at(&live_state, storage.clone(), "main", true)
+        let tombstones = scan_selected_tab_at(&live_state, &storage, "main", true)
             .await
             .expect("scan should succeed");
         assert_eq!(tombstones.len(), 1);
-        assert_eq!(tombstones[0].version_id, "main");
+        assert_eq!(tombstones[0].branch_id, "main");
         assert!(!tombstones[0].global);
         assert_eq!(tombstones[0].snapshot_content, None);
     }
 
     #[tokio::test]
-    async fn writer_allows_commit_fact_to_share_the_touched_version_commit_id() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+    async fn writer_allows_commit_fact_to_share_the_touched_branch_commit_id() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let live_state = live_state_context();
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
 
         {
             let rows = [
                 tracked_row_at_with_commit(
-                    "version-a",
-                    "version-row",
-                    Some("change-version"),
-                    "commit-version",
+                    "branch-a",
+                    "branch-row",
+                    Some("change-branch"),
+                    "commit-branch",
                 ),
-                commit_live_state_row("commit-version"),
+                commit_live_state_row("commit-branch"),
             ];
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("commit facts are changelog projections, not root-local rows");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("commit facts are changelog projections, not root-local rows");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("commit fact rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
         write_untracked_rows_to_store(
-            transaction.as_mut(),
-            &[version_ref_row("version-a", "commit-version")],
+            &storage,
+            &read,
+            &[branch_ref_row("branch-a", "commit-branch")],
         )
         .await;
-        transaction.commit().await.expect("commit should persist");
 
-        let loaded = load_selected_tab_at(&live_state, storage.clone(), "version-a")
+        let loaded = load_selected_tab_at(&live_state, &storage, "branch-a")
             .await
             .expect("load should succeed")
-            .expect("version row should be visible");
+            .expect("branch row should be visible");
         assert_eq!(
             loaded.snapshot_content.as_deref(),
-            Some("{\"value\":\"version-row\"}")
+            Some("{\"value\":\"branch-row\"}")
         );
     }
 
     #[tokio::test]
     async fn writer_uses_first_parent_as_merge_root_base() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
-        let mut seed_transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("seed transaction should open");
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        write_empty_commits_to_store(&storage, &read, &["parent-left"]).await;
         let mut writes = StorageWriteSet::new();
-        {
-            CommitStoreContext::new()
-                .writer(&mut seed_transaction.as_mut(), &mut writes)
-                .stage_commit_draft(
-                    CommitDraftRef {
-                        id: "parent-left",
-                        change_id: "parent-left:commit",
-                        parent_ids: &[],
-                        author_account_ids: &[],
-                        created_at: "1970-01-01T00:00:00.000Z",
-                    },
-                    Vec::new(),
-                    Vec::new(),
-                )
-                .await
-                .expect("first parent commit should stage");
-            TrackedStateContext::new()
-                .writer(&mut seed_transaction.as_mut(), &mut writes)
-                .stage_delta("parent-left", None, &[])
-                .await
-                .expect("first parent root should exist");
-        }
-        writes
-            .apply(&mut seed_transaction.as_mut())
+        TrackedStateContext::new()
+            .writer(&read, &mut writes)
+            .stage_commit_root("parent-left", None, [])
             .await
-            .expect("first parent root should apply");
-        seed_transaction
-            .commit()
-            .await
-            .expect("seed transaction should commit");
+            .expect("first parent tracked root should stage");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("first parent tracked root should commit");
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
 
         {
             let rows = [
                 tracked_row_at_with_commit(
-                    "version-a",
-                    "version-row",
-                    Some("change-version"),
+                    "branch-a",
+                    "branch-row",
+                    Some("change-branch"),
                     "commit-merge",
                 ),
                 commit_live_state_row_with_parents(
@@ -1738,31 +1593,23 @@ mod tests {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("merge commit should use first parent as tracked-root base");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("merge commit should use first parent as tracked-root base");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("merge commit rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
     }
 
     #[tokio::test]
     async fn non_global_root_does_not_store_global_rows() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let tracked_state = TrackedStateContext::new();
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
 
         {
             let rows = [
@@ -1777,49 +1624,56 @@ mod tests {
             let mut writes = StorageWriteSet::new();
             let mut json_writer = JsonStoreContext::new().writer();
             {
-                stage_materialized_live_rows(
-                    transaction.as_mut(),
-                    &mut writes,
-                    &mut json_writer,
-                    &rows,
-                )
-                .await
-                .expect("tracked rows should stage");
+                stage_materialized_live_rows(&read, &mut writes, &mut json_writer, &rows)
+                    .await
+                    .expect("tracked rows should stage");
             }
-            writes
-                .apply(&mut transaction.as_mut())
-                .await
-                .expect("tracked rows should apply");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("writes should commit");
         }
-        transaction.commit().await.expect("commit should persist");
 
-        let global_root_rows =
-            scan_tracked_root(&tracked_state, storage.clone(), "commit-global").await;
-        assert_eq!(global_root_rows.len(), 1);
+        let global_root_rows = scan_tracked_root(&tracked_state, &storage, "commit-global").await;
+        assert_eq!(global_root_rows.len(), 2);
+        let Some(global_row) = global_root_rows
+            .iter()
+            .find(|row| row.schema_key == "lix_key_value")
+        else {
+            panic!("global root should contain the explicit global tracked row");
+        };
         assert_eq!(
-            global_root_rows[0].snapshot_content.as_deref(),
+            global_row.snapshot_content.as_deref(),
             Some("{\"value\":\"global-tracked\"}")
         );
 
-        let main_root_rows =
-            scan_tracked_root(&tracked_state, storage.clone(), "commit-main").await;
-        assert_eq!(main_root_rows.len(), 1);
+        let main_root_rows = scan_tracked_root(&tracked_state, &storage, "commit-main").await;
+        assert_eq!(main_root_rows.len(), 2);
+        let Some(main_row) = main_root_rows
+            .iter()
+            .find(|row| row.schema_key == "lix_key_value")
+        else {
+            panic!("main root should contain the explicit main tracked row");
+        };
         assert_eq!(
-            main_root_rows[0].snapshot_content.as_deref(),
+            main_row.snapshot_content.as_deref(),
             Some("{\"value\":\"main-tracked\"}")
         );
     }
 
     async fn load_selected_tab(
         live_state: &LiveStateContext,
-        storage: StorageContext,
+        storage: &StorageContext,
     ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
         live_state
-            .reader(storage)
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .load_row(&LiveStateRowRequest {
                 schema_key: "lix_key_value".to_string(),
-                version_id: "global".to_string(),
-                entity_id: crate::entity_identity::EntityIdentity::single("selected-tab"),
+                branch_id: "global".to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single("selected-tab"),
                 file_id: NullableKeyFilter::Null,
             })
             .await
@@ -1827,15 +1681,19 @@ mod tests {
 
     async fn load_selected_tab_at(
         live_state: &LiveStateContext,
-        storage: StorageContext,
-        version_id: &str,
+        storage: &StorageContext,
+        branch_id: &str,
     ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
         live_state
-            .reader(storage)
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .load_row(&LiveStateRowRequest {
                 schema_key: "lix_key_value".to_string(),
-                version_id: version_id.to_string(),
-                entity_id: crate::entity_identity::EntityIdentity::single("selected-tab"),
+                branch_id: branch_id.to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single("selected-tab"),
                 file_id: NullableKeyFilter::Null,
             })
             .await
@@ -1843,19 +1701,21 @@ mod tests {
 
     async fn scan_selected_tab_at(
         live_state: &LiveStateContext,
-        storage: StorageContext,
-        version_id: &str,
+        storage: &StorageContext,
+        branch_id: &str,
         include_tombstones: bool,
     ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
         live_state
-            .reader(storage)
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .scan_rows(&LiveStateScanRequest {
                 filter: LiveStateFilter {
                     schema_keys: vec!["lix_key_value".to_string()],
-                    entity_ids: vec![crate::entity_identity::EntityIdentity::single(
-                        "selected-tab",
-                    )],
-                    version_ids: vec![version_id.to_string()],
+                    entity_pks: vec![crate::entity_pk::EntityPk::single("selected-tab")],
+                    branch_ids: vec![branch_id.to_string()],
                     file_ids: vec![NullableKeyFilter::Null],
                     include_tombstones,
                     ..LiveStateFilter::default()
@@ -1867,11 +1727,15 @@ mod tests {
 
     async fn scan_tracked_root(
         tracked_state: &TrackedStateContext,
-        storage: StorageContext,
+        storage: &StorageContext,
         commit_id: &str,
     ) -> Vec<MaterializedTrackedStateRow> {
         tracked_state
-            .reader(storage)
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .scan_rows_at_commit(
                 commit_id,
                 &TrackedStateScanRequest {
@@ -1895,13 +1759,13 @@ mod tests {
     }
 
     fn tracked_row_at_with_commit(
-        version_id: &str,
+        branch_id: &str,
         value: &str,
         change_id: Option<&str>,
         commit_id: &str,
     ) -> MaterializedLiveStateRow {
         MaterializedLiveStateRow {
-            entity_id: identity("selected-tab"),
+            entity_pk: identity("selected-tab"),
             schema_key: "lix_key_value".to_string(),
             file_id: None,
             snapshot_content: Some(format!("{{\"value\":\"{value}\"}}")),
@@ -1909,23 +1773,23 @@ mod tests {
             deleted: false,
             created_at: "2026-01-01T00:00:00Z".to_string(),
             updated_at: "2026-01-01T00:00:00Z".to_string(),
-            global: version_id == "global",
+            global: branch_id == "global",
             change_id: change_id.map(str::to_string),
             commit_id: Some(commit_id.to_string()),
             untracked: false,
-            version_id: version_id.to_string(),
+            branch_id: branch_id.to_string(),
         }
     }
 
     fn tombstone_tracked_row_at_with_commit(
-        version_id: &str,
+        branch_id: &str,
         change_id: Option<&str>,
         commit_id: &str,
     ) -> MaterializedLiveStateRow {
         MaterializedLiveStateRow {
             snapshot_content: None,
             deleted: true,
-            ..tracked_row_at_with_commit(version_id, "ignored", change_id, commit_id)
+            ..tracked_row_at_with_commit(branch_id, "ignored", change_id, commit_id)
         }
     }
 
@@ -1933,9 +1797,9 @@ mod tests {
         untracked_row_at("global", value)
     }
 
-    fn untracked_row_at(version_id: &str, value: &str) -> MaterializedUntrackedStateRow {
+    fn untracked_row_at(branch_id: &str, value: &str) -> MaterializedUntrackedStateRow {
         MaterializedUntrackedStateRow {
-            entity_id: identity("selected-tab"),
+            entity_pk: identity("selected-tab"),
             schema_key: "lix_key_value".to_string(),
             file_id: None,
             snapshot_content: Some(format!("{{\"value\":\"{value}\"}}")),
@@ -1943,29 +1807,29 @@ mod tests {
             deleted: false,
             created_at: "2026-01-01T00:00:00Z".to_string(),
             updated_at: "2026-01-01T00:00:00Z".to_string(),
-            global: version_id == "global",
-            version_id: version_id.to_string(),
+            global: branch_id == "global",
+            branch_id: branch_id.to_string(),
         }
     }
 
-    fn version_ref_row(version_id: &str, commit_id: &str) -> MaterializedUntrackedStateRow {
+    fn branch_ref_row(branch_id: &str, commit_id: &str) -> MaterializedUntrackedStateRow {
         MaterializedUntrackedStateRow {
-            entity_id: identity(version_id),
-            schema_key: "lix_version_ref".to_string(),
+            entity_pk: identity(branch_id),
+            schema_key: "lix_branch_ref".to_string(),
             file_id: None,
             snapshot_content: Some(
                 serde_json::to_string(&json!({
-                    "id": version_id,
+                    "id": branch_id,
                     "commit_id": commit_id,
                 }))
-                .expect("version ref should serialize"),
+                .expect("branch ref should serialize"),
             ),
             metadata: None,
             deleted: false,
             created_at: "2026-01-01T00:00:00Z".to_string(),
             updated_at: "2026-01-01T00:00:00Z".to_string(),
             global: true,
-            version_id: "global".to_string(),
+            branch_id: "global".to_string(),
         }
     }
 
@@ -1995,7 +1859,7 @@ mod tests {
         snapshot: serde_json::Value,
     ) -> MaterializedLiveStateRow {
         MaterializedLiveStateRow {
-            entity_id: identity(commit_id),
+            entity_pk: identity(commit_id),
             schema_key: COMMIT_SCHEMA_KEY.to_string(),
             file_id: None,
             snapshot_content: Some(
@@ -2009,11 +1873,11 @@ mod tests {
             change_id: Some(format!("change-{commit_id}")),
             commit_id: Some(commit_id.to_string()),
             untracked: false,
-            version_id: "global".to_string(),
+            branch_id: "global".to_string(),
         }
     }
 
-    fn identity(entity_id: &str) -> EntityIdentity {
-        EntityIdentity::single(entity_id)
+    fn identity(entity_pk: &str) -> EntityPk {
+        EntityPk::single(entity_pk)
     }
 }