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

package/dist-engine-src/src/untracked_state/storage.rs

@@ -1,13 +1,13 @@
-use crate::json_store::JsonStoreContext;
 use crate::storage::KvScanRange;
 use crate::storage::{KvGetGroup, KvGetRequest, KvScanRequest, StorageReader, StorageWriteSet};
 use crate::untracked_state::{
     MaterializedUntrackedStateRow, UntrackedMaterializationProjection, UntrackedStateIdentity,
-    UntrackedStateRow, UntrackedStateRowRequest, UntrackedStateScanRequest,
+    UntrackedStateIdentityRef, UntrackedStateRow, UntrackedStateRowRef, UntrackedStateRowRequest,
+    UntrackedStateScanRequest,
 };
 use crate::{LixError, NullableKeyFilter};
 
-const UNTRACKED_STATE_ROW_NAMESPACE: &str = "untracked_state.row";
+pub(super) const UNTRACKED_STATE_ROW_NAMESPACE: &str = "untracked_state.row";
 
 pub(crate) async fn scan_rows(
     store: &mut impl StorageReader,
@@ -19,12 +19,9 @@ pub(crate) async fn scan_rows(
         rows.truncate(limit);
     }
     let projection = UntrackedMaterializationProjection::from_columns(&request.projection.columns);
-    let mut json_reader = JsonStoreContext::new().reader(store);
     let mut materialized = Vec::with_capacity(rows.len());
     for row in rows {
-        materialized.push(
-            crate::untracked_state::materialize_row(&mut json_reader, row, &projection).await?,
-        );
+        materialized.push(crate::untracked_state::materialize_row(row, &projection)?);
     }
     Ok(materialized)
 }
@@ -52,46 +49,98 @@ pub(crate) async fn load_row(
         return Ok(None);
     };
     let row = crate::untracked_state::codec::decode_row(&bytes)?;
-    let mut json_reader = JsonStoreContext::new().reader(store);
-    crate::untracked_state::materialize_row(
-        &mut json_reader,
-        row,
-        &UntrackedMaterializationProjection::full(),
-    )
-    .await
-    .map(Some)
+    crate::untracked_state::materialize_row(row, &UntrackedMaterializationProjection::full())
+        .map(Some)
+}
+
+pub(super) async fn existing_identities<'a>(
+    store: &mut (impl StorageReader + ?Sized),
+    identities: impl IntoIterator<Item = UntrackedStateIdentityRef<'a>>,
+) -> Result<Vec<UntrackedStateIdentity>, LixError> {
+    let mut candidates = identities
+        .into_iter()
+        .map(|identity| {
+            let owned = UntrackedStateIdentity {
+                version_id: identity.version_id.to_string(),
+                schema_key: identity.schema_key.to_string(),
+                entity_id: identity.entity_id.clone(),
+                file_id: identity.file_id.map(str::to_string),
+            };
+            let key = encode_untracked_state_row_key_ref(owned.as_ref());
+            (key, owned)
+        })
+        .collect::<Vec<_>>();
+    candidates.sort_by(|(left, _), (right, _)| left.cmp(right));
+    candidates.dedup_by(|(left, _), (right, _)| left == right);
+    if candidates.is_empty() {
+        return Ok(Vec::new());
+    }
+    let keys = candidates
+        .iter()
+        .map(|(key, _)| key.clone())
+        .collect::<Vec<_>>();
+
+    let result = store
+        .exists_many(KvGetRequest {
+            groups: vec![KvGetGroup {
+                namespace: UNTRACKED_STATE_ROW_NAMESPACE.to_string(),
+                keys,
+            }],
+        })
+        .await?;
+    let group = result.groups.into_iter().next().ok_or_else(|| {
+        LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            "untracked identity existence probe returned no result group",
+        )
+    })?;
+    if group.exists.len() != candidates.len() {
+        return Err(LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            format!(
+                "untracked identity existence probe returned {} results for {} requested keys",
+                group.exists.len(),
+                candidates.len()
+            ),
+        ));
+    }
+
+    Ok(candidates
+        .into_iter()
+        .zip(group.exists)
+        .filter_map(|((_, identity), exists)| exists.then_some(identity))
+        .collect())
 }
 
-pub(crate) fn stage_rows(
-    writes: &mut StorageWriteSet,
-    rows: &[UntrackedStateRow],
-) -> Result<(), LixError> {
+pub(crate) fn stage_rows<'a, I>(writes: &mut StorageWriteSet, rows: I) -> Result<(), LixError>
+where
+    I: IntoIterator<Item = UntrackedStateRowRef<'a>>,
+{
     for row in rows {
-        let identity = UntrackedStateIdentity::from_row(row);
-        if row.snapshot_ref.is_none() {
+        if row.snapshot_content.is_none() {
             writes.delete(
                 UNTRACKED_STATE_ROW_NAMESPACE,
-                encode_untracked_state_row_key(&identity),
+                encode_untracked_state_row_key_ref(row.into()),
             );
         } else {
             writes.put(
                 UNTRACKED_STATE_ROW_NAMESPACE,
-                encode_untracked_state_row_key(&identity),
-                crate::untracked_state::codec::encode_row(row)?,
+                encode_untracked_state_row_key_ref(row.into()),
+                crate::untracked_state::codec::encode_row_ref(row)?,
             );
         }
     }
     Ok(())
 }
 
-pub(crate) fn stage_delete_rows(
-    writes: &mut StorageWriteSet,
-    identities: &[UntrackedStateIdentity],
-) {
+pub(crate) fn stage_delete_rows<'a, I>(writes: &mut StorageWriteSet, identities: I)
+where
+    I: IntoIterator<Item = UntrackedStateIdentityRef<'a>>,
+{
     for identity in identities {
         writes.delete(
             UNTRACKED_STATE_ROW_NAMESPACE,
-            encode_untracked_state_row_key(identity),
+            encode_untracked_state_row_key_ref(identity),
         );
     }
 }
@@ -146,17 +195,21 @@ fn identity_from_request(request: &UntrackedStateRowRequest) -> Option<Untracked
 }
 
 fn encode_untracked_state_row_key(identity: &UntrackedStateIdentity) -> Vec<u8> {
+    encode_untracked_state_row_key_ref(identity.as_ref())
+}
+
+pub(super) fn encode_untracked_state_row_key_ref(
+    identity: UntrackedStateIdentityRef<'_>,
+) -> Vec<u8> {
     let mut out = Vec::new();
-    push_component(&mut out, &identity.version_id);
-    push_component(&mut out, &identity.schema_key);
-    push_component(
-        &mut out,
-        &identity
-            .entity_id
-            .as_string()
-            .expect("untracked-state identity should project"),
-    );
-    match &identity.file_id {
+    push_component(&mut out, identity.version_id);
+    push_component(&mut out, identity.schema_key);
+    let entity_id = identity
+        .entity_id
+        .as_json_array_text()
+        .expect("untracked-state identity should project");
+    push_component(&mut out, &entity_id);
+    match identity.file_id {
         Some(file_id) => {
             out.push(1);
             push_component(&mut out, file_id);
@@ -179,7 +232,7 @@ mod tests {
     use super::*;
     use crate::backend::testing::UnitTestBackend;
     use crate::storage::{StorageContext, StorageWriteTransaction};
-    use crate::untracked_state::{canonicalize_materialized_row, UntrackedStateContext};
+    use crate::untracked_state::UntrackedStateContext;
 
     async fn write_materialized_rows_to_store(
         context: &UntrackedStateContext,
@@ -187,16 +240,14 @@ mod tests {
         rows: &[MaterializedUntrackedStateRow],
     ) {
         let mut writes = StorageWriteSet::new();
-        let canonical_rows = {
-            let mut json_writer = JsonStoreContext::new().writer();
-            rows.iter()
-                .map(|row| canonicalize_materialized_row(&mut writes, &mut json_writer, row))
-                .collect::<Result<Vec<_>, _>>()
-                .expect("rows should canonicalize")
-        };
+        let canonical_rows = rows
+            .iter()
+            .map(|row| crate::test_support::untracked_state_row_from_materialized(&mut writes, row))
+            .collect::<Result<Vec<_>, _>>()
+            .expect("rows should canonicalize");
         context
             .writer(&mut writes)
-            .stage_rows(&canonical_rows)
+            .stage_rows(canonical_rows.iter().map(|row| row.as_ref()))
             .expect("rows should write");
         writes.apply(store).await.expect("rows should apply");
     }
@@ -290,22 +341,19 @@ mod tests {
             entity_id: row.entity_id.clone(),
             file_id: row.file_id.clone(),
         };
-
         let mut transaction = storage
             .begin_write_transaction()
             .await
             .expect("transaction should open");
         let mut writes = StorageWriteSet::new();
-        let canonical_row = {
-            let mut json_writer = JsonStoreContext::new().writer();
-            canonicalize_materialized_row(&mut writes, &mut json_writer, &row)
-                .expect("row should canonicalize")
-        };
+        let canonical_row =
+            crate::test_support::untracked_state_row_from_materialized(&mut writes, &row)
+                .expect("row should canonicalize");
         let mut writer = context.writer(&mut writes);
         writer
-            .stage_rows(&[canonical_row])
+            .stage_rows(std::iter::once(canonical_row.as_ref()))
             .expect("write should succeed");
-        writer.stage_delete_rows(&[identity]);
+        writer.stage_delete_rows(std::iter::once(identity.as_ref()));
         writes
             .apply(&mut transaction.as_mut())
             .await
@@ -338,7 +386,7 @@ mod tests {
             file_id: None,
             snapshot_content: Some(format!("{{\"key\":\"{}\",\"value\":\"value\"}}", entity_id)),
             metadata: None,
-            schema_version: "1".to_string(),
+            deleted: false,
             created_at: "2026-01-01T00:00:00Z".to_string(),
             updated_at: "2026-01-01T00:00:00Z".to_string(),
             global: version_id == "global",

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

@@ -1,25 +1,56 @@
 use crate::entity_identity::EntityIdentity;
-use crate::json_store::JsonRef;
-use crate::{NullableKeyFilter, RowMetadata};
+use crate::NullableKeyFilter;
 
 /// Durable local row excluded from changelog and commit membership.
 ///
 /// This is the canonical physical shape: identity/header fields are stored
-/// directly, while JSON payloads live in json_store and are referenced by hash.
+/// directly, and mutable JSON payloads are stored inline in the sidecar row.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct UntrackedStateRow {
     pub(crate) entity_id: EntityIdentity,
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
-    pub(crate) snapshot_ref: Option<JsonRef>,
-    pub(crate) metadata_ref: Option<JsonRef>,
-    pub(crate) schema_version: String,
+    pub(crate) snapshot_content: Option<String>,
+    pub(crate) metadata: Option<String>,
     pub(crate) created_at: String,
     pub(crate) updated_at: String,
     pub(crate) global: bool,
     pub(crate) version_id: String,
 }
 
+impl UntrackedStateRow {
+    pub(crate) fn as_ref(&self) -> UntrackedStateRowRef<'_> {
+        UntrackedStateRowRef {
+            entity_id: &self.entity_id,
+            schema_key: &self.schema_key,
+            file_id: self.file_id.as_deref(),
+            snapshot_content: self.snapshot_content.as_deref(),
+            metadata: self.metadata.as_deref(),
+            created_at: &self.created_at,
+            updated_at: &self.updated_at,
+            global: self.global,
+            version_id: &self.version_id,
+        }
+    }
+}
+
+/// Zero-copy view of untracked-state write row.
+///
+/// Untracked state owns this storage-facing write shape. Callers adapt into it
+/// without making untracked_state depend on transaction or live-state types.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct UntrackedStateRowRef<'a> {
+    pub(crate) entity_id: &'a EntityIdentity,
+    pub(crate) schema_key: &'a str,
+    pub(crate) file_id: Option<&'a str>,
+    pub(crate) snapshot_content: Option<&'a str>,
+    pub(crate) metadata: Option<&'a str>,
+    pub(crate) created_at: &'a str,
+    pub(crate) updated_at: &'a str,
+    pub(crate) global: bool,
+    pub(crate) version_id: &'a str,
+}
+
 /// Hydrated boundary shape for callers that still work with JSON payloads.
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub(crate) struct MaterializedUntrackedStateRow {
@@ -27,8 +58,8 @@ pub(crate) struct MaterializedUntrackedStateRow {
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
     pub(crate) snapshot_content: Option<String>,
-    pub(crate) metadata: Option<RowMetadata>,
-    pub(crate) schema_version: String,
+    pub(crate) metadata: Option<String>,
+    pub(crate) deleted: bool,
     pub(crate) created_at: String,
     pub(crate) updated_at: String,
     pub(crate) global: bool,
@@ -44,13 +75,32 @@ pub(crate) struct UntrackedStateIdentity {
     pub(crate) file_id: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct UntrackedStateIdentityRef<'a> {
+    pub(crate) version_id: &'a str,
+    pub(crate) schema_key: &'a str,
+    pub(crate) entity_id: &'a EntityIdentity,
+    pub(crate) file_id: Option<&'a str>,
+}
+
 impl UntrackedStateIdentity {
-    pub(crate) fn from_row(row: &UntrackedStateRow) -> Self {
+    pub(crate) fn as_ref(&self) -> UntrackedStateIdentityRef<'_> {
+        UntrackedStateIdentityRef {
+            version_id: &self.version_id,
+            schema_key: &self.schema_key,
+            entity_id: &self.entity_id,
+            file_id: self.file_id.as_deref(),
+        }
+    }
+}
+
+impl<'a> From<UntrackedStateRowRef<'a>> for UntrackedStateIdentityRef<'a> {
+    fn from(row: UntrackedStateRowRef<'a>) -> Self {
         Self {
-            version_id: row.version_id.clone(),
-            schema_key: row.schema_key.clone(),
-            entity_id: row.entity_id.clone(),
-            file_id: row.file_id.clone(),
+            version_id: row.version_id,
+            schema_key: row.schema_key,
+            entity_id: row.entity_id,
+            file_id: row.file_id,
         }
     }
 }

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

@@ -1,10 +1,9 @@
 use std::sync::Arc;
 
-use crate::json_store::JsonStoreWriter;
 use crate::storage::{StorageReader, StorageWriteSet};
 use crate::untracked_state::{UntrackedStateContext, UntrackedStateRow};
 
-use super::refs::{canonical_version_ref_row, VersionRefContext};
+use super::refs::VersionRefContext;
 use super::VersionRefReader;
 
 /// Aggregate entrypoint for version-domain services.
@@ -31,17 +30,6 @@ impl VersionContext {
         self.refs.reader(store)
     }
 
-    pub(crate) fn canonical_ref_row(
-        &self,
-        writes: &mut StorageWriteSet,
-        json_writer: &mut JsonStoreWriter,
-        version_id: &str,
-        commit_id: &str,
-        timestamp: &str,
-    ) -> Result<UntrackedStateRow, crate::LixError> {
-        canonical_version_ref_row(writes, json_writer, version_id, commit_id, timestamp)
-    }
-
     pub(crate) fn stage_canonical_ref_rows(
         &self,
         writes: &mut StorageWriteSet,

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

@@ -1,12 +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_DESCRIPTOR_SCHEMA_VERSION,
-    VERSION_REF_SCHEMA_KEY, VERSION_REF_SCHEMA_VERSION,
+    version_ref_tombstone_row, VERSION_DESCRIPTOR_SCHEMA_KEY, VERSION_REF_SCHEMA_KEY,
 };
 pub(crate) use types::{VersionHead, VersionRefReader};