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

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

@@ -1,37 +1,39 @@
 use crate::binary_cas::BinaryCasContext;
-use crate::commit_store::{ChangeRef, CommitDraftRef, CommitStoreContext, StagedCommitStoreCommit};
+use crate::branch::{BranchContext, BranchRefReader};
+use crate::changelog::{
+    ChangeRecord, ChangelogAppend, ChangelogContext, ChangelogWriter, CommitChangeRef,
+    CommitChangeRefSet, CommitRecord,
+};
+use crate::entity_pk::EntityPk;
 use crate::functions::FunctionContext;
-use crate::json_store::{JsonStoreContext, JsonWritePlacementRef, NormalizedJsonRef};
-use crate::storage::{StorageReader, StorageWriteSet, StorageWriteTransaction};
+use crate::json_store::{JsonRef, JsonStoreContext, JsonWritePlacementRef, NormalizedJsonRef};
+use crate::storage::{StorageRead, StorageWriteSet};
 use crate::tracked_state::{TrackedStateContext, TrackedStateDeltaRef};
-use crate::transaction::prepare_version_ref_row;
+use crate::transaction::prepare_branch_ref_row;
 use crate::transaction::staging::PreparedWriteSet;
-use crate::transaction::types::{PreparedAdoptedStateRow, PreparedStateRow, StagedCommitMembers};
+use crate::transaction::types::{PreparedStateRow, StagedCommitChangeRef, StagedCommitChangeRefs};
 use crate::untracked_state::{
     UntrackedStateContext, UntrackedStateIdentity, UntrackedStateIdentityRef, UntrackedStateRowRef,
 };
-use crate::version::{VersionContext, VersionRefReader};
 use crate::LixError;
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, BTreeSet};
 
 type RowIndex = usize;
-type AdoptedRowIndex = usize;
 
 /// Commits prepared transaction rows into durable tracked and untracked stores.
 ///
 /// Providers decode DataFusion DML into hydrated `PreparedStateRow`s. Untracked
-/// rows are durable local overlay state and bypass commit-store rows. Tracked
-/// rows stage canonical commit-store facts, then update the live-state serving
-/// projection. The tracked side of that projection is a prolly root keyed by
+/// rows are durable local overlay state and bypass changelog change refs. Tracked
+/// rows stage canonical changelog facts, then update the live-state serving
+/// commit root. The tracked side of that commit root is a prolly root keyed by
 /// the new commit id.
 pub(crate) async fn commit_prepared_writes(
     binary_cas: &BinaryCasContext,
-    commit_store: &CommitStoreContext,
-    version_ctx: &VersionContext,
+    branch_ctx: &BranchContext,
     runtime_functions: Option<&FunctionContext>,
-    transaction: &mut (impl StorageWriteTransaction + ?Sized),
+    read: &mut (impl StorageRead + Send + Sync),
     prepared_writes: PreparedWriteSet,
-) -> Result<(), LixError> {
+) -> Result<StorageWriteSet, LixError> {
     let mut writes = StorageWriteSet::new();
     let mut json_writer = JsonStoreContext::new().writer();
 
@@ -43,19 +45,17 @@ pub(crate) async fn commit_prepared_writes(
     }
 
     let state_rows = prepared_writes.state_rows;
-    let adopted_rows = prepared_writes.adopted_rows;
     let finalized = finalize_commit_rows(
-        prepared_writes.commit_members_by_version,
-        prepared_writes.extra_commit_parents_by_version,
-        version_ctx,
-        transaction,
+        prepared_writes.commit_change_refs_by_branch,
+        prepared_writes.extra_commit_parents_by_branch,
+        branch_ctx,
+        &*read,
     )
     .await?;
     let commit_rows = finalized.commit_rows;
-    let version_heads = finalized.version_heads;
+    let branch_heads = finalized.branch_heads;
     let tracked_roots = finalized.tracked_roots;
     let row_index = index_prepared_rows(&state_rows)?;
-    let adopted_index = index_adopted_rows(&adopted_rows);
 
     if let Some(runtime_functions) = runtime_functions {
         runtime_functions
@@ -64,50 +64,39 @@ pub(crate) async fn commit_prepared_writes(
     }
 
     if state_rows.is_empty()
-        && adopted_rows.is_empty()
         && commit_rows.is_empty()
-        && version_heads.is_empty()
+        && branch_heads.is_empty()
         && writes.is_empty()
     {
-        return Ok(());
+        return Ok(writes);
     }
 
-    let staged_commits = stage_commit_store_commits(
-        commit_store,
-        transaction,
+    let staged_commits = stage_changelog_commits(
+        read,
         &mut writes,
         &state_rows,
         &row_index.tracked_row_indices_by_commit,
-        &adopted_rows,
-        &adopted_index.tracked_row_indices_by_commit,
         &commit_rows,
     )
     .await?;
 
-    let json_pack_indexes_by_commit = stage_prepared_json_payloads(
+    stage_state_json_payloads(
         &mut json_writer,
         &mut writes,
         &state_rows,
-        &row_index.tracked_row_indices_by_commit,
-        &staged_commits,
-        &row_index.untracked_row_indices,
+        &row_index.canonical_row_indices,
     )?;
 
-    // The serving projection is updated in the same backend transaction as the
-    // commit-store append. Tracked rows become prolly mutations under their owning
+    // The serving commit root is updated in the same backend transaction as the
+    // changelog append. Tracked rows become prolly mutations under their owning
     // commit root; untracked rows remain in the separate local overlay store.
     {
         let untracked_overlay_delete_identities = existing_untracked_overlay_delete_identities(
-            transaction,
+            &*read,
             row_index
                 .canonical_row_indices
                 .iter()
-                .map(|&row_index| untracked_identity_ref_from_state_row(&state_rows[row_index]))
-                .chain(
-                    adopted_rows
-                        .iter()
-                        .map(untracked_identity_ref_from_adopted_row),
-                ),
+                .map(|&row_index| untracked_identity_ref_from_state_row(&state_rows[row_index])),
         )
         .await?;
         UntrackedStateContext::new()
@@ -124,89 +113,44 @@ pub(crate) async fn commit_prepared_writes(
                 untracked_overlay_delete_identities
                     .iter()
                     .map(UntrackedStateIdentity::as_ref),
-            );
+            )?;
         stage_tracked_roots(
-            transaction,
+            read,
             &mut writes,
             &state_rows,
             row_index.tracked_row_indices_by_commit,
-            &adopted_rows,
-            adopted_index.tracked_row_indices_by_commit,
             tracked_roots,
             staged_commits,
-            json_pack_indexes_by_commit,
         )
         .await?;
     }
 
-    for version_head in version_heads {
-        let canonical_row = prepare_version_ref_row(
-            &version_head.version_id,
-            &version_head.commit_id,
-            &version_head.timestamp,
+    for branch_head in branch_heads {
+        let canonical_row = prepare_branch_ref_row(
+            &branch_head.branch_id,
+            &branch_head.commit_id,
+            &branch_head.timestamp,
         )?;
-        version_ctx.stage_canonical_ref_rows(&mut writes, &[canonical_row.row])?;
+        branch_ctx.stage_canonical_ref_rows(&mut writes, &[canonical_row.row])?;
     }
 
-    writes.apply(transaction).await?;
-    Ok(())
+    Ok(writes)
 }
 
-fn stage_prepared_json_payloads(
+fn stage_state_json_payloads(
     json_writer: &mut crate::json_store::JsonStoreWriter,
     writes: &mut StorageWriteSet,
     state_rows: &[PreparedStateRow],
-    tracked_row_indices_by_commit: &BTreeMap<String, Vec<RowIndex>>,
-    staged_commits: &BTreeMap<String, StagedCommitStoreCommit>,
-    untracked_row_indices: &[RowIndex],
-) -> Result<BTreeMap<String, BTreeMap<u32, std::collections::HashMap<[u8; 32], usize>>>, LixError> {
-    let mut pack_indexes_by_commit = BTreeMap::new();
-    for (commit_id, row_indices) in tracked_row_indices_by_commit {
-        let staged_commit = staged_commits.get(commit_id).ok_or_else(|| {
-            LixError::new(
-                LixError::CODE_INTERNAL_ERROR,
-                format!("commit '{commit_id}' has tracked JSON rows but no staged commit-store locators"),
-            )
-        })?;
-        if row_indices.len() != staged_commit.authored_locators.len() {
-            return Err(LixError::new(
-                LixError::CODE_INTERNAL_ERROR,
-                format!(
-                    "commit '{commit_id}' has {} tracked JSON rows but {} authored locators",
-                    row_indices.len(),
-                    staged_commit.authored_locators.len()
-                ),
-            ));
-        }
-        let mut row_indices_by_pack = BTreeMap::<u32, Vec<RowIndex>>::new();
-        for (&row_index, locator) in row_indices.iter().zip(&staged_commit.authored_locators) {
-            row_indices_by_pack
-                .entry(locator.source_pack_id)
-                .or_default()
-                .push(row_index);
-        }
-        for (pack_id, pack_row_indices) in row_indices_by_pack {
-            let report = json_writer.stage_batch_report(
-                writes,
-                JsonWritePlacementRef::CommitPack { commit_id, pack_id },
-                pack_row_indices
-                    .iter()
-                    .flat_map(|&row_index| json_payloads_from_state_row(&state_rows[row_index])),
-            )?;
-            pack_indexes_by_commit
-                .entry(commit_id.clone())
-                .or_insert_with(BTreeMap::new)
-                .insert(pack_id, report.pack_indexes);
-        }
-    }
+    row_indices: &[RowIndex],
+) -> Result<(), LixError> {
     json_writer.stage_batch(
         writes,
         JsonWritePlacementRef::OutOfBand,
-        untracked_row_indices
+        row_indices
             .iter()
             .flat_map(|&row_index| json_payloads_from_state_row(&state_rows[row_index])),
     )?;
-    Ok(pack_indexes_by_commit)
+    Ok(())
 }
 
 fn json_payloads_from_state_row(
@@ -219,11 +163,11 @@ fn json_payloads_from_state_row(
 }
 
 async fn existing_untracked_overlay_delete_identities<'a>(
-    transaction: &mut (impl StorageReader + ?Sized),
+    read: &(impl StorageRead + Send + Sync + ?Sized),
     identities: impl IntoIterator<Item = UntrackedStateIdentityRef<'a>>,
 ) -> Result<Vec<UntrackedStateIdentity>, LixError> {
     UntrackedStateContext::new()
-        .reader(transaction)
+        .reader(read)
         .existing_identities(identities)
         .await
 }
@@ -234,10 +178,6 @@ struct PreparedRowIndex {
     tracked_row_indices_by_commit: BTreeMap<String, Vec<RowIndex>>,
 }
 
-struct PreparedAdoptedRowIndex {
-    tracked_row_indices_by_commit: BTreeMap<String, Vec<AdoptedRowIndex>>,
-}
-
 fn index_prepared_rows(rows: &[PreparedStateRow]) -> Result<PreparedRowIndex, LixError> {
     let mut canonical_row_indices = Vec::new();
     let mut untracked_row_indices = Vec::new();
@@ -268,242 +208,277 @@ fn index_prepared_rows(rows: &[PreparedStateRow]) -> Result<PreparedRowIndex, Li
     })
 }
 
-fn index_adopted_rows(rows: &[PreparedAdoptedStateRow]) -> PreparedAdoptedRowIndex {
-    let mut tracked_row_indices_by_commit = BTreeMap::<String, Vec<AdoptedRowIndex>>::new();
-    for (row_index, row) in rows.iter().enumerate() {
-        tracked_row_indices_by_commit
-            .entry(row.commit_id.clone())
-            .or_default()
-            .push(row_index);
-    }
-    PreparedAdoptedRowIndex {
-        tracked_row_indices_by_commit,
-    }
+#[derive(Clone, Debug)]
+struct StagedChangelogCommit {
+    change_ids: Vec<String>,
+    selected_change_refs: Vec<StagedCommitChangeRef>,
+    commit_change_id: String,
+    commit_created_at: String,
 }
 
-async fn stage_commit_store_commits(
-    commit_store: &CommitStoreContext,
-    transaction: &mut (impl StorageReader + ?Sized),
+async fn stage_changelog_commits(
+    read: &mut (impl StorageRead + Send + Sync),
     writes: &mut StorageWriteSet,
     state_rows: &[PreparedStateRow],
     tracked_row_indices_by_commit: &BTreeMap<String, Vec<RowIndex>>,
-    adopted_rows: &[PreparedAdoptedStateRow],
-    adopted_row_indices_by_commit: &BTreeMap<String, Vec<AdoptedRowIndex>>,
     commit_rows: &[FinalizedCommitRow],
-) -> Result<BTreeMap<String, StagedCommitStoreCommit>, LixError> {
+) -> Result<BTreeMap<String, StagedChangelogCommit>, LixError> {
+    if commit_rows.is_empty() {
+        return Ok(BTreeMap::new());
+    }
+
     let mut commits = Vec::with_capacity(commit_rows.len());
-    let mut commit_ids = Vec::with_capacity(commit_rows.len());
+    let mut changes = Vec::new();
+    let mut commit_change_refs = Vec::with_capacity(commit_rows.len());
+    let mut staged = BTreeMap::<String, StagedChangelogCommit>::new();
     for commit_row in commit_rows {
         let state_row_indices = tracked_row_indices_by_commit
             .get(&commit_row.commit_id)
             .map(Vec::as_slice)
             .unwrap_or_default();
-        let adopted_row_indices = adopted_row_indices_by_commit
-            .get(&commit_row.commit_id)
-            .map(Vec::as_slice)
-            .unwrap_or_default();
-        let mut authored_changes = Vec::with_capacity(state_row_indices.len());
+        let mut refs = Vec::with_capacity(state_row_indices.len());
+        let mut change_ids =
+            Vec::with_capacity(state_row_indices.len() + commit_row.selected_change_refs.len());
         for &row_index in state_row_indices {
-            authored_changes.push(change_ref_from_state_row(&state_rows[row_index])?);
+            let row = &state_rows[row_index];
+            let change_id = row.change_id.as_ref().ok_or_else(|| {
+                LixError::new(
+                    LixError::CODE_INTERNAL_ERROR,
+                    "tracked staged row is missing change_id before changelog append",
+                )
+            })?;
+            refs.push(commit_change_ref_from_state_row(row, change_id));
+            change_ids.push(change_id.clone());
+            changes.push(change_record_from_state_row(row)?);
         }
-        let mut adopted_changes = Vec::with_capacity(adopted_row_indices.len());
-        for &row_index in adopted_row_indices {
-            adopted_changes.push(change_ref_from_adopted_row(&adopted_rows[row_index]));
+        for change_ref in &commit_row.selected_change_refs {
+            refs.push(commit_change_ref_from_selected_change_ref(change_ref));
+            change_ids.push(change_ref.change_id.clone());
         }
-
-        let commit = CommitDraftRef {
-            id: &commit_row.commit_id,
-            change_id: &commit_row.change_id,
-            parent_ids: &commit_row.parent_commit_ids,
-            author_account_ids: &[],
-            created_at: &commit_row.created_at,
-        };
-        commit_ids.push(commit_row.commit_id.clone());
-        commits.push((commit, authored_changes, adopted_changes));
+        commits.push(CommitRecord {
+            format_version: 1,
+            commit_id: commit_row.commit_id.clone(),
+            parent_commit_ids: commit_row.parent_commit_ids.clone(),
+            change_id: commit_row.change_id.clone(),
+            author_account_ids: Vec::new(),
+            created_at: commit_row.created_at.clone(),
+        });
+        commit_change_refs.push(CommitChangeRefSet {
+            commit_id: commit_row.commit_id.clone(),
+            entries: refs,
+        });
+        staged.insert(
+            commit_row.commit_id.clone(),
+            StagedChangelogCommit {
+                change_ids,
+                selected_change_refs: commit_row.selected_change_refs.clone(),
+                commit_change_id: commit_row.change_id.clone(),
+                commit_created_at: commit_row.created_at.clone(),
+            },
+        );
     }
-    let staged = commit_store
-        .writer(transaction, writes)
-        .stage_tracked_commit_drafts(commits)
-        .await?;
-    if staged.len() != commit_ids.len() {
+
+    let append = ChangelogAppend {
+        commits,
+        changes,
+        commit_change_refs,
+    };
+
+    let mut writer = ChangelogContext::new().writer(read, writes);
+    writer.stage_append(append).await?;
+    stage_commit_row_json_payloads(writes, commit_rows)?;
+    Ok(staged)
+}
+
+fn change_record_from_state_row(row: &PreparedStateRow) -> Result<ChangeRecord, LixError> {
+    let Some(change_id) = row.change_id.as_ref() else {
         return Err(LixError::new(
             LixError::CODE_INTERNAL_ERROR,
-            format!(
-                "commit-store staged {} commits for {} finalized commit rows",
-                staged.len(),
-                commit_ids.len()
-            ),
+            "tracked staged row is missing change_id before changelog change construction",
         ));
+    };
+    Ok(ChangeRecord {
+        format_version: 1,
+        change_id: change_id.clone(),
+        entity_pk: row.entity_pk.clone(),
+        schema_key: row.schema_key.clone(),
+        file_id: row.file_id.clone(),
+        snapshot_ref: row.snapshot.as_ref().map(|snapshot| snapshot.json_ref),
+        metadata_ref: row.metadata.as_ref().map(|metadata| metadata.json_ref),
+        created_at: row.updated_at.clone(),
+    })
+}
+
+fn stage_commit_row_json_payloads(
+    writes: &mut StorageWriteSet,
+    commit_rows: &[FinalizedCommitRow],
+) -> Result<(), LixError> {
+    let snapshots = commit_rows
+        .iter()
+        .map(|row| commit_row_snapshot_content(&row.commit_id))
+        .collect::<Result<Vec<_>, _>>()?;
+    JsonStoreContext::new().writer().stage_batch(
+        writes,
+        JsonWritePlacementRef::OutOfBand,
+        snapshots
+            .iter()
+            .map(|snapshot| NormalizedJsonRef::new(snapshot.as_str())),
+    )?;
+    Ok(())
+}
+
+fn commit_row_snapshot_content(commit_id: &str) -> Result<String, LixError> {
+    serde_json::to_string(&serde_json::json!({
+        "id": commit_id,
+    }))
+    .map_err(|error| {
+        LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            format!("failed to encode lix_commit snapshot: {error}"),
+        )
+    })
+}
+
+fn commit_change_ref_from_state_row(row: &PreparedStateRow, change_id: &str) -> CommitChangeRef {
+    CommitChangeRef {
+        schema_key: row.schema_key.clone(),
+        file_id: row.file_id.clone(),
+        entity_pk: row.entity_pk.clone(),
+        change_id: change_id.to_string(),
     }
-    Ok(commit_ids.into_iter().zip(staged).collect())
 }
 
-fn change_ref_from_state_row(row: &PreparedStateRow) -> Result<ChangeRef<'_>, LixError> {
+fn commit_change_ref_from_selected_change_ref(
+    change_ref: &StagedCommitChangeRef,
+) -> CommitChangeRef {
+    CommitChangeRef {
+        schema_key: change_ref.schema_key.clone(),
+        file_id: change_ref.file_id.clone(),
+        entity_pk: change_ref.entity_pk.clone(),
+        change_id: change_ref.change_id.clone(),
+    }
+}
+
+fn tracked_delta_from_state_row(
+    row: &PreparedStateRow,
+) -> Result<TrackedStateDeltaRef<'_>, LixError> {
     let Some(change_id) = row.change_id.as_deref() else {
         return Err(LixError::new(
-            "LIX_ERROR_UNKNOWN",
-            "tracked staged row is missing change_id before commit-store append",
+            LixError::CODE_INTERNAL_ERROR,
+            "tracked staged row is missing change_id before tracked root staging",
         ));
     };
-
-    Ok(ChangeRef {
-        id: change_id,
-        entity_id: &row.entity_id,
+    let Some(commit_id) = row.commit_id.as_deref() else {
+        return Err(LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            "tracked staged row is missing commit_id before tracked root staging",
+        ));
+    };
+    Ok(TrackedStateDeltaRef {
         schema_key: &row.schema_key,
         file_id: row.file_id.as_deref(),
+        entity_pk: &row.entity_pk,
+        change_id,
+        commit_id,
         snapshot_ref: row.snapshot.as_ref().map(|snapshot| &snapshot.json_ref),
         metadata_ref: row.metadata.as_ref().map(|metadata| &metadata.json_ref),
-        created_at: &row.updated_at,
+        deleted: row.snapshot.is_none(),
+        created_at: &row.created_at,
+        updated_at: &row.updated_at,
     })
 }
 
-fn change_ref_from_adopted_row(row: &PreparedAdoptedStateRow) -> ChangeRef<'_> {
-    ChangeRef {
-        id: &row.change_id,
-        entity_id: &row.entity_id,
-        schema_key: &row.schema_key,
-        file_id: row.file_id.as_deref(),
-        snapshot_ref: row.snapshot.as_ref().map(|snapshot| &snapshot.json_ref),
-        metadata_ref: row.metadata.as_ref().map(|metadata| &metadata.json_ref),
-        created_at: &row.updated_at,
-    }
+fn tracked_delta_from_selected_change_ref<'a>(
+    change_ref: &'a StagedCommitChangeRef,
+    commit_id: &'a str,
+) -> Result<TrackedStateDeltaRef<'a>, LixError> {
+    Ok(TrackedStateDeltaRef {
+        schema_key: &change_ref.schema_key,
+        file_id: change_ref.file_id.as_deref(),
+        entity_pk: &change_ref.entity_pk,
+        change_id: &change_ref.change_id,
+        commit_id,
+        snapshot_ref: change_ref.snapshot_ref.as_ref(),
+        metadata_ref: change_ref.metadata_ref.as_ref(),
+        deleted: change_ref.deleted,
+        created_at: &change_ref.created_at,
+        updated_at: &change_ref.updated_at,
+    })
 }
 
 async fn stage_tracked_roots(
-    transaction: &mut (impl StorageReader + ?Sized),
+    read: &(impl StorageRead + Send + Sync + ?Sized),
     writes: &mut StorageWriteSet,
     state_rows: &[PreparedStateRow],
-    mut tracked_row_indices_by_commit: BTreeMap<String, Vec<RowIndex>>,
-    adopted_rows: &[PreparedAdoptedStateRow],
-    mut adopted_row_indices_by_commit: BTreeMap<String, Vec<AdoptedRowIndex>>,
+    tracked_row_indices_by_commit: BTreeMap<String, Vec<RowIndex>>,
     tracked_roots: Vec<PendingTrackedRoot>,
-    mut staged_commits: BTreeMap<String, StagedCommitStoreCommit>,
-    json_pack_indexes_by_commit: BTreeMap<
-        String,
-        BTreeMap<u32, std::collections::HashMap<[u8; 32], usize>>,
-    >,
+    staged_commits: BTreeMap<String, StagedChangelogCommit>,
 ) -> Result<(), LixError> {
     let tracked_state = TrackedStateContext::new();
-    let mut writer = tracked_state.writer(transaction, writes);
-    for root in tracked_roots {
-        let staged = staged_commits.remove(&root.commit_id).ok_or_else(|| {
+    let mut tracked_writer = tracked_state.writer(read, writes);
+    for root in tracked_roots_parent_first(&tracked_roots)? {
+        let staged = staged_commits.get(&root.commit_id).ok_or_else(|| {
             LixError::new(
                 LixError::CODE_INTERNAL_ERROR,
                 format!(
-                    "tracked-state root for commit '{}' has no staged commit-store locators",
+                    "tracked-state root for commit '{}' has no staged changelog facts",
                     root.commit_id
                 ),
             )
         })?;
         let state_row_indices = tracked_row_indices_by_commit
-            .remove(&root.commit_id)
-            .unwrap_or_default();
-        let adopted_row_indices = adopted_row_indices_by_commit
-            .remove(&root.commit_id)
+            .get(&root.commit_id)
+            .map(Vec::as_slice)
             .unwrap_or_default();
-        if state_row_indices.len() != staged.authored_locators.len() {
+        if state_row_indices.len() > staged.change_ids.len() {
             return Err(LixError::new(
                 LixError::CODE_INTERNAL_ERROR,
                 format!(
-                    "commit '{}' has {} tracked authored rows but {} commit-store authored locators",
+                    "commit '{}' has {} tracked rows but only {} changelog changes",
                     root.commit_id,
                     state_row_indices.len(),
-                    staged.authored_locators.len()
-                ),
-            ));
-        }
-        if adopted_row_indices.len() != staged.adopted_locators.len() {
-            return Err(LixError::new(
-                LixError::CODE_INTERNAL_ERROR,
-                format!(
-                    "commit '{}' has {} tracked adopted rows but {} commit-store adopted locators",
-                    root.commit_id,
-                    adopted_row_indices.len(),
-                    staged.adopted_locators.len()
+                    staged.change_ids.len()
                 ),
             ));
         }
-        let authored_changes = state_row_indices
+        let commit_snapshot = commit_row_snapshot_content(&root.commit_id)?;
+        let commit_snapshot_ref = JsonRef::for_content(commit_snapshot.as_bytes());
+        let commit_entity_pk = EntityPk::single(root.commit_id.clone());
+        let mut deltas = state_row_indices
             .iter()
-            .map(|&row_index| change_ref_from_state_row(&state_rows[row_index]))
+            .map(|&row_index| tracked_delta_from_state_row(&state_rows[row_index]))
+            .chain(staged.selected_change_refs.iter().map(|change_ref| {
+                tracked_delta_from_selected_change_ref(change_ref, &root.commit_id)
+            }))
             .collect::<Result<Vec<_>, _>>()?;
-        let adopted_changes = adopted_row_indices
-            .iter()
-            .map(|&row_index| change_ref_from_adopted_row(&adopted_rows[row_index]))
-            .collect::<Vec<_>>();
-        let authored_updated_at = state_row_indices
-            .iter()
-            .map(|&row_index| state_rows[row_index].updated_at.as_str())
-            .collect::<Vec<_>>();
-        let authored_created_at = state_row_indices
-            .iter()
-            .map(|&row_index| state_rows[row_index].created_at.as_str())
-            .collect::<Vec<_>>();
-        let adopted_updated_at = adopted_row_indices
-            .iter()
-            .map(|&row_index| adopted_rows[row_index].updated_at.as_str())
-            .collect::<Vec<_>>();
-        let adopted_created_at = adopted_row_indices
-            .iter()
-            .map(|&row_index| adopted_rows[row_index].created_at.as_str())
-            .collect::<Vec<_>>();
-        let mut deltas = Vec::with_capacity(authored_changes.len() + adopted_changes.len());
-        deltas.extend(
-            authored_changes
-                .iter()
-                .zip(&staged.authored_locators)
-                .zip(authored_created_at)
-                .zip(authored_updated_at)
-                .map(
-                    |(((change, locator), created_at), updated_at)| TrackedStateDeltaRef {
-                        change: *change,
-                        locator: locator.as_ref(),
-                        created_at,
-                        updated_at,
-                    },
-                ),
-        );
-        deltas.extend(
-            adopted_changes
-                .iter()
-                .zip(&staged.adopted_locators)
-                .zip(adopted_created_at)
-                .zip(adopted_updated_at)
-                .map(
-                    |(((change, locator), created_at), updated_at)| TrackedStateDeltaRef {
-                        change: *change,
-                        locator: locator.as_ref(),
-                        created_at,
-                        updated_at,
-                    },
-                ),
-        );
-        if let Some(indexes) = json_pack_indexes_by_commit
-            .get(&root.commit_id)
-            .and_then(|packs| packs.get(&0))
-        {
-            writer
-                .stage_delta_with_json_pack_indexes(
-                    &root.commit_id,
-                    root.parent_commit_id.as_deref(),
-                    &deltas,
-                    crate::tracked_state::DeltaJsonPackIndexesRef {
-                        commit_id: &root.commit_id,
-                        pack_id: 0,
-                        indexes,
-                    },
-                )
-                .await?;
-        } else {
-            writer
-                .stage_delta(&root.commit_id, root.parent_commit_id.as_deref(), &deltas)
-                .await?;
-        }
+        deltas.push(TrackedStateDeltaRef {
+            schema_key: "lix_commit",
+            file_id: None,
+            entity_pk: &commit_entity_pk,
+            change_id: &staged.commit_change_id,
+            commit_id: &root.commit_id,
+            snapshot_ref: Some(&commit_snapshot_ref),
+            metadata_ref: None,
+            deleted: false,
+            created_at: &staged.commit_created_at,
+            updated_at: &staged.commit_created_at,
+        });
+        tracked_writer
+            .stage_commit_root(&root.commit_id, root.parent_commit_id.as_deref(), deltas)
+            .await?;
     }
-    if !tracked_row_indices_by_commit.is_empty() || !adopted_row_indices_by_commit.is_empty() {
+    let rooted_commit_ids = tracked_roots
+        .iter()
+        .map(|root| root.commit_id.as_str())
+        .collect::<BTreeSet<_>>();
+    let extra_tracked = tracked_row_indices_by_commit
+        .keys()
+        .filter(|commit_id| !rooted_commit_ids.contains(commit_id.as_str()))
+        .cloned()
+        .collect::<BTreeSet<_>>();
+    if !extra_tracked.is_empty() {
         let mut commit_ids = tracked_row_indices_by_commit
             .keys()
-            .chain(adopted_row_indices_by_commit.keys())
             .cloned()
             .collect::<Vec<_>>();
         commit_ids.sort();
@@ -517,11 +492,18 @@ async fn stage_tracked_roots(
         ));
     }
     if !staged_commits.is_empty() {
-        let commit_ids = staged_commits.keys().cloned().collect::<Vec<_>>();
+        let commit_ids = staged_commits
+            .keys()
+            .filter(|commit_id| !rooted_commit_ids.contains(commit_id.as_str()))
+            .cloned()
+            .collect::<Vec<_>>();
+        if commit_ids.is_empty() {
+            return Ok(());
+        }
         return Err(LixError::new(
             LixError::CODE_INTERNAL_ERROR,
             format!(
-                "commit-store staged commits without tracked root metadata: {}",
+                "changelog staged commits without tracked root metadata: {}",
                 commit_ids.join(", ")
             ),
         ));
@@ -529,9 +511,67 @@ async fn stage_tracked_roots(
     Ok(())
 }
 
+fn tracked_roots_parent_first(
+    tracked_roots: &[PendingTrackedRoot],
+) -> Result<Vec<&PendingTrackedRoot>, LixError> {
+    let mut roots_by_id = BTreeMap::new();
+    for root in tracked_roots {
+        if roots_by_id.insert(root.commit_id.as_str(), root).is_some() {
+            return Err(LixError::unknown(format!(
+                "cannot stage duplicate tracked_state root '{}'",
+                root.commit_id
+            )));
+        }
+    }
+
+    let mut ordered = Vec::with_capacity(tracked_roots.len());
+    let mut visiting = BTreeSet::new();
+    let mut visited = BTreeSet::new();
+    for root in tracked_roots {
+        visit_tracked_root_parent_first(
+            root.commit_id.as_str(),
+            &roots_by_id,
+            &mut visiting,
+            &mut visited,
+            &mut ordered,
+        )?;
+    }
+    Ok(ordered)
+}
+
+fn visit_tracked_root_parent_first<'a>(
+    commit_id: &str,
+    roots_by_id: &BTreeMap<&'a str, &'a PendingTrackedRoot>,
+    visiting: &mut BTreeSet<&'a str>,
+    visited: &mut BTreeSet<&'a str>,
+    ordered: &mut Vec<&'a PendingTrackedRoot>,
+) -> Result<(), LixError> {
+    if visited.contains(commit_id) {
+        return Ok(());
+    }
+    let Some(root) = roots_by_id.get(commit_id).copied() else {
+        return Ok(());
+    };
+    if !visiting.insert(root.commit_id.as_str()) {
+        return Err(LixError::unknown(format!(
+            "cannot stage tracked_state root '{}' because staged root parents contain a cycle",
+            root.commit_id
+        )));
+    }
+    if let Some(parent_id) = root.parent_commit_id.as_deref() {
+        if roots_by_id.contains_key(parent_id) {
+            visit_tracked_root_parent_first(parent_id, roots_by_id, visiting, visited, ordered)?;
+        }
+    }
+    visiting.remove(root.commit_id.as_str());
+    visited.insert(root.commit_id.as_str());
+    ordered.push(root);
+    Ok(())
+}
+
 fn untracked_row_ref_from_state_row(row: &PreparedStateRow) -> UntrackedStateRowRef<'_> {
     UntrackedStateRowRef {
-        entity_id: &row.entity_id,
+        entity_pk: &row.entity_pk,
         schema_key: &row.schema_key,
         file_id: row.file_id.as_deref(),
         snapshot_content: row
@@ -545,51 +585,37 @@ fn untracked_row_ref_from_state_row(row: &PreparedStateRow) -> UntrackedStateRow
         created_at: &row.created_at,
         updated_at: &row.updated_at,
         global: row.global,
-        version_id: &row.version_id,
+        branch_id: &row.branch_id,
     }
 }
 
 fn untracked_identity_ref_from_state_row(row: &PreparedStateRow) -> UntrackedStateIdentityRef<'_> {
     UntrackedStateIdentityRef {
-        version_id: &row.version_id,
+        branch_id: &row.branch_id,
         schema_key: &row.schema_key,
-        entity_id: &row.entity_id,
+        entity_pk: &row.entity_pk,
         file_id: row.file_id.as_deref(),
     }
 }
 
-fn untracked_identity_ref_from_adopted_row(
-    row: &PreparedAdoptedStateRow,
-) -> UntrackedStateIdentityRef<'_> {
-    UntrackedStateIdentityRef {
-        version_id: &row.version_id,
-        schema_key: &row.schema_key,
-        entity_id: &row.entity_id,
-        file_id: row.file_id.as_deref(),
-    }
-}
-
-/// Materializes tracked staged membership into commit-store commits.
+/// Materializes tracked staged change refs into changelog commits.
 ///
-/// Staging only accumulates `version_id -> change_ids` because commit ids,
+/// Staging only accumulates `branch_id -> change_ids` because commit ids,
 /// parent heads, and commit-row timestamps belong to transaction finalization.
 /// The `change_ids` list is the ordered set of canonical changes whose effects
-/// the commit introduces relative to its first parent; merge commits may later
-/// populate this list with existing source-parent changes instead of copied
-/// change payloads.
-/// This function turns those membership sets into finalized commit facts.
+/// the commit introduces relative to its first parent.
+/// This function turns those change-ref sets into finalized commit facts.
 ///
 /// Commit finalization output split by durability target.
 ///
-/// `commit_rows` are canonical commit-store facts. live_state later projects
-/// commit SQL surfaces from commit_store; tracked_state roots do not store
-/// commit graph facts.
+/// `commit_rows` are canonical changelog commit facts. tracked_state roots store
+/// serving commit roots keyed by the corresponding commit id.
 ///
-/// `version_heads` are moving refs. They are written through `VersionContext`,
-/// not the canonical commit store.
+/// `branch_heads` are moving refs. They are written through `BranchContext`,
+/// not the canonical changelog.
 struct FinalizedCommitRows {
     commit_rows: Vec<FinalizedCommitRow>,
-    version_heads: Vec<PendingVersionHead>,
+    branch_heads: Vec<PendingBranchHead>,
     tracked_roots: Vec<PendingTrackedRoot>,
 }
 
@@ -598,10 +624,11 @@ struct FinalizedCommitRow {
     parent_commit_ids: Vec<String>,
     created_at: String,
     change_id: String,
+    selected_change_refs: Vec<StagedCommitChangeRef>,
 }
 
-struct PendingVersionHead {
-    version_id: String,
+struct PendingBranchHead {
+    branch_id: String,
     commit_id: String,
     timestamp: String,
 }
@@ -612,34 +639,34 @@ struct PendingTrackedRoot {
 }
 
 async fn finalize_commit_rows(
-    commit_members_by_version: BTreeMap<String, StagedCommitMembers>,
-    extra_commit_parents_by_version: BTreeMap<String, Vec<String>>,
-    version_ctx: &VersionContext,
-    transaction: &mut (impl StorageReader + ?Sized),
+    commit_change_refs_by_branch: BTreeMap<String, StagedCommitChangeRefs>,
+    extra_commit_parents_by_branch: BTreeMap<String, Vec<String>>,
+    branch_ctx: &BranchContext,
+    read: &(impl StorageRead + Send + Sync + ?Sized),
 ) -> Result<FinalizedCommitRows, LixError> {
     let mut commit_rows = Vec::new();
-    let mut version_heads = Vec::new();
+    let mut branch_heads = Vec::new();
     let mut tracked_roots = Vec::new();
 
-    for (version_id, members) in commit_members_by_version {
-        if members.is_empty() && !members.allow_empty {
+    for (branch_id, change_refs) in commit_change_refs_by_branch {
+        if change_refs.is_empty() && !change_refs.allow_empty {
             continue;
         }
 
-        let commit_id = members.commit_id;
-        let commit_change_id = members.commit_change_id;
-        let timestamp = members.created_at;
-        let _change_ids = members.change_ids;
-        let parent_commit_ids = version_ctx
-            .ref_reader(&mut *transaction)
-            .load_head_commit_id(&version_id)
+        let commit_id = change_refs.commit_id;
+        let commit_change_id = change_refs.commit_change_id;
+        let timestamp = change_refs.created_at;
+        let selected_change_refs = change_refs.selected_change_refs;
+        let parent_commit_ids = branch_ctx
+            .ref_reader(read)
+            .load_head_commit_id(&branch_id)
             .await?
             .into_iter()
             .collect::<Vec<_>>();
         let parent_commit_ids = merge_parent_commit_ids(
             parent_commit_ids,
-            extra_commit_parents_by_version
-                .get(&version_id)
+            extra_commit_parents_by_branch
+                .get(&branch_id)
                 .cloned()
                 .unwrap_or_default(),
         );
@@ -650,9 +677,10 @@ async fn finalize_commit_rows(
             parent_commit_ids: parent_commit_ids.clone(),
             created_at: timestamp.clone(),
             change_id: commit_change_id,
+            selected_change_refs,
         });
-        version_heads.push(PendingVersionHead {
-            version_id: version_id.clone(),
+        branch_heads.push(PendingBranchHead {
+            branch_id: branch_id.clone(),
             commit_id: commit_id.clone(),
             timestamp,
         });
@@ -664,7 +692,7 @@ async fn finalize_commit_rows(
 
     Ok(FinalizedCommitRows {
         commit_rows,
-        version_heads,
+        branch_heads,
         tracked_roots,
     })
 }
@@ -688,23 +716,23 @@ mod tests {
 
     use super::*;
     use crate::backend::{
-        testing::UnitTestBackend, Backend, BackendKvEntryPage, BackendKvExistsBatch,
-        BackendKvGetRequest, BackendKvKeyPage, BackendKvScanRequest, BackendKvValueBatch,
-        BackendKvValuePage, BackendKvWriteBatch, BackendKvWriteStats, BackendReadTransaction,
-        BackendWriteTransaction,
+        Backend, BackendCapabilities, BackendError, BackendWrite, CommitResult, DurableWriteLock,
+        KeyRange, PutBatch,
     };
+    use crate::branch::BranchContext;
     use crate::catalog::SchemaPlanId;
-    use crate::commit_store::{ChangeIndexEntry, ChangeLocator};
+    use crate::changelog::ChangelogReader;
     use crate::live_state::{LiveStateContext, LiveStateRowRequest};
-    use crate::storage::StorageContext;
+    use crate::storage::{
+        InMemoryStorageBackend, InMemoryStorageRead, InMemoryStorageWrite, StorageContext,
+        StorageKey, StorageReadOptions, StorageWriteOptions,
+    };
     use crate::transaction::types::PreparedRowFacts;
     use crate::untracked_state::{
         MaterializedUntrackedStateRow, UntrackedStateContext, UntrackedStateRowRequest,
     };
-    use crate::version::VersionContext;
     use crate::NullableKeyFilter;
-    use crate::GLOBAL_VERSION_ID;
-    use async_trait::async_trait;
+    use crate::GLOBAL_BRANCH_ID;
 
     const DETERMINISTIC_MODE_KEY: &str = "lix_deterministic_mode";
     const DETERMINISTIC_SEQUENCE_KEY: &str = "lix_deterministic_sequence_number";
@@ -718,138 +746,215 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn commit_staged_writes_appends_commit_store_and_updates_serving_projection() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+    async fn commit_staged_writes_appends_changelog_and_updates_commit_root() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let binary_cas = BinaryCasContext::new();
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
 
         let state_rows = vec![tracked_global_row("change-1")];
-        commit_prepared_writes(
+        let writes = commit_prepared_writes(
             &binary_cas,
-            &crate::commit_store::CommitStoreContext::new(),
-            &version_ctx,
+            &branch_ctx,
             None,
-            transaction.as_mut(),
+            &mut read,
             PreparedWriteSet {
                 insert_identities: BTreeMap::new(),
                 state_rows,
-                adopted_rows: Vec::new(),
-                commit_members_by_version: BTreeMap::from([(
-                    GLOBAL_VERSION_ID.to_string(),
-                    members(["change-1"]),
+                commit_change_refs_by_branch: BTreeMap::from([(
+                    GLOBAL_BRANCH_ID.to_string(),
+                    change_refs(["change-1"]),
                 )]),
-                extra_commit_parents_by_version: BTreeMap::new(),
+                extra_commit_parents_by_branch: BTreeMap::new(),
                 file_data_writes: Vec::new(),
             },
         )
         .await
         .expect("commit should flush staged rows");
-        transaction
-            .commit()
-            .await
-            .expect("commit should persist kv");
-
-        let commit_reader = crate::commit_store::CommitStoreContext::new().reader(storage.clone());
-        let commit = commit_reader
-            .load_commit("test-uuid-1")
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("writes should commit");
+
+        let mut changelog_reader = crate::changelog::ChangelogContext::new().reader(
+            storage
+                .begin_read(StorageReadOptions::default())
+                .expect("read should open"),
+        );
+        let commits = changelog_reader
+            .load_commits(crate::changelog::CommitLoadRequest {
+                commit_ids: &["test-uuid-1".to_string()],
+                projection: crate::changelog::CommitProjection::Full,
+            })
             .await
-            .expect("commit-store commit should load")
-            .expect("commit-store commit should exist");
-        assert_eq!(commit.change_id, "test-uuid-2");
-        assert_eq!(commit.change_pack_count, 1);
-        assert_eq!(commit.membership_pack_count, 0);
-        let index_entries = commit_reader
-            .load_change_index_entries(&["change-1".to_string(), "test-uuid-2".to_string()])
+            .expect("changelog commit should load");
+        let Some(crate::changelog::CommitLoadEntry::Full {
+            record,
+            change_ref_chunks,
+        }) = commits.entries.into_iter().next().flatten()
+        else {
+            panic!("changelog commit should exist");
+        };
+        assert_eq!(record.change_id, "test-uuid-2");
+        assert!(change_ref_chunks
+            .iter()
+            .flat_map(|chunk| chunk.entries.iter())
+            .any(|entry| entry.change_id == "change-1"));
+        let changes = changelog_reader
+            .load_changes(crate::changelog::ChangeLoadRequest {
+                change_ids: &["change-1".to_string(), record.change_id.clone()],
+            })
             .await
-            .expect("commit-store change index should load");
-        assert_eq!(
-            index_entries,
-            vec![
-                Some(ChangeIndexEntry::PackedChange {
-                    locator: ChangeLocator {
-                        source_commit_id: "test-uuid-1".to_string(),
-                        source_pack_id: 0,
-                        source_ordinal: 0,
-                        change_id: "change-1".to_string(),
-                    },
-                }),
-                Some(ChangeIndexEntry::CommitHeader {
-                    commit_id: "test-uuid-1".to_string(),
-                    change_id: "test-uuid-2".to_string(),
-                }),
-            ]
+            .expect("changelog change should load");
+        let mut loaded_changes = changes.entries.into_iter();
+        let Some(change) = loaded_changes.next().flatten() else {
+            panic!("changelog change should exist");
+        };
+        assert_eq!(change.change_id, "change-1");
+        assert_eq!(change.schema_key, "test_schema");
+        assert!(
+            loaded_changes.next().flatten().is_none(),
+            "commit row change is derived from changelog.commit, not stored as changelog.change"
+        );
+
+        let mut tracked_reader = crate::tracked_state::TrackedStateContext::new().reader(
+            storage
+                .begin_read(StorageReadOptions::default())
+                .expect("read should open"),
         );
-        let change_pack = commit_reader
-            .load_change_pack("test-uuid-1", 0)
+        let commit_rows = tracked_reader
+            .scan_rows_at_commit(
+                "test-uuid-1",
+                &crate::tracked_state::TrackedStateScanRequest {
+                    filter: crate::tracked_state::TrackedStateFilter {
+                        schema_keys: vec!["lix_commit".to_string()],
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                },
+            )
             .await
-            .expect("commit-store change pack should load")
-            .expect("commit-store change pack should exist");
-        assert_eq!(change_pack.len(), 1);
-        assert_eq!(change_pack[0].id, "change-1");
-        assert_eq!(change_pack[0].schema_key, "test_schema");
-
-        let loaded_head = version_ctx
-            .ref_reader(storage.clone())
-            .load_head_commit_id(GLOBAL_VERSION_ID)
+            .expect("commit root should scan");
+        assert!(
+            commit_rows
+                .iter()
+                .any(|row| row.change_id == record.change_id && row.snapshot_content.is_some()),
+            "commit root should surface the derived lix_commit row"
+        );
+
+        let loaded_head = branch_ctx
+            .ref_reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
+            .load_head_commit_id(GLOBAL_BRANCH_ID)
             .await
-            .expect("version ref load should succeed");
+            .expect("branch ref load should succeed");
         assert_eq!(loaded_head.as_deref(), Some("test-uuid-1"));
     }
 
+    #[tokio::test]
+    async fn stage_changelog_commits_orders_staged_parents_before_children() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let mut writes = StorageWriteSet::new();
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut parent_row = tracked_global_row("parent-change");
+        parent_row.commit_id = Some("parent-commit".to_string());
+        let mut child_row = tracked_global_row("child-change");
+        child_row.commit_id = Some("child-commit".to_string());
+
+        let commits = vec![
+            FinalizedCommitRow {
+                commit_id: "child-commit".to_string(),
+                parent_commit_ids: vec!["parent-commit".to_string()],
+                created_at: "2026-01-01T00:00:01Z".to_string(),
+                change_id: "child-commit-change".to_string(),
+                selected_change_refs: Vec::new(),
+            },
+            FinalizedCommitRow {
+                commit_id: "parent-commit".to_string(),
+                parent_commit_ids: Vec::new(),
+                created_at: "2026-01-01T00:00:00Z".to_string(),
+                change_id: "parent-commit-change".to_string(),
+                selected_change_refs: Vec::new(),
+            },
+        ];
+        stage_changelog_commits(
+            &mut read,
+            &mut writes,
+            &[parent_row, child_row],
+            &BTreeMap::from([
+                ("parent-commit".to_string(), vec![0]),
+                ("child-commit".to_string(), vec![1]),
+            ]),
+            &commits,
+        )
+        .await
+        .expect("child-before-parent input should still stage parent first");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("writes should persist");
+
+        let mut changelog_reader = crate::changelog::ChangelogContext::new().reader(
+            storage
+                .begin_read(StorageReadOptions::default())
+                .expect("read should open"),
+        );
+        let commits = changelog_reader
+            .load_commits(crate::changelog::CommitLoadRequest {
+                commit_ids: &["parent-commit".to_string(), "child-commit".to_string()],
+                projection: crate::changelog::CommitProjection::Record,
+            })
+            .await
+            .expect("commits should load");
+        assert!(commits.entries.iter().all(Option::is_some));
+    }
+
     #[tokio::test]
     async fn commit_with_only_untracked_writes_does_not_create_lix_commit() {
-        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 binary_cas = BinaryCasContext::new();
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
         let untracked_state = UntrackedStateContext::new();
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
 
         let state_rows = vec![untracked_global_row("change-untracked")];
-        commit_prepared_writes(
+        let writes = commit_prepared_writes(
             &binary_cas,
-            &crate::commit_store::CommitStoreContext::new(),
-            &version_ctx,
+            &branch_ctx,
             None,
-            transaction.as_mut(),
+            &mut read,
             PreparedWriteSet {
                 insert_identities: BTreeMap::new(),
                 state_rows,
-                adopted_rows: Vec::new(),
-                commit_members_by_version: BTreeMap::new(),
-                extra_commit_parents_by_version: BTreeMap::new(),
+                commit_change_refs_by_branch: BTreeMap::new(),
+                extra_commit_parents_by_branch: BTreeMap::new(),
                 file_data_writes: Vec::new(),
             },
         )
         .await
         .expect("commit should flush untracked row");
-        transaction
-            .commit()
-            .await
-            .expect("commit should persist kv");
-
-        let commit_reader = crate::commit_store::CommitStoreContext::new().reader(storage.clone());
-        let index_entries = commit_reader
-            .load_change_index_entries(&["change-untracked".to_string()])
-            .await
-            .expect("commit-store change index should load");
-        assert_eq!(index_entries, vec![None]);
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("writes should commit");
 
         let loaded = {
-            let mut untracked_reader = untracked_state.reader(storage.clone());
+            let mut untracked_reader = untracked_state.reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            );
             untracked_reader
                 .load_row(&UntrackedStateRowRequest {
                     schema_key: "test_schema".to_string(),
-                    version_id: GLOBAL_VERSION_ID.to_string(),
-                    entity_id: crate::entity_identity::EntityIdentity::single("entity-1"),
+                    branch_id: GLOBAL_BRANCH_ID.to_string(),
+                    entity_pk: crate::entity_pk::EntityPk::single("entity-1"),
                     file_id: NullableKeyFilter::Null,
                 })
                 .await
@@ -864,17 +969,12 @@ mod tests {
 
     #[tokio::test]
     async fn tracked_write_deletes_matching_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 binary_cas = BinaryCasContext::new();
         let untracked_state = UntrackedStateContext::new();
         let live_state = Arc::new(live_state_context());
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
 
-        let mut seed_transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("seed transaction should open");
         let mut writes = StorageWriteSet::new();
         let staged_row = untracked_global_row("change-untracked");
         let canonical_row = crate::test_support::untracked_state_row_from_materialized(
@@ -886,54 +986,53 @@ mod tests {
             .writer(&mut writes)
             .stage_rows(std::iter::once(canonical_row.as_ref()))
             .expect("untracked seed should write");
-        writes
-            .apply(&mut seed_transaction.as_mut())
-            .await
-            .expect("untracked seed should apply");
-        seed_transaction
-            .commit()
-            .await
-            .expect("seed transaction should persist");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("untracked seed should commit");
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         let state_rows = vec![tracked_global_row("change-tracked")];
-        commit_prepared_writes(
+        let writes = commit_prepared_writes(
             &binary_cas,
-            &crate::commit_store::CommitStoreContext::new(),
-            &version_ctx,
+            &branch_ctx,
             None,
-            transaction.as_mut(),
+            &mut read,
             PreparedWriteSet {
                 insert_identities: BTreeMap::new(),
                 state_rows,
-                adopted_rows: Vec::new(),
-                commit_members_by_version: BTreeMap::from([(
-                    GLOBAL_VERSION_ID.to_string(),
-                    members(["change-tracked"]),
+                commit_change_refs_by_branch: BTreeMap::from([(
+                    GLOBAL_BRANCH_ID.to_string(),
+                    change_refs(["change-tracked"]),
                 )]),
-                extra_commit_parents_by_version: BTreeMap::new(),
+                extra_commit_parents_by_branch: BTreeMap::new(),
                 file_data_writes: Vec::new(),
             },
         )
         .await
         .expect("tracked commit should flush");
-        transaction
-            .commit()
-            .await
-            .expect("commit should persist kv");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("writes should commit");
 
         let untracked = {
-            let mut untracked_reader = untracked_state.reader(storage.clone());
+            let mut untracked_reader = untracked_state.reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            );
             untracked_reader.load_row(&untracked_request()).await
         }
         .expect("untracked load should succeed");
         assert_eq!(untracked, None);
 
         let visible = live_state
-            .reader(storage.clone())
+            .reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
             .load_row(&live_state_request())
             .await
             .expect("live-state load should succeed")
@@ -945,20 +1044,43 @@ mod tests {
 
     #[tokio::test]
     async fn commit_staged_writes_applies_cross_subsystem_rows_as_one_backend_batch() {
-        let counting_backend = Arc::new(CountingBackend::new());
+        let counting_backend = CountingBackend::new();
         let write_batches = counting_backend.write_batches();
-        let backend: Arc<dyn Backend + Send + Sync> = counting_backend;
-        let storage = StorageContext::new(backend);
+        let storage = StorageContext::new(counting_backend);
         let binary_cas = BinaryCasContext::new();
         let live_state = Arc::new(live_state_context());
         let untracked_state = UntrackedStateContext::new();
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
-        crate::test_support::seed_global_version_head(storage.clone()).await;
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
+        {
+            let mut read = storage
+                .begin_read(StorageReadOptions::default())
+                .expect("seed read should open");
+            let mut writes = storage.new_write_set();
+            crate::test_support::stage_tracked_root_from_materialized(
+                &mut read,
+                &mut writes,
+                &crate::tracked_state::TrackedStateContext::new(),
+                crate::test_support::TEST_EMPTY_ROOT_COMMIT_ID,
+                None,
+                &[],
+            )
+            .await
+            .expect("empty tracked root should stage");
+            let branch_ref_row = crate::transaction::prepare_branch_ref_row(
+                GLOBAL_BRANCH_ID,
+                crate::test_support::TEST_EMPTY_ROOT_COMMIT_ID,
+                "1970-01-01T00:00:00.000Z",
+            )
+            .expect("global branch ref should stage");
+            UntrackedStateContext::new()
+                .writer(&mut writes)
+                .stage_rows([branch_ref_row.row.as_ref()])
+                .expect("global branch ref should stage");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("global branch ref should commit");
+        }
         {
-            let mut seed_transaction = storage
-                .begin_write_transaction()
-                .await
-                .expect("seed transaction should open");
             let mut writes = StorageWriteSet::new();
             let mode_snapshot = serde_json::to_string(&serde_json::json!({
                 "key": DETERMINISTIC_MODE_KEY,
@@ -974,7 +1096,7 @@ mod tests {
                 )
                 .expect("deterministic mode snapshot should stage");
             let row = crate::untracked_state::UntrackedStateRow {
-                entity_id: crate::entity_identity::EntityIdentity::single(DETERMINISTIC_MODE_KEY),
+                entity_pk: crate::entity_pk::EntityPk::single(DETERMINISTIC_MODE_KEY),
                 schema_key: "lix_key_value".to_string(),
                 file_id: None,
                 snapshot_content: Some(mode_snapshot.to_string()),
@@ -982,53 +1104,49 @@ mod tests {
                 created_at: "2026-01-01T00:00:00Z".to_string(),
                 updated_at: "2026-01-01T00:00:00Z".to_string(),
                 global: true,
-                version_id: GLOBAL_VERSION_ID.to_string(),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
             };
             UntrackedStateContext::new()
                 .writer(&mut writes)
                 .stage_rows(std::iter::once(row.as_ref()))
                 .expect("deterministic mode should stage");
-            writes
-                .apply(&mut seed_transaction.as_mut())
-                .await
-                .expect("deterministic mode should apply");
-            seed_transaction
-                .commit()
-                .await
-                .expect("seed transaction should persist");
+            storage
+                .commit_write_set(writes, StorageWriteOptions::default())
+                .expect("deterministic mode should commit");
         }
         write_batches.store(0, Ordering::SeqCst);
         let runtime_functions = {
-            let reader = live_state.reader(storage.clone());
+            let reader = live_state.reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            );
             FunctionContext::prepare(&reader)
                 .await
                 .expect("runtime context should prepare")
         };
         runtime_functions.provider().call_uuid_v7();
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
 
         let tracked_row = tracked_global_row("change-tracked");
         let mut untracked_row = untracked_global_row("change-untracked");
-        untracked_row.entity_id = crate::entity_identity::EntityIdentity::single("entity-2");
+        untracked_row.entity_pk = crate::entity_pk::EntityPk::single("entity-2");
 
-        commit_prepared_writes(
+        let writes = commit_prepared_writes(
             &binary_cas,
-            &crate::commit_store::CommitStoreContext::new(),
-            &version_ctx,
+            &branch_ctx,
             Some(&runtime_functions),
-            transaction.as_mut(),
+            &mut read,
             PreparedWriteSet {
                 insert_identities: BTreeMap::new(),
                 state_rows: vec![tracked_row, untracked_row],
-                adopted_rows: Vec::new(),
-                commit_members_by_version: BTreeMap::from([(
-                    GLOBAL_VERSION_ID.to_string(),
-                    members(["change-tracked"]),
+                commit_change_refs_by_branch: BTreeMap::from([(
+                    GLOBAL_BRANCH_ID.to_string(),
+                    change_refs(["change-tracked"]),
                 )]),
-                extra_commit_parents_by_version: BTreeMap::new(),
+                extra_commit_parents_by_branch: BTreeMap::new(),
                 file_data_writes: Vec::new(),
             },
         )
@@ -1037,46 +1155,65 @@ mod tests {
 
         assert_eq!(
             write_batches.load(Ordering::SeqCst),
-            1,
-            "tracked, json, untracked, commit-store, and version refs must apply as one backend write batch"
+            0,
+            "prepared writes should not touch the backend before the write set is committed"
         );
-
-        transaction
-            .commit()
-            .await
-            .expect("commit should persist kv");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("writes should commit");
         assert_eq!(write_batches.load(Ordering::SeqCst), 1);
 
-        let commit_reader = crate::commit_store::CommitStoreContext::new().reader(storage.clone());
-        let commit = commit_reader
-            .load_commit("test-uuid-1")
+        let mut changelog_reader = crate::changelog::ChangelogContext::new().reader(
+            storage
+                .begin_read(StorageReadOptions::default())
+                .expect("read should open"),
+        );
+        let commits = changelog_reader
+            .load_commits(crate::changelog::CommitLoadRequest {
+                commit_ids: &["test-uuid-1".to_string()],
+                projection: crate::changelog::CommitProjection::Record,
+            })
             .await
-            .expect("commit-store commit should load")
-            .expect("commit-store commit should exist");
+            .expect("changelog commit should load");
+        let Some(crate::changelog::CommitLoadEntry::Record(commit)) =
+            commits.entries.into_iter().next().flatten()
+        else {
+            panic!("changelog commit should exist");
+        };
         assert_eq!(commit.change_id, "test-uuid-2");
-        let index_entries = commit_reader
-            .load_change_index_entries(&["change-tracked".to_string()])
+        let changes = changelog_reader
+            .load_changes(crate::changelog::ChangeLoadRequest {
+                change_ids: &["change-tracked".to_string()],
+            })
             .await
-            .expect("commit-store change index should load");
+            .expect("changelog change should load");
         assert!(matches!(
-            index_entries.as_slice(),
-            [Some(ChangeIndexEntry::PackedChange { .. })]
+            changes.entries.as_slice(),
+            [Some(change)] if change.change_id == "change-tracked"
         ));
 
-        let loaded_head = version_ctx
-            .ref_reader(storage.clone())
-            .load_head_commit_id(GLOBAL_VERSION_ID)
+        let loaded_head = branch_ctx
+            .ref_reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
+            .load_head_commit_id(GLOBAL_BRANCH_ID)
             .await
-            .expect("version ref load should succeed");
+            .expect("branch ref load should succeed");
         assert_eq!(loaded_head.as_deref(), Some("test-uuid-1"));
 
         let untracked = {
-            let mut untracked_reader = untracked_state.reader(storage.clone());
+            let mut untracked_reader = untracked_state.reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            );
             untracked_reader
                 .load_row(&UntrackedStateRowRequest {
                     schema_key: "test_schema".to_string(),
-                    version_id: GLOBAL_VERSION_ID.to_string(),
-                    entity_id: crate::entity_identity::EntityIdentity::single("entity-2"),
+                    branch_id: GLOBAL_BRANCH_ID.to_string(),
+                    entity_pk: crate::entity_pk::EntityPk::single("entity-2"),
                     file_id: NullableKeyFilter::Null,
                 })
                 .await
@@ -1089,13 +1226,15 @@ mod tests {
         );
 
         let sequence_row = 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_VERSION_ID.to_string(),
-                entity_id: crate::entity_identity::EntityIdentity::single(
-                    DETERMINISTIC_SEQUENCE_KEY,
-                ),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single(DETERMINISTIC_SEQUENCE_KEY),
                 file_id: NullableKeyFilter::Null,
             })
             .await
@@ -1108,189 +1247,181 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn non_global_tracked_write_creates_one_commit_and_advances_only_touched_version() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
+    async fn non_global_tracked_write_creates_one_commit_and_advances_only_touched_branch() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let binary_cas = BinaryCasContext::new();
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
-        crate::test_support::seed_version_head(storage.clone(), GLOBAL_VERSION_ID, "global-before")
-            .await;
-        crate::test_support::seed_version_head(storage.clone(), "version-a", "version-a-before")
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
+        crate::test_support::seed_branch_head(storage.clone(), GLOBAL_BRANCH_ID, "global-before")
             .await;
+        crate::test_support::seed_branch_head(storage.clone(), "branch-a", "branch-a-before").await;
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        let state_rows = vec![tracked_version_row("version-a", "change-version-a")];
-        commit_prepared_writes(
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let state_rows = vec![tracked_branch_row("branch-a", "change-branch-a")];
+        let writes = commit_prepared_writes(
             &binary_cas,
-            &crate::commit_store::CommitStoreContext::new(),
-            &version_ctx,
+            &branch_ctx,
             None,
-            transaction.as_mut(),
+            &mut read,
             PreparedWriteSet {
                 insert_identities: BTreeMap::new(),
                 state_rows,
-                adopted_rows: Vec::new(),
-                commit_members_by_version: BTreeMap::from([(
-                    "version-a".to_string(),
-                    members(["change-version-a"]),
+                commit_change_refs_by_branch: BTreeMap::from([(
+                    "branch-a".to_string(),
+                    change_refs(["change-branch-a"]),
                 )]),
-                extra_commit_parents_by_version: BTreeMap::new(),
+                extra_commit_parents_by_branch: BTreeMap::new(),
                 file_data_writes: Vec::new(),
             },
         )
         .await
-        .expect("version commit should flush");
-        transaction
-            .commit()
-            .await
-            .expect("commit should persist kv");
-
-        let commit_reader = crate::commit_store::CommitStoreContext::new().reader(storage.clone());
-        let commit = commit_reader
-            .load_commit("test-uuid-1")
+        .expect("branch commit should flush");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("writes should commit");
+
+        let mut changelog_reader = crate::changelog::ChangelogContext::new().reader(
+            storage
+                .begin_read(StorageReadOptions::default())
+                .expect("read should open"),
+        );
+        let commits = changelog_reader
+            .load_commits(crate::changelog::CommitLoadRequest {
+                commit_ids: &["test-uuid-1".to_string()],
+                projection: crate::changelog::CommitProjection::Record,
+            })
             .await
-            .expect("commit-store commit should load")
-            .expect("commit-store commit should exist");
+            .expect("changelog commit should load");
+        let Some(crate::changelog::CommitLoadEntry::Record(commit)) =
+            commits.entries.into_iter().next().flatten()
+        else {
+            panic!("changelog commit should exist");
+        };
         assert_eq!(commit.change_id, "test-uuid-2");
-        assert_eq!(commit.parent_ids, vec!["version-a-before"]);
-        let index_entries = commit_reader
-            .load_change_index_entries(&["change-version-a".to_string()])
-            .await
-            .expect("commit-store change index should load");
-        assert!(matches!(
-            index_entries.as_slice(),
-            [Some(ChangeIndexEntry::PackedChange { .. })]
-        ));
+        assert_eq!(commit.parent_commit_ids, vec!["branch-a-before"]);
 
-        let global_head = version_ctx
-            .ref_reader(storage.clone())
-            .load_head_commit_id(GLOBAL_VERSION_ID)
+        let global_head = branch_ctx
+            .ref_reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
+            .load_head_commit_id(GLOBAL_BRANCH_ID)
             .await
             .expect("global head should load");
-        let version_head = version_ctx
-            .ref_reader(storage.clone())
-            .load_head_commit_id("version-a")
+        let branch_head = branch_ctx
+            .ref_reader(
+                storage
+                    .begin_read(StorageReadOptions::default())
+                    .expect("read should open"),
+            )
+            .load_head_commit_id("branch-a")
             .await
-            .expect("version head should load");
+            .expect("branch head should load");
         assert_eq!(global_head.as_deref(), Some("global-before"));
-        assert_eq!(version_head.as_deref(), Some("test-uuid-1"));
+        assert_eq!(branch_head.as_deref(), Some("test-uuid-1"));
     }
 
     #[tokio::test]
-    async fn finalize_commit_rows_parents_global_commit_to_existing_version_ref() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
-        crate::test_support::seed_version_head(
-            storage.clone(),
-            GLOBAL_VERSION_ID,
-            "initial-commit",
-        )
-        .await;
+    async fn finalize_commit_rows_parents_global_commit_to_existing_branch_ref() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
+        crate::test_support::seed_branch_head(storage.clone(), GLOBAL_BRANCH_ID, "initial-commit")
+            .await;
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         let rows = finalize_commit_rows(
             BTreeMap::from([(
-                GLOBAL_VERSION_ID.to_string(),
-                members(["change-a", "change-b"]),
+                GLOBAL_BRANCH_ID.to_string(),
+                change_refs(["change-a", "change-b"]),
             )]),
             BTreeMap::new(),
-            &version_ctx,
-            transaction.as_mut(),
+            &branch_ctx,
+            &mut read,
         )
         .await
         .expect("global commit row should finalize");
 
         assert_eq!(rows.commit_rows.len(), 1);
-        assert_eq!(rows.version_heads.len(), 1);
+        assert_eq!(rows.branch_heads.len(), 1);
         let row = &rows.commit_rows[0];
         assert_eq!(row.commit_id, "test-uuid-1");
         assert_eq!(row.change_id, "test-uuid-2");
         assert_eq!(row.created_at, "test-timestamp-1");
         assert_eq!(row.parent_commit_ids, vec!["initial-commit"]);
 
-        let version_head = &rows.version_heads[0];
-        assert_eq!(version_head.version_id, GLOBAL_VERSION_ID);
-        assert_eq!(version_head.commit_id, "test-uuid-1");
+        let branch_head = &rows.branch_heads[0];
+        assert_eq!(branch_head.branch_id, GLOBAL_BRANCH_ID);
+        assert_eq!(branch_head.commit_id, "test-uuid-1");
     }
 
     #[tokio::test]
     async fn finalize_commit_rows_skips_empty_members() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         let rows = finalize_commit_rows(
             BTreeMap::from([(
-                GLOBAL_VERSION_ID.to_string(),
-                StagedCommitMembers::default(),
+                GLOBAL_BRANCH_ID.to_string(),
+                StagedCommitChangeRefs::default(),
             )]),
             BTreeMap::new(),
-            &version_ctx,
-            transaction.as_mut(),
+            &branch_ctx,
+            &mut read,
         )
         .await
-        .expect("empty members should be ignored");
+        .expect("empty change_refs should be ignored");
 
         assert!(rows.commit_rows.is_empty());
-        assert!(rows.version_heads.is_empty());
+        assert!(rows.branch_heads.is_empty());
     }
 
     #[tokio::test]
-    async fn finalize_commit_rows_uses_existing_version_ref_as_parent() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
-        crate::test_support::seed_version_head(storage.clone(), GLOBAL_VERSION_ID, "global-before")
-            .await;
-        crate::test_support::seed_version_head(storage.clone(), "version-a", "previous-commit")
+    async fn finalize_commit_rows_uses_existing_branch_ref_as_parent() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
+        crate::test_support::seed_branch_head(storage.clone(), GLOBAL_BRANCH_ID, "global-before")
             .await;
+        crate::test_support::seed_branch_head(storage.clone(), "branch-a", "previous-commit").await;
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         let rows = finalize_commit_rows(
-            BTreeMap::from([("version-a".to_string(), members(["change-a"]))]),
+            BTreeMap::from([("branch-a".to_string(), change_refs(["change-a"]))]),
             BTreeMap::new(),
-            &version_ctx,
-            transaction.as_mut(),
+            &branch_ctx,
+            &mut read,
         )
         .await
-        .expect("active-version commit finalization should resolve parent");
+        .expect("active-branch commit finalization should resolve parent");
 
         assert_eq!(
             rows.commit_rows[0].parent_commit_ids,
             vec!["previous-commit"]
         );
-        assert_eq!(rows.version_heads[0].version_id, "version-a");
+        assert_eq!(rows.branch_heads[0].branch_id, "branch-a");
     }
 
     #[tokio::test]
     async fn finalize_commit_rows_appends_extra_merge_parent_after_target_head() {
-        let backend: Arc<dyn Backend + Send + Sync> = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(Arc::clone(&backend));
-        let version_ctx = VersionContext::new(Arc::new(UntrackedStateContext::new()));
-        crate::test_support::seed_version_head(storage.clone(), "version-a", "target-head").await;
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let branch_ctx = BranchContext::new(Arc::new(UntrackedStateContext::new()));
+        crate::test_support::seed_branch_head(storage.clone(), "branch-a", "target-head").await;
 
-        let mut transaction = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
         let rows = finalize_commit_rows(
-            BTreeMap::from([("version-a".to_string(), members(["change-a"]))]),
-            BTreeMap::from([("version-a".to_string(), vec!["source-head".to_string()])]),
-            &version_ctx,
-            transaction.as_mut(),
+            BTreeMap::from([("branch-a".to_string(), change_refs(["change-a"]))]),
+            BTreeMap::from([("branch-a".to_string(), vec!["source-head".to_string()])]),
+            &branch_ctx,
+            &mut read,
         )
         .await
         .expect("merge commit finalization should resolve parents");
@@ -1301,27 +1432,27 @@ mod tests {
         );
     }
 
-    fn members<const N: usize>(change_ids: [&str; N]) -> StagedCommitMembers {
-        let mut members = StagedCommitMembers::new(
+    fn change_refs<const N: usize>(change_ids: [&str; N]) -> StagedCommitChangeRefs {
+        let mut change_refs = StagedCommitChangeRefs::new(
             "test-uuid-1".to_string(),
             "test-uuid-2".to_string(),
             "test-timestamp-1".to_string(),
         );
         for change_id in change_ids {
-            members.add_change_id(change_id.to_string());
+            change_refs.add_change_id(change_id.to_string());
         }
-        members
+        change_refs
     }
 
     fn tracked_global_row(change_id: &str) -> PreparedStateRow {
-        tracked_version_row(GLOBAL_VERSION_ID, change_id)
+        tracked_branch_row(GLOBAL_BRANCH_ID, change_id)
     }
 
-    fn tracked_version_row(version_id: &str, change_id: &str) -> PreparedStateRow {
+    fn tracked_branch_row(branch_id: &str, change_id: &str) -> PreparedStateRow {
         PreparedStateRow {
             schema_plan_id: SchemaPlanId::for_test(0),
             facts: PreparedRowFacts::default(),
-            entity_id: crate::entity_identity::EntityIdentity::single("entity-1"),
+            entity_pk: crate::entity_pk::EntityPk::single("entity-1"),
             schema_key: "test_schema".to_string(),
             file_id: None,
             snapshot: Some(
@@ -1337,11 +1468,11 @@ mod tests {
             origin: None,
             created_at: "2026-01-01T00:00:00Z".to_string(),
             updated_at: "2026-01-01T00:00:00Z".to_string(),
-            global: version_id == GLOBAL_VERSION_ID,
+            global: branch_id == GLOBAL_BRANCH_ID,
             change_id: Some(change_id.to_string()),
             commit_id: Some("test-uuid-1".to_string()),
             untracked: false,
-            version_id: version_id.to_string(),
+            branch_id: branch_id.to_string(),
         }
     }
 
@@ -1367,8 +1498,8 @@ mod tests {
     fn untracked_request() -> UntrackedStateRowRequest {
         UntrackedStateRowRequest {
             schema_key: "test_schema".to_string(),
-            version_id: GLOBAL_VERSION_ID.to_string(),
-            entity_id: crate::entity_identity::EntityIdentity::single("entity-1"),
+            branch_id: GLOBAL_BRANCH_ID.to_string(),
+            entity_pk: crate::entity_pk::EntityPk::single("entity-1"),
             file_id: NullableKeyFilter::Null,
         }
     }
@@ -1376,21 +1507,21 @@ mod tests {
     fn live_state_request() -> LiveStateRowRequest {
         LiveStateRowRequest {
             schema_key: "test_schema".to_string(),
-            version_id: GLOBAL_VERSION_ID.to_string(),
-            entity_id: crate::entity_identity::EntityIdentity::single("entity-1"),
+            branch_id: GLOBAL_BRANCH_ID.to_string(),
+            entity_pk: crate::entity_pk::EntityPk::single("entity-1"),
             file_id: NullableKeyFilter::Null,
         }
     }
 
     struct CountingBackend {
-        inner: UnitTestBackend,
+        inner: InMemoryStorageBackend,
         write_batches: Arc<AtomicUsize>,
     }
 
     impl CountingBackend {
         fn new() -> Self {
             Self {
-                inner: UnitTestBackend::new(),
+                inner: InMemoryStorageBackend::new(),
                 write_batches: Arc::new(AtomicUsize::new(0)),
             }
         }
@@ -1400,85 +1531,62 @@ mod tests {
         }
     }
 
-    #[async_trait]
     impl Backend for CountingBackend {
-        async fn begin_read_transaction(
-            &self,
-        ) -> Result<Box<dyn BackendReadTransaction + Send + Sync + 'static>, LixError> {
-            self.inner.begin_read_transaction().await
+        type Read<'a>
+            = InMemoryStorageRead
+        where
+            Self: 'a;
+
+        type Write<'a>
+            = CountingWrite
+        where
+            Self: 'a;
+
+        fn capabilities(&self) -> BackendCapabilities {
+            self.inner.capabilities()
         }
 
-        async fn begin_write_transaction(
-            &self,
-        ) -> Result<Box<dyn BackendWriteTransaction + Send + Sync + 'static>, LixError> {
-            Ok(Box::new(CountingWriteTransaction {
-                inner: self.inner.begin_write_transaction().await?,
-                write_batches: Arc::clone(&self.write_batches),
-            }))
+        fn begin_read(&self, opts: StorageReadOptions) -> Result<Self::Read<'_>, BackendError> {
+            self.inner.begin_read(opts)
         }
-    }
-
-    struct CountingWriteTransaction {
-        inner: Box<dyn BackendWriteTransaction + Send + Sync + 'static>,
-        write_batches: Arc<AtomicUsize>,
-    }
 
-    #[async_trait]
-    impl BackendReadTransaction for CountingWriteTransaction {
-        async fn get_values(
-            &mut self,
-            request: BackendKvGetRequest,
-        ) -> Result<BackendKvValueBatch, LixError> {
-            self.inner.get_values(request).await
+        fn begin_write(&self, opts: StorageWriteOptions) -> Result<Self::Write<'_>, BackendError> {
+            Ok(CountingWrite {
+                inner: self.inner.begin_write(opts)?,
+                write_batches: Arc::clone(&self.write_batches),
+            })
         }
 
-        async fn exists_many(
-            &mut self,
-            request: BackendKvGetRequest,
-        ) -> Result<BackendKvExistsBatch, LixError> {
-            self.inner.exists_many(request).await
+        fn durable_write_lock(&self) -> DurableWriteLock {
+            self.inner.durable_write_lock()
         }
+    }
 
-        async fn scan_keys(
-            &mut self,
-            request: BackendKvScanRequest,
-        ) -> Result<BackendKvKeyPage, LixError> {
-            self.inner.scan_keys(request).await
-        }
+    struct CountingWrite {
+        inner: InMemoryStorageWrite,
+        write_batches: Arc<AtomicUsize>,
+    }
 
-        async fn scan_values(
-            &mut self,
-            request: BackendKvScanRequest,
-        ) -> Result<BackendKvValuePage, LixError> {
-            self.inner.scan_values(request).await
+    impl BackendWrite for CountingWrite {
+        fn put_many(&mut self, entries: PutBatch) -> Result<(), BackendError> {
+            self.inner.put_many(entries)
         }
 
-        async fn scan_entries(
-            &mut self,
-            request: BackendKvScanRequest,
-        ) -> Result<BackendKvEntryPage, LixError> {
-            self.inner.scan_entries(request).await
+        fn delete_many(&mut self, keys: &[StorageKey]) -> Result<(), BackendError> {
+            self.inner.delete_many(keys)
         }
 
-        async fn rollback(self: Box<Self>) -> Result<(), LixError> {
-            let Self { inner, .. } = *self;
-            inner.rollback().await
+        fn delete_range(&mut self, range: KeyRange) -> Result<(), BackendError> {
+            self.inner.delete_range(range)
         }
-    }
 
-    #[async_trait]
-    impl BackendWriteTransaction for CountingWriteTransaction {
-        async fn write_kv_batch(
-            &mut self,
-            batch: BackendKvWriteBatch,
-        ) -> Result<BackendKvWriteStats, LixError> {
+        fn commit(self) -> Result<CommitResult, BackendError> {
             self.write_batches.fetch_add(1, Ordering::SeqCst);
-            self.inner.write_kv_batch(batch).await
+            self.inner.commit()
         }
 
-        async fn commit(self: Box<Self>) -> Result<(), LixError> {
-            let Self { inner, .. } = *self;
-            inner.commit().await
+        fn rollback(self) -> Result<(), BackendError> {
+            self.inner.rollback()
         }
     }
 }