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

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

@@ -0,0 +1,403 @@
+use crate::entity_identity::EntityIdentity;
+use crate::json_store::JsonRef;
+use crate::json_store::{JsonLoadRequestRef, JsonReadScopeRef, JsonStoreContext};
+use crate::storage::StorageReader;
+use crate::tracked_state::types::{TrackedStateIndexValue, TrackedStateKey};
+use crate::tracked_state::MaterializedTrackedStateRow;
+use crate::LixError;
+use std::collections::BTreeMap;
+
+/// Materializes tracked-state index entries.
+///
+/// The durable tracked_state value is authoritative for scalar projection
+/// fields and stores the JSON refs needed for payload projections. Snapshot and
+/// metadata bytes are hydrated from grouped json_store loads only when the
+/// requested projection needs them.
+pub(crate) async fn materialize_index_entries<S>(
+    store: &mut S,
+    entries: Vec<(TrackedStateKey, TrackedStateIndexValue)>,
+    projection: &TrackedMaterializationProjection,
+) -> Result<Vec<MaterializedTrackedStateRow>, LixError>
+where
+    S: StorageReader,
+{
+    if !projection.snapshot_content && !projection.metadata {
+        return Ok(entries
+            .into_iter()
+            .map(materialize_entry_without_json)
+            .collect());
+    }
+
+    let json_slots_per_row =
+        usize::from(projection.snapshot_content) + usize::from(projection.metadata);
+    let json_ref_capacity = entries.len().saturating_mul(json_slots_per_row);
+    let mut row_plans = Vec::with_capacity(entries.len());
+    let mut json_refs = Vec::with_capacity(json_ref_capacity);
+    let mut json_ref_localities = Vec::with_capacity(json_ref_capacity);
+    for (key, value) in entries {
+        let row_index = row_plans.len();
+        let snapshot_ref_index = projected_json_ref_index(
+            projection.snapshot_content,
+            value.snapshot_ref,
+            row_index,
+            value.change_locator.source_pack_id,
+            &mut json_refs,
+            &mut json_ref_localities,
+        );
+        let metadata_ref_index = projected_json_ref_index(
+            projection.metadata,
+            value.metadata_ref,
+            row_index,
+            value.change_locator.source_pack_id,
+            &mut json_refs,
+            &mut json_ref_localities,
+        );
+        row_plans.push(MaterializedTrackedStateRowPlan {
+            entity_id: key.entity_id,
+            schema_key: key.schema_key,
+            file_id: key.file_id,
+            deleted: value.deleted,
+            created_at: value.created_at,
+            updated_at: value.updated_at,
+            change_id: value.change_locator.change_id,
+            commit_id: value.change_locator.source_commit_id,
+            snapshot_ref_index,
+            metadata_ref_index,
+        });
+    }
+
+    let mut json_values =
+        load_projection_json_values(store, &json_refs, &json_ref_localities, &row_plans).await?;
+    row_plans
+        .into_iter()
+        .map(|plan| materialize_row_plan(plan, &json_refs, &mut json_values))
+        .collect()
+}
+
+fn materialize_entry_without_json(
+    (key, value): (TrackedStateKey, TrackedStateIndexValue),
+) -> MaterializedTrackedStateRow {
+    MaterializedTrackedStateRow {
+        entity_id: key.entity_id,
+        schema_key: key.schema_key,
+        file_id: key.file_id,
+        snapshot_content: None,
+        metadata: None,
+        deleted: value.deleted,
+        created_at: value.created_at,
+        updated_at: value.updated_at,
+        change_id: value.change_locator.change_id,
+        commit_id: value.change_locator.source_commit_id,
+    }
+}
+
+struct MaterializedTrackedStateRowPlan {
+    entity_id: EntityIdentity,
+    schema_key: String,
+    file_id: Option<String>,
+    deleted: bool,
+    created_at: String,
+    updated_at: String,
+    change_id: String,
+    commit_id: String,
+    snapshot_ref_index: Option<usize>,
+    metadata_ref_index: Option<usize>,
+}
+
+fn projected_json_ref_index(
+    include: bool,
+    json_ref: Option<JsonRef>,
+    row_index: usize,
+    pack_id: u32,
+    json_refs: &mut Vec<JsonRef>,
+    json_ref_localities: &mut Vec<JsonRefLocality>,
+) -> Option<usize> {
+    if !include {
+        return None;
+    }
+    let index = json_refs.len();
+    json_refs.push(json_ref?);
+    json_ref_localities.push(JsonRefLocality { row_index, pack_id });
+    Some(index)
+}
+
+struct JsonRefLocality {
+    row_index: usize,
+    pack_id: u32,
+}
+
+async fn load_projection_json_values<S>(
+    store: &mut S,
+    json_refs: &[JsonRef],
+    json_ref_localities: &[JsonRefLocality],
+    row_plans: &[MaterializedTrackedStateRowPlan],
+) -> Result<Vec<Option<Vec<u8>>>, LixError>
+where
+    S: StorageReader,
+{
+    if json_refs.len() != json_ref_localities.len() {
+        return Err(LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            "tracked_state materialization JSON refs and locality indexes diverged",
+        ));
+    }
+
+    let json_store = JsonStoreContext::new();
+    if let Some((commit_id, pack_id)) = single_projection_pack(json_ref_localities, row_plans)? {
+        let pack_ids = [pack_id];
+        return json_store
+            .load_bytes_many(
+                store,
+                JsonLoadRequestRef {
+                    refs: json_refs,
+                    scope: JsonReadScopeRef::CommitPacks {
+                        commit_id,
+                        pack_ids: &pack_ids,
+                    },
+                },
+            )
+            .await
+            .map(|batch| batch.into_values());
+    }
+
+    let mut json_values = vec![None; json_refs.len()];
+    let mut refs_by_pack = BTreeMap::<(&str, u32), Vec<(usize, JsonRef)>>::new();
+    for (index, json_ref) in json_refs.iter().copied().enumerate() {
+        let locality = json_ref_localities.get(index).ok_or_else(|| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "tracked_state materialization lost JSON locality index",
+            )
+        })?;
+        let row_plan = row_plans.get(locality.row_index).ok_or_else(|| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "tracked_state materialization lost JSON row locality index",
+            )
+        })?;
+        refs_by_pack
+            .entry((row_plan.commit_id.as_str(), locality.pack_id))
+            .or_default()
+            .push((index, json_ref));
+    }
+
+    for ((commit_id, pack_id), refs) in refs_by_pack {
+        let indexes = refs.iter().map(|(index, _)| *index).collect::<Vec<_>>();
+        let refs = refs
+            .into_iter()
+            .map(|(_, json_ref)| json_ref)
+            .collect::<Vec<_>>();
+        let pack_ids = [pack_id];
+        let values = json_store
+            .load_bytes_many(
+                store,
+                JsonLoadRequestRef {
+                    refs: &refs,
+                    scope: JsonReadScopeRef::CommitPacks {
+                        commit_id: &commit_id,
+                        pack_ids: &pack_ids,
+                    },
+                },
+            )
+            .await?
+            .into_values();
+        for (index, value) in indexes.into_iter().zip(values) {
+            json_values[index] = value;
+        }
+    }
+    Ok(json_values)
+}
+
+fn single_projection_pack<'a>(
+    json_ref_localities: &[JsonRefLocality],
+    row_plans: &'a [MaterializedTrackedStateRowPlan],
+) -> Result<Option<(&'a str, u32)>, LixError> {
+    let Some(first_locality) = json_ref_localities.first() else {
+        return Ok(None);
+    };
+    let first_plan = row_plans.get(first_locality.row_index).ok_or_else(|| {
+        LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            "tracked_state materialization lost JSON row locality index",
+        )
+    })?;
+    let commit_id = first_plan.commit_id.as_str();
+    let pack_id = first_locality.pack_id;
+
+    for locality in &json_ref_localities[1..] {
+        let row_plan = row_plans.get(locality.row_index).ok_or_else(|| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "tracked_state materialization lost JSON row locality index",
+            )
+        })?;
+        if row_plan.commit_id != commit_id || locality.pack_id != pack_id {
+            return Ok(None);
+        }
+    }
+    Ok(Some((commit_id, pack_id)))
+}
+
+fn materialize_row_plan(
+    plan: MaterializedTrackedStateRowPlan,
+    json_refs: &[JsonRef],
+    json_values: &mut [Option<Vec<u8>>],
+) -> Result<MaterializedTrackedStateRow, LixError> {
+    Ok(MaterializedTrackedStateRow {
+        entity_id: plan.entity_id,
+        schema_key: plan.schema_key,
+        file_id: plan.file_id,
+        snapshot_content: materialized_json_string(
+            plan.snapshot_ref_index,
+            json_refs,
+            json_values,
+        )?,
+        metadata: materialized_json_string(plan.metadata_ref_index, json_refs, json_values)?,
+        deleted: plan.deleted,
+        created_at: plan.created_at,
+        updated_at: plan.updated_at,
+        change_id: plan.change_id,
+        commit_id: plan.commit_id,
+    })
+}
+
+fn materialized_json_string(
+    index: Option<usize>,
+    json_refs: &[JsonRef],
+    json_values: &mut [Option<Vec<u8>>],
+) -> Result<Option<String>, LixError> {
+    let Some(index) = index else {
+        return Ok(None);
+    };
+    let json_ref = json_refs.get(index).ok_or_else(|| {
+        LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            "tracked_state materialization lost JSON ref index",
+        )
+    })?;
+    // Each row plan owns its projected JSON slots. If this path starts
+    // deduplicating refs, duplicate consumers must clone intentionally.
+    let bytes = json_values
+        .get_mut(index)
+        .ok_or_else(|| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "tracked_state materialization lost JSON value index",
+            )
+        })?
+        .take()
+        .ok_or_else(|| {
+            LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                format!(
+                    "tracked_state materialization missing JSON payload '{}'",
+                    json_ref.to_hex()
+                ),
+            )
+        })?;
+    String::from_utf8(bytes).map(Some).map_err(|error| {
+        let utf8_error = error.utf8_error();
+        LixError::new(
+            LixError::CODE_INTERNAL_ERROR,
+            format!("tracked_state materialized JSON payload is not UTF-8: {utf8_error}"),
+        )
+    })
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct TrackedMaterializationProjection {
+    pub(crate) snapshot_content: bool,
+    pub(crate) metadata: bool,
+}
+
+impl TrackedMaterializationProjection {
+    pub(crate) fn full() -> Self {
+        Self {
+            snapshot_content: true,
+            metadata: true,
+        }
+    }
+
+    pub(crate) fn from_columns(columns: &[String]) -> Self {
+        if columns.is_empty() {
+            return Self::full();
+        }
+        Self {
+            snapshot_content: columns.iter().any(|column| column == "snapshot_content"),
+            metadata: columns.iter().any(|column| column == "metadata"),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn row_plan(commit_id: &str) -> MaterializedTrackedStateRowPlan {
+        MaterializedTrackedStateRowPlan {
+            entity_id: EntityIdentity::single("entity"),
+            schema_key: "schema".to_string(),
+            file_id: None,
+            deleted: false,
+            created_at: "2024-01-01T00:00:00.000Z".to_string(),
+            updated_at: "2024-01-01T00:00:00.000Z".to_string(),
+            change_id: "change".to_string(),
+            commit_id: commit_id.to_string(),
+            snapshot_ref_index: None,
+            metadata_ref_index: None,
+        }
+    }
+
+    #[test]
+    fn single_projection_pack_accepts_duplicate_slots_from_same_pack() {
+        let row_plans = vec![row_plan("commit-a")];
+        let localities = vec![
+            JsonRefLocality {
+                row_index: 0,
+                pack_id: 7,
+            },
+            JsonRefLocality {
+                row_index: 0,
+                pack_id: 7,
+            },
+        ];
+
+        assert_eq!(
+            single_projection_pack(&localities, &row_plans).expect("pack detection should succeed"),
+            Some(("commit-a", 7))
+        );
+    }
+
+    #[test]
+    fn single_projection_pack_rejects_mixed_packs() {
+        let row_plans = vec![row_plan("commit-a")];
+        let localities = vec![
+            JsonRefLocality {
+                row_index: 0,
+                pack_id: 7,
+            },
+            JsonRefLocality {
+                row_index: 0,
+                pack_id: 8,
+            },
+        ];
+
+        assert_eq!(
+            single_projection_pack(&localities, &row_plans).expect("pack detection should succeed"),
+            None
+        );
+    }
+
+    #[test]
+    fn materialized_json_string_consumes_owned_payload_bytes() {
+        let json = br#"{"value":1}"#.to_vec();
+        let json_ref = JsonRef::for_content(&json);
+        let mut json_values = vec![Some(json)];
+
+        let materialized = materialized_json_string(Some(0), &[json_ref], &mut json_values)
+            .expect("json should materialize");
+
+        assert_eq!(materialized, Some(r#"{"value":1}"#.to_string()));
+        assert!(json_values[0].is_none());
+    }
+}