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

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

@@ -0,0 +1,324 @@
+use crate::entity_identity::EntityIdentity;
+use crate::live_state::MaterializedLiveStateRow;
+use crate::{NullableKeyFilter, GLOBAL_VERSION_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
+/// 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,
+    untracked: bool,
+    file_scope: DomainFileScope,
+}
+
+impl Domain {
+    pub(crate) fn exact_file(
+        version_id: impl Into<String>,
+        untracked: bool,
+        file_id: Option<String>,
+    ) -> Self {
+        Self {
+            version_id: version_id.into(),
+            untracked,
+            file_scope: DomainFileScope::Exact(file_id),
+        }
+    }
+
+    pub(crate) fn any_file(version_id: impl Into<String>, untracked: bool) -> Self {
+        Self {
+            version_id: version_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 for_live_row(row: &MaterializedLiveStateRow) -> Self {
+        Self::exact_file(row.version_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
+        // 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)
+    }
+
+    pub(crate) fn version_id(&self) -> &str {
+        &self.version_id
+    }
+
+    pub(crate) fn untracked(&self) -> bool {
+        self.untracked
+    }
+
+    pub(crate) fn fingerprint_component(&self) -> String {
+        let file_scope = match &self.file_scope {
+            DomainFileScope::Any => "*".to_string(),
+            DomainFileScope::Exact(Some(file_id)) => format!("={file_id}"),
+            DomainFileScope::Exact(None) => "=".to_string(),
+        };
+        format!("{}|{}|{}", self.version_id, self.untracked, file_scope)
+    }
+
+    #[cfg(test)]
+    pub(crate) fn file_scope(&self) -> &DomainFileScope {
+        &self.file_scope
+    }
+
+    pub(crate) fn is_exact_file(&self, file_id: &Option<String>) -> bool {
+        matches!(&self.file_scope, DomainFileScope::Exact(exact) if exact == file_id)
+    }
+
+    pub(crate) fn with_untracked(&self, untracked: bool) -> Self {
+        Self {
+            version_id: self.version_id.clone(),
+            untracked,
+            file_scope: self.file_scope.clone(),
+        }
+    }
+
+    pub(crate) fn with_file_scope(&self, file_scope: DomainFileScope) -> Self {
+        Self {
+            version_id: self.version_id.clone(),
+            untracked: self.untracked,
+            file_scope,
+        }
+    }
+
+    pub(crate) fn with_exact_file_scope(&self, file_id: Option<String>) -> Self {
+        self.with_file_scope(DomainFileScope::Exact(file_id))
+    }
+
+    pub(crate) fn file_filters(&self) -> Vec<NullableKeyFilter<String>> {
+        match &self.file_scope {
+            DomainFileScope::Any => Vec::new(),
+            DomainFileScope::Exact(file_id) => vec![nullable_filter_from_option(file_id)],
+        }
+    }
+
+    pub(crate) fn contains(&self, row: &MaterializedLiveStateRow) -> bool {
+        row.version_id == self.version_id
+            && row.untracked == self.untracked
+            && committed_row_is_exact_version_scoped(row, &self.version_id)
+            && match &self.file_scope {
+                DomainFileScope::Any => true,
+                DomainFileScope::Exact(file_id) => row.file_id == *file_id,
+            }
+    }
+
+    fn reachable_target_domains(&self) -> Vec<Self> {
+        if self.untracked {
+            vec![self.with_untracked(false), self.clone()]
+        } else {
+            vec![self.clone()]
+        }
+    }
+
+    fn source_domains_that_can_reach(&self) -> Vec<Self> {
+        if self.untracked {
+            vec![self.clone()]
+        } else {
+            vec![self.clone(), self.with_untracked(true)]
+        }
+    }
+
+    fn can_reach(&self, target: &Self) -> bool {
+        self.version_id == target.version_id
+            && self.file_scope == target.file_scope
+            && (self.untracked || !target.untracked)
+    }
+
+    pub(crate) fn schema_catalog_domains(&self) -> Vec<Self> {
+        self.schema_catalog_domain().reachable_target_domains()
+    }
+
+    pub(crate) fn fk_target_domains(&self) -> Vec<Self> {
+        self.reachable_target_domains()
+    }
+
+    pub(crate) fn fk_source_domains_for_target(&self) -> Vec<Self> {
+        self.source_domains_that_can_reach()
+    }
+
+    pub(crate) fn file_owner_domains(&self) -> Vec<Self> {
+        self.reachable_target_domains()
+    }
+
+    pub(crate) fn directory_parent_domains(&self) -> Vec<Self> {
+        self.reachable_target_domains()
+    }
+
+    pub(crate) fn version_descriptor_domains_for_ref_delete(&self) -> Vec<Self> {
+        self.source_domains_that_can_reach()
+    }
+
+    pub(crate) fn file_scoped_row_domains_for_file_descriptor_delete(&self) -> Vec<Self> {
+        self.source_domains_that_can_reach()
+    }
+
+    pub(crate) fn validation_scope_contains_constraint_domain(&self, target: &Self) -> bool {
+        self.can_reach(target)
+    }
+
+    pub(crate) fn tombstone_domain_affects_validation_scope(
+        &self,
+        validation_scope: &Self,
+    ) -> bool {
+        self.can_reach(validation_scope)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub(crate) enum DomainFileScope {
+    Any,
+    Exact(Option<String>),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub(crate) struct DomainRowIdentity {
+    domain: Domain,
+    schema_key: String,
+    entity_id: EntityIdentity,
+}
+
+impl DomainRowIdentity {
+    pub(crate) fn new(
+        domain: Domain,
+        schema_key: impl Into<String>,
+        entity_id: EntityIdentity,
+    ) -> Self {
+        Self {
+            domain,
+            schema_key: schema_key.into(),
+            entity_id,
+        }
+    }
+
+    pub(crate) fn from_live_row(row: &MaterializedLiveStateRow) -> Self {
+        Self::new(
+            Domain::for_live_row(row),
+            row.schema_key.clone(),
+            row.entity_id.clone(),
+        )
+    }
+
+    pub(crate) fn in_domain(
+        domain: Domain,
+        schema_key: impl Into<String>,
+        entity_id: EntityIdentity,
+    ) -> Self {
+        Self::new(domain, schema_key, entity_id)
+    }
+
+    #[cfg(test)]
+    pub(crate) fn exact(
+        version_id: impl Into<String>,
+        untracked: bool,
+        file_id: Option<String>,
+        schema_key: impl Into<String>,
+        entity_id: EntityIdentity,
+    ) -> Self {
+        Self::new(
+            Domain::exact_file(version_id, untracked, file_id),
+            schema_key,
+            entity_id,
+        )
+    }
+
+    pub(crate) fn with_domain(&self, domain: Domain) -> Self {
+        Self {
+            domain,
+            schema_key: self.schema_key.clone(),
+            entity_id: self.entity_id.clone(),
+        }
+    }
+
+    pub(crate) fn domain(&self) -> &Domain {
+        &self.domain
+    }
+
+    pub(crate) fn schema_key(&self) -> &str {
+        &self.schema_key
+    }
+
+    pub(crate) fn schema_key_owned(&self) -> String {
+        self.schema_key.clone()
+    }
+
+    pub(crate) fn entity_id(&self) -> &EntityIdentity {
+        &self.entity_id
+    }
+
+    pub(crate) fn entity_id_owned(&self) -> EntityIdentity {
+        self.entity_id.clone()
+    }
+
+    pub(crate) fn matches_parts(
+        &self,
+        domain: &Domain,
+        schema_key: &str,
+        entity_id: &EntityIdentity,
+    ) -> bool {
+        &self.domain == domain && self.schema_key == schema_key && &self.entity_id == entity_id
+    }
+
+    pub(crate) fn reachable_target_identities(&self) -> Vec<Self> {
+        self.domain
+            .fk_target_domains()
+            .into_iter()
+            .map(|domain| self.with_domain(domain))
+            .collect()
+    }
+
+    pub(crate) fn source_identities_that_can_reach(&self) -> Vec<Self> {
+        self.domain
+            .fk_source_domains_for_target()
+            .into_iter()
+            .map(|domain| self.with_domain(domain))
+            .collect()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub(crate) struct DomainSchemaIdentity {
+    domain: Domain,
+    schema_key: String,
+}
+
+impl DomainSchemaIdentity {
+    pub(crate) fn new(domain: Domain, schema_key: impl Into<String>) -> Self {
+        Self {
+            domain: domain.schema_catalog_domain(),
+            schema_key: schema_key.into(),
+        }
+    }
+
+    pub(crate) fn fingerprint_component(&self) -> String {
+        format!(
+            "{}|{}",
+            self.domain.fingerprint_component(),
+            self.schema_key
+        )
+    }
+}
+
+pub(crate) fn committed_row_is_exact_version_scoped(
+    row: &MaterializedLiveStateRow,
+    version_id: &str,
+) -> bool {
+    row.version_id == version_id && row.global == (row.version_id == GLOBAL_VERSION_ID)
+}
+
+fn nullable_filter_from_option(value: &Option<String>) -> NullableKeyFilter<String> {
+    match value {
+        Some(value) => NullableKeyFilter::Value(value.clone()),
+        None => NullableKeyFilter::Null,
+    }
+}

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

@@ -1,14 +1,13 @@
 use std::sync::Arc;
 
 use crate::binary_cas::BinaryCasContext;
-use crate::changelog::ChangelogContext;
+use crate::catalog::CatalogContext;
 use crate::commit_graph::CommitGraphContext;
+use crate::commit_store::CommitStoreContext;
 use crate::entity_identity::EntityIdentity;
 use crate::init::InitReceipt;
-use crate::json_store::JsonStoreContext;
 use crate::live_state::LiveStateContext;
 use crate::live_state::LiveStateRowRequest;
-use crate::schema_registry::SchemaRegistry;
 use crate::session::SessionContext;
 use crate::storage::{StorageContext, StorageWriteSet};
 use crate::tracked_state::TrackedStateContext;
@@ -24,12 +23,12 @@ pub struct Engine {
     live_state: Arc<LiveStateContext>,
     version_ctx: Arc<VersionContext>,
     binary_cas: Arc<BinaryCasContext>,
-    changelog: Arc<ChangelogContext>,
-    schema_registry: Arc<SchemaRegistry>,
+    commit_store: Arc<CommitStoreContext>,
+    catalog_context: Arc<CatalogContext>,
 }
 
 impl Engine {
-    /// Seeds an empty backend with the engine2 repository bootstrap facts.
+    /// Seeds an empty backend with the engine repository bootstrap facts.
     ///
     /// Initialization is a storage lifecycle operation, separate from runtime
     /// construction. Call this before `Engine::new(...)` for a brand-new
@@ -39,13 +38,15 @@ impl Engine {
     ) -> Result<InitReceipt, LixError> {
         let backend: Arc<dyn Backend + Send + Sync> = Arc::from(backend);
         let storage = StorageContext::new(backend);
-        let changelog = ChangelogContext::new();
-        let commit_graph = CommitGraphContext::new(changelog);
-        let tracked_state = TrackedStateContext::new();
-        let untracked_state = UntrackedStateContext::new();
-        let live_state = LiveStateContext::new(tracked_state, untracked_state, commit_graph);
+        let commit_store = CommitStoreContext::new();
 
-        crate::init::initialize(storage, &changelog, &live_state).await
+        crate::init::initialize(
+            storage,
+            &commit_store,
+            &TrackedStateContext::new(),
+            &UntrackedStateContext::new(),
+        )
+        .await
     }
 
     /// Creates a clean DataFusion-first engine over an initialized backend.
@@ -58,8 +59,8 @@ impl Engine {
 
         let tracked_state = Arc::new(TrackedStateContext::new());
         let untracked_state = Arc::new(UntrackedStateContext::new());
-        let changelog = Arc::new(ChangelogContext::new());
-        let commit_graph = CommitGraphContext::new(changelog.as_ref().clone());
+        let commit_store = Arc::new(CommitStoreContext::new());
+        let commit_graph = CommitGraphContext::new();
         let live_state = Arc::new(LiveStateContext::new(
             tracked_state.as_ref().clone(),
             *untracked_state,
@@ -74,12 +75,12 @@ impl Engine {
 
         Ok(Self {
             binary_cas: Arc::new(BinaryCasContext::new()),
-            changelog,
+            commit_store,
             storage,
             tracked_state,
             live_state,
             version_ctx,
-            schema_registry: Arc::new(SchemaRegistry::new()),
+            catalog_context: Arc::new(CatalogContext::new()),
         })
     }
 
@@ -87,11 +88,6 @@ impl Engine {
         self.storage.clone()
     }
 
-    #[cfg(test)]
-    pub(crate) fn tracked_state(&self) -> Arc<TrackedStateContext> {
-        Arc::clone(&self.tracked_state)
-    }
-
     /// Loads the current commit head for a version.
     ///
     /// This is the public engine-level form of the typed `version_ref` context:
@@ -129,9 +125,9 @@ impl Engine {
             Arc::clone(&self.live_state),
             Arc::clone(&self.tracked_state),
             Arc::clone(&self.binary_cas),
-            Arc::clone(&self.changelog),
+            Arc::clone(&self.commit_store),
             Arc::clone(&self.version_ctx),
-            Arc::clone(&self.schema_registry),
+            Arc::clone(&self.catalog_context),
         )
         .await
     }
@@ -142,19 +138,19 @@ impl Engine {
             Arc::clone(&self.live_state),
             Arc::clone(&self.tracked_state),
             Arc::clone(&self.binary_cas),
-            Arc::clone(&self.changelog),
+            Arc::clone(&self.commit_store),
             Arc::clone(&self.version_ctx),
-            Arc::clone(&self.schema_registry),
+            Arc::clone(&self.catalog_context),
         )
         .await
     }
 
-    /// Rebuilds the tracked serving projection for one version from changelog.
+    /// Materializes the tracked serving projection root for one version from commit_store.
     ///
     /// This is intentionally an engine-level operation: callers should not need
     /// to know which KV namespaces back changelog, commit graph, or tracked
     /// state. The current version head is read from the live-state facade so
-    /// rebuild uses the same moving-ref visibility as normal execution.
+    /// materialization uses the same moving-ref visibility as normal execution.
     pub async fn rebuild_tracked_state_for_version(
         &self,
         version_id: &str,
@@ -169,29 +165,19 @@ impl Engine {
                     "target",
                 )
             })?;
-        let commit_graph = CommitGraphContext::new(ChangelogContext::new());
         let storage = self.storage();
-        let mut read_transaction = storage.begin_read_transaction().await?;
         let mut transaction = storage.begin_write_transaction().await?;
         let mut writes = StorageWriteSet::new();
-        let mut json_writer = JsonStoreContext::new().writer();
-        let rebuild_result = self
+        let materialize_result = self
             .tracked_state
-            .rebuild_state_at_commit(
-                &commit_graph,
-                read_transaction.as_mut(),
+            .materializer(
                 transaction.as_mut(),
                 &mut writes,
-                &mut json_writer,
-                &head_commit_id,
+                self.commit_store.as_ref(),
             )
+            .materialize_root_at(&head_commit_id)
             .await;
-        if let Err(error) = rebuild_result {
-            let _ = read_transaction.rollback().await;
-            let _ = transaction.rollback().await;
-            return Err(error);
-        }
-        if let Err(error) = read_transaction.rollback().await {
+        if let Err(error) = materialize_result {
             let _ = transaction.rollback().await;
             return Err(error);
         }
@@ -234,6 +220,6 @@ async fn assert_initialized(
 
     Err(LixError::new(
         "LIX_ERROR_NOT_INITIALIZED",
-        "engine2 backend is not initialized; call Engine::initialize(...) before Engine::new(...)",
+        "engine backend is not initialized; call Engine::initialize(...) before Engine::new(...)",
     ))
 }