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

package/dist-engine-src/src/changelog/materialization.rs

@@ -1,121 +0,0 @@
-use crate::changelog::{CanonicalChange, MaterializedCanonicalChange};
-use crate::json_store::{JsonRef, JsonStoreReader, JsonStoreWriter};
-use crate::storage::{StorageReader, StorageWriteSet};
-use crate::{serialize_row_metadata, validate_row_metadata, LixError, RowMetadata};
-
-pub(crate) fn canonicalize_materialized_change(
-    writes: &mut StorageWriteSet,
-    json_writer: &mut JsonStoreWriter,
-    change: &MaterializedCanonicalChange,
-) -> Result<CanonicalChange, LixError> {
-    let snapshot_ref =
-        stage_optional_json(writes, json_writer, change.snapshot_content.as_deref())?;
-    let metadata_ref = stage_optional_metadata(writes, json_writer, change.metadata.as_ref())?;
-    Ok(CanonicalChange {
-        id: change.id.clone(),
-        entity_id: change.entity_id.clone(),
-        schema_key: change.schema_key.clone(),
-        schema_version: change.schema_version.clone(),
-        file_id: change.file_id.clone(),
-        snapshot_ref,
-        metadata_ref,
-        created_at: change.created_at.clone(),
-    })
-}
-
-pub(crate) async fn materialize_change<S>(
-    json_reader: &mut JsonStoreReader<S>,
-    change: CanonicalChange,
-) -> Result<MaterializedCanonicalChange, LixError>
-where
-    S: StorageReader,
-{
-    let snapshot_content =
-        load_optional_json(json_reader, change.snapshot_ref.as_ref(), "snapshot_ref").await?;
-    let metadata = load_optional_metadata(json_reader, change.metadata_ref.as_ref()).await?;
-    Ok(MaterializedCanonicalChange {
-        id: change.id,
-        entity_id: change.entity_id,
-        schema_key: change.schema_key,
-        schema_version: change.schema_version,
-        file_id: change.file_id,
-        snapshot_content,
-        metadata,
-        created_at: change.created_at,
-    })
-}
-
-fn stage_optional_json(
-    writes: &mut StorageWriteSet,
-    json_writer: &mut JsonStoreWriter,
-    value: Option<&str>,
-) -> Result<Option<JsonRef>, LixError> {
-    let Some(value) = value else {
-        return Ok(None);
-    };
-    json_writer.stage_bytes(writes, value.as_bytes()).map(Some)
-}
-
-fn stage_optional_metadata(
-    writes: &mut StorageWriteSet,
-    json_writer: &mut JsonStoreWriter,
-    value: Option<&RowMetadata>,
-) -> Result<Option<JsonRef>, LixError> {
-    let Some(value) = value else {
-        return Ok(None);
-    };
-    let serialized = serialize_row_metadata(value);
-    json_writer
-        .stage_bytes(writes, serialized.as_bytes())
-        .map(Some)
-}
-
-async fn load_optional_metadata<S>(
-    json_reader: &mut JsonStoreReader<S>,
-    json_ref: Option<&JsonRef>,
-) -> Result<Option<RowMetadata>, LixError>
-where
-    S: StorageReader,
-{
-    let Some(json) = load_optional_json(json_reader, json_ref, "metadata_ref").await? else {
-        return Ok(None);
-    };
-    let metadata = serde_json::from_str::<RowMetadata>(&json).map_err(|error| {
-        LixError::new(
-            "LIX_ERROR_INVALID_JSON",
-            format!("metadata_ref is invalid JSON: {error}"),
-        )
-    })?;
-    validate_row_metadata(metadata, "metadata_ref").map(Some)
-}
-
-async fn load_optional_json<S>(
-    json_reader: &mut JsonStoreReader<S>,
-    json_ref: Option<&JsonRef>,
-    field: &str,
-) -> Result<Option<String>, LixError>
-where
-    S: StorageReader,
-{
-    let Some(json_ref) = json_ref else {
-        return Ok(None);
-    };
-    let bytes = json_reader.load_bytes(json_ref).await?.ok_or_else(|| {
-        LixError::new(
-            "LIX_ERROR_UNKNOWN",
-            format!(
-                "changelog {field} '{}' is missing from json_store",
-                json_ref.to_hex()
-            ),
-        )
-    })?;
-    String::from_utf8(bytes).map(Some).map_err(|error| {
-        LixError::new(
-            "LIX_ERROR_UNKNOWN",
-            format!(
-                "changelog {field} '{}' is not valid UTF-8 JSON bytes: {error}",
-                json_ref.to_hex()
-            ),
-        )
-    })
-}

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

@@ -1,13 +0,0 @@
-pub(crate) mod codec;
-mod context;
-mod materialization;
-mod reader;
-mod storage;
-mod types;
-
-#[allow(unused_imports)]
-pub(crate) use context::{ChangelogContext, ChangelogStoreReader, ChangelogWriter};
-pub(crate) use materialization::{canonicalize_materialized_change, materialize_change};
-pub(crate) use reader::ChangelogReader;
-#[allow(unused_imports)]
-pub(crate) use types::{CanonicalChange, ChangelogScanRequest, MaterializedCanonicalChange};

package/dist-engine-src/src/changelog/reader.rs

@@ -1,20 +0,0 @@
-use async_trait::async_trait;
-
-use crate::changelog::{CanonicalChange, ChangelogScanRequest};
-use crate::LixError;
-
-/// Read side for immutable changelog facts.
-///
-/// SQL providers and commit-graph readers depend on this role instead of
-/// knowing which KV store backs the changelog for the current execution.
-#[async_trait]
-pub(crate) trait ChangelogReader: Send + Sync {
-    #[allow(dead_code)]
-    async fn load_change(&self, change_id: &str) -> Result<Option<CanonicalChange>, LixError>;
-
-    #[allow(dead_code)]
-    async fn scan_changes(
-        &self,
-        request: &ChangelogScanRequest,
-    ) -> Result<Vec<CanonicalChange>, LixError>;
-}

package/dist-engine-src/src/changelog/storage.rs

@@ -1,220 +0,0 @@
-use crate::changelog::codec::{decode_change, encode_change};
-use crate::changelog::{CanonicalChange, ChangelogScanRequest};
-use crate::storage::KvScanRange;
-use crate::storage::{KvGetGroup, KvGetRequest, KvScanRequest, StorageReader, StorageWriteSet};
-use crate::LixError;
-
-const CHANGELOG_CHANGE_NAMESPACE: &str = "changelog.change";
-
-pub(crate) async fn load_change(
-    store: &mut impl StorageReader,
-    change_id: &str,
-) -> Result<Option<CanonicalChange>, LixError> {
-    let bytes = store
-        .get_values(KvGetRequest {
-            groups: vec![KvGetGroup {
-                namespace: CHANGELOG_CHANGE_NAMESPACE.to_string(),
-                keys: vec![encode_change_key(change_id)],
-            }],
-        })
-        .await?
-        .groups
-        .into_iter()
-        .next()
-        .and_then(|group| group.single_value_owned());
-    let Some(bytes) = bytes else {
-        return Ok(None);
-    };
-    decode_change(&bytes).map(Some)
-}
-
-pub(crate) async fn scan_changes(
-    store: &mut impl StorageReader,
-    request: &ChangelogScanRequest,
-) -> Result<Vec<CanonicalChange>, LixError> {
-    // TODO(engine2): scan by a durable append sequence instead of change id.
-    // This first index is enough for exact lookup and deterministic debug scans.
-    let page = store
-        .scan_values(KvScanRequest {
-            namespace: CHANGELOG_CHANGE_NAMESPACE.to_string(),
-            range: KvScanRange::prefix(Vec::new()),
-            after: None,
-            limit: request.limit.unwrap_or(usize::MAX),
-        })
-        .await?;
-    page.values.iter().map(decode_change).collect()
-}
-
-pub(crate) fn stage_changes(
-    writes: &mut StorageWriteSet,
-    changes: &[CanonicalChange],
-) -> Result<(), LixError> {
-    for change in changes {
-        writes.put(
-            CHANGELOG_CHANGE_NAMESPACE,
-            encode_change_key(&change.id),
-            encode_change(change)?,
-        );
-    }
-    Ok(())
-}
-
-fn encode_change_key(change_id: &str) -> Vec<u8> {
-    change_id.as_bytes().to_vec()
-}
-
-#[cfg(test)]
-mod tests {
-    use std::sync::Arc;
-
-    use crate::backend::testing::UnitTestBackend;
-    use crate::changelog::{
-        canonicalize_materialized_change, materialize_change, ChangelogContext,
-        ChangelogScanRequest, MaterializedCanonicalChange,
-    };
-    use crate::json_store::JsonStoreContext;
-    use crate::storage::{StorageContext, StorageWriteSet, StorageWriteTransaction};
-
-    use super::*;
-
-    #[tokio::test]
-    async fn append_and_load_change_roundtrips() {
-        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
-        let changelog = ChangelogContext::new();
-        let change = test_change("change-1");
-
-        let mut tx = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        append_test_changes(&changelog, &mut tx, std::slice::from_ref(&change)).await;
-        tx.commit().await.expect("commit should succeed");
-
-        let loaded = load_test_change(&changelog, storage, "change-1").await;
-        assert_eq!(loaded, Some(change));
-    }
-
-    #[tokio::test]
-    async fn append_and_load_composite_entity_identity_roundtrips() {
-        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
-        let changelog = ChangelogContext::new();
-        let mut change = test_change("change-composite");
-        change.entity_id = crate::entity_identity::EntityIdentity::tuple(vec![
-            crate::entity_identity::EntityIdentityPart::String("entity".to_string()),
-            crate::entity_identity::EntityIdentityPart::Number("7".to_string()),
-            crate::entity_identity::EntityIdentityPart::Bool(true),
-        ])
-        .expect("composite identity should be valid");
-
-        let mut tx = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        append_test_changes(&changelog, &mut tx, std::slice::from_ref(&change)).await;
-        tx.commit().await.expect("commit should succeed");
-
-        let loaded = load_test_change(&changelog, storage, "change-composite").await;
-        assert_eq!(loaded, Some(change));
-    }
-
-    #[test]
-    fn decode_rejects_non_flatbuffer_bytes() {
-        let error = decode_change(br#"{"id":"change-json"}"#)
-            .expect_err("json changelog payloads are not accepted after the hard cut");
-        assert!(
-            error
-                .message
-                .contains("invalid FlatBuffers file identifier"),
-            "unexpected error: {error:?}"
-        );
-    }
-
-    #[tokio::test]
-    async fn scan_changes_respects_limit() {
-        let storage = StorageContext::new(Arc::new(UnitTestBackend::new()));
-        let changelog = ChangelogContext::new();
-        let mut tx = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        append_test_changes(
-            &changelog,
-            &mut tx,
-            &[test_change("change-1"), test_change("change-2")],
-        )
-        .await;
-        tx.commit().await.expect("commit should succeed");
-
-        let canonical_changes = {
-            let reader = changelog.reader(storage.clone());
-            reader
-                .scan_changes(&ChangelogScanRequest { limit: Some(1) })
-                .await
-        }
-        .expect("scan should succeed");
-        let mut json_reader = JsonStoreContext::new().reader(storage);
-        let mut changes = Vec::new();
-        for change in canonical_changes {
-            changes.push(
-                materialize_change(&mut json_reader, change)
-                    .await
-                    .expect("change should materialize"),
-            );
-        }
-        assert_eq!(changes, vec![test_change("change-1")]);
-    }
-
-    fn test_change(id: &str) -> MaterializedCanonicalChange {
-        MaterializedCanonicalChange {
-            id: id.to_string(),
-            entity_id: crate::entity_identity::EntityIdentity::single("entity-1"),
-            schema_key: "test_schema".to_string(),
-            schema_version: "1".to_string(),
-            file_id: None,
-            snapshot_content: Some("{\"value\":1}".to_string()),
-            metadata: None,
-            created_at: "2026-01-01T00:00:00Z".to_string(),
-        }
-    }
-
-    async fn append_test_changes(
-        changelog: &ChangelogContext,
-        tx: &mut Box<dyn StorageWriteTransaction + Send + Sync + 'static>,
-        changes: &[MaterializedCanonicalChange],
-    ) {
-        let mut writes = StorageWriteSet::new();
-        let mut json_writer = JsonStoreContext::new().writer();
-        let canonical_changes = changes
-            .iter()
-            .map(|change| canonicalize_materialized_change(&mut writes, &mut json_writer, change))
-            .collect::<Result<Vec<_>, _>>()
-            .expect("changes should canonicalize");
-        let mut writer = changelog.writer(&mut writes);
-        writer
-            .stage_changes(&canonical_changes)
-            .expect("append should succeed");
-        writes
-            .apply(&mut tx.as_mut())
-            .await
-            .expect("writes should apply");
-    }
-
-    async fn load_test_change(
-        changelog: &ChangelogContext,
-        storage: StorageContext,
-        change_id: &str,
-    ) -> Option<MaterializedCanonicalChange> {
-        let canonical = {
-            let reader = changelog.reader(storage.clone());
-            reader
-                .load_change(change_id)
-                .await
-                .expect("load should succeed")
-        }?;
-        let mut json_reader = JsonStoreContext::new().reader(storage);
-        materialize_change(&mut json_reader, canonical)
-            .await
-            .map(Some)
-            .expect("change should materialize")
-    }
-}

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

@@ -1,38 +0,0 @@
-use crate::entity_identity::EntityIdentity;
-use crate::json_store::JsonRef;
-use crate::RowMetadata;
-
-/// Immutable canonical change fact stored in the changelog.
-#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
-pub(crate) struct CanonicalChange {
-    pub(crate) id: String,
-    pub(crate) entity_id: EntityIdentity,
-    pub(crate) schema_key: String,
-    pub(crate) schema_version: String,
-    pub(crate) file_id: Option<String>,
-    pub(crate) snapshot_ref: Option<JsonRef>,
-    pub(crate) metadata_ref: Option<JsonRef>,
-    pub(crate) created_at: String,
-}
-
-/// Boundary shape for callers that still work with materialized JSON payloads.
-#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
-pub(crate) struct MaterializedCanonicalChange {
-    pub(crate) id: String,
-    pub(crate) entity_id: EntityIdentity,
-    pub(crate) schema_key: String,
-    pub(crate) schema_version: String,
-    pub(crate) file_id: Option<String>,
-    pub(crate) snapshot_content: Option<String>,
-    pub(crate) metadata: Option<RowMetadata>,
-    pub(crate) created_at: String,
-}
-
-/// Minimal changelog scan request.
-///
-/// TODO(engine2): add filters and append-order cursors once changelog storage
-/// has real append sequence keys.
-#[derive(Debug, Clone, Default, PartialEq, Eq)]
-pub(crate) struct ChangelogScanRequest {
-    pub(crate) limit: Option<usize>,
-}

package/dist-engine-src/src/schema/builtin/lix_change_set.json

@@ -1,18 +0,0 @@
-{
-  "x-lix-key": "lix_change_set",
-  "x-lix-version": "1",
-  "x-lix-primary-key": [
-    "/id"
-  ],
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "string",
-      "x-lix-default": "lix_uuid_v7()"
-    }
-  },
-  "required": [
-    "id"
-  ],
-  "additionalProperties": false
-}

package/dist-engine-src/src/schema/builtin/lix_change_set_element.json

@@ -1,75 +0,0 @@
-{
-  "x-lix-key": "lix_change_set_element",
-  "x-lix-version": "1",
-  "description": "Derived relational index mapping a change_set to the canonical changes introduced by its commit relative to the commit's first parent. Rebuildable from `lix_commit.change_ids` plus the referenced `lix_change` rows; the unique constraint enforces at most one change per (entity, schema, file) tuple within a single change_set.",
-  "x-lix-primary-key": [
-    "/change_set_id",
-    "/change_id"
-  ],
-  "x-lix-unique": [
-    [
-      "/change_set_id",
-      "/entity_id",
-      "/schema_key",
-      "/file_id"
-    ]
-  ],
-  "x-lix-foreign-keys": [
-    {
-      "properties": [
-        "/change_set_id"
-      ],
-      "references": {
-        "schemaKey": "lix_change_set",
-        "properties": [
-          "/id"
-        ]
-      }
-    },
-    {
-      "properties": [
-        "/change_id"
-      ],
-      "references": {
-        "schemaKey": "lix_change",
-        "properties": [
-          "/id"
-        ]
-      }
-    }
-  ],
-  "type": "object",
-  "properties": {
-    "change_set_id": {
-      "type": "string",
-      "description": "The change_set this element belongs to (references `lix_change_set.id`)."
-    },
-    "change_id": {
-      "type": "string",
-      "description": "The canonical change introduced/adopted by the change_set's commit (references `lix_change.id`)."
-    },
-    "entity_id": {
-      "type": "string",
-      "description": "Denormalized from the referenced `lix_change` for fast entity-scoped queries and to anchor the unique constraint."
-    },
-    "schema_key": {
-      "type": "string",
-      "description": "Denormalized schema identifier from the referenced `lix_change`; part of the per-change_set uniqueness tuple."
-    },
-    "file_id": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Denormalized file scope from the referenced `lix_change`; NULL for engine-internal entities. Part of the per-change_set uniqueness tuple."
-    }
-  },
-  "required": [
-    "change_set_id",
-    "change_id",
-    "entity_id",
-    "schema_key",
-    "file_id"
-  ],
-  "additionalProperties": false
-}

package/dist-engine-src/src/schema/builtin/lix_entity_label.json

@@ -1,63 +0,0 @@
-{
-  "x-lix-key": "lix_entity_label",
-  "x-lix-version": "1",
-  "x-lix-primary-key": [
-    "/entity_id",
-    "/schema_key",
-    "/file_id",
-    "/label_id"
-  ],
-  "x-lix-foreign-keys": [
-    {
-      "properties": [
-        "/entity_id",
-        "/schema_key",
-        "/file_id"
-      ],
-      "references": {
-        "schemaKey": "lix_state",
-        "properties": [
-          "/entity_id",
-          "/schema_key",
-          "/file_id"
-        ]
-      }
-    },
-    {
-      "properties": [
-        "/label_id"
-      ],
-      "references": {
-        "schemaKey": "lix_label",
-        "properties": [
-          "/id"
-        ]
-      }
-    }
-  ],
-  "type": "object",
-  "properties": {
-    "entity_id": {
-      "type": "string"
-    },
-    "schema_key": {
-      "type": "string"
-    },
-    "file_id": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "label_id": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "entity_id",
-    "schema_key",
-    "file_id",
-    "label_id"
-  ],
-  "additionalProperties": false
-}