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

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

@@ -1,320 +0,0 @@
-use crate::entity_pk::EntityPk;
-use crate::live_state::MaterializedLiveStateRow;
-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:
-/// 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 {
-    branch_id: String,
-    untracked: bool,
-    file_scope: DomainFileScope,
-}
-
-impl Domain {
-    pub(crate) fn exact_file(
-        branch_id: impl Into<String>,
-        untracked: bool,
-        file_id: Option<String>,
-    ) -> Self {
-        Self {
-            branch_id: branch_id.into(),
-            untracked,
-            file_scope: DomainFileScope::Exact(file_id),
-        }
-    }
-
-    pub(crate) fn any_file(branch_id: impl Into<String>, untracked: bool) -> Self {
-        Self {
-            branch_id: branch_id.into(),
-            untracked,
-            file_scope: DomainFileScope::Any,
-        }
-    }
-
-    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.branch_id.clone(), row.untracked, row.file_id.clone())
-    }
-
-    pub(crate) fn schema_catalog_domain(&self) -> Self {
-        // 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.branch_id.clone(), self.untracked)
-    }
-
-    pub(crate) fn branch_id(&self) -> &str {
-        &self.branch_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.branch_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 {
-            branch_id: self.branch_id.clone(),
-            untracked,
-            file_scope: self.file_scope.clone(),
-        }
-    }
-
-    pub(crate) fn with_file_scope(&self, file_scope: DomainFileScope) -> Self {
-        Self {
-            branch_id: self.branch_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.branch_id == self.branch_id
-            && row.untracked == self.untracked
-            && 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,
-            }
-    }
-
-    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.branch_id == target.branch_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 branch_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_pk: EntityPk,
-}
-
-impl DomainRowIdentity {
-    pub(crate) fn new(domain: Domain, schema_key: impl Into<String>, entity_pk: EntityPk) -> Self {
-        Self {
-            domain,
-            schema_key: schema_key.into(),
-            entity_pk,
-        }
-    }
-
-    pub(crate) fn from_live_row(row: &MaterializedLiveStateRow) -> Self {
-        Self::new(
-            Domain::for_live_row(row),
-            row.schema_key.clone(),
-            row.entity_pk.clone(),
-        )
-    }
-
-    pub(crate) fn in_domain(
-        domain: Domain,
-        schema_key: impl Into<String>,
-        entity_pk: EntityPk,
-    ) -> Self {
-        Self::new(domain, schema_key, entity_pk)
-    }
-
-    #[cfg(test)]
-    pub(crate) fn exact(
-        branch_id: impl Into<String>,
-        untracked: bool,
-        file_id: Option<String>,
-        schema_key: impl Into<String>,
-        entity_pk: EntityPk,
-    ) -> Self {
-        Self::new(
-            Domain::exact_file(branch_id, untracked, file_id),
-            schema_key,
-            entity_pk,
-        )
-    }
-
-    pub(crate) fn with_domain(&self, domain: Domain) -> Self {
-        Self {
-            domain,
-            schema_key: self.schema_key.clone(),
-            entity_pk: self.entity_pk.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_pk(&self) -> &EntityPk {
-        &self.entity_pk
-    }
-
-    pub(crate) fn entity_pk_owned(&self) -> EntityPk {
-        self.entity_pk.clone()
-    }
-
-    pub(crate) fn matches_parts(
-        &self,
-        domain: &Domain,
-        schema_key: &str,
-        entity_pk: &EntityPk,
-    ) -> bool {
-        &self.domain == domain && self.schema_key == schema_key && &self.entity_pk == entity_pk
-    }
-
-    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_branch_scoped(
-    row: &MaterializedLiveStateRow,
-    branch_id: &str,
-) -> bool {
-    row.branch_id == branch_id && row.global == (row.branch_id == GLOBAL_BRANCH_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,203 +0,0 @@
-use std::sync::Arc;
-
-use crate::binary_cas::BinaryCasContext;
-use crate::branch::{BranchContext, BranchRefReader};
-use crate::catalog::CatalogContext;
-use crate::commit_graph::CommitGraphContext;
-use crate::entity_pk::EntityPk;
-use crate::init::InitReceipt;
-use crate::live_state::LiveStateContext;
-use crate::live_state::LiveStateRowRequest;
-use crate::session::SessionContext;
-use crate::storage::{DurableWriteLock, StorageBackend, StorageReadOptions, StorageWriteOptions};
-use crate::storage::{StorageContext, StorageWriteSet};
-use crate::tracked_state::TrackedStateContext;
-use crate::untracked_state::UntrackedStateContext;
-use crate::GLOBAL_BRANCH_ID;
-use crate::{LixError, NullableKeyFilter};
-
-#[derive(Clone)]
-pub struct Engine<B: StorageBackend = crate::storage::InMemoryStorageBackend> {
-    storage: StorageContext<B>,
-    tracked_state: Arc<TrackedStateContext>,
-    live_state: Arc<LiveStateContext>,
-    branch_ctx: Arc<BranchContext>,
-    binary_cas: Arc<BinaryCasContext>,
-    catalog_context: Arc<CatalogContext>,
-    write_lock: DurableWriteLock,
-}
-
-impl<B> Engine<B>
-where
-    B: StorageBackend + Clone + Send + Sync + 'static,
-    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
-    for<'backend> B::Write<'backend>: Send,
-{
-    /// 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: B) -> Result<InitReceipt, LixError> {
-        let storage = StorageContext::new(backend);
-        let _write_guard = storage.durable_write_lock().lock_owned().await;
-
-        crate::init::initialize(
-            storage,
-            &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: B) -> Result<Self, LixError> {
-        let storage = StorageContext::new(backend);
-
-        let tracked_state = Arc::new(TrackedStateContext::new());
-        let untracked_state = Arc::new(UntrackedStateContext::new());
-        let commit_graph = CommitGraphContext::new();
-        let live_state = Arc::new(LiveStateContext::new(
-            tracked_state.as_ref().clone(),
-            *untracked_state,
-            commit_graph,
-        ));
-        let branch_ctx = Arc::new(BranchContext::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()),
-            write_lock: storage.durable_write_lock(),
-            storage,
-            tracked_state,
-            live_state,
-            branch_ctx,
-            catalog_context: Arc::new(CatalogContext::new()),
-        })
-    }
-
-    pub(crate) fn storage(&self) -> StorageContext<B> {
-        self.storage.clone()
-    }
-
-    /// Loads the current commit head for a branch.
-    ///
-    /// This is the public engine-level form of the typed `branch_ref` context:
-    /// callers should not need to know that branch heads are represented as
-    /// untracked `lix_branch_ref` rows in live_state.
-    pub async fn load_branch_head_commit_id(
-        &self,
-        branch_id: &str,
-    ) -> Result<Option<String>, LixError> {
-        let read = self.storage.begin_read(StorageReadOptions::default())?;
-        let result = self
-            .branch_ctx
-            .ref_reader(&read)
-            .load_head_commit_id(branch_id)
-            .await;
-        result
-    }
-
-    pub async fn open_session(
-        &self,
-        active_branch_id: impl Into<String>,
-    ) -> Result<SessionContext<B>, LixError> {
-        SessionContext::open(
-            active_branch_id.into(),
-            self.storage(),
-            Arc::clone(&self.live_state),
-            Arc::clone(&self.tracked_state),
-            Arc::clone(&self.binary_cas),
-            Arc::clone(&self.branch_ctx),
-            Arc::clone(&self.catalog_context),
-            self.write_lock.clone(),
-        )
-        .await
-    }
-
-    pub async fn open_workspace_session(&self) -> Result<SessionContext<B>, LixError> {
-        SessionContext::open_workspace(
-            self.storage(),
-            Arc::clone(&self.live_state),
-            Arc::clone(&self.tracked_state),
-            Arc::clone(&self.binary_cas),
-            Arc::clone(&self.branch_ctx),
-            Arc::clone(&self.catalog_context),
-            self.write_lock.clone(),
-        )
-        .await
-    }
-
-    /// Rebuilds the tracked serving commit root for one branch from changelog.
-    ///
-    /// 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 branch head is read from the live-state facade so
-    /// rebuild uses the same moving-ref visibility as normal execution.
-    pub async fn rebuild_tracked_state_for_branch(&self, branch_id: &str) -> Result<(), LixError> {
-        let _write_guard = self.write_lock.lock_owned().await;
-        let head_commit_id = self
-            .load_branch_head_commit_id(branch_id)
-            .await?
-            .ok_or_else(|| {
-                LixError::branch_not_found(
-                    branch_id.to_string(),
-                    "rebuild_tracked_state_for_branch",
-                    "target",
-                )
-            })?;
-        let storage = self.storage();
-        let read = storage.begin_read(StorageReadOptions::default())?;
-        let mut writes = StorageWriteSet::new();
-        let rebuild_result = self
-            .tracked_state
-            .root_rebuilder(&read, &mut writes)
-            .rebuild_commit_root_at(&head_commit_id)
-            .await;
-        if let Err(error) = rebuild_result {
-            return Err(error);
-        }
-        storage
-            .commit_write_set(writes, StorageWriteOptions::default())
-            .map(|_| ())
-            .map_err(Into::into)
-    }
-}
-
-async fn assert_initialized<B>(
-    storage: StorageContext<B>,
-    live_state: &LiveStateContext,
-) -> Result<(), LixError>
-where
-    B: StorageBackend + Clone + Send + Sync + 'static,
-    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
-    for<'backend> B::Write<'backend>: Send,
-{
-    let read = storage.begin_read(StorageReadOptions::default())?;
-    let reader = live_state.reader(&read);
-    let initialized = reader
-        .load_row(&LiveStateRowRequest {
-            schema_key: "lix_key_value".to_string(),
-            branch_id: GLOBAL_BRANCH_ID.to_string(),
-            entity_pk: EntityPk::single("lix_id"),
-            file_id: NullableKeyFilter::Null,
-        })
-        .await?
-        .is_some();
-
-    if initialized {
-        return Ok(());
-    }
-
-    Err(LixError::new(
-        "LIX_ERROR_NOT_INITIALIZED",
-        "engine backend is not initialized; call Engine::initialize(...) before Engine::new(...)",
-    ))
-}