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

package/dist-engine-src/src/session/merge/{version.rs → branch.rs}

@@ -1,11 +1,10 @@
 use serde_json::{json, Value as JsonValue};
 
-use crate::transaction::types::TransactionWrite;
-use crate::version::{VersionLifecycle, VersionOperation, VersionReferenceRole};
+use crate::branch::{BranchLifecycle, BranchOperation, BranchReferenceRole};
+use crate::storage::StorageBackend;
 use crate::LixError;
 
 use super::analysis::{analyze, MergeCommits, MergeOutcome};
-use super::apply::adopted_changes_from_merge_plan;
 use super::conflicts::{
     MergeConflict as AnalysisMergeConflict,
     MergeConflictChangeKind as AnalysisMergeConflictChangeKind,
@@ -13,28 +12,30 @@ use super::conflicts::{
 };
 use super::stats::MergeStats;
 use crate::session::context::SessionContext;
+use crate::tracked_state::TrackedStateMergePick;
+use crate::transaction::types::StagedCommitChangeRef;
 
-/// Options for merging another version into this session's active version.
+/// Options for merging another branch into this session's active branch.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct MergeVersionOptions {
-    /// Version whose changes should be merged into the active session version.
-    pub source_version_id: String,
+pub struct MergeBranchOptions {
+    /// Branch whose changes should be merged into the active session branch.
+    pub source_branch_id: String,
 }
 
-/// Options for previewing a merge from another version into this session's
-/// active version.
+/// Options for previewing a merge from another branch into this session's
+/// active branch.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct MergeVersionPreviewOptions {
-    /// Version whose changes would be merged into the active session version.
-    pub source_version_id: String,
+pub struct MergeBranchPreviewOptions {
+    /// Branch whose changes would be merged into the active session branch.
+    pub source_branch_id: String,
 }
 
-/// Receipt returned after merging a version.
+/// Receipt returned after merging a branch.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct MergeVersionReceipt {
-    pub outcome: MergeVersionOutcome,
-    pub target_version_id: String,
-    pub source_version_id: String,
+pub struct MergeBranchReceipt {
+    pub outcome: MergeBranchOutcome,
+    pub target_branch_id: String,
+    pub source_branch_id: String,
     pub base_commit_id: String,
     pub target_head_before_commit_id: String,
     pub source_head_before_commit_id: String,
@@ -52,10 +53,10 @@ pub struct MergeChangeStats {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct MergeVersionPreview {
-    pub outcome: MergeVersionOutcome,
-    pub target_version_id: String,
-    pub source_version_id: String,
+pub struct MergeBranchPreview {
+    pub outcome: MergeBranchOutcome,
+    pub target_branch_id: String,
+    pub source_branch_id: String,
     pub base_commit_id: String,
     pub target_head_commit_id: String,
     pub source_head_commit_id: String,
@@ -67,7 +68,7 @@ pub struct MergeVersionPreview {
 pub struct MergeConflict {
     pub kind: MergeConflictKind,
     pub schema_key: String,
-    pub entity_id: JsonValue,
+    pub entity_pk: JsonValue,
     pub file_id: Option<String>,
     pub target: MergeConflictSide,
     pub source: MergeConflictSide,
@@ -93,43 +94,48 @@ pub enum MergeConflictChangeKind {
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum MergeVersionOutcome {
+pub enum MergeBranchOutcome {
     AlreadyUpToDate,
     FastForward,
     MergeCommitted,
 }
 
-impl SessionContext {
-    /// Previews merging `source_version_id` into this session's active version
+impl<B> SessionContext<B>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    /// Previews merging `source_branch_id` into this session's active branch
     /// without advancing refs, staging changes, or creating commits.
-    pub async fn merge_version_preview(
+    pub async fn merge_branch_preview(
         &self,
-        options: MergeVersionPreviewOptions,
-    ) -> Result<MergeVersionPreview, LixError> {
-        let source_version_id = options.source_version_id;
+        options: MergeBranchPreviewOptions,
+    ) -> Result<MergeBranchPreview, LixError> {
+        let source_branch_id = options.source_branch_id;
 
         self.with_write_transaction(|transaction| {
             Box::pin(async move {
-                let active_version_id = transaction.active_version_id().to_string();
-                if source_version_id == active_version_id {
-                    return Err(LixError::invalid_self_merge(active_version_id));
+                let active_branch_id = transaction.active_branch_id().to_string();
+                if source_branch_id == active_branch_id {
+                    return Err(LixError::invalid_self_merge(active_branch_id));
                 }
 
                 let (target_head, source_head) = {
-                    let reader = transaction.version_ref_reader();
-                    let lifecycle = VersionLifecycle::new(&reader);
+                    let reader = transaction.branch_ref_reader();
+                    let lifecycle = BranchLifecycle::new(&reader);
                     let target_head = lifecycle
                         .require_existing_commit_id(
-                            &active_version_id,
-                            VersionOperation::MergeVersionPreview,
-                            VersionReferenceRole::Target,
+                            &active_branch_id,
+                            BranchOperation::MergeBranchPreview,
+                            BranchReferenceRole::Target,
                         )
                         .await?;
                     let source_head = lifecycle
                         .require_existing_commit_id(
-                            &source_version_id,
-                            VersionOperation::MergeVersionPreview,
-                            VersionReferenceRole::Source,
+                            &source_branch_id,
+                            BranchOperation::MergeBranchPreview,
+                            BranchReferenceRole::Source,
                         )
                         .await?;
                     (target_head, source_head)
@@ -154,8 +160,8 @@ impl SessionContext {
                 };
 
                 Ok(preview_from_analysis(
-                    &active_version_id,
-                    &source_version_id,
+                    &active_branch_id,
+                    &source_branch_id,
                     &analysis,
                 ))
             })
@@ -163,40 +169,40 @@ impl SessionContext {
         .await
     }
 
-    /// Merges `source_version_id` into this session's active version.
+    /// Merges `source_branch_id` into this session's active branch.
     ///
     /// The generated target commit keeps the previous target head as its first
     /// parent and records the source head as an additional parent, so the
-    /// commit graph preserves branch ancestry while tracked-state storage can
-    /// build the new root by applying source effects onto the target root.
-    pub async fn merge_version(
+    /// commit graph preserves branch ancestry while tracked-state storage
+    /// selects the planned source changes into the new target root.
+    pub async fn merge_branch(
         &self,
-        options: MergeVersionOptions,
-    ) -> Result<MergeVersionReceipt, LixError> {
-        let source_version_id = options.source_version_id;
+        options: MergeBranchOptions,
+    ) -> Result<MergeBranchReceipt, LixError> {
+        let source_branch_id = options.source_branch_id;
 
         self.with_write_transaction(|transaction| {
             Box::pin(async move {
-                let active_version_id = transaction.active_version_id().to_string();
-                if source_version_id == active_version_id {
-                    return Err(LixError::invalid_self_merge(active_version_id));
+                let active_branch_id = transaction.active_branch_id().to_string();
+                if source_branch_id == active_branch_id {
+                    return Err(LixError::invalid_self_merge(active_branch_id));
                 }
 
                 let (target_head, source_head) = {
-                    let reader = transaction.version_ref_reader();
-                    let lifecycle = VersionLifecycle::new(&reader);
+                    let reader = transaction.branch_ref_reader();
+                    let lifecycle = BranchLifecycle::new(&reader);
                     let target_head = lifecycle
                         .require_existing_commit_id(
-                            &active_version_id,
-                            VersionOperation::MergeVersion,
-                            VersionReferenceRole::Target,
+                            &active_branch_id,
+                            BranchOperation::MergeBranch,
+                            BranchReferenceRole::Target,
                         )
                         .await?;
                     let source_head = lifecycle
                         .require_existing_commit_id(
-                            &source_version_id,
-                            VersionOperation::MergeVersion,
-                            VersionReferenceRole::Source,
+                            &source_branch_id,
+                            BranchOperation::MergeBranch,
+                            BranchReferenceRole::Source,
                         )
                         .await?;
                     (target_head, source_head)
@@ -222,10 +228,10 @@ impl SessionContext {
                 };
 
                 if analysis.outcome == MergeOutcome::AlreadyUpToDate {
-                    return Ok(MergeVersionReceipt {
-                        outcome: MergeVersionOutcome::AlreadyUpToDate,
-                        target_version_id: active_version_id,
-                        source_version_id,
+                    return Ok(MergeBranchReceipt {
+                        outcome: MergeBranchOutcome::AlreadyUpToDate,
+                        target_branch_id: active_branch_id,
+                        source_branch_id,
                         base_commit_id: analysis.commits.base_commit_id,
                         target_head_after_commit_id: analysis.commits.target_commit_id.clone(),
                         target_head_before_commit_id: analysis.commits.target_commit_id,
@@ -237,13 +243,13 @@ impl SessionContext {
 
                 if analysis.outcome == MergeOutcome::FastForward {
                     transaction
-                        .advance_version_ref(&active_version_id, &analysis.commits.source_commit_id)
+                        .advance_branch_ref(&active_branch_id, &analysis.commits.source_commit_id)
                         .await?;
 
-                    return Ok(MergeVersionReceipt {
-                        outcome: MergeVersionOutcome::FastForward,
-                        target_version_id: active_version_id,
-                        source_version_id,
+                    return Ok(MergeBranchReceipt {
+                        outcome: MergeBranchOutcome::FastForward,
+                        target_branch_id: active_branch_id,
+                        source_branch_id,
                         base_commit_id: analysis.commits.base_commit_id,
                         target_head_before_commit_id: analysis.commits.target_commit_id,
                         source_head_before_commit_id: analysis.commits.source_commit_id.clone(),
@@ -267,72 +273,56 @@ impl SessionContext {
                     )?);
                 }
 
-                let adopted_changes =
-                    adopted_changes_from_merge_plan(merge_plan, &active_version_id);
-                if adopted_changes.is_empty() {
-                    let created_merge_commit_id =
-                        transaction.stage_empty_commit(active_version_id.clone())?;
-                    transaction.add_commit_parent(
-                        active_version_id.clone(),
-                        analysis.commits.source_commit_id.clone(),
-                    )?;
-                    return Ok(MergeVersionReceipt {
-                        outcome: MergeVersionOutcome::MergeCommitted,
-                        target_version_id: active_version_id,
-                        source_version_id,
-                        base_commit_id: analysis.commits.base_commit_id,
-                        target_head_after_commit_id: created_merge_commit_id.clone(),
-                        target_head_before_commit_id: analysis.commits.target_commit_id,
-                        source_head_before_commit_id: analysis.commits.source_commit_id,
-                        created_merge_commit_id: Some(created_merge_commit_id),
-                        change_stats: merge_change_stats_from_analysis(&analysis.stats),
-                    });
-                }
-
-                transaction
-                    .stage_write(TransactionWrite::AdoptedChanges {
-                        changes: adopted_changes,
-                    })
-                    .await?;
-                let created_merge_commit_id = transaction
-                    .staged_commit_id(&active_version_id)?
-                    .ok_or_else(|| {
-                        LixError::new(
-                            "LIX_ERROR_UNKNOWN",
-                            "merge_version staged tracked rows without a commit id",
-                        )
-                    })?;
-                transaction.add_commit_parent(
-                    active_version_id.clone(),
+                let selected_changes = merge_plan
+                    .picks
+                    .iter()
+                    .map(selected_change_from_merge_pick)
+                    .collect::<Vec<_>>();
+                let created_merge_commit_id = transaction.stage_merge_commit(
+                    active_branch_id.clone(),
                     analysis.commits.source_commit_id.clone(),
+                    selected_changes,
                 )?;
-
-                Ok(MergeVersionReceipt {
-                    outcome: MergeVersionOutcome::MergeCommitted,
-                    target_version_id: active_version_id,
-                    source_version_id,
+                return Ok(MergeBranchReceipt {
+                    outcome: MergeBranchOutcome::MergeCommitted,
+                    target_branch_id: active_branch_id,
+                    source_branch_id,
                     base_commit_id: analysis.commits.base_commit_id,
+                    target_head_after_commit_id: created_merge_commit_id.clone(),
                     target_head_before_commit_id: analysis.commits.target_commit_id,
                     source_head_before_commit_id: analysis.commits.source_commit_id,
-                    created_merge_commit_id: Some(created_merge_commit_id.clone()),
-                    target_head_after_commit_id: created_merge_commit_id,
+                    created_merge_commit_id: Some(created_merge_commit_id),
                     change_stats: merge_change_stats_from_analysis(&analysis.stats),
-                })
+                });
             })
         })
         .await
     }
 }
 
+fn selected_change_from_merge_pick(pick: &TrackedStateMergePick) -> StagedCommitChangeRef {
+    StagedCommitChangeRef {
+        schema_key: pick.selected_row.schema_key.clone(),
+        file_id: pick.selected_row.file_id.clone(),
+        entity_pk: pick.selected_row.entity_pk.clone(),
+        change_id: pick.change_id.clone(),
+        snapshot_ref: pick.selected_row.snapshot_ref,
+        metadata_ref: pick.selected_row.metadata_ref,
+        deleted: pick.selected_row.deleted,
+        created_at: pick.selected_row.created_at.clone(),
+        updated_at: pick.selected_row.updated_at.clone(),
+    }
+}
+
 fn preview_from_analysis(
-    target_version_id: &str,
-    source_version_id: &str,
+    target_branch_id: &str,
+    source_branch_id: &str,
     analysis: &super::analysis::MergeAnalysis,
-) -> MergeVersionPreview {
-    MergeVersionPreview {
-        outcome: merge_version_outcome_from_analysis(analysis.outcome),
-        target_version_id: target_version_id.to_string(),
-        source_version_id: source_version_id.to_string(),
+) -> MergeBranchPreview {
+    MergeBranchPreview {
+        outcome: merge_branch_outcome_from_analysis(analysis.outcome),
+        target_branch_id: target_branch_id.to_string(),
+        source_branch_id: source_branch_id.to_string(),
         base_commit_id: analysis.commits.base_commit_id.clone(),
         target_head_commit_id: analysis.commits.target_commit_id.clone(),
         source_head_commit_id: analysis.commits.source_commit_id.clone(),
@@ -345,11 +335,11 @@ fn preview_from_analysis(
     }
 }
 
-fn merge_version_outcome_from_analysis(outcome: MergeOutcome) -> MergeVersionOutcome {
+fn merge_branch_outcome_from_analysis(outcome: MergeOutcome) -> MergeBranchOutcome {
     match outcome {
-        MergeOutcome::AlreadyUpToDate => MergeVersionOutcome::AlreadyUpToDate,
-        MergeOutcome::FastForward => MergeVersionOutcome::FastForward,
-        MergeOutcome::MergeCommitted => MergeVersionOutcome::MergeCommitted,
+        MergeOutcome::AlreadyUpToDate => MergeBranchOutcome::AlreadyUpToDate,
+        MergeOutcome::FastForward => MergeBranchOutcome::FastForward,
+        MergeOutcome::MergeCommitted => MergeBranchOutcome::MergeCommitted,
     }
 }
 
@@ -368,7 +358,7 @@ fn merge_conflict_from_analysis(conflict: &AnalysisMergeConflict) -> MergeConfli
             AnalysisMergeConflictKind::SameEntityChanged => MergeConflictKind::SameEntityChanged,
         },
         schema_key: conflict.schema_key.clone(),
-        entity_id: conflict.entity_id.clone(),
+        entity_pk: conflict.entity_pk.clone(),
         file_id: conflict.file_id.clone(),
         target: merge_conflict_side_from_analysis(&conflict.target),
         source: merge_conflict_side_from_analysis(&conflict.source),
@@ -391,9 +381,9 @@ fn merge_conflict_error(conflicts: &[MergeConflict]) -> Result<LixError, LixErro
     let conflict_count = conflicts.len();
     Ok(LixError::new(
         LixError::CODE_MERGE_CONFLICT,
-        format!("merge_version found {conflict_count} tracked-state conflict(s)"),
+        format!("merge_branch found {conflict_count} tracked-state conflict(s)"),
     )
-    .with_hint("Resolve the conflicting entities in the target version, then retry the merge.")
+    .with_hint("Resolve the conflicting entities in the target branch, then retry the merge.")
     .with_details(json!({
         "conflicts": conflicts.iter()
             .map(merge_conflict_details)
@@ -407,7 +397,7 @@ fn merge_conflict_details(conflict: &MergeConflict) -> serde_json::Value {
             MergeConflictKind::SameEntityChanged => "sameEntityChanged",
         },
         "schemaKey": conflict.schema_key,
-        "entityId": conflict.entity_id,
+        "entityPk": conflict.entity_pk,
         "fileId": conflict.file_id,
         "target": merge_conflict_side_details(&conflict.target),
         "source": merge_conflict_side_details(&conflict.source),

package/dist-engine-src/src/session/merge/conflicts.rs

@@ -8,7 +8,7 @@ use serde_json::Value as JsonValue;
 pub(crate) struct MergeConflict {
     pub(crate) kind: MergeConflictKind,
     pub(crate) schema_key: String,
-    pub(crate) entity_id: JsonValue,
+    pub(crate) entity_pk: JsonValue,
     pub(crate) file_id: Option<String>,
     pub(crate) target: MergeConflictSide,
     pub(crate) source: MergeConflictSide,
@@ -43,7 +43,7 @@ fn conflict_from_tracked(conflict: &TrackedStateMergeConflict) -> Result<MergeCo
     Ok(MergeConflict {
         kind: MergeConflictKind::SameEntityChanged,
         schema_key: conflict.identity.schema_key.clone(),
-        entity_id: conflict.identity.entity_id.as_json_array_value()?,
+        entity_pk: conflict.identity.entity_pk.as_json_array_value()?,
         file_id: conflict.identity.file_id.clone(),
         target: conflict_side_from_diff_entry(&conflict.target),
         source: conflict_side_from_diff_entry(&conflict.source),

package/dist-engine-src/src/session/merge/mod.rs

@@ -1,11 +1,10 @@
 mod analysis;
-mod apply;
+mod branch;
 mod conflicts;
 mod stats;
-mod version;
 
-pub use version::{
-    MergeChangeStats, MergeConflict, MergeConflictChangeKind, MergeConflictKind, MergeConflictSide,
-    MergeVersionOptions, MergeVersionOutcome, MergeVersionPreview, MergeVersionPreviewOptions,
-    MergeVersionReceipt,
+pub use branch::{
+    MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchPreviewOptions,
+    MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictChangeKind,
+    MergeConflictKind, MergeConflictSide,
 };

package/dist-engine-src/src/session/merge/stats.rs

@@ -1,5 +1,5 @@
 use crate::tracked_state::{
-    TrackedStateDiff, TrackedStateDiffKind, TrackedStateMergePatch, TrackedStateMergePlan,
+    TrackedStateDiff, TrackedStateDiffKind, TrackedStateMergePick, TrackedStateMergePlan,
 };
 use crate::LixError;
 
@@ -24,8 +24,8 @@ pub(crate) fn stats_from_plan(
     source_diff: &TrackedStateDiff,
 ) -> Result<MergeStats, LixError> {
     let mut stats = MergeStats::default();
-    for patch in &plan.patches {
-        let identity = patch_identity(patch);
+    for pick in &plan.picks {
+        let identity = pick_identity(pick);
         let Some(entry) = source_diff
             .entries
             .iter()
@@ -34,9 +34,9 @@ pub(crate) fn stats_from_plan(
             return Err(LixError::new(
                 "LIX_ERROR_UNKNOWN",
                 format!(
-                    "merge analysis could not find source diff entry for adopted schema '{}' entity '{}'",
+                    "merge analysis could not find source diff entry for source schema '{}' entity '{}'",
                     identity.schema_key,
-                    identity.entity_id.as_json_array_text()?
+                    identity.entity_pk.as_json_array_text()?
                 ),
             ));
         };
@@ -56,10 +56,6 @@ impl MergeStats {
     }
 }
 
-fn patch_identity(
-    patch: &TrackedStateMergePatch,
-) -> &crate::tracked_state::TrackedStateDiffIdentity {
-    match patch {
-        TrackedStateMergePatch::Adopt { identity, .. } => identity,
-    }
+fn pick_identity(pick: &TrackedStateMergePick) -> &crate::tracked_state::TrackedStateDiffIdentity {
+    &pick.identity
 }

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

@@ -2,26 +2,29 @@
 //!
 //! Transaction invariant: a session has one execution lease. Parent-handle
 //! calls use it for implicit single-statement execution; explicit transactions
-//! hold it until commit or rollback. Session APIs must not open `Transaction`
-//! directly or use session-level read helpers inside write flows.
+//! hold it until commit or rollback. Session feature submodules should enter
+//! write flows through the centralized session helpers rather than opening
+//! `Transaction` directly or using session-level read helpers inside writes.
+//!
+//! MVP boundary: session close can cancel queued or pre-boundary writes until
+//! the durable commit point-of-no-return. After that point, close waits for
+//! commit completion. Durability itself is the backend's responsibility.
 
 mod context;
-mod create_version;
+mod create_branch;
 mod execute;
 mod merge;
-#[cfg(feature = "storage-benches")]
-pub mod optimization9_sql2_bench;
-mod switch_version;
+mod switch_branch;
 mod transaction;
 
 pub use context::SessionContext;
-pub(crate) use context::{SessionMode, WORKSPACE_VERSION_KEY};
-pub use create_version::{CreateVersionOptions, CreateVersionReceipt};
+pub(crate) use context::{SessionMode, WORKSPACE_BRANCH_KEY};
+pub use create_branch::{CreateBranchOptions, CreateBranchReceipt};
 pub use execute::{ExecuteResult, Row, RowRef, TryFromValue};
 pub use merge::{
-    MergeChangeStats, MergeConflict, MergeConflictChangeKind, MergeConflictKind, MergeConflictSide,
-    MergeVersionOptions, MergeVersionOutcome, MergeVersionPreview, MergeVersionPreviewOptions,
-    MergeVersionReceipt,
+    MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchPreviewOptions,
+    MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictChangeKind,
+    MergeConflictKind, MergeConflictSide,
 };
-pub use switch_version::{SwitchVersionOptions, SwitchVersionReceipt};
+pub use switch_branch::{SwitchBranchOptions, SwitchBranchReceipt};
 pub use transaction::SessionTransaction;

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

@@ -0,0 +1,113 @@
+use std::sync::Arc;
+
+use serde_json::json;
+
+use crate::branch::{BranchLifecycle, BranchOperation, BranchReferenceRole};
+use crate::storage::StorageBackend;
+use crate::transaction::types::{TransactionJson, TransactionWriteRow};
+use crate::LixError;
+use crate::GLOBAL_BRANCH_ID;
+
+use super::context::{SessionContext, SessionMode, WORKSPACE_BRANCH_KEY};
+
+const KEY_VALUE_SCHEMA_KEY: &str = "lix_key_value";
+
+/// Options for switching a session to another branch.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SwitchBranchOptions {
+    pub branch_id: String,
+}
+
+/// Receipt returned after switching to another branch.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SwitchBranchReceipt {
+    pub branch_id: String,
+}
+
+impl<B> SessionContext<B>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    /// Switches the session's active branch selector.
+    ///
+    /// Pinned sessions switch in memory and return a new pinned session.
+    /// Workspace sessions update the shared workspace selector so other
+    /// workspace sessions observe the new active branch on their next use.
+    pub async fn switch_branch(
+        &self,
+        options: SwitchBranchOptions,
+    ) -> Result<(SessionContext<B>, SwitchBranchReceipt), LixError> {
+        let branch_id = options.branch_id;
+        let receipt_branch_id = branch_id.clone();
+        let current_mode = self.mode.clone();
+        let next_mode = self
+            .with_write_transaction(|transaction| {
+                Box::pin(async move {
+                    {
+                        let reader = transaction.branch_ref_reader();
+                        BranchLifecycle::new(&reader)
+                            .require_existing_commit_id(
+                                &branch_id,
+                                BranchOperation::SwitchBranch,
+                                BranchReferenceRole::Target,
+                            )
+                            .await?
+                    };
+
+                    match current_mode {
+                        SessionMode::Pinned { .. } => Ok(SessionMode::Pinned {
+                            branch_id: branch_id.clone(),
+                        }),
+                        SessionMode::Workspace => {
+                            transaction
+                                .stage_rows(vec![workspace_branch_stage_row(&branch_id)?])
+                                .await?;
+                            Ok(SessionMode::Workspace)
+                        }
+                    }
+                })
+            })
+            .await?;
+
+        let session = SessionContext::new_with_transaction_manager(
+            next_mode,
+            self.storage.clone(),
+            Arc::clone(&self.live_state),
+            Arc::clone(&self.tracked_state),
+            Arc::clone(&self.binary_cas),
+            Arc::clone(&self.branch_ctx),
+            Arc::clone(&self.catalog_context),
+            self.write_lock.clone(),
+            self.transaction_manager(),
+        );
+        Ok((
+            session,
+            SwitchBranchReceipt {
+                branch_id: receipt_branch_id,
+            },
+        ))
+    }
+}
+
+fn workspace_branch_stage_row(branch_id: &str) -> Result<TransactionWriteRow, LixError> {
+    Ok(TransactionWriteRow {
+        entity_pk: Some(crate::entity_pk::EntityPk::single(WORKSPACE_BRANCH_KEY)),
+        schema_key: KEY_VALUE_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot: Some(TransactionJson::from_value_unchecked(json!({
+            "key": WORKSPACE_BRANCH_KEY,
+            "value": branch_id,
+        }))),
+        metadata: None,
+        origin: None,
+        created_at: None,
+        updated_at: None,
+        global: true,
+        change_id: None,
+        commit_id: None,
+        untracked: true,
+        branch_id: GLOBAL_BRANCH_ID.to_string(),
+    })
+}