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

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

@@ -1,405 +0,0 @@
-use serde_json::Value as JsonValue;
-
-use crate::common::json_pointer_get;
-use crate::LixError;
-
-/// Logical entity identity derived from a schema primary key.
-///
-/// Keep this as typed tuple data inside engine. SQL `entity_id` surfaces
-/// should use the JSON-array projection.
-#[derive(
-    Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
-)]
-pub(crate) struct EntityIdentity {
-    pub(crate) parts: Vec<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) enum EntityIdentityError {
-    EmptyPrimaryKey,
-    EmptyPrimaryKeyPath { index: usize },
-    EmptyPrimaryKeyValue { index: usize },
-    MissingPrimaryKeyValue { 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::EmptyPrimaryKeyValue { index } => {
-                write!(
-                    formatter,
-                    "primary-key value at index {index} must not be empty"
-                )
-            }
-            Self::MissingPrimaryKeyValue { index } => {
-                write!(formatter, "primary-key value at index {index} is missing")
-            }
-            Self::UnsupportedPrimaryKeyValue { index } => write!(
-                formatter,
-                "primary-key value at index {index} must be a JSON string"
-            ),
-            Self::InvalidEncodedEntityIdentity => {
-                write!(
-                    formatter,
-                    "encoded entity identity must be a non-empty JSON array of strings"
-                )
-            }
-        }
-    }
-}
-
-impl EntityIdentity {
-    pub(crate) fn single(value: impl Into<String>) -> Self {
-        Self {
-            parts: vec![value.into()],
-        }
-    }
-
-    #[cfg(test)]
-    pub(crate) fn tuple(parts: Vec<String>) -> Result<Self, EntityIdentityError> {
-        if parts.is_empty() {
-            return Err(EntityIdentityError::EmptyPrimaryKey);
-        }
-        if let Some((index, _)) = parts.iter().enumerate().find(|(_, part)| part.is_empty()) {
-            return Err(EntityIdentityError::EmptyPrimaryKeyValue { index });
-        }
-        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(string_part_from_json_value(value, index)?);
-        }
-
-        Ok(Self { parts })
-    }
-
-    pub(crate) fn as_json_array_value(&self) -> Result<JsonValue, LixError> {
-        if self.parts.is_empty() {
-            return Err(LixError::unknown(
-                "entity identity must contain at least one primary-key part",
-            ));
-        }
-
-        Ok(JsonValue::Array(
-            self.parts
-                .iter()
-                .map(|part| JsonValue::String(part.clone()))
-                .collect(),
-        ))
-    }
-
-    pub(crate) fn as_json_array_text(&self) -> Result<String, LixError> {
-        serde_json::to_string(&self.as_json_array_value()?).map_err(|error| {
-            LixError::unknown(format!("failed to encode entity id as JSON: {error}"))
-        })
-    }
-
-    pub(crate) fn as_single_string(&self) -> Result<&str, LixError> {
-        if self.parts.is_empty() {
-            return Err(LixError::unknown(
-                "entity identity must contain at least one primary-key part",
-            ));
-        }
-
-        if let [value] = self.parts.as_slice() {
-            return Ok(value.as_str());
-        }
-
-        Err(LixError::unknown(
-            "entity identity is not a single string primary-key tuple",
-        ))
-    }
-
-    pub(crate) fn as_single_string_owned(&self) -> Result<String, LixError> {
-        Ok(self.as_single_string()?.to_owned())
-    }
-
-    pub(crate) fn from_json_array_text(entity_id: &str) -> Result<Self, EntityIdentityError> {
-        let value = serde_json::from_str::<JsonValue>(entity_id)
-            .map_err(|_| EntityIdentityError::InvalidEncodedEntityIdentity)?;
-        Self::from_json_array_value(&value)
-    }
-
-    pub(crate) fn from_json_array_value(
-        entity_id: &JsonValue,
-    ) -> Result<Self, EntityIdentityError> {
-        let JsonValue::Array(values) = entity_id else {
-            return Err(EntityIdentityError::InvalidEncodedEntityIdentity);
-        };
-        if values.is_empty() {
-            return Err(EntityIdentityError::EmptyPrimaryKey);
-        }
-
-        let mut parts = Vec::with_capacity(values.len());
-        for (index, value) in values.iter().enumerate() {
-            parts.push(string_part_from_json_value(value, index)?);
-        }
-        Ok(Self { parts })
-    }
-}
-
-fn string_part_from_json_value(
-    value: &JsonValue,
-    index: usize,
-) -> Result<String, EntityIdentityError> {
-    match value {
-        JsonValue::String(value) if value.is_empty() => {
-            Err(EntityIdentityError::EmptyPrimaryKeyValue { index })
-        }
-        JsonValue::String(value) => Ok(value.clone()),
-        _ => Err(EntityIdentityError::UnsupportedPrimaryKeyValue { index }),
-    }
-}
-
-pub(crate) fn canonical_json_text(value: &JsonValue) -> serde_json::Result<String> {
-    serde_json::to_string(&canonical_json_value(value))
-}
-
-fn canonical_json_value(value: &JsonValue) -> JsonValue {
-    match value {
-        JsonValue::Array(values) => {
-            JsonValue::Array(values.iter().map(canonical_json_value).collect())
-        }
-        JsonValue::Object(object) => {
-            let mut entries = object.iter().collect::<Vec<_>>();
-            entries.sort_by(|(left, _), (right, _)| left.cmp(right));
-
-            let mut canonical = serde_json::Map::new();
-            for (key, value) in entries {
-                canonical.insert(key.clone(), canonical_json_value(value));
-            }
-            JsonValue::Object(canonical)
-        }
-        _ => value.clone(),
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use serde_json::json;
-
-    use super::*;
-
-    #[test]
-    fn single_string_identity_projects_to_single_string() {
-        let identity = EntityIdentity::single("plain-id");
-
-        assert_eq!(
-            identity.as_single_string().expect("projection should work"),
-            "plain-id"
-        );
-    }
-
-    #[test]
-    fn single_identity_projects_to_json_array_entity_id() {
-        let identity = EntityIdentity::single("plain-id");
-
-        assert_eq!(
-            identity
-                .as_json_array_text()
-                .expect("projection should work"),
-            "[\"plain-id\"]"
-        );
-    }
-
-    #[test]
-    fn composite_identity_projects_to_json_array_entity_id() {
-        let identity = EntityIdentity::tuple(vec!["namespace".to_string(), "42".to_string()])
-            .expect("tuple identity");
-
-        assert_eq!(
-            identity
-                .as_json_array_text()
-                .expect("projection should work"),
-            "[\"namespace\",\"42\"]"
-        );
-    }
-
-    #[test]
-    fn entity_id_json_array_roundtrips() {
-        let identity = EntityIdentity::tuple(vec!["namespace".to_string(), "42".to_string()])
-            .expect("tuple identity");
-        let encoded = identity
-            .as_json_array_text()
-            .expect("projection should work");
-
-        assert_eq!(
-            EntityIdentity::from_json_array_text(&encoded).expect("decode should work"),
-            identity
-        );
-    }
-
-    #[test]
-    fn entity_id_json_array_rejects_empty_string_part() {
-        assert_eq!(
-            EntityIdentity::from_json_array_text("[\"\"]"),
-            Err(EntityIdentityError::EmptyPrimaryKeyValue { index: 0 })
-        );
-    }
-
-    #[test]
-    fn tuple_rejects_empty_string_part() {
-        assert_eq!(
-            EntityIdentity::tuple(vec!["namespace".to_string(), "".to_string()]),
-            Err(EntityIdentityError::EmptyPrimaryKeyValue { index: 1 })
-        );
-    }
-
-    #[test]
-    fn entity_id_json_array_does_not_collide_on_delimiter_like_values() {
-        let left = EntityIdentity::tuple(vec!["a~b".to_string(), "c".to_string()])
-            .expect("left tuple identity");
-        let right = EntityIdentity::tuple(vec!["a".to_string(), "b~c".to_string()])
-            .expect("right tuple identity");
-
-        assert_ne!(
-            left.as_json_array_text().expect("left should encode"),
-            right.as_json_array_text().expect("right should encode")
-        );
-    }
-
-    #[test]
-    fn composite_identity_rejects_single_string_projection() {
-        let identity = EntityIdentity::tuple(vec!["namespace".to_string(), "42".to_string()])
-            .expect("tuple identity");
-
-        assert!(identity.as_single_string().is_err());
-    }
-
-    #[test]
-    fn composite_identity_does_not_collide_on_delimiter_like_values() {
-        let left = EntityIdentity::tuple(vec!["a~b".to_string(), "1".to_string()])
-            .expect("left tuple identity");
-        let right = EntityIdentity::tuple(vec!["a".to_string(), "b~1".to_string()])
-            .expect("right tuple identity");
-
-        assert_ne!(
-            left.as_json_array_text().expect("left should encode"),
-            right.as_json_array_text().expect("right should encode")
-        );
-    }
-
-    #[test]
-    fn from_primary_key_paths_derives_ordered_parts() {
-        let snapshot = json!({
-            "namespace": "messages",
-            "locale": "en"
-        });
-
-        let identity = EntityIdentity::from_primary_key_paths(
-            &snapshot,
-            &[vec!["namespace".to_string()], vec!["locale".to_string()]],
-        )
-        .expect("primary key should derive");
-
-        assert_eq!(
-            identity,
-            EntityIdentity {
-                parts: vec!["messages".to_string(), "en".to_string()],
-            }
-        );
-    }
-
-    #[test]
-    fn entity_id_json_array_rejects_non_string_parts() {
-        assert_eq!(
-            EntityIdentity::from_json_array_text("[\"namespace\",42]"),
-            Err(EntityIdentityError::UnsupportedPrimaryKeyValue { index: 1 })
-        );
-        assert_eq!(
-            EntityIdentity::from_json_array_text("[\"namespace\",null]"),
-            Err(EntityIdentityError::UnsupportedPrimaryKeyValue { index: 1 })
-        );
-        assert_eq!(
-            EntityIdentity::from_json_array_text("[[\"nested\"]]"),
-            Err(EntityIdentityError::UnsupportedPrimaryKeyValue { index: 0 })
-        );
-    }
-
-    #[test]
-    fn from_primary_key_paths_rejects_non_string_parts() {
-        let snapshot = json!({
-            "namespace": "messages",
-            "index": 7
-        });
-
-        assert_eq!(
-            EntityIdentity::from_primary_key_paths(
-                &snapshot,
-                &[vec!["namespace".to_string()], vec!["index".to_string()],],
-            ),
-            Err(EntityIdentityError::UnsupportedPrimaryKeyValue { index: 1 })
-        );
-    }
-
-    #[test]
-    fn from_primary_key_paths_rejects_empty_string_parts() {
-        let snapshot = json!({
-            "namespace": "messages",
-            "id": ""
-        });
-
-        assert_eq!(
-            EntityIdentity::from_primary_key_paths(
-                &snapshot,
-                &[vec!["namespace".to_string()], vec!["id".to_string()],],
-            ),
-            Err(EntityIdentityError::EmptyPrimaryKeyValue { index: 1 })
-        );
-    }
-
-    #[test]
-    fn from_primary_key_paths_rejects_nested_json_parts() {
-        let snapshot = json!({
-            "entity_id": ["welcome.title", "en"],
-            "schema_key": "message"
-        });
-
-        assert_eq!(
-            EntityIdentity::from_primary_key_paths(
-                &snapshot,
-                &[
-                    vec!["entity_id".to_string()],
-                    vec!["schema_key".to_string()],
-                ],
-            ),
-            Err(EntityIdentityError::UnsupportedPrimaryKeyValue { index: 0 })
-        );
-    }
-
-    #[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 })
-        );
-    }
-}

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

@@ -1,292 +0,0 @@
-use crate::functions::{
-    state, DeterministicFunctionProvider, DeterministicSequence, FunctionProvider,
-    FunctionProviderHandle, SharedFunctionProvider, SystemFunctionProvider,
-};
-use crate::live_state::LiveStateReader;
-use crate::storage::StorageWriteSet;
-use crate::LixError;
-
-/// Execution-scoped runtime function context.
-///
-/// Lower layers should only receive function providers. This context owns the
-/// lifecycle at the session/transaction boundary: prepare the right function
-/// source before execution and persist deterministic sequence progress after
-/// successful execution.
-pub(crate) struct FunctionContext {
-    functions: FunctionProviderHandle,
-    bookkeeping_timestamp: String,
-}
-
-impl FunctionContext {
-    /// Prepares the runtime function provider for one execution.
-    ///
-    /// If deterministic mode is absent or disabled, the context uses system
-    /// functions. If enabled, it starts from the persisted sequence + 1.
-    pub(crate) async fn prepare(live_state: &dyn LiveStateReader) -> Result<Self, LixError> {
-        let mode = state::load_mode(live_state).await?;
-        let mut bookkeeping_functions = SystemFunctionProvider;
-        let bookkeeping_timestamp = bookkeeping_functions.timestamp();
-        if !mode.enabled {
-            return Ok(Self {
-                functions: SharedFunctionProvider::new(
-                    Box::new(SystemFunctionProvider) as Box<dyn FunctionProvider + Send>
-                ),
-                bookkeeping_timestamp,
-            });
-        }
-
-        let sequence = state::load_sequence(live_state).await?;
-        Ok(Self {
-            functions: SharedFunctionProvider::new(Box::new(DeterministicFunctionProvider::new(
-                sequence.next_sequence(),
-                mode.timestamp_shuffle,
-            ))
-                as Box<dyn FunctionProvider + Send>),
-            bookkeeping_timestamp,
-        })
-    }
-
-    /// Returns the engine-owned provider used by SQL and transaction staging.
-    pub(crate) fn provider(&self) -> FunctionProviderHandle {
-        self.functions.clone()
-    }
-
-    /// Persists deterministic sequence progress if this execution used any.
-    ///
-    /// System functions report no sequence state, so this is a no-op when
-    /// deterministic mode is disabled.
-    pub(crate) async fn stage_persist_if_needed(
-        &self,
-        writes: &mut StorageWriteSet,
-    ) -> Result<(), LixError> {
-        let Some(highest_seen) = self.functions.deterministic_sequence_persist_highest_seen()
-        else {
-            return Ok(());
-        };
-        state::stage_sequence(
-            writes,
-            DeterministicSequence { highest_seen },
-            &self.bookkeeping_timestamp,
-        )
-        .await
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use std::sync::Arc;
-
-    use crate::backend::testing::UnitTestBackend;
-    use crate::functions::state::{DETERMINISTIC_MODE_KEY, DETERMINISTIC_SEQUENCE_KEY};
-    use crate::functions::{state::load_sequence, DeterministicSequence};
-    use crate::live_state::LiveStateContext;
-    use crate::storage::StorageContext;
-    use crate::GLOBAL_VERSION_ID;
-
-    use super::*;
-
-    fn live_state_context() -> LiveStateContext {
-        LiveStateContext::new(
-            crate::tracked_state::TrackedStateContext::new(),
-            crate::untracked_state::UntrackedStateContext::new(),
-            crate::commit_graph::CommitGraphContext::new(),
-        )
-    }
-
-    #[tokio::test]
-    async fn prepare_uses_system_functions_when_mode_missing() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        let live_state = live_state_context();
-        let reader = live_state.reader(storage.clone());
-
-        let context = FunctionContext::prepare(&reader)
-            .await
-            .expect("runtime context should prepare");
-
-        assert_eq!(
-            context
-                .provider()
-                .deterministic_sequence_persist_highest_seen(),
-            None
-        );
-    }
-
-    #[tokio::test]
-    async fn prepare_starts_deterministic_functions_at_sequence_zero() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        let live_state = live_state_context();
-        crate::test_support::seed_global_version_head(storage.clone()).await;
-        write_key_value(
-            storage.clone(),
-            DETERMINISTIC_MODE_KEY,
-            serde_json::json!({
-                "enabled": true,
-            }),
-        )
-        .await;
-
-        let reader = live_state.reader(storage.clone());
-        let context = FunctionContext::prepare(&reader)
-            .await
-            .expect("runtime context should prepare");
-        let functions = context.provider();
-
-        assert_eq!(
-            functions.call_uuid_v7(),
-            "01920000-0000-7000-8000-000000000000"
-        );
-        assert_eq!(functions.call_timestamp(), "1970-01-01T00:00:00.001Z");
-        assert_eq!(
-            context
-                .provider()
-                .deterministic_sequence_persist_highest_seen(),
-            Some(1)
-        );
-    }
-
-    #[tokio::test]
-    async fn prepare_continues_from_persisted_sequence() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        let live_state = live_state_context();
-        crate::test_support::seed_global_version_head(storage.clone()).await;
-        write_key_value(
-            storage.clone(),
-            DETERMINISTIC_MODE_KEY,
-            serde_json::json!({
-                "enabled": true,
-            }),
-        )
-        .await;
-        write_key_value(
-            storage.clone(),
-            DETERMINISTIC_SEQUENCE_KEY,
-            serde_json::json!(41),
-        )
-        .await;
-
-        let reader = live_state.reader(storage.clone());
-        let context = FunctionContext::prepare(&reader)
-            .await
-            .expect("runtime context should prepare");
-        let functions = context.provider();
-
-        assert_eq!(
-            functions.call_uuid_v7(),
-            "01920000-0000-7000-8000-00000000002a"
-        );
-        assert_eq!(
-            context
-                .provider()
-                .deterministic_sequence_persist_highest_seen(),
-            Some(42)
-        );
-    }
-
-    #[tokio::test]
-    async fn persist_if_needed_writes_sequence_when_deterministic_functions_advanced() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        let live_state = live_state_context();
-        crate::test_support::seed_global_version_head(storage.clone()).await;
-        write_key_value(
-            storage.clone(),
-            DETERMINISTIC_MODE_KEY,
-            serde_json::json!({
-                "enabled": true,
-            }),
-        )
-        .await;
-
-        let context = {
-            let reader = live_state.reader(storage.clone());
-            FunctionContext::prepare(&reader)
-                .await
-                .expect("runtime context should prepare")
-        };
-        context.provider().call_uuid_v7();
-
-        let mut tx = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        let mut writes = StorageWriteSet::new();
-        context
-            .stage_persist_if_needed(&mut writes)
-            .await
-            .expect("sequence should stage");
-        writes
-            .apply(&mut tx.as_mut())
-            .await
-            .expect("sequence should apply");
-        tx.commit().await.expect("transaction should commit");
-
-        let reader = live_state.reader(storage.clone());
-        let sequence = load_sequence(&reader).await.expect("sequence should load");
-        assert_eq!(sequence, DeterministicSequence { highest_seen: 0 });
-    }
-
-    #[tokio::test]
-    async fn persist_if_needed_is_noop_for_system_functions() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        let live_state = live_state_context();
-        let reader = live_state.reader(storage.clone());
-        let context = FunctionContext::prepare(&reader)
-            .await
-            .expect("runtime context should prepare");
-
-        let tx = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        let mut writes = StorageWriteSet::new();
-        context
-            .stage_persist_if_needed(&mut writes)
-            .await
-            .expect("persist should no-op");
-        assert!(writes.is_empty());
-        tx.commit().await.expect("transaction should commit");
-
-        let reader = live_state.reader(storage.clone());
-        let sequence = load_sequence(&reader)
-            .await
-            .expect("missing sequence should load");
-        assert_eq!(sequence, DeterministicSequence::uninitialized());
-    }
-
-    async fn write_key_value(storage: StorageContext, key: &str, value: serde_json::Value) {
-        let mut tx = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        let snapshot_content = serde_json::to_string(&serde_json::json!({
-            "key": key,
-            "value": value,
-        }))
-        .expect("snapshot should serialize");
-        let mut writes = StorageWriteSet::new();
-        let row = crate::untracked_state::UntrackedStateRow {
-            entity_id: crate::entity_identity::EntityIdentity::single(key),
-            schema_key: "lix_key_value".to_string(),
-            file_id: None,
-            snapshot_content: Some(snapshot_content),
-            metadata: None,
-            created_at: "1970-01-01T00:00:00.000Z".to_string(),
-            updated_at: "1970-01-01T00:00:00.000Z".to_string(),
-            global: true,
-            version_id: GLOBAL_VERSION_ID.to_string(),
-        };
-        crate::untracked_state::UntrackedStateContext::new()
-            .writer(&mut writes)
-            .stage_rows(std::iter::once(row.as_ref()))
-            .expect("test key-value should stage");
-        writes
-            .apply(&mut tx.as_mut())
-            .await
-            .expect("test key-value should apply");
-        tx.commit().await.expect("transaction should commit");
-    }
-}