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

package/dist-engine-src/src/version/refs.rs

@@ -0,0 +1,421 @@
+use std::sync::Arc;
+
+use serde_json::json;
+use tokio::sync::Mutex;
+
+use crate::entity_identity::EntityIdentity;
+use crate::json_store::JsonStoreWriter;
+use crate::storage::{StorageReader, StorageWriteSet};
+use crate::untracked_state::{
+    canonicalize_materialized_row, MaterializedUntrackedStateRow, UntrackedStateContext,
+    UntrackedStateFilter, UntrackedStateRow, UntrackedStateRowRequest, UntrackedStateScanRequest,
+};
+use crate::version::{VersionHead, VersionRefReader};
+use crate::version::{VERSION_REF_SCHEMA_KEY, VERSION_REF_SCHEMA_VERSION};
+use crate::GLOBAL_VERSION_ID;
+use crate::{LixError, NullableKeyFilter};
+
+/// Typed access to moving version heads stored in untracked state.
+///
+/// Version refs are one of the inputs used by live_state visibility, so this
+/// context deliberately bypasses live_state and reads the underlying untracked
+/// rows directly. That keeps the dependency acyclic:
+/// untracked_state -> version_ref -> live_state.
+pub(super) struct VersionRefContext {
+    untracked_state: Arc<UntrackedStateContext>,
+}
+
+impl VersionRefContext {
+    pub(super) fn new(untracked_state: Arc<UntrackedStateContext>) -> Self {
+        Self { untracked_state }
+    }
+
+    /// Creates a version-ref reader over a caller-provided KV store.
+    pub(super) fn reader<S>(&self, store: S) -> VersionRefStoreReader<S>
+    where
+        S: StorageReader,
+    {
+        VersionRefStoreReader {
+            untracked_state: Arc::clone(&self.untracked_state),
+            store: Mutex::new(store),
+        }
+    }
+
+    /// Creates a version-ref writer over a transaction-local storage write set.
+    pub(super) fn writer<'a>(&self, writes: &'a mut StorageWriteSet) -> VersionRefWriter<'a> {
+        VersionRefWriter {
+            untracked_state: Arc::clone(&self.untracked_state),
+            writes,
+        }
+    }
+}
+
+/// Read side for version heads.
+pub(super) struct VersionRefStoreReader<S>
+where
+    S: StorageReader,
+{
+    untracked_state: Arc<UntrackedStateContext>,
+    store: Mutex<S>,
+}
+
+impl<S> VersionRefStoreReader<S>
+where
+    S: StorageReader,
+{
+    pub(crate) async fn load_head(
+        &self,
+        version_id: &str,
+    ) -> Result<Option<VersionHead>, LixError> {
+        let mut store = self.store.lock().await;
+        let Some(row) = self
+            .untracked_state
+            .reader(&mut *store as &mut dyn StorageReader)
+            .load_row(&UntrackedStateRowRequest {
+                schema_key: VERSION_REF_SCHEMA_KEY.to_string(),
+                version_id: GLOBAL_VERSION_ID.to_string(),
+                entity_id: EntityIdentity::single(version_id),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await?
+        else {
+            return Ok(None);
+        };
+
+        decode_version_head(version_id, &row)
+    }
+
+    pub(crate) async fn load_head_commit_id(
+        &self,
+        version_id: &str,
+    ) -> Result<Option<String>, LixError> {
+        Ok(self.load_head(version_id).await?.map(|head| head.commit_id))
+    }
+
+    pub(crate) async fn scan_heads(&self) -> Result<Vec<VersionHead>, LixError> {
+        let mut store = self.store.lock().await;
+        let rows = self
+            .untracked_state
+            .reader(&mut *store as &mut dyn StorageReader)
+            .scan_rows(&UntrackedStateScanRequest {
+                filter: UntrackedStateFilter {
+                    schema_keys: vec![VERSION_REF_SCHEMA_KEY.to_string()],
+                    version_ids: vec![GLOBAL_VERSION_ID.to_string()],
+                    ..UntrackedStateFilter::default()
+                },
+                ..UntrackedStateScanRequest::default()
+            })
+            .await?;
+        let mut heads = rows
+            .iter()
+            .map(|row| {
+                let version_id = row.entity_id.as_string()?;
+                decode_version_head(&version_id, row)
+            })
+            .collect::<Result<Vec<_>, _>>()?
+            .into_iter()
+            .flatten()
+            .collect::<Vec<_>>();
+        heads.sort_by(|left, right| left.version_id.cmp(&right.version_id));
+        Ok(heads)
+    }
+}
+
+#[async_trait::async_trait]
+impl<S> VersionRefReader for VersionRefStoreReader<S>
+where
+    S: StorageReader + Send,
+{
+    async fn load_head(&self, version_id: &str) -> Result<Option<VersionHead>, LixError> {
+        VersionRefStoreReader::load_head(self, version_id).await
+    }
+
+    async fn load_head_commit_id(&self, version_id: &str) -> Result<Option<String>, LixError> {
+        VersionRefStoreReader::load_head_commit_id(self, version_id).await
+    }
+
+    async fn scan_heads(&self) -> Result<Vec<VersionHead>, LixError> {
+        VersionRefStoreReader::scan_heads(self).await
+    }
+}
+
+/// Write side for moving version heads.
+pub(super) struct VersionRefWriter<'a> {
+    untracked_state: Arc<UntrackedStateContext>,
+    writes: &'a mut StorageWriteSet,
+}
+
+impl VersionRefWriter<'_> {
+    pub(crate) fn stage_rows(&mut self, rows: &[UntrackedStateRow]) -> Result<(), LixError> {
+        self.untracked_state.writer(self.writes).stage_rows(rows)
+    }
+}
+
+pub(super) fn canonical_version_ref_row(
+    writes: &mut StorageWriteSet,
+    json_writer: &mut JsonStoreWriter,
+    version_id: &str,
+    commit_id: &str,
+    timestamp: &str,
+) -> Result<UntrackedStateRow, LixError> {
+    let row = version_ref_row(version_id, commit_id, timestamp)?;
+    canonicalize_materialized_row(writes, json_writer, &row)
+}
+
+fn decode_version_head(
+    requested_version_id: &str,
+    row: &MaterializedUntrackedStateRow,
+) -> Result<Option<VersionHead>, LixError> {
+    let Some(snapshot_content) = row.snapshot_content.as_deref() else {
+        return Ok(None);
+    };
+    let snapshot =
+        serde_json::from_str::<serde_json::Value>(snapshot_content).map_err(|error| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("engine2 version-ref snapshot parse failed: {error}"),
+            )
+        })?;
+    let commit_id = snapshot
+        .get("commit_id")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("version ref for version '{requested_version_id}' is missing commit_id"),
+            )
+        })?;
+    Ok(Some(VersionHead {
+        version_id: requested_version_id.to_string(),
+        commit_id: commit_id.to_string(),
+    }))
+}
+
+fn version_ref_row(
+    version_id: &str,
+    commit_id: &str,
+    timestamp: &str,
+) -> Result<MaterializedUntrackedStateRow, LixError> {
+    let snapshot_content = serde_json::to_string(&json!({
+        "id": version_id,
+        "commit_id": commit_id,
+    }))
+    .map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("engine2 version-ref snapshot serialization failed: {error}"),
+        )
+    })?;
+
+    Ok(MaterializedUntrackedStateRow {
+        entity_id: crate::entity_identity::EntityIdentity::single(version_id),
+        schema_key: VERSION_REF_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot_content: Some(snapshot_content),
+        metadata: None,
+        schema_version: VERSION_REF_SCHEMA_VERSION.to_string(),
+        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::json_store::JsonStoreContext;
+    use crate::storage::{StorageContext, StorageWriteSet};
+    use crate::untracked_state::{
+        canonicalize_materialized_row, UntrackedStateContext, UntrackedStateRowRequest,
+    };
+
+    use super::*;
+
+    #[tokio::test]
+    async fn load_head_returns_none_when_missing() {
+        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
+        let version_ref = test_version_ref();
+
+        let head = version_ref
+            .reader(storage)
+            .load_head("missing-version")
+            .await
+            .expect("missing version ref should load cleanly");
+
+        assert_eq!(head, None);
+    }
+
+    #[tokio::test]
+    async fn advance_head_writes_untracked_global_ref() {
+        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
+        let version_ref = VersionRefContext::new(Arc::new(UntrackedStateContext::new()));
+        let mut transaction = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+
+        let mut writes = StorageWriteSet::new();
+        stage_version_head(
+            &version_ref,
+            &mut writes,
+            "version-a",
+            "commit-a",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("version head should advance");
+        writes
+            .apply(&mut transaction.as_mut())
+            .await
+            .expect("version head should apply");
+        transaction
+            .commit()
+            .await
+            .expect("transaction should commit");
+
+        let head = version_ref
+            .reader(storage.clone())
+            .load_head("version-a")
+            .await
+            .expect("version head should load")
+            .expect("version head should exist");
+        assert_eq!(head.version_id, "version-a");
+        assert_eq!(head.commit_id, "commit-a");
+
+        let mut reader = UntrackedStateContext::new().reader(storage);
+        let row = reader
+            .load_row(&UntrackedStateRowRequest {
+                schema_key: VERSION_REF_SCHEMA_KEY.to_string(),
+                version_id: GLOBAL_VERSION_ID.to_string(),
+                entity_id: crate::entity_identity::EntityIdentity::single("version-a"),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await
+            .expect("version-ref row should load")
+            .expect("version-ref row should exist");
+        assert!(row.global);
+        assert_eq!(row.created_at, "2026-01-01T00:00:00Z");
+        assert_eq!(row.updated_at, "2026-01-01T00:00:00Z");
+    }
+
+    #[tokio::test]
+    async fn scan_heads_returns_sorted_version_heads() {
+        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
+        let version_ref = test_version_ref();
+        let mut transaction = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+
+        let mut writes = StorageWriteSet::new();
+        stage_version_head(
+            &version_ref,
+            &mut writes,
+            "version-b",
+            "commit-b",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("version-b should advance");
+        stage_version_head(
+            &version_ref,
+            &mut writes,
+            "version-a",
+            "commit-a",
+            "2026-01-01T00:00:00Z",
+        )
+        .expect("version-a should advance");
+        writes
+            .apply(&mut transaction.as_mut())
+            .await
+            .expect("version heads should apply");
+        transaction
+            .commit()
+            .await
+            .expect("transaction should commit");
+
+        let heads = version_ref
+            .reader(storage)
+            .scan_heads()
+            .await
+            .expect("heads should scan");
+
+        assert_eq!(
+            heads,
+            vec![
+                VersionHead {
+                    version_id: "version-a".to_string(),
+                    commit_id: "commit-a".to_string(),
+                },
+                VersionHead {
+                    version_id: "version-b".to_string(),
+                    commit_id: "commit-b".to_string(),
+                },
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn malformed_snapshot_errors_clearly() {
+        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
+        let untracked_state = UntrackedStateContext::new();
+        let version_ref = VersionRefContext::new(Arc::new(UntrackedStateContext::new()));
+        let mut transaction = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+        let mut row = version_ref_row("version-b", "commit-b", "2026-01-01T00:00:00Z")
+            .expect("version-ref row should plan");
+        row.snapshot_content = Some("{not-json".to_string());
+        let mut writes = StorageWriteSet::new();
+        let canonical_row = {
+            let mut json_writer = JsonStoreContext::new().writer();
+            canonicalize_materialized_row(&mut writes, &mut json_writer, &row)
+                .expect("malformed row should canonicalize for test setup")
+        };
+        untracked_state
+            .writer(&mut writes)
+            .stage_rows(&[canonical_row])
+            .expect("malformed row should write for test setup");
+        writes
+            .apply(&mut transaction.as_mut())
+            .await
+            .expect("malformed row should apply for test setup");
+        transaction
+            .commit()
+            .await
+            .expect("transaction should commit");
+
+        let error = version_ref
+            .reader(storage)
+            .load_head("version-b")
+            .await
+            .expect_err("malformed snapshot should error");
+
+        assert!(
+            error
+                .message
+                .contains("engine2 version-ref snapshot parse failed"),
+            "unexpected error: {error:?}"
+        );
+    }
+
+    fn test_version_ref() -> VersionRefContext {
+        VersionRefContext::new(Arc::new(UntrackedStateContext::new()))
+    }
+
+    fn stage_version_head(
+        version_ref: &VersionRefContext,
+        writes: &mut StorageWriteSet,
+        version_id: &str,
+        commit_id: &str,
+        timestamp: &str,
+    ) -> Result<(), LixError> {
+        let canonical_row = {
+            let mut json_writer = JsonStoreContext::new().writer();
+            canonical_version_ref_row(writes, &mut json_writer, version_id, commit_id, timestamp)?
+        };
+        version_ref.writer(writes).stage_rows(&[canonical_row])
+    }
+}

package/dist-engine-src/src/version/stage_rows.rs

@@ -0,0 +1,71 @@
+use serde_json::json;
+
+use crate::entity_identity::EntityIdentity;
+use crate::transaction::types::StageRow;
+use crate::GLOBAL_VERSION_ID;
+
+pub(crate) const VERSION_DESCRIPTOR_SCHEMA_KEY: &str = "lix_version_descriptor";
+pub(crate) const VERSION_DESCRIPTOR_SCHEMA_VERSION: &str = "1";
+pub(crate) const VERSION_REF_SCHEMA_KEY: &str = "lix_version_ref";
+pub(crate) const VERSION_REF_SCHEMA_VERSION: &str = "1";
+
+pub(crate) fn version_descriptor_stage_row(version_id: &str, name: &str, hidden: bool) -> StageRow {
+    StageRow {
+        entity_id: Some(EntityIdentity::single(version_id)),
+        schema_key: VERSION_DESCRIPTOR_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot_content: Some(encode_snapshot(json!({
+            "id": version_id,
+            "name": name,
+            "hidden": hidden,
+        }))),
+        metadata: None,
+        origin: None,
+        schema_version: VERSION_DESCRIPTOR_SCHEMA_VERSION.to_string(),
+        created_at: None,
+        updated_at: None,
+        global: true,
+        change_id: None,
+        commit_id: None,
+        untracked: false,
+        version_id: GLOBAL_VERSION_ID.to_string(),
+    }
+}
+
+pub(crate) fn version_ref_stage_row(version_id: &str, commit_id: &str) -> StageRow {
+    StageRow {
+        entity_id: Some(EntityIdentity::single(version_id)),
+        schema_key: VERSION_REF_SCHEMA_KEY.to_string(),
+        file_id: None,
+        snapshot_content: Some(encode_snapshot(json!({
+            "id": version_id,
+            "commit_id": commit_id,
+        }))),
+        metadata: None,
+        origin: None,
+        schema_version: VERSION_REF_SCHEMA_VERSION.to_string(),
+        created_at: None,
+        updated_at: None,
+        global: true,
+        change_id: None,
+        commit_id: None,
+        untracked: true,
+        version_id: GLOBAL_VERSION_ID.to_string(),
+    }
+}
+
+pub(crate) fn version_descriptor_tombstone_row(version_id: &str) -> StageRow {
+    let mut row = version_descriptor_stage_row(version_id, "", false);
+    row.snapshot_content = None;
+    row
+}
+
+pub(crate) fn version_ref_tombstone_row(version_id: &str) -> StageRow {
+    let mut row = version_ref_stage_row(version_id, "");
+    row.snapshot_content = None;
+    row
+}
+
+fn encode_snapshot(value: serde_json::Value) -> String {
+    serde_json::to_string(&value).expect("version snapshot should be serializable")
+}

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

@@ -0,0 +1,21 @@
+/// Current changelog head for a version.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct VersionHead {
+    pub(crate) version_id: String,
+    pub(crate) commit_id: String,
+}
+
+/// Typed reader for moving version heads.
+#[async_trait::async_trait]
+pub(crate) trait VersionRefReader: Send + Sync {
+    async fn load_head(&self, version_id: &str) -> Result<Option<VersionHead>, crate::LixError>;
+
+    async fn load_head_commit_id(
+        &self,
+        version_id: &str,
+    ) -> Result<Option<String>, crate::LixError> {
+        Ok(self.load_head(version_id).await?.map(|head| head.commit_id))
+    }
+
+    async fn scan_heads(&self) -> Result<Vec<VersionHead>, crate::LixError>;
+}

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

@@ -0,0 +1,60 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use crate::LixError;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WasmLimits {
+    pub max_memory_bytes: u64,
+    pub max_fuel: Option<u64>,
+    pub timeout_ms: Option<u64>,
+}
+
+impl Default for WasmLimits {
+    fn default() -> Self {
+        Self {
+            max_memory_bytes: 64 * 1024 * 1024,
+            max_fuel: None,
+            timeout_ms: None,
+        }
+    }
+}
+
+#[async_trait(?Send)]
+pub trait WasmRuntime: Send + Sync {
+    async fn init_component(
+        &self,
+        bytes: Vec<u8>,
+        limits: WasmLimits,
+    ) -> Result<Arc<dyn WasmComponentInstance>, LixError>;
+}
+
+#[async_trait(?Send)]
+pub trait WasmComponentInstance: Send + Sync {
+    async fn call(&self, export: &str, input: &[u8]) -> Result<Vec<u8>, LixError>;
+
+    async fn close(&self) -> Result<(), LixError> {
+        Ok(())
+    }
+}
+
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopWasmRuntime;
+
+#[async_trait(?Send)]
+impl WasmRuntime for NoopWasmRuntime {
+    async fn init_component(
+        &self,
+        _bytes: Vec<u8>,
+        _limits: WasmLimits,
+    ) -> Result<Arc<dyn WasmComponentInstance>, LixError> {
+        Err(LixError {
+            code: "LIX_ERROR_UNKNOWN".to_string(),
+            message: "wasm runtime is required to execute plugins; provide a non-noop runtime"
+                .to_string(),
+            hint: None,
+            details: None,
+        })
+    }
+}