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

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

@@ -0,0 +1,327 @@
+use crate::functions::{
+    state, DeterministicFunctionProvider, DeterministicSequence, FunctionProvider,
+    FunctionProviderHandle, SharedFunctionProvider, SystemFunctionProvider,
+};
+use crate::json_store::JsonStoreWriter;
+use crate::live_state::{LiveStateReader, LiveStateWriter};
+use crate::storage::{StorageReader, 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 engine2-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<S>(
+        &self,
+        writer: &mut LiveStateWriter<S>,
+        writes: &mut StorageWriteSet,
+        json_writer: &mut JsonStoreWriter,
+    ) -> Result<(), LixError>
+    where
+        S: StorageReader,
+    {
+        let Some(highest_seen) = self.functions.deterministic_sequence_persist_highest_seen()
+        else {
+            return Ok(());
+        };
+        state::stage_sequence(
+            writer,
+            writes,
+            json_writer,
+            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, LiveStateRow};
+    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(crate::changelog::ChangelogContext::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(),
+            &live_state,
+            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(),
+            &live_state,
+            DETERMINISTIC_MODE_KEY,
+            serde_json::json!({
+                "enabled": true,
+            }),
+        )
+        .await;
+        write_key_value(
+            storage.clone(),
+            &live_state,
+            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(),
+            &live_state,
+            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();
+        let mut json_writer = crate::json_store::JsonStoreContext::new().writer();
+        context
+            .stage_persist_if_needed(
+                &mut live_state.writer(tx.as_mut()),
+                &mut writes,
+                &mut json_writer,
+            )
+            .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 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();
+        context
+            .stage_persist_if_needed(
+                &mut live_state.writer(tx.as_mut()),
+                &mut writes,
+                &mut json_writer,
+            )
+            .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,
+        live_state: &LiveStateContext,
+        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 row = LiveStateRow {
+            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,
+            schema_version: "1".to_string(),
+            created_at: "1970-01-01T00:00:00.000Z".to_string(),
+            updated_at: "1970-01-01T00:00:00.000Z".to_string(),
+            global: true,
+            change_id: None,
+            commit_id: None,
+            untracked: true,
+            version_id: GLOBAL_VERSION_ID.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/deterministic.rs

@@ -0,0 +1,113 @@
+use crate::functions::FunctionProvider;
+
+const DETERMINISTIC_UUID_COUNTER_MASK: u64 = 0x0000_FFFF_FFFF_FFFF;
+
+/// Deterministic function provider for engine2 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 @@
+//! Engine2 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;
+
+/// Engine2-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("engine2 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("engine2 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 engine2 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)
+    }
+}