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

package/dist-engine-src/src/common/error.rs

@@ -70,7 +70,7 @@ impl LixError {
     /// A SQL write targeted a read-only internal/component surface.
     pub const CODE_READ_ONLY: &'static str = "LIX_ERROR_READ_ONLY";
 
-    /// A history table was queried without an explicit commit/version range.
+    /// A history table was queried without an explicit commit/branch range.
     pub const CODE_HISTORY_FILTER_REQUIRED: &'static str = "LIX_HISTORY_FILTER_REQUIRED";
 
     /// SQL syntax is valid, but the feature is intentionally outside the Lix
@@ -99,7 +99,7 @@ impl LixError {
     pub const CODE_FOREIGN_KEY: &'static str = "LIX_ERROR_FOREIGN_KEY";
 
     /// A row references a non-null `file_id` that has no matching `lix_file`
-    /// descriptor in the same effective version scope.
+    /// descriptor in the same effective branch scope.
     pub const CODE_FILE_NOT_FOUND: &'static str = "LIX_ERROR_FILE_NOT_FOUND";
 
     /// A primary-key or `x-lix-unique` constraint was violated — another
@@ -126,18 +126,21 @@ impl LixError {
     /// A merge found incompatible changes to the same tracked-state identity.
     pub const CODE_MERGE_CONFLICT: &'static str = "LIX_MERGE_CONFLICT";
 
-    /// A caller referenced a version id that has no matching version ref.
-    pub const CODE_VERSION_NOT_FOUND: &'static str = "LIX_VERSION_NOT_FOUND";
+    /// A caller referenced a branch id that has no matching branch ref.
+    pub const CODE_BRANCH_NOT_FOUND: &'static str = "LIX_BRANCH_NOT_FOUND";
+
+    /// A caller referenced a commit id that has no matching commit record.
+    pub const CODE_COMMIT_NOT_FOUND: &'static str = "LIX_COMMIT_NOT_FOUND";
 
     /// A staged row's storage scope flags disagree, such as a global row not
-    /// using the reserved global version id.
+    /// using the reserved global branch id.
     pub const CODE_INVALID_STORAGE_SCOPE: &'static str = "LIX_ERROR_INVALID_STORAGE_SCOPE";
 
     /// Merge graph analysis found multiple equally valid merge bases.
     pub const CODE_AMBIGUOUS_MERGE_BASE: &'static str = "LIX_AMBIGUOUS_MERGE_BASE";
 
     /// A merge request is well-formed but nonsensical for the commit graph,
-    /// such as merging a version into itself.
+    /// such as merging a branch into itself.
     pub const CODE_INVALID_MERGE: &'static str = "LIX_INVALID_MERGE";
 
     pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
@@ -153,20 +156,39 @@ impl LixError {
         Self::new("LIX_ERROR_UNKNOWN", message)
     }
 
-    pub fn version_not_found(
-        version_id: impl Into<String>,
+    pub fn branch_not_found(
+        branch_id: impl Into<String>,
+        operation: impl Into<String>,
+        role: impl Into<String>,
+    ) -> Self {
+        let branch_id = branch_id.into();
+        let operation = operation.into();
+        let role = role.into();
+        Self::new(
+            Self::CODE_BRANCH_NOT_FOUND,
+            format!("branch '{branch_id}' was not found"),
+        )
+        .with_details(json!({
+            "branch_id": branch_id,
+            "operation": operation,
+            "role": role,
+        }))
+    }
+
+    pub fn commit_not_found(
+        commit_id: impl Into<String>,
         operation: impl Into<String>,
         role: impl Into<String>,
     ) -> Self {
-        let version_id = version_id.into();
+        let commit_id = commit_id.into();
         let operation = operation.into();
         let role = role.into();
         Self::new(
-            Self::CODE_VERSION_NOT_FOUND,
-            format!("version '{version_id}' was not found"),
+            Self::CODE_COMMIT_NOT_FOUND,
+            format!("commit '{commit_id}' was not found"),
         )
         .with_details(json!({
-            "version_id": version_id,
+            "commit_id": commit_id,
             "operation": operation,
             "role": role,
         }))
@@ -190,16 +212,16 @@ impl LixError {
         }))
     }
 
-    pub fn invalid_self_merge(version_id: impl Into<String>) -> Self {
-        let version_id = version_id.into();
+    pub fn invalid_self_merge(branch_id: impl Into<String>) -> Self {
+        let branch_id = branch_id.into();
         Self::new(
             Self::CODE_INVALID_MERGE,
-            format!("cannot merge version '{version_id}' into itself"),
+            format!("cannot merge branch '{branch_id}' into itself"),
         )
         .with_details(json!({
-            "operation": "merge_version",
-            "target_version_id": version_id,
-            "source_version_id": version_id,
+            "operation": "merge_branch",
+            "target_branch_id": branch_id,
+            "source_branch_id": branch_id,
         }))
     }
 
@@ -259,6 +281,18 @@ impl LixError {
     }
 }
 
+impl From<crate::storage::StorageBackendError> for LixError {
+    fn from(error: crate::storage::StorageBackendError) -> Self {
+        Self::new(Self::CODE_STORAGE_ERROR, error.to_string())
+    }
+}
+
+impl From<crate::storage::StorageWriteSetError> for LixError {
+    fn from(error: crate::storage::StorageWriteSetError) -> Self {
+        Self::new(Self::CODE_STORAGE_ERROR, error.to_string())
+    }
+}
+
 impl std::fmt::Display for LixError {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{}", self.format())

package/dist-engine-src/src/common/identity.rs

@@ -106,9 +106,9 @@ macro_rules! canonical_identity_type {
     };
 }
 
-canonical_identity_type!(EntityId, "entity_id");
+canonical_identity_type!(EntityPk, "entity_pk");
 canonical_identity_type!(FileId, "file_id");
-canonical_identity_type!(VersionId, "version_id");
+canonical_identity_type!(BranchId, "branch_id");
 canonical_identity_type!(CanonicalSchemaKey, "schema_key");
 canonical_identity_type!(CanonicalPluginKey, "plugin_key");
 

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

@@ -14,7 +14,7 @@ pub(crate) use fs_path::{
     normalize_path_segment, parent_directory_path, ParsedFilePath,
 };
 pub(crate) use identity::{json_pointer_get, validate_non_empty_identity_value};
-pub use identity::{CanonicalPluginKey, CanonicalSchemaKey, EntityId, FileId, VersionId};
+pub use identity::{BranchId, CanonicalPluginKey, CanonicalSchemaKey, EntityPk, FileId};
 pub(crate) use json_pointer::{format_json_pointer, parse_json_pointer, top_level_property_name};
 pub(crate) use metadata::{
     parse_row_metadata, parse_row_metadata_value, serialize_row_metadata, validate_row_metadata,

package/dist-engine-src/src/domain.rs

@@ -1,57 +1,57 @@
-use crate::entity_identity::EntityIdentity;
+use crate::entity_pk::EntityPk;
 use crate::live_state::MaterializedLiveStateRow;
-use crate::{NullableKeyFilter, GLOBAL_VERSION_ID};
+use crate::{NullableKeyFilter, GLOBAL_BRANCH_ID};
 
 /// Validation/storage coordinate for repository facts.
 ///
 /// A domain is the complete scope in which a row identity is meaningful:
-/// version, durability, and file scope. Projection methods on this type are
+/// branch, durability, and file scope. Projection methods on this type are
 /// deliberately named so callers cannot silently erase part of the coordinate.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub(crate) struct Domain {
-    version_id: String,
+    branch_id: String,
     untracked: bool,
     file_scope: DomainFileScope,
 }
 
 impl Domain {
     pub(crate) fn exact_file(
-        version_id: impl Into<String>,
+        branch_id: impl Into<String>,
         untracked: bool,
         file_id: Option<String>,
     ) -> Self {
         Self {
-            version_id: version_id.into(),
+            branch_id: branch_id.into(),
             untracked,
             file_scope: DomainFileScope::Exact(file_id),
         }
     }
 
-    pub(crate) fn any_file(version_id: impl Into<String>, untracked: bool) -> Self {
+    pub(crate) fn any_file(branch_id: impl Into<String>, untracked: bool) -> Self {
         Self {
-            version_id: version_id.into(),
+            branch_id: branch_id.into(),
             untracked,
             file_scope: DomainFileScope::Any,
         }
     }
 
-    pub(crate) fn schema_catalog(version_id: impl Into<String>, untracked: bool) -> Self {
-        Self::any_file(version_id, untracked)
+    pub(crate) fn schema_catalog(branch_id: impl Into<String>, untracked: bool) -> Self {
+        Self::any_file(branch_id, untracked)
     }
 
     pub(crate) fn for_live_row(row: &MaterializedLiveStateRow) -> Self {
-        Self::exact_file(row.version_id.clone(), row.untracked, row.file_id.clone())
+        Self::exact_file(row.branch_id.clone(), row.untracked, row.file_id.clone())
     }
 
     pub(crate) fn schema_catalog_domain(&self) -> Self {
-        // Schema definitions are version + durability scoped. They are not
+        // Schema definitions are branch + durability scoped. They are not
         // owned by a data file, so schema catalog lookup deliberately erases
         // row file scope into `Any`.
-        Self::schema_catalog(self.version_id.clone(), self.untracked)
+        Self::schema_catalog(self.branch_id.clone(), self.untracked)
     }
 
-    pub(crate) fn version_id(&self) -> &str {
-        &self.version_id
+    pub(crate) fn branch_id(&self) -> &str {
+        &self.branch_id
     }
 
     pub(crate) fn untracked(&self) -> bool {
@@ -64,7 +64,7 @@ impl Domain {
             DomainFileScope::Exact(Some(file_id)) => format!("={file_id}"),
             DomainFileScope::Exact(None) => "=".to_string(),
         };
-        format!("{}|{}|{}", self.version_id, self.untracked, file_scope)
+        format!("{}|{}|{}", self.branch_id, self.untracked, file_scope)
     }
 
     #[cfg(test)]
@@ -78,7 +78,7 @@ impl Domain {
 
     pub(crate) fn with_untracked(&self, untracked: bool) -> Self {
         Self {
-            version_id: self.version_id.clone(),
+            branch_id: self.branch_id.clone(),
             untracked,
             file_scope: self.file_scope.clone(),
         }
@@ -86,7 +86,7 @@ impl Domain {
 
     pub(crate) fn with_file_scope(&self, file_scope: DomainFileScope) -> Self {
         Self {
-            version_id: self.version_id.clone(),
+            branch_id: self.branch_id.clone(),
             untracked: self.untracked,
             file_scope,
         }
@@ -104,9 +104,9 @@ impl Domain {
     }
 
     pub(crate) fn contains(&self, row: &MaterializedLiveStateRow) -> bool {
-        row.version_id == self.version_id
+        row.branch_id == self.branch_id
             && row.untracked == self.untracked
-            && committed_row_is_exact_version_scoped(row, &self.version_id)
+            && committed_row_is_exact_branch_scoped(row, &self.branch_id)
             && match &self.file_scope {
                 DomainFileScope::Any => true,
                 DomainFileScope::Exact(file_id) => row.file_id == *file_id,
@@ -130,7 +130,7 @@ impl Domain {
     }
 
     fn can_reach(&self, target: &Self) -> bool {
-        self.version_id == target.version_id
+        self.branch_id == target.branch_id
             && self.file_scope == target.file_scope
             && (self.untracked || !target.untracked)
     }
@@ -155,7 +155,7 @@ impl Domain {
         self.reachable_target_domains()
     }
 
-    pub(crate) fn version_descriptor_domains_for_ref_delete(&self) -> Vec<Self> {
+    pub(crate) fn branch_descriptor_domains_for_ref_delete(&self) -> Vec<Self> {
         self.source_domains_that_can_reach()
     }
 
@@ -185,19 +185,15 @@ pub(crate) enum DomainFileScope {
 pub(crate) struct DomainRowIdentity {
     domain: Domain,
     schema_key: String,
-    entity_id: EntityIdentity,
+    entity_pk: EntityPk,
 }
 
 impl DomainRowIdentity {
-    pub(crate) fn new(
-        domain: Domain,
-        schema_key: impl Into<String>,
-        entity_id: EntityIdentity,
-    ) -> Self {
+    pub(crate) fn new(domain: Domain, schema_key: impl Into<String>, entity_pk: EntityPk) -> Self {
         Self {
             domain,
             schema_key: schema_key.into(),
-            entity_id,
+            entity_pk,
         }
     }
 
@@ -205,30 +201,30 @@ impl DomainRowIdentity {
         Self::new(
             Domain::for_live_row(row),
             row.schema_key.clone(),
-            row.entity_id.clone(),
+            row.entity_pk.clone(),
         )
     }
 
     pub(crate) fn in_domain(
         domain: Domain,
         schema_key: impl Into<String>,
-        entity_id: EntityIdentity,
+        entity_pk: EntityPk,
     ) -> Self {
-        Self::new(domain, schema_key, entity_id)
+        Self::new(domain, schema_key, entity_pk)
     }
 
     #[cfg(test)]
     pub(crate) fn exact(
-        version_id: impl Into<String>,
+        branch_id: impl Into<String>,
         untracked: bool,
         file_id: Option<String>,
         schema_key: impl Into<String>,
-        entity_id: EntityIdentity,
+        entity_pk: EntityPk,
     ) -> Self {
         Self::new(
-            Domain::exact_file(version_id, untracked, file_id),
+            Domain::exact_file(branch_id, untracked, file_id),
             schema_key,
-            entity_id,
+            entity_pk,
         )
     }
 
@@ -236,7 +232,7 @@ impl DomainRowIdentity {
         Self {
             domain,
             schema_key: self.schema_key.clone(),
-            entity_id: self.entity_id.clone(),
+            entity_pk: self.entity_pk.clone(),
         }
     }
 
@@ -252,21 +248,21 @@ impl DomainRowIdentity {
         self.schema_key.clone()
     }
 
-    pub(crate) fn entity_id(&self) -> &EntityIdentity {
-        &self.entity_id
+    pub(crate) fn entity_pk(&self) -> &EntityPk {
+        &self.entity_pk
     }
 
-    pub(crate) fn entity_id_owned(&self) -> EntityIdentity {
-        self.entity_id.clone()
+    pub(crate) fn entity_pk_owned(&self) -> EntityPk {
+        self.entity_pk.clone()
     }
 
     pub(crate) fn matches_parts(
         &self,
         domain: &Domain,
         schema_key: &str,
-        entity_id: &EntityIdentity,
+        entity_pk: &EntityPk,
     ) -> bool {
-        &self.domain == domain && self.schema_key == schema_key && &self.entity_id == entity_id
+        &self.domain == domain && self.schema_key == schema_key && &self.entity_pk == entity_pk
     }
 
     pub(crate) fn reachable_target_identities(&self) -> Vec<Self> {
@@ -309,11 +305,11 @@ impl DomainSchemaIdentity {
     }
 }
 
-pub(crate) fn committed_row_is_exact_version_scoped(
+pub(crate) fn committed_row_is_exact_branch_scoped(
     row: &MaterializedLiveStateRow,
-    version_id: &str,
+    branch_id: &str,
 ) -> bool {
-    row.version_id == version_id && row.global == (row.version_id == GLOBAL_VERSION_ID)
+    row.branch_id == branch_id && row.global == (row.branch_id == GLOBAL_BRANCH_ID)
 }
 
 fn nullable_filter_from_option(value: &Option<String>) -> NullableKeyFilter<String> {