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

package/dist-engine-src/src/version/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::{VersionHead, VersionRefReader};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum VersionOperation {
+    CreateVersion,
+    SwitchVersion,
+    MergeVersion,
+    MergeVersionPreview,
+    LoadWorkspaceSelector,
+}
+
+impl VersionOperation {
+    pub(crate) fn label(self) -> &'static str {
+        match self {
+            Self::CreateVersion => "create_version",
+            Self::SwitchVersion => "switch_version",
+            Self::MergeVersion => "merge_version",
+            Self::MergeVersionPreview => "merge_version_preview",
+            Self::LoadWorkspaceSelector => "load_workspace_version_id",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum VersionReferenceRole {
+    Source,
+    Target,
+    WorkspaceSelector,
+    CommitSource,
+}
+
+impl VersionReferenceRole {
+    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 version references.
+///
+/// Built-in version schemas describe row shape. This service owns semantic
+/// ref validation: non-empty ids, global sentinel handling, and missing refs.
+pub(crate) struct VersionLifecycle<'a> {
+    refs: &'a dyn VersionRefReader,
+}
+
+impl<'a> VersionLifecycle<'a> {
+    pub(crate) fn new(refs: &'a dyn VersionRefReader) -> Self {
+        Self { refs }
+    }
+
+    pub(crate) fn require_non_empty_id(
+        version_id: &str,
+        operation: VersionOperation,
+        role: VersionReferenceRole,
+    ) -> Result<(), LixError> {
+        require_non_empty_public_id("version_id", version_id, operation, role)
+    }
+
+    pub(crate) async fn require_existing_commit(
+        commit_graph: &mut dyn CommitGraphReader,
+        commit_id: &str,
+        operation: VersionOperation,
+        role: VersionReferenceRole,
+    ) -> 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::version_not_found(commit_id, operation.label(), role.label()))
+    }
+
+    pub(crate) async fn require_existing_ref(
+        &self,
+        version_id: &str,
+        operation: VersionOperation,
+        role: VersionReferenceRole,
+    ) -> Result<VersionHead, LixError> {
+        Self::require_non_empty_id(version_id, operation, role)?;
+        self.require_existing_stored_ref(version_id, operation, role)
+            .await
+    }
+
+    pub(crate) async fn require_existing_commit_id(
+        &self,
+        version_id: &str,
+        operation: VersionOperation,
+        role: VersionReferenceRole,
+    ) -> Result<String, LixError> {
+        Ok(self
+            .require_existing_ref(version_id, operation, role)
+            .await?
+            .commit_id)
+    }
+
+    async fn require_existing_stored_ref(
+        &self,
+        version_id: &str,
+        operation: VersionOperation,
+        role: VersionReferenceRole,
+    ) -> Result<VersionHead, LixError> {
+        self.refs
+            .load_head(version_id)
+            .await?
+            .ok_or_else(|| LixError::version_not_found(version_id, operation.label(), role.label()))
+    }
+}
+
+fn require_non_empty_public_id(
+    label: &str,
+    value: &str,
+    operation: VersionOperation,
+    role: VersionReferenceRole,
+) -> 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 = RowsVersionRefReader::new(vec![VersionHead {
+            version_id: "version-a".to_string(),
+            commit_id: "commit-a".to_string(),
+        }]);
+        let lifecycle = VersionLifecycle::new(&reader);
+
+        let head = lifecycle
+            .require_existing_ref(
+                "version-a",
+                VersionOperation::SwitchVersion,
+                VersionReferenceRole::Target,
+            )
+            .await
+            .expect("version should resolve");
+
+        assert_eq!(head.commit_id, "commit-a");
+    }
+
+    #[tokio::test]
+    async fn require_existing_ref_rejects_empty_id_as_invalid_param() {
+        let reader = RowsVersionRefReader::new(Vec::new());
+        let lifecycle = VersionLifecycle::new(&reader);
+
+        let error = lifecycle
+            .require_existing_ref(
+                "",
+                VersionOperation::SwitchVersion,
+                VersionReferenceRole::Target,
+            )
+            .await
+            .expect_err("empty version id should be rejected before lookup");
+
+        assert_eq!(error.code, LixError::CODE_INVALID_PARAM);
+    }
+
+    #[tokio::test]
+    async fn require_existing_ref_reports_missing_version() {
+        let reader = RowsVersionRefReader::new(Vec::new());
+        let lifecycle = VersionLifecycle::new(&reader);
+
+        let error = lifecycle
+            .require_existing_ref(
+                "missing",
+                VersionOperation::SwitchVersion,
+                VersionReferenceRole::Target,
+            )
+            .await
+            .expect_err("missing version should be rejected");
+
+        assert_eq!(error.code, LixError::CODE_VERSION_NOT_FOUND);
+    }
+
+    struct RowsVersionRefReader {
+        heads: Vec<VersionHead>,
+    }
+
+    impl RowsVersionRefReader {
+        fn new(heads: Vec<VersionHead>) -> Self {
+            Self { heads }
+        }
+    }
+
+    #[async_trait]
+    impl VersionRefReader for RowsVersionRefReader {
+        async fn load_head(&self, version_id: &str) -> Result<Option<VersionHead>, LixError> {
+            Ok(self
+                .heads
+                .iter()
+                .find(|head| head.version_id == version_id)
+                .cloned())
+        }
+
+        async fn scan_heads(&self) -> Result<Vec<VersionHead>, LixError> {
+            Ok(self.heads.clone())
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+mod context;
+mod lifecycle;
+mod refs;
+mod stage_rows;
+mod types;
+
+pub(crate) use context::VersionContext;
+pub(crate) use lifecycle::{VersionLifecycle, VersionOperation, VersionReferenceRole};
+pub(crate) use stage_rows::{
+    version_descriptor_stage_row, version_descriptor_tombstone_row, version_ref_stage_row,
+    version_ref_tombstone_row, VERSION_DESCRIPTOR_SCHEMA_KEY, VERSION_REF_SCHEMA_KEY,
+};
+pub(crate) use types::{VersionHead, VersionRefReader};

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

@@ -0,0 +1,330 @@
+use std::sync::Arc;
+
+use tokio::sync::Mutex;
+
+use crate::entity_identity::EntityIdentity;
+use crate::storage::{StorageReader, StorageWriteSet};
+use crate::untracked_state::{
+    MaterializedUntrackedStateRow, UntrackedStateContext, UntrackedStateFilter, UntrackedStateRow,
+    UntrackedStateRowRequest, UntrackedStateScanRequest,
+};
+use crate::version::VERSION_REF_SCHEMA_KEY;
+use crate::version::{VersionHead, VersionRefReader};
+use crate::GLOBAL_VERSION_ID;
+use crate::{LixError, NullableKeyFilter};
+
+/// Typed access to moving version heads stored in untracked state.
+///
+/// Version 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 -> version_ref -> live_state.
+pub(super) struct VersionRefContext {
+    untracked_state: Arc<UntrackedStateContext>,
+}
+
+impl VersionRefContext {
+    pub(super) fn new(untracked_state: Arc<UntrackedStateContext>) -> Self {
+        Self { untracked_state }
+    }
+
+    /// Creates a version-ref reader over a caller-provided KV store.
+    pub(super) fn reader<S>(&self, store: S) -> VersionRefStoreReader<S>
+    where
+        S: StorageReader,
+    {
+        VersionRefStoreReader {
+            untracked_state: Arc::clone(&self.untracked_state),
+            store: Mutex::new(store),
+        }
+    }
+
+    /// Creates a version-ref writer over a transaction-local storage write set.
+    pub(super) fn writer<'a>(&self, writes: &'a mut StorageWriteSet) -> VersionRefWriter<'a> {
+        VersionRefWriter {
+            untracked_state: Arc::clone(&self.untracked_state),
+            writes,
+        }
+    }
+}
+
+/// Read side for version heads.
+pub(super) struct VersionRefStoreReader<S>
+where
+    S: StorageReader,
+{
+    untracked_state: Arc<UntrackedStateContext>,
+    store: Mutex<S>,
+}
+
+impl<S> VersionRefStoreReader<S>
+where
+    S: StorageReader,
+{
+    pub(crate) async fn load_head(
+        &self,
+        version_id: &str,
+    ) -> Result<Option<VersionHead>, LixError> {
+        let mut store = self.store.lock().await;
+        let Some(row) = self
+            .untracked_state
+            .reader(&mut *store as &mut dyn StorageReader)
+            .load_row(&UntrackedStateRowRequest {
+                schema_key: VERSION_REF_SCHEMA_KEY.to_string(),
+                version_id: GLOBAL_VERSION_ID.to_string(),
+                entity_id: EntityIdentity::single(version_id),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await?
+        else {
+            return Ok(None);
+        };
+
+        decode_version_head(version_id, &row)
+    }
+
+    pub(crate) async fn load_head_commit_id(
+        &self,
+        version_id: &str,
+    ) -> Result<Option<String>, LixError> {
+        Ok(self.load_head(version_id).await?.map(|head| head.commit_id))
+    }
+
+    pub(crate) async fn scan_heads(&self) -> Result<Vec<VersionHead>, LixError> {
+        let mut store = self.store.lock().await;
+        let rows = self
+            .untracked_state
+            .reader(&mut *store as &mut dyn StorageReader)
+            .scan_rows(&UntrackedStateScanRequest {
+                filter: UntrackedStateFilter {
+                    schema_keys: vec![VERSION_REF_SCHEMA_KEY.to_string()],
+                    version_ids: vec![GLOBAL_VERSION_ID.to_string()],
+                    ..UntrackedStateFilter::default()
+                },
+                ..UntrackedStateScanRequest::default()
+            })
+            .await?;
+        let mut heads = rows
+            .iter()
+            .map(|row| {
+                let version_id = row.entity_id.as_single_string_owned()?;
+                decode_version_head(&version_id, row)
+            })
+            .collect::<Result<Vec<_>, _>>()?
+            .into_iter()
+            .flatten()
+            .collect::<Vec<_>>();
+        heads.sort_by(|left, right| left.version_id.cmp(&right.version_id));
+        Ok(heads)
+    }
+}
+
+#[async_trait::async_trait]
+impl<S> VersionRefReader for VersionRefStoreReader<S>
+where
+    S: StorageReader + Send,
+{
+    async fn load_head(&self, version_id: &str) -> Result<Option<VersionHead>, LixError> {
+        VersionRefStoreReader::load_head(self, version_id).await
+    }
+
+    async fn load_head_commit_id(&self, version_id: &str) -> Result<Option<String>, LixError> {
+        VersionRefStoreReader::load_head_commit_id(self, version_id).await
+    }
+
+    async fn scan_heads(&self) -> Result<Vec<VersionHead>, LixError> {
+        VersionRefStoreReader::scan_heads(self).await
+    }
+}
+
+/// Write side for moving version heads.
+pub(super) struct VersionRefWriter<'a> {
+    untracked_state: Arc<UntrackedStateContext>,
+    writes: &'a mut StorageWriteSet,
+}
+
+impl VersionRefWriter<'_> {
+    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_version_head(
+    requested_version_id: &str,
+    row: &MaterializedUntrackedStateRow,
+) -> Result<Option<VersionHead>, 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 version-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!("version ref for version '{requested_version_id}' is missing commit_id"),
+            )
+        })?;
+    Ok(Some(VersionHead {
+        version_id: requested_version_id.to_string(),
+        commit_id: commit_id.to_string(),
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use crate::backend::testing::UnitTestBackend;
+    use crate::storage::{StorageContext, StorageWriteSet};
+    use crate::transaction::prepare_version_ref_row;
+    use crate::untracked_state::{UntrackedStateContext, UntrackedStateRowRequest};
+
+    use super::*;
+
+    #[tokio::test]
+    async fn load_head_returns_none_when_missing() {
+        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
+        let version_ref = test_version_ref();
+
+        let head = version_ref
+            .reader(storage)
+            .load_head("missing-version")
+            .await
+            .expect("missing version ref should load cleanly");
+
+        assert_eq!(head, None);
+    }
+
+    #[tokio::test]
+    async fn advance_head_writes_untracked_global_ref() {
+        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
+        let version_ref = VersionRefContext::new(Arc::new(UntrackedStateContext::new()));
+        let mut transaction = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+
+        let mut writes = StorageWriteSet::new();
+        stage_version_head(
+            &version_ref,
+            &mut writes,
+            "version-a",
+            "commit-a",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("version head should advance");
+        writes
+            .apply(&mut transaction.as_mut())
+            .await
+            .expect("version head should apply");
+        transaction
+            .commit()
+            .await
+            .expect("transaction should commit");
+
+        let head = version_ref
+            .reader(storage.clone())
+            .load_head("version-a")
+            .await
+            .expect("version head should load")
+            .expect("version head should exist");
+        assert_eq!(head.version_id, "version-a");
+        assert_eq!(head.commit_id, "commit-a");
+
+        let mut reader = UntrackedStateContext::new().reader(storage);
+        let row = reader
+            .load_row(&UntrackedStateRowRequest {
+                schema_key: VERSION_REF_SCHEMA_KEY.to_string(),
+                version_id: GLOBAL_VERSION_ID.to_string(),
+                entity_id: crate::entity_identity::EntityIdentity::single("version-a"),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await
+            .expect("version-ref row should load")
+            .expect("version-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_version_heads() {
+        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
+        let version_ref = test_version_ref();
+        let mut transaction = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+
+        let mut writes = StorageWriteSet::new();
+        stage_version_head(
+            &version_ref,
+            &mut writes,
+            "version-b",
+            "commit-b",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("version-b should advance");
+        stage_version_head(
+            &version_ref,
+            &mut writes,
+            "version-a",
+            "commit-a",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("version-a should advance");
+        writes
+            .apply(&mut transaction.as_mut())
+            .await
+            .expect("version heads should apply");
+        transaction
+            .commit()
+            .await
+            .expect("transaction should commit");
+
+        let heads = version_ref
+            .reader(storage)
+            .scan_heads()
+            .await
+            .expect("heads should scan");
+
+        assert_eq!(
+            heads,
+            vec![
+                VersionHead {
+                    version_id: "version-a".to_string(),
+                    commit_id: "commit-a".to_string(),
+                },
+                VersionHead {
+                    version_id: "version-b".to_string(),
+                    commit_id: "commit-b".to_string(),
+                },
+            ]
+        );
+    }
+
+    fn test_version_ref() -> VersionRefContext {
+        VersionRefContext::new(Arc::new(UntrackedStateContext::new()))
+    }
+
+    fn stage_version_head(
+        version_ref: &VersionRefContext,
+        writes: &mut StorageWriteSet,
+        version_id: &str,
+        commit_id: &str,
+        timestamp: &str,
+    ) -> Result<(), LixError> {
+        let canonical_row = prepare_version_ref_row(version_id, commit_id, timestamp)?;
+        version_ref.writer(writes).stage_rows(&[canonical_row.row])
+    }
+}

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

@@ -0,0 +1,67 @@
+use serde_json::json;
+
+use crate::entity_identity::EntityIdentity;
+use crate::transaction::types::{TransactionJson, TransactionWriteRow};
+use crate::GLOBAL_VERSION_ID;
+
+pub(crate) const VERSION_DESCRIPTOR_SCHEMA_KEY: &str = "lix_version_descriptor";
+pub(crate) const VERSION_REF_SCHEMA_KEY: &str = "lix_version_ref";
+
+pub(crate) fn version_descriptor_stage_row(
+    version_id: &str,
+    name: &str,
+    hidden: bool,
+) -> TransactionWriteRow {
+    TransactionWriteRow {
+        entity_id: Some(EntityIdentity::single(version_id)),
+        schema_key: VERSION_DESCRIPTOR_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot: Some(TransactionJson::from_value_unchecked(json!({
+            "id": version_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,
+        version_id: GLOBAL_VERSION_ID.to_string(),
+    }
+}
+
+pub(crate) fn version_ref_stage_row(version_id: &str, commit_id: &str) -> TransactionWriteRow {
+    TransactionWriteRow {
+        entity_id: Some(EntityIdentity::single(version_id)),
+        schema_key: VERSION_REF_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot: Some(TransactionJson::from_value_unchecked(json!({
+            "id": version_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,
+        version_id: GLOBAL_VERSION_ID.to_string(),
+    }
+}
+
+pub(crate) fn version_descriptor_tombstone_row(version_id: &str) -> TransactionWriteRow {
+    let mut row = version_descriptor_stage_row(version_id, "", false);
+    row.snapshot = None;
+    row
+}
+
+pub(crate) fn version_ref_tombstone_row(version_id: &str) -> TransactionWriteRow {
+    let mut row = version_ref_stage_row(version_id, "");
+    row.snapshot = None;
+    row
+}

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

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