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

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

@@ -0,0 +1,363 @@
+use serde_json::Value as JsonValue;
+
+use crate::entity_identity::EntityIdentity;
+use crate::functions::{DeterministicMode, DeterministicSequence};
+use crate::json_store::JsonStoreWriter;
+use crate::live_state::{LiveStateReader, LiveStateRow, LiveStateRowRequest, LiveStateWriter};
+use crate::storage::{StorageReader, StorageWriteSet};
+use crate::GLOBAL_VERSION_ID;
+use crate::{LixError, NullableKeyFilter};
+
+pub(crate) const DETERMINISTIC_MODE_KEY: &str = "lix_deterministic_mode";
+pub(crate) const DETERMINISTIC_SEQUENCE_KEY: &str = "lix_deterministic_sequence_number";
+
+const KEY_VALUE_SCHEMA_KEY: &str = "lix_key_value";
+const KEY_VALUE_SCHEMA_VERSION: &str = "1";
+
+/// Loads deterministic-mode settings from visible live state.
+///
+/// Missing mode means deterministic execution is disabled. Malformed mode rows
+/// are errors because they would make runtime function behavior ambiguous.
+pub(crate) async fn load_mode(
+    live_state: &dyn LiveStateReader,
+) -> Result<DeterministicMode, LixError> {
+    let Some(row) = load_key_value_row(live_state, DETERMINISTIC_MODE_KEY).await? else {
+        return Ok(DeterministicMode::disabled());
+    };
+    let value = key_value_payload(&row, DETERMINISTIC_MODE_KEY)?;
+    parse_mode_value(value)
+}
+
+/// Loads the persisted deterministic sequence position.
+///
+/// Missing sequence means no deterministic values have been produced yet, so
+/// execution starts at sequence zero.
+pub(crate) async fn load_sequence(
+    live_state: &dyn LiveStateReader,
+) -> Result<DeterministicSequence, LixError> {
+    let Some(row) = load_key_value_row(live_state, DETERMINISTIC_SEQUENCE_KEY).await? else {
+        return Ok(DeterministicSequence::uninitialized());
+    };
+    let value = key_value_payload(&row, DETERMINISTIC_SEQUENCE_KEY)?;
+    parse_sequence_value(value)
+}
+
+/// Persists the highest deterministic sequence value used by an execution.
+///
+/// The row is untracked global `lix_key_value` state: it is durable local
+/// runtime state, not a changelog fact.
+pub(crate) async fn stage_sequence<S>(
+    writer: &mut LiveStateWriter<S>,
+    writes: &mut StorageWriteSet,
+    json_writer: &mut JsonStoreWriter,
+    sequence: DeterministicSequence,
+    timestamp: &str,
+) -> Result<(), LixError>
+where
+    S: StorageReader,
+{
+    let snapshot_content = serde_json::to_string(&serde_json::json!({
+        "key": DETERMINISTIC_SEQUENCE_KEY,
+        "value": sequence.highest_seen,
+    }))
+    .map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("deterministic sequence snapshot serialization failed: {error}"),
+        )
+    })?;
+    let row = deterministic_key_value_row(
+        DETERMINISTIC_SEQUENCE_KEY,
+        snapshot_content,
+        timestamp.to_string(),
+    );
+    writer.stage_rows(writes, json_writer, &[row]).await
+}
+
+async fn load_key_value_row(
+    live_state: &dyn LiveStateReader,
+    key: &str,
+) -> Result<Option<LiveStateRow>, LixError> {
+    live_state
+        .load_row(&LiveStateRowRequest {
+            schema_key: KEY_VALUE_SCHEMA_KEY.to_string(),
+            version_id: GLOBAL_VERSION_ID.to_string(),
+            entity_id: EntityIdentity::single(key),
+            file_id: NullableKeyFilter::Null,
+        })
+        .await
+}
+
+fn key_value_payload(row: &LiveStateRow, key: &str) -> Result<JsonValue, LixError> {
+    let snapshot_content = row.snapshot_content.as_deref().ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("deterministic key-value row '{key}' is missing snapshot_content"),
+        )
+    })?;
+    let snapshot = serde_json::from_str::<JsonValue>(snapshot_content).map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("deterministic key-value row '{key}' has invalid JSON: {error}"),
+        )
+    })?;
+    let stored_key = snapshot.get("key").and_then(JsonValue::as_str);
+    if stored_key != Some(key) {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("deterministic key-value row '{key}' has mismatched key field"),
+        ));
+    }
+    snapshot.get("value").cloned().ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("deterministic key-value row '{key}' is missing value"),
+        )
+    })
+}
+
+fn parse_mode_value(value: JsonValue) -> Result<DeterministicMode, LixError> {
+    let Some(object) = value.as_object() else {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "deterministic mode value must be an object",
+        ));
+    };
+
+    let enabled = object
+        .get("enabled")
+        .and_then(JsonValue::as_bool)
+        .unwrap_or(false);
+    if !enabled {
+        return Ok(DeterministicMode::disabled());
+    }
+    let timestamp_shuffle = object
+        .get("timestamp_shuffle")
+        .and_then(JsonValue::as_bool)
+        .unwrap_or(false);
+    Ok(DeterministicMode {
+        enabled,
+        timestamp_shuffle,
+    })
+}
+
+fn parse_sequence_value(value: JsonValue) -> Result<DeterministicSequence, LixError> {
+    let Some(highest_seen) = value.as_i64() else {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "deterministic sequence value must be an integer",
+        ));
+    };
+    Ok(DeterministicSequence { highest_seen })
+}
+
+fn deterministic_key_value_row(
+    key: &str,
+    snapshot_content: String,
+    timestamp: String,
+) -> LiveStateRow {
+    LiveStateRow {
+        entity_id: crate::entity_identity::EntityIdentity::single(key),
+        schema_key: KEY_VALUE_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot_content: Some(snapshot_content),
+        metadata: None,
+        schema_version: KEY_VALUE_SCHEMA_VERSION.to_string(),
+        created_at: timestamp.clone(),
+        updated_at: timestamp,
+        global: true,
+        change_id: None,
+        commit_id: None,
+        untracked: true,
+        version_id: GLOBAL_VERSION_ID.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use crate::backend::testing::UnitTestBackend;
+    use crate::live_state::{LiveStateContext, LiveStateRowRequest};
+    use crate::storage::StorageContext;
+
+    use super::*;
+
+    fn live_state_context() -> LiveStateContext {
+        LiveStateContext::new(
+            crate::tracked_state::TrackedStateContext::new(),
+            crate::untracked_state::UntrackedStateContext::new(),
+            crate::commit_graph::CommitGraphContext::new(crate::changelog::ChangelogContext::new()),
+        )
+    }
+
+    #[tokio::test]
+    async fn missing_mode_is_disabled() {
+        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 mode = load_mode(&reader)
+            .await
+            .expect("missing mode should decode");
+
+        assert_eq!(mode, DeterministicMode::disabled());
+    }
+
+    #[tokio::test]
+    async fn valid_mode_decodes_flags() {
+        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_test_key_value(
+            storage.clone(),
+            &live_state,
+            DETERMINISTIC_MODE_KEY,
+            serde_json::json!({
+                "enabled": true,
+                "timestamp_shuffle": true,
+            }),
+        )
+        .await;
+
+        let reader = live_state.reader(storage.clone());
+        let mode = load_mode(&reader).await.expect("valid mode should decode");
+
+        assert_eq!(
+            mode,
+            DeterministicMode {
+                enabled: true,
+                timestamp_shuffle: true,
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn missing_sequence_is_uninitialized() {
+        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 sequence = load_sequence(&reader)
+            .await
+            .expect("missing sequence should decode");
+
+        assert_eq!(sequence, DeterministicSequence::uninitialized());
+    }
+
+    #[tokio::test]
+    async fn valid_sequence_decodes_highest_seen() {
+        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_test_key_value(
+            storage.clone(),
+            &live_state,
+            DETERMINISTIC_SEQUENCE_KEY,
+            serde_json::json!(41),
+        )
+        .await;
+
+        let reader = live_state.reader(storage.clone());
+        let sequence = load_sequence(&reader)
+            .await
+            .expect("valid sequence should decode");
+
+        assert_eq!(sequence, DeterministicSequence { highest_seen: 41 });
+        assert_eq!(sequence.next_sequence(), 42);
+    }
+
+    #[tokio::test]
+    async fn write_sequence_persists_untracked_global_key_value() {
+        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;
+        let mut tx = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+
+        let mut writes = StorageWriteSet::new();
+        let mut json_writer = crate::json_store::JsonStoreContext::new().writer();
+        {
+            let mut writer = live_state.writer(tx.as_mut());
+            stage_sequence(
+                &mut writer,
+                &mut writes,
+                &mut json_writer,
+                DeterministicSequence { highest_seen: 7 },
+                "1970-01-01T00:00:00.000Z",
+            )
+            .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 row = reader
+            .load_row(&LiveStateRowRequest {
+                schema_key: KEY_VALUE_SCHEMA_KEY.to_string(),
+                version_id: GLOBAL_VERSION_ID.to_string(),
+                entity_id: crate::entity_identity::EntityIdentity::single(
+                    DETERMINISTIC_SEQUENCE_KEY,
+                ),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await
+            .expect("sequence row should load")
+            .expect("sequence row should exist");
+        assert!(row.untracked);
+        assert!(row.global);
+        assert_eq!(row.change_id, None);
+        assert_eq!(row.commit_id, None);
+        assert_eq!(
+            row.snapshot_content.as_deref(),
+            Some("{\"key\":\"lix_deterministic_sequence_number\",\"value\":7}")
+        );
+    }
+
+    async fn write_test_key_value(
+        storage: StorageContext,
+        live_state: &LiveStateContext,
+        key: &str,
+        value: JsonValue,
+    ) {
+        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 row = deterministic_key_value_row(
+            key,
+            snapshot_content,
+            "1970-01-01T00:00:00.000Z".to_string(),
+        );
+        let mut writes = StorageWriteSet::new();
+        let mut json_writer = crate::json_store::JsonStoreContext::new().writer();
+        {
+            let mut writer = live_state.writer(tx.as_mut());
+            writer
+                .stage_rows(&mut writes, &mut json_writer, &[row])
+                .await
+                .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");
+    }
+}

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

@@ -0,0 +1,37 @@
+/// Decoded deterministic-mode setting.
+///
+/// Storage can decide where this setting lives. The type only describes the
+/// behavior engine2 should apply while preparing runtime functions.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct DeterministicMode {
+    pub(crate) enabled: bool,
+    pub(crate) timestamp_shuffle: bool,
+}
+
+impl DeterministicMode {
+    pub(crate) fn disabled() -> Self {
+        Self {
+            enabled: false,
+            timestamp_shuffle: false,
+        }
+    }
+}
+
+/// Persisted deterministic sequence position.
+///
+/// `highest_seen` is the last sequence value returned by the runtime provider.
+/// The next deterministic execution starts at `highest_seen + 1`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct DeterministicSequence {
+    pub(crate) highest_seen: i64,
+}
+
+impl DeterministicSequence {
+    pub(crate) fn uninitialized() -> Self {
+        Self { highest_seen: -1 }
+    }
+
+    pub(crate) fn next_sequence(self) -> i64 {
+        self.highest_seen + 1
+    }
+}