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

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

@@ -0,0 +1,348 @@
+use crate::json_store::JsonStoreContext;
+use crate::storage::KvScanRange;
+use crate::storage::{KvGetGroup, KvGetRequest, KvScanRequest, StorageReader, StorageWriteSet};
+use crate::untracked_state::{
+    MaterializedUntrackedStateRow, UntrackedMaterializationProjection, UntrackedStateIdentity,
+    UntrackedStateRow, UntrackedStateRowRequest, UntrackedStateScanRequest,
+};
+use crate::{LixError, NullableKeyFilter};
+
+const UNTRACKED_STATE_ROW_NAMESPACE: &str = "untracked_state.row";
+
+pub(crate) async fn scan_rows(
+    store: &mut impl StorageReader,
+    request: &UntrackedStateScanRequest,
+) -> Result<Vec<MaterializedUntrackedStateRow>, LixError> {
+    let mut rows = scan_all_canonical_rows(store).await?;
+    rows.retain(|row| row_matches_scan(row, request));
+    if let Some(limit) = request.limit {
+        rows.truncate(limit);
+    }
+    let projection = UntrackedMaterializationProjection::from_columns(&request.projection.columns);
+    let mut json_reader = JsonStoreContext::new().reader(store);
+    let mut materialized = Vec::with_capacity(rows.len());
+    for row in rows {
+        materialized.push(
+            crate::untracked_state::materialize_row(&mut json_reader, row, &projection).await?,
+        );
+    }
+    Ok(materialized)
+}
+
+pub(crate) async fn load_row(
+    store: &mut impl StorageReader,
+    request: &UntrackedStateRowRequest,
+) -> Result<Option<MaterializedUntrackedStateRow>, LixError> {
+    let Some(identity) = identity_from_request(request) else {
+        return Ok(None);
+    };
+    let bytes = store
+        .get_values(KvGetRequest {
+            groups: vec![KvGetGroup {
+                namespace: UNTRACKED_STATE_ROW_NAMESPACE.to_string(),
+                keys: vec![encode_untracked_state_row_key(&identity)],
+            }],
+        })
+        .await?
+        .groups
+        .into_iter()
+        .next()
+        .and_then(|group| group.single_value_owned());
+    let Some(bytes) = bytes else {
+        return Ok(None);
+    };
+    let row = crate::untracked_state::codec::decode_row(&bytes)?;
+    let mut json_reader = JsonStoreContext::new().reader(store);
+    crate::untracked_state::materialize_row(
+        &mut json_reader,
+        row,
+        &UntrackedMaterializationProjection::full(),
+    )
+    .await
+    .map(Some)
+}
+
+pub(crate) fn stage_rows(
+    writes: &mut StorageWriteSet,
+    rows: &[UntrackedStateRow],
+) -> Result<(), LixError> {
+    for row in rows {
+        let identity = UntrackedStateIdentity::from_row(row);
+        if row.snapshot_ref.is_none() {
+            writes.delete(
+                UNTRACKED_STATE_ROW_NAMESPACE,
+                encode_untracked_state_row_key(&identity),
+            );
+        } else {
+            writes.put(
+                UNTRACKED_STATE_ROW_NAMESPACE,
+                encode_untracked_state_row_key(&identity),
+                crate::untracked_state::codec::encode_row(row)?,
+            );
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn stage_delete_rows(
+    writes: &mut StorageWriteSet,
+    identities: &[UntrackedStateIdentity],
+) {
+    for identity in identities {
+        writes.delete(
+            UNTRACKED_STATE_ROW_NAMESPACE,
+            encode_untracked_state_row_key(identity),
+        );
+    }
+}
+
+async fn scan_all_canonical_rows(
+    store: &mut impl StorageReader,
+) -> Result<Vec<UntrackedStateRow>, LixError> {
+    let page = store
+        .scan_values(KvScanRequest {
+            namespace: UNTRACKED_STATE_ROW_NAMESPACE.to_string(),
+            range: KvScanRange::prefix(Vec::new()),
+            after: None,
+            limit: usize::MAX,
+        })
+        .await?;
+    page.values
+        .iter()
+        .map(crate::untracked_state::codec::decode_row)
+        .collect()
+}
+
+fn row_matches_scan(row: &UntrackedStateRow, request: &UntrackedStateScanRequest) -> bool {
+    (request.filter.schema_keys.is_empty() || request.filter.schema_keys.contains(&row.schema_key))
+        && (request.filter.entity_ids.is_empty()
+            || request.filter.entity_ids.contains(&row.entity_id))
+        && (request.filter.version_ids.is_empty()
+            || request.filter.version_ids.contains(&row.version_id))
+        && nullable_matches_filters(&row.file_id, &request.filter.file_ids)
+}
+
+fn nullable_matches_filters(value: &Option<String>, filters: &[NullableKeyFilter<String>]) -> bool {
+    filters.is_empty()
+        || filters.iter().any(|filter| match filter {
+            NullableKeyFilter::Any => true,
+            NullableKeyFilter::Null => value.is_none(),
+            NullableKeyFilter::Value(expected) => value.as_ref() == Some(expected),
+        })
+}
+
+fn identity_from_request(request: &UntrackedStateRowRequest) -> Option<UntrackedStateIdentity> {
+    let file_id = match &request.file_id {
+        NullableKeyFilter::Null => None,
+        NullableKeyFilter::Value(value) => Some(value.clone()),
+        NullableKeyFilter::Any => return None,
+    };
+    Some(UntrackedStateIdentity {
+        version_id: request.version_id.clone(),
+        schema_key: request.schema_key.clone(),
+        entity_id: request.entity_id.clone(),
+        file_id,
+    })
+}
+
+fn encode_untracked_state_row_key(identity: &UntrackedStateIdentity) -> Vec<u8> {
+    let mut out = Vec::new();
+    push_component(&mut out, &identity.version_id);
+    push_component(&mut out, &identity.schema_key);
+    push_component(
+        &mut out,
+        &identity
+            .entity_id
+            .as_string()
+            .expect("untracked-state identity should project"),
+    );
+    match &identity.file_id {
+        Some(file_id) => {
+            out.push(1);
+            push_component(&mut out, file_id);
+        }
+        None => out.push(0),
+    }
+    out
+}
+
+fn push_component(out: &mut Vec<u8>, value: &str) {
+    let bytes = value.as_bytes();
+    out.extend_from_slice(&(bytes.len() as u32).to_be_bytes());
+    out.extend_from_slice(bytes);
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use super::*;
+    use crate::backend::testing::UnitTestBackend;
+    use crate::storage::{StorageContext, StorageWriteTransaction};
+    use crate::untracked_state::{canonicalize_materialized_row, UntrackedStateContext};
+
+    async fn write_materialized_rows_to_store(
+        context: &UntrackedStateContext,
+        store: &mut (impl StorageWriteTransaction + ?Sized),
+        rows: &[MaterializedUntrackedStateRow],
+    ) {
+        let mut writes = StorageWriteSet::new();
+        let canonical_rows = {
+            let mut json_writer = JsonStoreContext::new().writer();
+            rows.iter()
+                .map(|row| canonicalize_materialized_row(&mut writes, &mut json_writer, row))
+                .collect::<Result<Vec<_>, _>>()
+                .expect("rows should canonicalize")
+        };
+        context
+            .writer(&mut writes)
+            .stage_rows(&canonical_rows)
+            .expect("rows should write");
+        writes.apply(store).await.expect("rows should apply");
+    }
+
+    #[tokio::test]
+    async fn write_and_load_roundtrips() {
+        let backend = Arc::new(UnitTestBackend::new());
+        let storage = StorageContext::new(backend.clone());
+        let context = UntrackedStateContext::new();
+        let row = untracked_row("global", "lix_key_value", "ui-tab");
+
+        let mut transaction = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+        write_materialized_rows_to_store(
+            &context,
+            transaction.as_mut(),
+            std::slice::from_ref(&row),
+        )
+        .await;
+        transaction.commit().await.expect("commit should succeed");
+
+        let loaded = {
+            let mut reader = context.reader(storage.clone());
+            reader
+                .load_row(&UntrackedStateRowRequest {
+                    schema_key: "lix_key_value".to_string(),
+                    version_id: "global".to_string(),
+                    entity_id: crate::entity_identity::EntityIdentity::single("ui-tab"),
+                    file_id: NullableKeyFilter::Null,
+                })
+                .await
+        }
+        .expect("load should succeed");
+        assert_eq!(loaded, Some(row));
+    }
+
+    #[tokio::test]
+    async fn scan_filters_by_schema_and_version() {
+        let backend = Arc::new(UnitTestBackend::new());
+        let storage = StorageContext::new(backend.clone());
+        let context = UntrackedStateContext::new();
+        let mut transaction = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+        write_materialized_rows_to_store(
+            &context,
+            transaction.as_mut(),
+            &[
+                untracked_row("global", "lix_key_value", "global-ui"),
+                untracked_row("version-a", "lix_key_value", "version-ui"),
+                untracked_row("version-a", "other_schema", "other"),
+            ],
+        )
+        .await;
+        transaction.commit().await.expect("commit should succeed");
+
+        let rows = {
+            let mut reader = context.reader(storage.clone());
+            reader
+                .scan_rows(&UntrackedStateScanRequest {
+                    filter: crate::untracked_state::UntrackedStateFilter {
+                        schema_keys: vec!["lix_key_value".to_string()],
+                        version_ids: vec!["version-a".to_string()],
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                })
+                .await
+        }
+        .expect("scan should succeed");
+
+        assert_eq!(rows.len(), 1);
+        assert_eq!(
+            rows[0].entity_id,
+            crate::entity_identity::EntityIdentity::single("version-ui")
+        );
+    }
+
+    #[tokio::test]
+    async fn delete_removes_row() {
+        let backend = Arc::new(UnitTestBackend::new());
+        let storage = StorageContext::new(backend.clone());
+        let context = UntrackedStateContext::new();
+        let row = untracked_row("global", "lix_key_value", "ui-tab");
+        let identity = UntrackedStateIdentity {
+            version_id: row.version_id.clone(),
+            schema_key: row.schema_key.clone(),
+            entity_id: row.entity_id.clone(),
+            file_id: row.file_id.clone(),
+        };
+
+        let mut transaction = storage
+            .begin_write_transaction()
+            .await
+            .expect("transaction should open");
+        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("row should canonicalize")
+        };
+        let mut writer = context.writer(&mut writes);
+        writer
+            .stage_rows(&[canonical_row])
+            .expect("write should succeed");
+        writer.stage_delete_rows(&[identity]);
+        writes
+            .apply(&mut transaction.as_mut())
+            .await
+            .expect("writes should apply");
+        transaction.commit().await.expect("commit should succeed");
+
+        let loaded = {
+            let mut reader = context.reader(storage.clone());
+            reader
+                .load_row(&UntrackedStateRowRequest {
+                    schema_key: "lix_key_value".to_string(),
+                    version_id: "global".to_string(),
+                    entity_id: crate::entity_identity::EntityIdentity::single("ui-tab"),
+                    file_id: NullableKeyFilter::Null,
+                })
+                .await
+        }
+        .expect("load should succeed");
+        assert_eq!(loaded, None);
+    }
+
+    fn untracked_row(
+        version_id: &str,
+        schema_key: &str,
+        entity_id: &str,
+    ) -> MaterializedUntrackedStateRow {
+        MaterializedUntrackedStateRow {
+            entity_id: crate::entity_identity::EntityIdentity::single(entity_id),
+            schema_key: schema_key.to_string(),
+            file_id: None,
+            snapshot_content: Some(format!("{{\"key\":\"{}\",\"value\":\"value\"}}", entity_id)),
+            metadata: None,
+            schema_version: "1".to_string(),
+            created_at: "2026-01-01T00:00:00Z".to_string(),
+            updated_at: "2026-01-01T00:00:00Z".to_string(),
+            global: version_id == "global",
+            version_id: version_id.to_string(),
+        }
+    }
+}

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

@@ -0,0 +1,96 @@
+use crate::entity_identity::EntityIdentity;
+use crate::json_store::JsonRef;
+use crate::{NullableKeyFilter, RowMetadata};
+
+/// Durable local row excluded from changelog and commit membership.
+///
+/// This is the canonical physical shape: identity/header fields are stored
+/// directly, while JSON payloads live in json_store and are referenced by hash.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct UntrackedStateRow {
+    pub(crate) entity_id: EntityIdentity,
+    pub(crate) schema_key: String,
+    pub(crate) file_id: Option<String>,
+    pub(crate) snapshot_ref: Option<JsonRef>,
+    pub(crate) metadata_ref: Option<JsonRef>,
+    pub(crate) schema_version: String,
+    pub(crate) created_at: String,
+    pub(crate) updated_at: String,
+    pub(crate) global: bool,
+    pub(crate) version_id: String,
+}
+
+/// Hydrated boundary shape for callers that still work with JSON payloads.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub(crate) struct MaterializedUntrackedStateRow {
+    pub(crate) entity_id: EntityIdentity,
+    pub(crate) schema_key: String,
+    pub(crate) file_id: Option<String>,
+    pub(crate) snapshot_content: Option<String>,
+    pub(crate) metadata: Option<RowMetadata>,
+    pub(crate) schema_version: String,
+    pub(crate) created_at: String,
+    pub(crate) updated_at: String,
+    pub(crate) global: bool,
+    pub(crate) version_id: String,
+}
+
+/// Stable identity for one local untracked overlay row.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub(crate) struct UntrackedStateIdentity {
+    pub(crate) version_id: String,
+    pub(crate) schema_key: String,
+    pub(crate) entity_id: EntityIdentity,
+    pub(crate) file_id: Option<String>,
+}
+
+impl UntrackedStateIdentity {
+    pub(crate) fn from_row(row: &UntrackedStateRow) -> Self {
+        Self {
+            version_id: row.version_id.clone(),
+            schema_key: row.schema_key.clone(),
+            entity_id: row.entity_id.clone(),
+            file_id: row.file_id.clone(),
+        }
+    }
+}
+
+/// Identity-centered filter for untracked local overlay scans.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Default)]
+pub(crate) struct UntrackedStateFilter {
+    #[serde(default)]
+    pub(crate) schema_keys: Vec<String>,
+    #[serde(default)]
+    pub(crate) entity_ids: Vec<EntityIdentity>,
+    #[serde(default)]
+    pub(crate) version_ids: Vec<String>,
+    #[serde(default)]
+    pub(crate) file_ids: Vec<NullableKeyFilter<String>>,
+}
+
+/// Requested property set for an untracked-state scan.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Default)]
+pub(crate) struct UntrackedStateProjection {
+    #[serde(default)]
+    pub(crate) columns: Vec<String>,
+}
+
+/// Scan request for local untracked overlay rows.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Default)]
+pub(crate) struct UntrackedStateScanRequest {
+    #[serde(default)]
+    pub(crate) filter: UntrackedStateFilter,
+    #[serde(default)]
+    pub(crate) projection: UntrackedStateProjection,
+    #[serde(default)]
+    pub(crate) limit: Option<usize>,
+}
+
+/// Point lookup request for one untracked local overlay row.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct UntrackedStateRowRequest {
+    pub(crate) schema_key: String,
+    pub(crate) version_id: String,
+    pub(crate) entity_id: EntityIdentity,
+    pub(crate) file_id: NullableKeyFilter<String>,
+}

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

@@ -0,0 +1,52 @@
+use std::sync::Arc;
+
+use crate::json_store::JsonStoreWriter;
+use crate::storage::{StorageReader, StorageWriteSet};
+use crate::untracked_state::{UntrackedStateContext, UntrackedStateRow};
+
+use super::refs::{canonical_version_ref_row, VersionRefContext};
+use super::VersionRefReader;
+
+/// Aggregate entrypoint for version-domain services.
+///
+/// Today this owns the moving-ref subsystem. Descriptor helpers are re-exported
+/// by `version`; future version APIs can grow here without making session or
+/// SQL code depend directly on ref storage details.
+pub(crate) struct VersionContext {
+    refs: Arc<VersionRefContext>,
+}
+
+impl VersionContext {
+    pub(crate) fn new(untracked_state: Arc<UntrackedStateContext>) -> Self {
+        Self {
+            refs: Arc::new(VersionRefContext::new(untracked_state)),
+        }
+    }
+
+    /// Creates a version-ref reader over a caller-provided KV store.
+    pub(crate) fn ref_reader<S>(&self, store: S) -> impl VersionRefReader
+    where
+        S: StorageReader + Send,
+    {
+        self.refs.reader(store)
+    }
+
+    pub(crate) fn canonical_ref_row(
+        &self,
+        writes: &mut StorageWriteSet,
+        json_writer: &mut JsonStoreWriter,
+        version_id: &str,
+        commit_id: &str,
+        timestamp: &str,
+    ) -> Result<UntrackedStateRow, crate::LixError> {
+        canonical_version_ref_row(writes, json_writer, version_id, commit_id, timestamp)
+    }
+
+    pub(crate) fn stage_canonical_ref_rows(
+        &self,
+        writes: &mut StorageWriteSet,
+        rows: &[UntrackedStateRow],
+    ) -> Result<(), crate::LixError> {
+        self.refs.writer(writes).stage_rows(rows)
+    }
+}

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

@@ -0,0 +1,12 @@
+mod context;
+mod refs;
+mod stage_rows;
+mod types;
+
+pub(crate) use context::VersionContext;
+pub(crate) use stage_rows::{
+    version_descriptor_stage_row, version_descriptor_tombstone_row, version_ref_stage_row,
+    version_ref_tombstone_row, VERSION_DESCRIPTOR_SCHEMA_KEY, VERSION_DESCRIPTOR_SCHEMA_VERSION,
+    VERSION_REF_SCHEMA_KEY, VERSION_REF_SCHEMA_VERSION,
+};
+pub(crate) use types::{VersionHead, VersionRefReader};