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

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

@@ -1,221 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,330 +0,0 @@
-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

@@ -1,67 +0,0 @@
-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

@@ -1,21 +0,0 @@
-/// 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>;
-}