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

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

@@ -1,396 +0,0 @@
-use crate::storage::KvScanRange;
-use crate::storage::{KvGetGroup, KvGetRequest, KvScanRequest, StorageReader, StorageWriteSet};
-use crate::untracked_state::{
-    MaterializedUntrackedStateRow, UntrackedMaterializationProjection, UntrackedStateIdentity,
-    UntrackedStateIdentityRef, UntrackedStateRow, UntrackedStateRowRef, UntrackedStateRowRequest,
-    UntrackedStateScanRequest,
-};
-use crate::{LixError, NullableKeyFilter};
-
-pub(super) 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 materialized = Vec::with_capacity(rows.len());
-    for row in rows {
-        materialized.push(crate::untracked_state::materialize_row(row, &projection)?);
-    }
-    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)?;
-    crate::untracked_state::materialize_row(row, &UntrackedMaterializationProjection::full())
-        .map(Some)
-}
-
-pub(super) async fn existing_identities<'a>(
-    store: &mut (impl StorageReader + ?Sized),
-    identities: impl IntoIterator<Item = UntrackedStateIdentityRef<'a>>,
-) -> Result<Vec<UntrackedStateIdentity>, LixError> {
-    let mut candidates = identities
-        .into_iter()
-        .map(|identity| {
-            let owned = UntrackedStateIdentity {
-                version_id: identity.version_id.to_string(),
-                schema_key: identity.schema_key.to_string(),
-                entity_id: identity.entity_id.clone(),
-                file_id: identity.file_id.map(str::to_string),
-            };
-            let key = encode_untracked_state_row_key_ref(owned.as_ref());
-            (key, owned)
-        })
-        .collect::<Vec<_>>();
-    candidates.sort_by(|(left, _), (right, _)| left.cmp(right));
-    candidates.dedup_by(|(left, _), (right, _)| left == right);
-    if candidates.is_empty() {
-        return Ok(Vec::new());
-    }
-    let keys = candidates
-        .iter()
-        .map(|(key, _)| key.clone())
-        .collect::<Vec<_>>();
-
-    let result = store
-        .exists_many(KvGetRequest {
-            groups: vec![KvGetGroup {
-                namespace: UNTRACKED_STATE_ROW_NAMESPACE.to_string(),
-                keys,
-            }],
-        })
-        .await?;
-    let group = result.groups.into_iter().next().ok_or_else(|| {
-        LixError::new(
-            LixError::CODE_INTERNAL_ERROR,
-            "untracked identity existence probe returned no result group",
-        )
-    })?;
-    if group.exists.len() != candidates.len() {
-        return Err(LixError::new(
-            LixError::CODE_INTERNAL_ERROR,
-            format!(
-                "untracked identity existence probe returned {} results for {} requested keys",
-                group.exists.len(),
-                candidates.len()
-            ),
-        ));
-    }
-
-    Ok(candidates
-        .into_iter()
-        .zip(group.exists)
-        .filter_map(|((_, identity), exists)| exists.then_some(identity))
-        .collect())
-}
-
-pub(crate) fn stage_rows<'a, I>(writes: &mut StorageWriteSet, rows: I) -> Result<(), LixError>
-where
-    I: IntoIterator<Item = UntrackedStateRowRef<'a>>,
-{
-    for row in rows {
-        if row.snapshot_content.is_none() {
-            writes.delete(
-                UNTRACKED_STATE_ROW_NAMESPACE,
-                encode_untracked_state_row_key_ref(row.into()),
-            );
-        } else {
-            writes.put(
-                UNTRACKED_STATE_ROW_NAMESPACE,
-                encode_untracked_state_row_key_ref(row.into()),
-                crate::untracked_state::codec::encode_row_ref(row)?,
-            );
-        }
-    }
-    Ok(())
-}
-
-pub(crate) fn stage_delete_rows<'a, I>(writes: &mut StorageWriteSet, identities: I)
-where
-    I: IntoIterator<Item = UntrackedStateIdentityRef<'a>>,
-{
-    for identity in identities {
-        writes.delete(
-            UNTRACKED_STATE_ROW_NAMESPACE,
-            encode_untracked_state_row_key_ref(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> {
-    encode_untracked_state_row_key_ref(identity.as_ref())
-}
-
-pub(super) fn encode_untracked_state_row_key_ref(
-    identity: UntrackedStateIdentityRef<'_>,
-) -> Vec<u8> {
-    let mut out = Vec::new();
-    push_component(&mut out, identity.version_id);
-    push_component(&mut out, identity.schema_key);
-    let entity_id = identity
-        .entity_id
-        .as_json_array_text()
-        .expect("untracked-state identity should project");
-    push_component(&mut out, &entity_id);
-    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::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 = rows
-            .iter()
-            .map(|row| crate::test_support::untracked_state_row_from_materialized(&mut writes, row))
-            .collect::<Result<Vec<_>, _>>()
-            .expect("rows should canonicalize");
-        context
-            .writer(&mut writes)
-            .stage_rows(canonical_rows.iter().map(|row| row.as_ref()))
-            .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 =
-            crate::test_support::untracked_state_row_from_materialized(&mut writes, &row)
-                .expect("row should canonicalize");
-        let mut writer = context.writer(&mut writes);
-        writer
-            .stage_rows(std::iter::once(canonical_row.as_ref()))
-            .expect("write should succeed");
-        writer.stage_delete_rows(std::iter::once(identity.as_ref()));
-        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,
-            deleted: false,
-            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

@@ -1,146 +0,0 @@
-use crate::entity_identity::EntityIdentity;
-use crate::NullableKeyFilter;
-
-/// Durable local row excluded from changelog and commit membership.
-///
-/// This is the canonical physical shape: identity/header fields are stored
-/// directly, and mutable JSON payloads are stored inline in the sidecar row.
-#[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_content: Option<String>,
-    pub(crate) metadata: Option<String>,
-    pub(crate) created_at: String,
-    pub(crate) updated_at: String,
-    pub(crate) global: bool,
-    pub(crate) version_id: String,
-}
-
-impl UntrackedStateRow {
-    pub(crate) fn as_ref(&self) -> UntrackedStateRowRef<'_> {
-        UntrackedStateRowRef {
-            entity_id: &self.entity_id,
-            schema_key: &self.schema_key,
-            file_id: self.file_id.as_deref(),
-            snapshot_content: self.snapshot_content.as_deref(),
-            metadata: self.metadata.as_deref(),
-            created_at: &self.created_at,
-            updated_at: &self.updated_at,
-            global: self.global,
-            version_id: &self.version_id,
-        }
-    }
-}
-
-/// Zero-copy view of untracked-state write row.
-///
-/// Untracked state owns this storage-facing write shape. Callers adapt into it
-/// without making untracked_state depend on transaction or live-state types.
-#[derive(Debug, Clone, Copy)]
-pub(crate) struct UntrackedStateRowRef<'a> {
-    pub(crate) entity_id: &'a EntityIdentity,
-    pub(crate) schema_key: &'a str,
-    pub(crate) file_id: Option<&'a str>,
-    pub(crate) snapshot_content: Option<&'a str>,
-    pub(crate) metadata: Option<&'a str>,
-    pub(crate) created_at: &'a str,
-    pub(crate) updated_at: &'a str,
-    pub(crate) global: bool,
-    pub(crate) version_id: &'a str,
-}
-
-/// 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<String>,
-    pub(crate) deleted: bool,
-    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>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub(crate) struct UntrackedStateIdentityRef<'a> {
-    pub(crate) version_id: &'a str,
-    pub(crate) schema_key: &'a str,
-    pub(crate) entity_id: &'a EntityIdentity,
-    pub(crate) file_id: Option<&'a str>,
-}
-
-impl UntrackedStateIdentity {
-    pub(crate) fn as_ref(&self) -> UntrackedStateIdentityRef<'_> {
-        UntrackedStateIdentityRef {
-            version_id: &self.version_id,
-            schema_key: &self.schema_key,
-            entity_id: &self.entity_id,
-            file_id: self.file_id.as_deref(),
-        }
-    }
-}
-
-impl<'a> From<UntrackedStateRowRef<'a>> for UntrackedStateIdentityRef<'a> {
-    fn from(row: UntrackedStateRowRef<'a>) -> Self {
-        Self {
-            version_id: row.version_id,
-            schema_key: row.schema_key,
-            entity_id: row.entity_id,
-            file_id: row.file_id,
-        }
-    }
-}
-
-/// 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

@@ -1,40 +0,0 @@
-use std::sync::Arc;
-
-use crate::storage::{StorageReader, StorageWriteSet};
-use crate::untracked_state::{UntrackedStateContext, UntrackedStateRow};
-
-use super::refs::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 stage_canonical_ref_rows(
-        &self,
-        writes: &mut StorageWriteSet,
-        rows: &[UntrackedStateRow],
-    ) -> Result<(), crate::LixError> {
-        self.refs.writer(writes).stage_rows(rows)
-    }
-}