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

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

@@ -1,31 +1,31 @@
 use std::sync::Arc;
 
-use crate::storage::{StorageReader, StorageWriteSet};
+use crate::storage::{StorageRead, StorageWriteSet};
 use crate::untracked_state::{UntrackedStateContext, UntrackedStateRow};
 
-use super::refs::VersionRefContext;
-use super::VersionRefReader;
+use super::refs::BranchRefContext;
+use super::BranchRefReader;
 
-/// Aggregate entrypoint for version-domain services.
+/// Aggregate entrypoint for branch-domain services.
 ///
 /// Today this owns the moving-ref subsystem. Descriptor helpers are re-exported
-/// by `version`; future version APIs can grow here without making session or
+/// by `branch`; future branch APIs can grow here without making session or
 /// SQL code depend directly on ref storage details.
-pub(crate) struct VersionContext {
-    refs: Arc<VersionRefContext>,
+pub(crate) struct BranchContext {
+    refs: Arc<BranchRefContext>,
 }
 
-impl VersionContext {
+impl BranchContext {
     pub(crate) fn new(untracked_state: Arc<UntrackedStateContext>) -> Self {
         Self {
-            refs: Arc::new(VersionRefContext::new(untracked_state)),
+            refs: Arc::new(BranchRefContext::new(untracked_state)),
         }
     }
 
-    /// Creates a version-ref reader over a caller-provided KV store.
-    pub(crate) fn ref_reader<S>(&self, store: S) -> impl VersionRefReader
+    /// Creates a branch-ref reader over a caller-provided KV store.
+    pub(crate) fn ref_reader<S>(&self, store: S) -> impl BranchRefReader
     where
-        S: StorageReader + Send,
+        S: StorageRead + Send + Sync,
     {
         self.refs.reader(store)
     }

package/dist-engine-src/src/branch/lifecycle.rs

@@ -0,0 +1,221 @@
+use crate::commit_graph::{CommitGraphCommit, CommitGraphReader};
+use crate::common::validate_non_empty_identity_value;
+use crate::LixError;
+
+use super::{BranchHead, BranchRefReader};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum BranchOperation {
+    CreateBranch,
+    SwitchBranch,
+    MergeBranch,
+    MergeBranchPreview,
+    LoadWorkspaceSelector,
+}
+
+impl BranchOperation {
+    pub(crate) fn label(self) -> &'static str {
+        match self {
+            Self::CreateBranch => "create_branch",
+            Self::SwitchBranch => "switch_branch",
+            Self::MergeBranch => "merge_branch",
+            Self::MergeBranchPreview => "merge_branch_preview",
+            Self::LoadWorkspaceSelector => "load_workspace_branch_id",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum BranchReferenceRole {
+    Source,
+    Target,
+    WorkspaceSelector,
+    CommitSource,
+}
+
+impl BranchReferenceRole {
+    pub(crate) fn label(self) -> &'static str {
+        match self {
+            Self::Source => "source",
+            Self::Target => "target",
+            Self::WorkspaceSelector => "workspace_selector",
+            Self::CommitSource => "commit_source",
+        }
+    }
+}
+
+/// Shared domain service for resolving public branch references.
+///
+/// Built-in branch schemas describe row shape. This service owns semantic
+/// ref validation: non-empty ids, global sentinel handling, and missing refs.
+pub(crate) struct BranchLifecycle<'a> {
+    refs: &'a dyn BranchRefReader,
+}
+
+impl<'a> BranchLifecycle<'a> {
+    pub(crate) fn new(refs: &'a dyn BranchRefReader) -> Self {
+        Self { refs }
+    }
+
+    pub(crate) fn require_non_empty_id(
+        branch_id: &str,
+        operation: BranchOperation,
+        role: BranchReferenceRole,
+    ) -> Result<(), LixError> {
+        require_non_empty_public_id("branch_id", branch_id, operation, role)
+    }
+
+    pub(crate) async fn require_existing_commit(
+        commit_graph: &mut dyn CommitGraphReader,
+        commit_id: &str,
+        operation: BranchOperation,
+        role: BranchReferenceRole,
+    ) -> Result<CommitGraphCommit, LixError> {
+        require_non_empty_public_id("commit_id", commit_id, operation, role)?;
+        commit_graph
+            .load_commit(commit_id)
+            .await?
+            .ok_or_else(|| LixError::commit_not_found(commit_id, operation.label(), role.label()))
+    }
+
+    pub(crate) async fn require_existing_ref(
+        &self,
+        branch_id: &str,
+        operation: BranchOperation,
+        role: BranchReferenceRole,
+    ) -> Result<BranchHead, LixError> {
+        Self::require_non_empty_id(branch_id, operation, role)?;
+        self.require_existing_stored_ref(branch_id, operation, role)
+            .await
+    }
+
+    pub(crate) async fn require_existing_commit_id(
+        &self,
+        branch_id: &str,
+        operation: BranchOperation,
+        role: BranchReferenceRole,
+    ) -> Result<String, LixError> {
+        Ok(self
+            .require_existing_ref(branch_id, operation, role)
+            .await?
+            .commit_id)
+    }
+
+    async fn require_existing_stored_ref(
+        &self,
+        branch_id: &str,
+        operation: BranchOperation,
+        role: BranchReferenceRole,
+    ) -> Result<BranchHead, LixError> {
+        self.refs
+            .load_head(branch_id)
+            .await?
+            .ok_or_else(|| LixError::branch_not_found(branch_id, operation.label(), role.label()))
+    }
+}
+
+fn require_non_empty_public_id(
+    label: &str,
+    value: &str,
+    operation: BranchOperation,
+    role: BranchReferenceRole,
+) -> Result<(), LixError> {
+    validate_non_empty_identity_value(label, value)
+        .map(|_| ())
+        .map_err(|_| {
+            LixError::new(
+                LixError::CODE_INVALID_PARAM,
+                format!(
+                    "{} {} {label} must be non-empty",
+                    operation.label(),
+                    role.label()
+                ),
+            )
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use async_trait::async_trait;
+
+    use super::*;
+
+    #[tokio::test]
+    async fn require_existing_ref_returns_head() {
+        let reader = RowsBranchRefReader::new(vec![BranchHead {
+            branch_id: "branch-a".to_string(),
+            commit_id: "commit-a".to_string(),
+        }]);
+        let lifecycle = BranchLifecycle::new(&reader);
+
+        let head = lifecycle
+            .require_existing_ref(
+                "branch-a",
+                BranchOperation::SwitchBranch,
+                BranchReferenceRole::Target,
+            )
+            .await
+            .expect("branch should resolve");
+
+        assert_eq!(head.commit_id, "commit-a");
+    }
+
+    #[tokio::test]
+    async fn require_existing_ref_rejects_empty_id_as_invalid_param() {
+        let reader = RowsBranchRefReader::new(Vec::new());
+        let lifecycle = BranchLifecycle::new(&reader);
+
+        let error = lifecycle
+            .require_existing_ref(
+                "",
+                BranchOperation::SwitchBranch,
+                BranchReferenceRole::Target,
+            )
+            .await
+            .expect_err("empty branch id should be rejected before lookup");
+
+        assert_eq!(error.code, LixError::CODE_INVALID_PARAM);
+    }
+
+    #[tokio::test]
+    async fn require_existing_ref_reports_missing_branch() {
+        let reader = RowsBranchRefReader::new(Vec::new());
+        let lifecycle = BranchLifecycle::new(&reader);
+
+        let error = lifecycle
+            .require_existing_ref(
+                "missing",
+                BranchOperation::SwitchBranch,
+                BranchReferenceRole::Target,
+            )
+            .await
+            .expect_err("missing branch should be rejected");
+
+        assert_eq!(error.code, LixError::CODE_BRANCH_NOT_FOUND);
+    }
+
+    struct RowsBranchRefReader {
+        heads: Vec<BranchHead>,
+    }
+
+    impl RowsBranchRefReader {
+        fn new(heads: Vec<BranchHead>) -> Self {
+            Self { heads }
+        }
+    }
+
+    #[async_trait]
+    impl BranchRefReader for RowsBranchRefReader {
+        async fn load_head(&self, branch_id: &str) -> Result<Option<BranchHead>, LixError> {
+            Ok(self
+                .heads
+                .iter()
+                .find(|head| head.branch_id == branch_id)
+                .cloned())
+        }
+
+        async fn scan_heads(&self) -> Result<Vec<BranchHead>, LixError> {
+            Ok(self.heads.clone())
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+mod context;
+mod lifecycle;
+mod refs;
+mod stage_rows;
+mod types;
+
+pub(crate) use context::BranchContext;
+pub(crate) use lifecycle::{BranchLifecycle, BranchOperation, BranchReferenceRole};
+pub(crate) use stage_rows::{
+    branch_descriptor_stage_row, branch_descriptor_tombstone_row, branch_ref_stage_row,
+    branch_ref_tombstone_row, BRANCH_DESCRIPTOR_SCHEMA_KEY, BRANCH_REF_SCHEMA_KEY,
+};
+pub(crate) use types::{BranchHead, BranchRefReader};

package/dist-engine-src/src/branch/refs.rs

@@ -0,0 +1,321 @@
+use std::sync::Arc;
+
+use tokio::sync::Mutex;
+
+use crate::branch::BRANCH_REF_SCHEMA_KEY;
+use crate::branch::{BranchHead, BranchRefReader};
+use crate::entity_pk::EntityPk;
+use crate::storage::{StorageRead, StorageWriteSet};
+use crate::untracked_state::{
+    MaterializedUntrackedStateRow, UntrackedStateContext, UntrackedStateFilter, UntrackedStateRow,
+    UntrackedStateRowRequest, UntrackedStateScanRequest,
+};
+use crate::GLOBAL_BRANCH_ID;
+use crate::{LixError, NullableKeyFilter};
+
+/// Typed access to moving branch heads stored in untracked state.
+///
+/// Branch refs are one of the inputs used by live_state visibility, so this
+/// context deliberately bypasses live_state and reads the underlying untracked
+/// rows directly. That keeps the dependency acyclic:
+/// untracked_state -> branch_ref -> live_state.
+pub(super) struct BranchRefContext {
+    untracked_state: Arc<UntrackedStateContext>,
+}
+
+impl BranchRefContext {
+    pub(super) fn new(untracked_state: Arc<UntrackedStateContext>) -> Self {
+        Self { untracked_state }
+    }
+
+    /// Creates a branch-ref reader over a caller-provided KV store.
+    pub(super) fn reader<S>(&self, store: S) -> BranchRefStoreReader<S>
+    where
+        S: StorageRead + Send + Sync,
+    {
+        BranchRefStoreReader {
+            untracked_state: Arc::clone(&self.untracked_state),
+            store: Mutex::new(store),
+        }
+    }
+
+    /// Creates a branch-ref writer over a transaction-local storage write set.
+    pub(super) fn writer<'a>(&self, writes: &'a mut StorageWriteSet) -> BranchRefWriter<'a> {
+        BranchRefWriter {
+            untracked_state: Arc::clone(&self.untracked_state),
+            writes,
+        }
+    }
+}
+
+/// Read side for branch heads.
+pub(super) struct BranchRefStoreReader<S>
+where
+    S: StorageRead + Send + Sync,
+{
+    untracked_state: Arc<UntrackedStateContext>,
+    store: Mutex<S>,
+}
+
+impl<S> BranchRefStoreReader<S>
+where
+    S: StorageRead + Send + Sync,
+{
+    pub(crate) async fn load_head(&self, branch_id: &str) -> Result<Option<BranchHead>, LixError> {
+        let store = self.store.lock().await;
+        let Some(row) = self
+            .untracked_state
+            .reader(&*store)
+            .load_row(&UntrackedStateRowRequest {
+                schema_key: BRANCH_REF_SCHEMA_KEY.to_string(),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
+                entity_pk: EntityPk::single(branch_id),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await?
+        else {
+            return Ok(None);
+        };
+
+        decode_branch_head(branch_id, &row)
+    }
+
+    pub(crate) async fn load_head_commit_id(
+        &self,
+        branch_id: &str,
+    ) -> Result<Option<String>, LixError> {
+        Ok(self.load_head(branch_id).await?.map(|head| head.commit_id))
+    }
+
+    pub(crate) async fn scan_heads(&self) -> Result<Vec<BranchHead>, LixError> {
+        let store = self.store.lock().await;
+        let rows = self
+            .untracked_state
+            .reader(&*store)
+            .scan_rows(&UntrackedStateScanRequest {
+                filter: UntrackedStateFilter {
+                    schema_keys: vec![BRANCH_REF_SCHEMA_KEY.to_string()],
+                    branch_ids: vec![GLOBAL_BRANCH_ID.to_string()],
+                    ..UntrackedStateFilter::default()
+                },
+                ..UntrackedStateScanRequest::default()
+            })
+            .await?;
+        let mut heads = rows
+            .iter()
+            .map(|row| {
+                let branch_id = row.entity_pk.as_single_string_owned()?;
+                decode_branch_head(&branch_id, row)
+            })
+            .collect::<Result<Vec<_>, _>>()?
+            .into_iter()
+            .flatten()
+            .collect::<Vec<_>>();
+        heads.sort_by(|left, right| left.branch_id.cmp(&right.branch_id));
+        Ok(heads)
+    }
+}
+
+#[async_trait::async_trait]
+impl<S> BranchRefReader for BranchRefStoreReader<S>
+where
+    S: StorageRead + Send + Sync,
+{
+    async fn load_head(&self, branch_id: &str) -> Result<Option<BranchHead>, LixError> {
+        BranchRefStoreReader::load_head(self, branch_id).await
+    }
+
+    async fn load_head_commit_id(&self, branch_id: &str) -> Result<Option<String>, LixError> {
+        BranchRefStoreReader::load_head_commit_id(self, branch_id).await
+    }
+
+    async fn scan_heads(&self) -> Result<Vec<BranchHead>, LixError> {
+        BranchRefStoreReader::scan_heads(self).await
+    }
+}
+
+/// Write side for moving branch heads.
+pub(super) struct BranchRefWriter<'a> {
+    untracked_state: Arc<UntrackedStateContext>,
+    writes: &'a mut StorageWriteSet,
+}
+
+impl BranchRefWriter<'_> {
+    pub(crate) fn stage_rows(&mut self, rows: &[UntrackedStateRow]) -> Result<(), LixError> {
+        self.untracked_state
+            .writer(self.writes)
+            .stage_rows(rows.iter().map(|row| row.as_ref()))
+    }
+}
+
+fn decode_branch_head(
+    requested_branch_id: &str,
+    row: &MaterializedUntrackedStateRow,
+) -> Result<Option<BranchHead>, LixError> {
+    let Some(snapshot_content) = row.snapshot_content.as_deref() else {
+        return Ok(None);
+    };
+    let snapshot =
+        serde_json::from_str::<serde_json::Value>(snapshot_content).map_err(|error| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("engine branch-ref snapshot parse failed: {error}"),
+            )
+        })?;
+    let commit_id = snapshot
+        .get("commit_id")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("branch ref for branch '{requested_branch_id}' is missing commit_id"),
+            )
+        })?;
+    Ok(Some(BranchHead {
+        branch_id: requested_branch_id.to_string(),
+        commit_id: commit_id.to_string(),
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use crate::storage::{InMemoryStorageBackend, StorageReadOptions, StorageWriteOptions};
+    use crate::storage::{StorageContext, StorageWriteSet};
+    use crate::transaction::prepare_branch_ref_row;
+    use crate::untracked_state::{UntrackedStateContext, UntrackedStateRowRequest};
+
+    use super::*;
+
+    #[tokio::test]
+    async fn load_head_returns_none_when_missing() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let branch_ref = test_branch_ref();
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+
+        let head = branch_ref
+            .reader(read)
+            .load_head("missing-branch")
+            .await
+            .expect("missing branch ref should load cleanly");
+
+        assert_eq!(head, None);
+    }
+
+    #[tokio::test]
+    async fn advance_head_writes_untracked_global_ref() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let branch_ref = BranchRefContext::new(Arc::new(UntrackedStateContext::new()));
+
+        let mut writes = storage.new_write_set();
+        stage_branch_head(
+            &branch_ref,
+            &mut writes,
+            "branch-a",
+            "commit-a",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("branch head should advance");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("branch head should commit");
+
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let head = branch_ref
+            .reader(read)
+            .load_head("branch-a")
+            .await
+            .expect("branch head should load")
+            .expect("branch head should exist");
+        assert_eq!(head.branch_id, "branch-a");
+        assert_eq!(head.commit_id, "commit-a");
+
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut reader = UntrackedStateContext::new().reader(read);
+        let row = reader
+            .load_row(&UntrackedStateRowRequest {
+                schema_key: BRANCH_REF_SCHEMA_KEY.to_string(),
+                branch_id: GLOBAL_BRANCH_ID.to_string(),
+                entity_pk: crate::entity_pk::EntityPk::single("branch-a"),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await
+            .expect("branch-ref row should load")
+            .expect("branch-ref row should exist");
+        assert!(row.global);
+        assert_eq!(row.created_at, "2026-01-01T00:00:00Z");
+        assert_eq!(row.updated_at, "2026-01-01T00:00:00Z");
+    }
+
+    #[tokio::test]
+    async fn scan_heads_returns_sorted_branch_heads() {
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let branch_ref = test_branch_ref();
+
+        let mut writes = storage.new_write_set();
+        stage_branch_head(
+            &branch_ref,
+            &mut writes,
+            "branch-b",
+            "commit-b",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("branch-b should advance");
+        stage_branch_head(
+            &branch_ref,
+            &mut writes,
+            "branch-a",
+            "commit-a",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("branch-a should advance");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("branch heads should commit");
+
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let heads = branch_ref
+            .reader(read)
+            .scan_heads()
+            .await
+            .expect("heads should scan");
+
+        assert_eq!(
+            heads,
+            vec![
+                BranchHead {
+                    branch_id: "branch-a".to_string(),
+                    commit_id: "commit-a".to_string(),
+                },
+                BranchHead {
+                    branch_id: "branch-b".to_string(),
+                    commit_id: "commit-b".to_string(),
+                },
+            ]
+        );
+    }
+
+    fn test_branch_ref() -> BranchRefContext {
+        BranchRefContext::new(Arc::new(UntrackedStateContext::new()))
+    }
+
+    fn stage_branch_head(
+        branch_ref: &BranchRefContext,
+        writes: &mut StorageWriteSet,
+        branch_id: &str,
+        commit_id: &str,
+        timestamp: &str,
+    ) -> Result<(), LixError> {
+        let canonical_row = prepare_branch_ref_row(branch_id, commit_id, timestamp)?;
+        branch_ref.writer(writes).stage_rows(&[canonical_row.row])
+    }
+}

package/dist-engine-src/src/branch/stage_rows.rs

@@ -0,0 +1,67 @@
+use serde_json::json;
+
+use crate::entity_pk::EntityPk;
+use crate::transaction::types::{TransactionJson, TransactionWriteRow};
+use crate::GLOBAL_BRANCH_ID;
+
+pub(crate) const BRANCH_DESCRIPTOR_SCHEMA_KEY: &str = "lix_branch_descriptor";
+pub(crate) const BRANCH_REF_SCHEMA_KEY: &str = "lix_branch_ref";
+
+pub(crate) fn branch_descriptor_stage_row(
+    branch_id: &str,
+    name: &str,
+    hidden: bool,
+) -> TransactionWriteRow {
+    TransactionWriteRow {
+        entity_pk: Some(EntityPk::single(branch_id)),
+        schema_key: BRANCH_DESCRIPTOR_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot: Some(TransactionJson::from_value_unchecked(json!({
+            "id": branch_id,
+            "name": name,
+            "hidden": hidden,
+        }))),
+        metadata: None,
+        origin: None,
+        created_at: None,
+        updated_at: None,
+        global: true,
+        change_id: None,
+        commit_id: None,
+        untracked: false,
+        branch_id: GLOBAL_BRANCH_ID.to_string(),
+    }
+}
+
+pub(crate) fn branch_ref_stage_row(branch_id: &str, commit_id: &str) -> TransactionWriteRow {
+    TransactionWriteRow {
+        entity_pk: Some(EntityPk::single(branch_id)),
+        schema_key: BRANCH_REF_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot: Some(TransactionJson::from_value_unchecked(json!({
+            "id": branch_id,
+            "commit_id": commit_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(),
+    }
+}
+
+pub(crate) fn branch_descriptor_tombstone_row(branch_id: &str) -> TransactionWriteRow {
+    let mut row = branch_descriptor_stage_row(branch_id, "", false);
+    row.snapshot = None;
+    row
+}
+
+pub(crate) fn branch_ref_tombstone_row(branch_id: &str) -> TransactionWriteRow {
+    let mut row = branch_ref_stage_row(branch_id, "");
+    row.snapshot = None;
+    row
+}

package/dist-engine-src/src/branch/types.rs

@@ -0,0 +1,21 @@
+/// Current changelog head for a branch.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct BranchHead {
+    pub(crate) branch_id: String,
+    pub(crate) commit_id: String,
+}
+
+/// Typed reader for moving branch heads.
+#[async_trait::async_trait]
+pub(crate) trait BranchRefReader: Send + Sync {
+    async fn load_head(&self, branch_id: &str) -> Result<Option<BranchHead>, crate::LixError>;
+
+    async fn load_head_commit_id(
+        &self,
+        branch_id: &str,
+    ) -> Result<Option<String>, crate::LixError> {
+        Ok(self.load_head(branch_id).await?.map(|head| head.commit_id))
+    }
+
+    async fn scan_heads(&self) -> Result<Vec<BranchHead>, crate::LixError>;
+}