@lix-js/sdk 0.6.0-preview.1 → 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

@@ -0,0 +1,225 @@
+use std::sync::Arc;
+
+use crate::binary_cas::BinaryCasContext;
+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::live_state::LiveStateContext;
+use crate::live_state::LiveStateRowRequest;
+use crate::session::SessionContext;
+use crate::storage::{StorageContext, StorageWriteSet};
+use crate::tracked_state::TrackedStateContext;
+use crate::untracked_state::UntrackedStateContext;
+use crate::version::{VersionContext, VersionRefReader};
+use crate::GLOBAL_VERSION_ID;
+use crate::{Backend, LixError, NullableKeyFilter};
+
+#[derive(Clone)]
+pub struct Engine {
+    storage: StorageContext,
+    tracked_state: Arc<TrackedStateContext>,
+    live_state: Arc<LiveStateContext>,
+    version_ctx: Arc<VersionContext>,
+    binary_cas: Arc<BinaryCasContext>,
+    commit_store: Arc<CommitStoreContext>,
+    catalog_context: Arc<CatalogContext>,
+}
+
+impl Engine {
+    /// 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
+    /// backend.
+    pub async fn initialize(
+        backend: Box<dyn Backend + Send + Sync>,
+    ) -> Result<InitReceipt, LixError> {
+        let backend: Arc<dyn Backend + Send + Sync> = Arc::from(backend);
+        let storage = StorageContext::new(backend);
+        let commit_store = CommitStoreContext::new();
+
+        crate::init::initialize(
+            storage,
+            &commit_store,
+            &TrackedStateContext::new(),
+            &UntrackedStateContext::new(),
+        )
+        .await
+    }
+
+    /// Creates a clean DataFusion-first engine over an initialized backend.
+    ///
+    /// SessionContext, execution, and transaction overlays are layered below the
+    /// instance instead of being hidden behind a legacy boot path.
+    pub async fn new(backend: Box<dyn Backend + Send + Sync>) -> Result<Self, LixError> {
+        let backend: Arc<dyn Backend + Send + Sync> = Arc::from(backend);
+        let storage = StorageContext::new(backend);
+
+        let tracked_state = Arc::new(TrackedStateContext::new());
+        let untracked_state = Arc::new(UntrackedStateContext::new());
+        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,
+            commit_graph,
+        ));
+        let version_ctx = Arc::new(VersionContext::new(Arc::clone(&untracked_state)));
+        assert_initialized(storage.clone(), live_state.as_ref()).await?;
+
+        // SessionContext::execute later projects these stable state contexts into one
+        // execution-scoped SQL context, optionally wrapped by a transaction
+        // overlay for writes.
+
+        Ok(Self {
+            binary_cas: Arc::new(BinaryCasContext::new()),
+            commit_store,
+            storage,
+            tracked_state,
+            live_state,
+            version_ctx,
+            catalog_context: Arc::new(CatalogContext::new()),
+        })
+    }
+
+    pub(crate) fn storage(&self) -> StorageContext {
+        self.storage.clone()
+    }
+
+    /// Loads the current commit head for a version.
+    ///
+    /// This is the public engine-level form of the typed `version_ref` context:
+    /// callers should not need to know that version heads are represented as
+    /// untracked `lix_version_ref` rows in live_state.
+    pub async fn load_version_head_commit_id(
+        &self,
+        version_id: &str,
+    ) -> Result<Option<String>, LixError> {
+        let mut transaction = self.storage.begin_read_transaction().await?;
+        let result = self
+            .version_ctx
+            .ref_reader(transaction.as_mut())
+            .load_head_commit_id(version_id)
+            .await;
+        match result {
+            Ok(result) => {
+                transaction.rollback().await?;
+                Ok(result)
+            }
+            Err(error) => {
+                let _ = transaction.rollback().await;
+                Err(error)
+            }
+        }
+    }
+
+    pub async fn open_session(
+        &self,
+        active_version_id: impl Into<String>,
+    ) -> Result<SessionContext, LixError> {
+        SessionContext::open(
+            active_version_id.into(),
+            self.storage(),
+            Arc::clone(&self.live_state),
+            Arc::clone(&self.tracked_state),
+            Arc::clone(&self.binary_cas),
+            Arc::clone(&self.commit_store),
+            Arc::clone(&self.version_ctx),
+            Arc::clone(&self.catalog_context),
+        )
+        .await
+    }
+
+    pub async fn open_workspace_session(&self) -> Result<SessionContext, LixError> {
+        SessionContext::open_workspace(
+            self.storage(),
+            Arc::clone(&self.live_state),
+            Arc::clone(&self.tracked_state),
+            Arc::clone(&self.binary_cas),
+            Arc::clone(&self.commit_store),
+            Arc::clone(&self.version_ctx),
+            Arc::clone(&self.catalog_context),
+        )
+        .await
+    }
+
+    /// 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
+    /// materialization uses the same moving-ref visibility as normal execution.
+    pub async fn rebuild_tracked_state_for_version(
+        &self,
+        version_id: &str,
+    ) -> Result<(), LixError> {
+        let head_commit_id = self
+            .load_version_head_commit_id(version_id)
+            .await?
+            .ok_or_else(|| {
+                LixError::version_not_found(
+                    version_id.to_string(),
+                    "rebuild_tracked_state_for_version",
+                    "target",
+                )
+            })?;
+        let storage = self.storage();
+        let mut transaction = storage.begin_write_transaction().await?;
+        let mut writes = StorageWriteSet::new();
+        let materialize_result = self
+            .tracked_state
+            .materializer(
+                transaction.as_mut(),
+                &mut writes,
+                self.commit_store.as_ref(),
+            )
+            .materialize_root_at(&head_commit_id)
+            .await;
+        if let Err(error) = materialize_result {
+            let _ = transaction.rollback().await;
+            return Err(error);
+        }
+        if let Err(error) = writes.apply(&mut transaction.as_mut()).await {
+            let _ = transaction.rollback().await;
+            return Err(error);
+        }
+        transaction.commit().await
+    }
+}
+
+async fn assert_initialized(
+    storage: StorageContext,
+    live_state: &LiveStateContext,
+) -> Result<(), LixError> {
+    let mut transaction = storage.begin_read_transaction().await?;
+    let reader = live_state.reader(transaction.as_mut());
+    let result = reader
+        .load_row(&LiveStateRowRequest {
+            schema_key: "lix_key_value".to_string(),
+            version_id: GLOBAL_VERSION_ID.to_string(),
+            entity_id: EntityIdentity::single("lix_id"),
+            file_id: NullableKeyFilter::Null,
+        })
+        .await;
+    let initialized = match result {
+        Ok(row) => {
+            transaction.rollback().await?;
+            row.is_some()
+        }
+        Err(error) => {
+            let _ = transaction.rollback().await;
+            return Err(error);
+        }
+    };
+
+    if initialized {
+        return Ok(());
+    }
+
+    Err(LixError::new(
+        "LIX_ERROR_NOT_INITIALIZED",
+        "engine backend is not initialized; call Engine::initialize(...) before Engine::new(...)",
+    ))
+}