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

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

@@ -0,0 +1,113 @@
+use crate::functions::FunctionProvider;
+
+const DETERMINISTIC_UUID_COUNTER_MASK: u64 = 0x0000_FFFF_FFFF_FFFF;
+
+/// Deterministic function provider for engine execution.
+///
+/// The provider is pure runtime state: it does not load or persist the sequence
+/// itself. Session/transaction code owns that boundary so tests can decide when
+/// deterministic state is read and written.
+#[derive(Debug, Clone)]
+pub(crate) struct DeterministicFunctionProvider {
+    next_sequence: i64,
+    timestamp_shuffle: bool,
+    highest_seen: Option<i64>,
+}
+
+impl DeterministicFunctionProvider {
+    pub(crate) fn new(next_sequence: i64, timestamp_shuffle: bool) -> Self {
+        Self {
+            next_sequence,
+            timestamp_shuffle,
+            highest_seen: None,
+        }
+    }
+
+    pub(crate) fn highest_seen(&self) -> Option<i64> {
+        self.highest_seen
+    }
+
+    fn take_sequence(&mut self) -> i64 {
+        let current = self.next_sequence;
+        self.next_sequence += 1;
+        self.highest_seen = Some(current);
+        current
+    }
+}
+
+impl FunctionProvider for DeterministicFunctionProvider {
+    fn uuid_v7(&mut self) -> String {
+        let counter = self.take_sequence();
+        let counter_bits = (counter as u64) & DETERMINISTIC_UUID_COUNTER_MASK;
+        format!("01920000-0000-7000-8000-{counter_bits:012x}")
+    }
+
+    fn timestamp(&mut self) -> String {
+        let counter = self.take_sequence();
+        let millis = if self.timestamp_shuffle {
+            shuffled_timestamp_millis(counter)
+        } else {
+            counter
+        };
+        let dt = chrono::DateTime::<chrono::Utc>::from_timestamp_millis(millis)
+            .unwrap_or(chrono::DateTime::<chrono::Utc>::UNIX_EPOCH);
+        dt.to_rfc3339_opts(chrono::SecondsFormat::Millis, true)
+    }
+
+    fn deterministic_sequence_persist_highest_seen(&self) -> Option<i64> {
+        self.highest_seen()
+    }
+}
+
+fn shuffled_timestamp_millis(counter: i64) -> i64 {
+    const WINDOW: i64 = 1000;
+    const MULTIPLIER: i64 = 733;
+    const OFFSET: i64 = 271;
+
+    let cycle = counter.div_euclid(WINDOW);
+    let within = counter.rem_euclid(WINDOW);
+    let shuffled = (within * MULTIPLIER + OFFSET).rem_euclid(WINDOW);
+    cycle * WINDOW + shuffled
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::functions::DeterministicSequence;
+
+    #[test]
+    fn deterministic_uuid_uses_sequence_counter() {
+        let mut provider = DeterministicFunctionProvider::new(0, false);
+
+        assert_eq!(provider.uuid_v7(), "01920000-0000-7000-8000-000000000000");
+        assert_eq!(provider.uuid_v7(), "01920000-0000-7000-8000-000000000001");
+        assert_eq!(provider.highest_seen(), Some(1));
+    }
+
+    #[test]
+    fn deterministic_timestamp_uses_sequence_counter() {
+        let mut provider = DeterministicFunctionProvider::new(1, false);
+
+        assert_eq!(provider.timestamp(), "1970-01-01T00:00:00.001Z");
+        assert_eq!(provider.highest_seen(), Some(1));
+    }
+
+    #[test]
+    fn deterministic_timestamp_shuffle_can_be_non_monotonic() {
+        let mut provider = DeterministicFunctionProvider::new(0, true);
+        let first = provider.timestamp();
+        let second = provider.timestamp();
+
+        assert!(second < first);
+        assert_eq!(provider.highest_seen(), Some(1));
+    }
+
+    #[test]
+    fn deterministic_sequence_can_start_after_persisted_highest_seen() {
+        let sequence = DeterministicSequence { highest_seen: 41 };
+        let mut provider = DeterministicFunctionProvider::new(sequence.next_sequence(), false);
+
+        assert_eq!(provider.uuid_v7(), "01920000-0000-7000-8000-00000000002a");
+        assert_eq!(provider.highest_seen(), Some(42));
+    }
+}

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

@@ -0,0 +1,18 @@
+//! Engine runtime function boundary.
+//!
+//! Sessions prepare one function context per execution. SQL, providers, and
+//! transaction staging receive only a function provider; deterministic mode is
+//! resolved privately inside this module.
+
+mod context;
+mod deterministic;
+mod provider;
+mod state;
+mod types;
+
+pub(crate) use context::FunctionContext;
+pub(crate) use deterministic::DeterministicFunctionProvider;
+pub(crate) use provider::{
+    FunctionProvider, FunctionProviderHandle, SharedFunctionProvider, SystemFunctionProvider,
+};
+pub(crate) use types::{DeterministicMode, DeterministicSequence};

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

@@ -0,0 +1,130 @@
+use std::sync::{Arc, Mutex};
+
+use crate::cel::CelFunctionProvider;
+
+/// Engine-owned runtime function provider trait.
+pub(crate) trait FunctionProvider: Send {
+    fn uuid_v7(&mut self) -> String;
+    fn timestamp(&mut self) -> String;
+
+    fn deterministic_sequence_persist_highest_seen(&self) -> Option<i64> {
+        None
+    }
+}
+
+pub(crate) type FunctionProviderHandle = SharedFunctionProvider<Box<dyn FunctionProvider + Send>>;
+
+/// Shareable function provider used across SQL planning, UDFs, and staging.
+pub(crate) struct SharedFunctionProvider<P> {
+    inner: Arc<Mutex<P>>,
+}
+
+impl<P> Clone for SharedFunctionProvider<P> {
+    fn clone(&self) -> Self {
+        Self {
+            inner: Arc::clone(&self.inner),
+        }
+    }
+}
+
+impl<P> SharedFunctionProvider<P> {
+    pub(crate) fn new(provider: P) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(provider)),
+        }
+    }
+
+    fn with_lock<R>(&self, f: impl FnOnce(&P) -> R) -> R {
+        let guard = self
+            .inner
+            .lock()
+            .expect("engine function provider mutex poisoned");
+        f(&guard)
+    }
+
+    fn with_lock_mut<R>(&self, f: impl FnOnce(&mut P) -> R) -> R {
+        let mut guard = self
+            .inner
+            .lock()
+            .expect("engine function provider mutex poisoned");
+        f(&mut guard)
+    }
+}
+
+impl<P> SharedFunctionProvider<P>
+where
+    P: FunctionProvider,
+{
+    pub(crate) fn call_uuid_v7(&self) -> String {
+        self.with_lock_mut(|provider| provider.uuid_v7())
+    }
+
+    pub(crate) fn call_timestamp(&self) -> String {
+        self.with_lock_mut(|provider| provider.timestamp())
+    }
+
+    pub(crate) fn deterministic_sequence_persist_highest_seen(&self) -> Option<i64> {
+        self.with_lock(|provider| provider.deterministic_sequence_persist_highest_seen())
+    }
+}
+
+impl<P> CelFunctionProvider for SharedFunctionProvider<P>
+where
+    P: FunctionProvider + Send + 'static,
+{
+    fn call_uuid_v7(&self) -> String {
+        SharedFunctionProvider::call_uuid_v7(self)
+    }
+
+    fn call_timestamp(&self) -> String {
+        SharedFunctionProvider::call_timestamp(self)
+    }
+}
+
+impl<P> FunctionProvider for SharedFunctionProvider<P>
+where
+    P: FunctionProvider,
+{
+    fn uuid_v7(&mut self) -> String {
+        self.call_uuid_v7()
+    }
+
+    fn timestamp(&mut self) -> String {
+        self.call_timestamp()
+    }
+
+    fn deterministic_sequence_persist_highest_seen(&self) -> Option<i64> {
+        SharedFunctionProvider::deterministic_sequence_persist_highest_seen(self)
+    }
+}
+
+impl<T> FunctionProvider for Box<T>
+where
+    T: FunctionProvider + ?Sized,
+{
+    fn uuid_v7(&mut self) -> String {
+        (**self).uuid_v7()
+    }
+
+    fn timestamp(&mut self) -> String {
+        (**self).timestamp()
+    }
+
+    fn deterministic_sequence_persist_highest_seen(&self) -> Option<i64> {
+        (**self).deterministic_sequence_persist_highest_seen()
+    }
+}
+
+/// System-backed engine function provider.
+#[derive(Debug, Default, Clone, Copy)]
+pub(crate) struct SystemFunctionProvider;
+
+impl FunctionProvider for SystemFunctionProvider {
+    fn uuid_v7(&mut self) -> String {
+        uuid::Uuid::now_v7().to_string()
+    }
+
+    fn timestamp(&mut self) -> String {
+        chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Millis, true)
+    }
+}

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

@@ -0,0 +1,336 @@
+use serde_json::Value as JsonValue;
+use std::sync::Arc;
+
+use crate::entity_identity::EntityIdentity;
+use crate::functions::{DeterministicMode, DeterministicSequence};
+use crate::json_store::NormalizedJson;
+use crate::live_state::{LiveStateReader, LiveStateRowRequest, MaterializedLiveStateRow};
+use crate::storage::StorageWriteSet;
+use crate::untracked_state::UntrackedStateContext;
+use crate::untracked_state::UntrackedStateRow;
+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";
+
+/// 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(
+    writes: &mut StorageWriteSet,
+    sequence: DeterministicSequence,
+    timestamp: &str,
+) -> Result<(), LixError> {
+    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 snapshot = NormalizedJson::from_arc_unchecked(Arc::from(snapshot_content.as_str()));
+    let row =
+        deterministic_key_value_row(DETERMINISTIC_SEQUENCE_KEY, snapshot.as_str(), timestamp)?;
+    UntrackedStateContext::new()
+        .writer(writes)
+        .stage_rows(std::iter::once(row.as_ref()))
+}
+
+async fn load_key_value_row(
+    live_state: &dyn LiveStateReader,
+    key: &str,
+) -> Result<Option<MaterializedLiveStateRow>, 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: &MaterializedLiveStateRow, 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: &str,
+    timestamp: &str,
+) -> Result<UntrackedStateRow, LixError> {
+    Ok(UntrackedStateRow {
+        entity_id: crate::entity_identity::EntityIdentity::single(key),
+        schema_key: KEY_VALUE_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot_content: Some(snapshot_content.to_string()),
+        metadata: None,
+        created_at: timestamp.to_string(),
+        updated_at: timestamp.to_string(),
+        global: 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(),
+        )
+    }
+
+    #[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(),
+            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(),
+            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();
+        stage_sequence(
+            &mut writes,
+            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, 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 mut writes = StorageWriteSet::new();
+        let row = deterministic_key_value_row(key, &snapshot_content, "1970-01-01T00:00:00.000Z")
+            .expect("test key-value should canonicalize");
+        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");
+    }
+}

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 engine 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
+    }
+}