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

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

@@ -0,0 +1,239 @@
+use std::sync::Arc;
+
+use crate::binary_cas::BinaryCasContext;
+use crate::changelog::ChangelogContext;
+use crate::commit_graph::CommitGraphContext;
+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;
+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>,
+    changelog: Arc<ChangelogContext>,
+    schema_registry: Arc<SchemaRegistry>,
+}
+
+impl Engine {
+    /// Seeds an empty backend with the engine2 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 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);
+
+        crate::init::initialize(storage, &changelog, &live_state).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 changelog = Arc::new(ChangelogContext::new());
+        let commit_graph = CommitGraphContext::new(changelog.as_ref().clone());
+        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()),
+            changelog,
+            storage,
+            tracked_state,
+            live_state,
+            version_ctx,
+            schema_registry: Arc::new(SchemaRegistry::new()),
+        })
+    }
+
+    pub(crate) fn storage(&self) -> StorageContext {
+        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:
+    /// 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.changelog),
+            Arc::clone(&self.version_ctx),
+            Arc::clone(&self.schema_registry),
+        )
+        .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.changelog),
+            Arc::clone(&self.version_ctx),
+            Arc::clone(&self.schema_registry),
+        )
+        .await
+    }
+
+    /// Rebuilds the tracked serving projection for one version 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 version 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_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 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
+            .tracked_state
+            .rebuild_state_at_commit(
+                &commit_graph,
+                read_transaction.as_mut(),
+                transaction.as_mut(),
+                &mut writes,
+                &mut json_writer,
+                &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 {
+            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",
+        "engine2 backend is not initialized; call Engine::initialize(...) before Engine::new(...)",
+    ))
+}

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

@@ -0,0 +1,285 @@
+use base64::Engine as _;
+use serde_json::Value as JsonValue;
+
+use crate::common::json_pointer_get;
+use crate::LixError;
+
+const COMPOSITE_ENTITY_ID_PREFIX: &str = "pk:v1:";
+
+/// Logical entity identity derived from a schema primary key.
+///
+/// Keep this as typed tuple data inside engine2. The string projection exists
+/// only for SQL/canonical boundaries that still expose a single `entity_id`.
+#[derive(
+    Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
+)]
+pub(crate) struct EntityIdentity {
+    pub(crate) parts: Vec<EntityIdentityPart>,
+}
+
+#[derive(
+    Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
+)]
+#[serde(tag = "type", content = "value")]
+pub(crate) enum EntityIdentityPart {
+    String(String),
+    Bool(bool),
+    Number(String),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum EntityIdentityError {
+    EmptyPrimaryKey,
+    EmptyPrimaryKeyPath { index: usize },
+    MissingPrimaryKeyValue { index: usize },
+    NullPrimaryKeyValue { index: usize },
+    EmptyPrimaryKeyValue { index: usize },
+    UnsupportedPrimaryKeyValue { index: usize },
+    InvalidEncodedEntityIdentity,
+}
+
+impl std::fmt::Display for EntityIdentityError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::EmptyPrimaryKey => {
+                write!(formatter, "primary key must contain at least one path")
+            }
+            Self::EmptyPrimaryKeyPath { index } => {
+                write!(
+                    formatter,
+                    "primary-key path at index {index} must not be empty"
+                )
+            }
+            Self::MissingPrimaryKeyValue { index } => {
+                write!(formatter, "primary-key value at index {index} is missing")
+            }
+            Self::NullPrimaryKeyValue { index } => {
+                write!(
+                    formatter,
+                    "primary-key value at index {index} must not be null"
+                )
+            }
+            Self::EmptyPrimaryKeyValue { index } => {
+                write!(
+                    formatter,
+                    "primary-key string value at index {index} must not be empty"
+                )
+            }
+            Self::UnsupportedPrimaryKeyValue { index } => write!(
+                formatter,
+                "primary-key value at index {index} must be a string, number, or boolean"
+            ),
+            Self::InvalidEncodedEntityIdentity => {
+                write!(formatter, "encoded entity identity is invalid")
+            }
+        }
+    }
+}
+
+impl EntityIdentity {
+    pub(crate) fn single(value: impl Into<String>) -> Self {
+        Self {
+            parts: vec![EntityIdentityPart::String(value.into())],
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) fn tuple(parts: Vec<EntityIdentityPart>) -> Result<Self, EntityIdentityError> {
+        if parts.is_empty() {
+            return Err(EntityIdentityError::EmptyPrimaryKey);
+        }
+        Ok(Self { parts })
+    }
+
+    pub(crate) fn from_primary_key_paths(
+        snapshot: &JsonValue,
+        primary_key_paths: &[Vec<String>],
+    ) -> Result<Self, EntityIdentityError> {
+        if primary_key_paths.is_empty() {
+            return Err(EntityIdentityError::EmptyPrimaryKey);
+        }
+
+        let mut parts = Vec::with_capacity(primary_key_paths.len());
+        for (index, path) in primary_key_paths.iter().enumerate() {
+            if path.is_empty() {
+                return Err(EntityIdentityError::EmptyPrimaryKeyPath { index });
+            }
+            let Some(value) = json_pointer_get(snapshot, path) else {
+                return Err(EntityIdentityError::MissingPrimaryKeyValue { index });
+            };
+            parts.push(EntityIdentityPart::from_json_value(value, index)?);
+        }
+
+        Ok(Self { parts })
+    }
+
+    pub(crate) fn as_string(&self) -> Result<String, LixError> {
+        if self.parts.is_empty() {
+            return Err(LixError::unknown(
+                "entity identity must contain at least one primary-key part",
+            ));
+        }
+
+        if let [EntityIdentityPart::String(value)] = self.parts.as_slice() {
+            return Ok(value.clone());
+        }
+
+        let payload = serde_json::to_vec(self).map_err(|error| {
+            LixError::unknown(format!(
+                "failed to encode composite entity identity: {error}"
+            ))
+        })?;
+        Ok(format!(
+            "{COMPOSITE_ENTITY_ID_PREFIX}{}",
+            base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(payload)
+        ))
+    }
+
+    pub(crate) fn from_string(entity_id: &str) -> Result<Self, EntityIdentityError> {
+        if let Some(encoded) = entity_id.strip_prefix(COMPOSITE_ENTITY_ID_PREFIX) {
+            let payload = base64::engine::general_purpose::URL_SAFE_NO_PAD
+                .decode(encoded)
+                .map_err(|_| EntityIdentityError::InvalidEncodedEntityIdentity)?;
+            let identity = serde_json::from_slice::<Self>(&payload)
+                .map_err(|_| EntityIdentityError::InvalidEncodedEntityIdentity)?;
+            if identity.parts.is_empty() {
+                return Err(EntityIdentityError::InvalidEncodedEntityIdentity);
+            }
+            return Ok(identity);
+        }
+
+        Ok(Self::single(entity_id))
+    }
+}
+
+impl EntityIdentityPart {
+    fn from_json_value(value: &JsonValue, index: usize) -> Result<Self, EntityIdentityError> {
+        match value {
+            JsonValue::Null => Err(EntityIdentityError::NullPrimaryKeyValue { index }),
+            JsonValue::String(value) if value.is_empty() => {
+                Err(EntityIdentityError::EmptyPrimaryKeyValue { index })
+            }
+            JsonValue::String(value) => Ok(Self::String(value.clone())),
+            JsonValue::Bool(value) => Ok(Self::Bool(*value)),
+            JsonValue::Number(value) => Ok(Self::Number(value.to_string())),
+            JsonValue::Array(_) | JsonValue::Object(_) => {
+                Err(EntityIdentityError::UnsupportedPrimaryKeyValue { index })
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn single_string_identity_projects_to_plain_entity_id() {
+        let identity = EntityIdentity::single("plain-id");
+
+        assert_eq!(
+            identity.as_string().expect("projection should work"),
+            "plain-id"
+        );
+    }
+
+    #[test]
+    fn composite_identity_projects_to_versioned_opaque_entity_id() {
+        let identity = EntityIdentity::tuple(vec![
+            EntityIdentityPart::String("namespace".to_string()),
+            EntityIdentityPart::String("key".to_string()),
+        ])
+        .expect("tuple identity");
+
+        let encoded = identity.as_string().expect("projection should work");
+
+        assert!(encoded.starts_with(COMPOSITE_ENTITY_ID_PREFIX));
+        assert!(!encoded.contains("namespace~key"));
+    }
+
+    #[test]
+    fn composite_identity_roundtrips_from_string() {
+        let identity = EntityIdentity::tuple(vec![
+            EntityIdentityPart::String("namespace".to_string()),
+            EntityIdentityPart::Number("42".to_string()),
+            EntityIdentityPart::Bool(true),
+        ])
+        .expect("tuple identity");
+
+        let encoded = identity.as_string().expect("projection should work");
+
+        assert_eq!(
+            EntityIdentity::from_string(&encoded).expect("decode should work"),
+            identity
+        );
+    }
+
+    #[test]
+    fn composite_identity_does_not_collide_on_delimiter_like_values() {
+        let left = EntityIdentity::tuple(vec![
+            EntityIdentityPart::String("a~b".to_string()),
+            EntityIdentityPart::String("1".to_string()),
+        ])
+        .expect("left tuple identity");
+        let right = EntityIdentity::tuple(vec![
+            EntityIdentityPart::String("a".to_string()),
+            EntityIdentityPart::String("b~1".to_string()),
+        ])
+        .expect("right tuple identity");
+
+        assert_ne!(
+            left.as_string().expect("left should encode"),
+            right.as_string().expect("right should encode")
+        );
+    }
+
+    #[test]
+    fn from_string_treats_plain_string_as_single_string_identity() {
+        assert_eq!(
+            EntityIdentity::single("plain-id"),
+            EntityIdentity::single("plain-id")
+        );
+    }
+
+    #[test]
+    fn from_primary_key_paths_derives_ordered_parts() {
+        let snapshot = json!({
+            "namespace": "messages",
+            "index": 7,
+            "active": true
+        });
+
+        let identity = EntityIdentity::from_primary_key_paths(
+            &snapshot,
+            &[
+                vec!["namespace".to_string()],
+                vec!["index".to_string()],
+                vec!["active".to_string()],
+            ],
+        )
+        .expect("primary key should derive");
+
+        assert_eq!(
+            identity,
+            EntityIdentity {
+                parts: vec![
+                    EntityIdentityPart::String("messages".to_string()),
+                    EntityIdentityPart::Number("7".to_string()),
+                    EntityIdentityPart::Bool(true),
+                ],
+            }
+        );
+    }
+
+    #[test]
+    fn from_primary_key_paths_rejects_missing_parts() {
+        let snapshot = json!({ "id": "a" });
+
+        assert_eq!(
+            EntityIdentity::from_primary_key_paths(&snapshot, &[vec!["missing".to_string()]]),
+            Err(EntityIdentityError::MissingPrimaryKeyValue { index: 0 })
+        );
+    }
+}