@lix-js/sdk 0.6.0-preview.5 → 0.6.1

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

@@ -1,113 +0,0 @@
-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

@@ -1,18 +0,0 @@
-//! 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

@@ -1,130 +0,0 @@
-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

@@ -1,335 +0,0 @@
-use serde_json::Value as JsonValue;
-use std::sync::Arc;
-
-use crate::entity_pk::EntityPk;
-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_BRANCH_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(),
-            branch_id: GLOBAL_BRANCH_ID.to_string(),
-            entity_pk: EntityPk::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_pk: crate::entity_pk::EntityPk::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,
-        branch_id: GLOBAL_BRANCH_ID.to_string(),
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use crate::live_state::{LiveStateContext, LiveStateRowRequest};
-    use crate::storage::StorageContext;
-    use crate::storage::{InMemoryStorageBackend, StorageReadOptions, StorageWriteOptions};
-
-    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 storage = StorageContext::new(InMemoryStorageBackend::new());
-        let live_state = live_state_context();
-        let reader = live_state.reader(
-            storage
-                .begin_read(StorageReadOptions::default())
-                .expect("read should open"),
-        );
-
-        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 storage = StorageContext::new(InMemoryStorageBackend::new());
-        let live_state = live_state_context();
-        crate::test_support::seed_global_branch_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
-                .begin_read(StorageReadOptions::default())
-                .expect("read should open"),
-        );
-        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 storage = StorageContext::new(InMemoryStorageBackend::new());
-        let live_state = live_state_context();
-        let reader = live_state.reader(
-            storage
-                .begin_read(StorageReadOptions::default())
-                .expect("read should open"),
-        );
-
-        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 storage = StorageContext::new(InMemoryStorageBackend::new());
-        let live_state = live_state_context();
-        crate::test_support::seed_global_branch_head(storage.clone()).await;
-        write_test_key_value(
-            storage.clone(),
-            DETERMINISTIC_SEQUENCE_KEY,
-            serde_json::json!(41),
-        )
-        .await;
-
-        let reader = live_state.reader(
-            storage
-                .begin_read(StorageReadOptions::default())
-                .expect("read should open"),
-        );
-        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 storage = StorageContext::new(InMemoryStorageBackend::new());
-        let live_state = live_state_context();
-        crate::test_support::seed_global_branch_head(storage.clone()).await;
-
-        let mut writes = storage.new_write_set();
-        stage_sequence(
-            &mut writes,
-            DeterministicSequence { highest_seen: 7 },
-            "1970-01-01T00:00:00.000Z",
-        )
-        .await
-        .expect("sequence should stage");
-        storage
-            .commit_write_set(writes, StorageWriteOptions::default())
-            .expect("sequence should commit");
-
-        let reader = live_state.reader(
-            storage
-                .begin_read(StorageReadOptions::default())
-                .expect("read should open"),
-        );
-        let row = reader
-            .load_row(&LiveStateRowRequest {
-                schema_key: KEY_VALUE_SCHEMA_KEY.to_string(),
-                branch_id: GLOBAL_BRANCH_ID.to_string(),
-                entity_pk: crate::entity_pk::EntityPk::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 snapshot_content = serde_json::to_string(&serde_json::json!({
-            "key": key,
-            "value": value,
-        }))
-        .expect("snapshot should serialize");
-        let mut writes = storage.new_write_set();
-        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");
-        storage
-            .commit_write_set(writes, StorageWriteOptions::default())
-            .expect("test key-value should commit");
-    }
-}

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

@@ -1,37 +0,0 @@
-/// 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
-    }
-}