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

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

@@ -1,11 +1,10 @@
-use crate::commit_store::{ChangeLocator, ChangeLocatorRef, ChangeRef};
-use crate::entity_identity::EntityIdentity;
+use crate::entity_pk::EntityPk;
 use crate::json_store::JsonRef;
 use crate::{LixError, NullableKeyFilter};
 
 pub(crate) const TRACKED_STATE_HASH_BYTES: usize = 32;
 
-/// Content-addressed root id for one tracked-state projection tree.
+/// Content-addressed root id for one tracked-state commit-root tree.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub(crate) struct TrackedStateRootId([u8; TRACKED_STATE_HASH_BYTES]);
 
@@ -34,12 +33,12 @@ impl TrackedStateRootId {
     }
 }
 
-/// Root-independent tracked entity identity.
+/// Root-independent tracked entity primary key.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub(crate) struct TrackedStateKey {
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
-    pub(crate) entity_id: EntityIdentity,
+    pub(crate) entity_pk: EntityPk,
 }
 
 /// Zero-copy view of primary tracked-state key.
@@ -47,32 +46,29 @@ pub(crate) struct TrackedStateKey {
 pub(crate) struct TrackedStateKeyRef<'a> {
     pub(crate) schema_key: &'a str,
     pub(crate) file_id: Option<&'a str>,
-    pub(crate) entity_id: &'a EntityIdentity,
+    pub(crate) entity_pk: &'a EntityPk,
 }
 
-/// Zero-copy tracked-state projection delta prepared from commit_store facts.
+/// Zero-copy tracked-state commit-root delta prepared from changelog facts.
 #[derive(Debug, Clone, Copy)]
 pub(crate) struct TrackedStateDeltaRef<'a> {
-    pub(crate) change: ChangeRef<'a>,
-    pub(crate) locator: ChangeLocatorRef<'a>,
+    pub(crate) schema_key: &'a str,
+    pub(crate) file_id: Option<&'a str>,
+    pub(crate) entity_pk: &'a EntityPk,
+    pub(crate) change_id: &'a str,
+    pub(crate) commit_id: &'a str,
+    pub(crate) snapshot_ref: Option<&'a JsonRef>,
+    pub(crate) metadata_ref: Option<&'a JsonRef>,
+    pub(crate) deleted: bool,
     pub(crate) created_at: &'a str,
     pub(crate) updated_at: &'a str,
 }
 
-/// Owned per-commit projection delta entry.
-///
-/// Normal commits persist these entries in `tracked_state.delta_pack`. Full
-/// projection roots are materialized separately from these deltas.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct TrackedStateDeltaEntry {
-    pub(crate) key: TrackedStateKey,
-    pub(crate) value: TrackedStateIndexValue,
-}
-
-/// Projection value stored in tracked-state trees.
+/// Value stored in tracked-state commit-root trees.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct TrackedStateIndexValue {
-    pub(crate) change_locator: ChangeLocator,
+    pub(crate) change_id: String,
+    pub(crate) commit_id: String,
     pub(crate) deleted: bool,
     pub(crate) snapshot_ref: Option<JsonRef>,
     pub(crate) metadata_ref: Option<JsonRef>,
@@ -80,10 +76,11 @@ pub(crate) struct TrackedStateIndexValue {
     pub(crate) updated_at: String,
 }
 
-/// Zero-copy view of a tracked-state projection value.
+/// Zero-copy view of a tracked-state commit-root value.
 #[derive(Debug, Clone, Copy)]
 pub(crate) struct TrackedStateIndexValueRef<'a> {
-    pub(crate) change_locator: ChangeLocatorRef<'a>,
+    pub(crate) change_id: &'a str,
+    pub(crate) commit_id: &'a str,
     pub(crate) deleted: bool,
     pub(crate) snapshot_ref: Option<&'a JsonRef>,
     pub(crate) metadata_ref: Option<&'a JsonRef>,
@@ -91,15 +88,34 @@ pub(crate) struct TrackedStateIndexValueRef<'a> {
     pub(crate) updated_at: &'a str,
 }
 
-/// Materialized tracked-state projection row.
+/// Durable tracked-state root metadata for one commit.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct TrackedStateCommitRoot {
+    pub(crate) commit_id: String,
+    pub(crate) root_id: TrackedStateRootId,
+    pub(crate) parent_roots: Vec<TrackedStateCommitRootParent>,
+    pub(crate) changed_key_count: u64,
+    pub(crate) row_count_estimate: u64,
+    pub(crate) tree_height: u32,
+    pub(crate) primary_chunk_count: u64,
+    pub(crate) primary_chunk_bytes: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct TrackedStateCommitRootParent {
+    pub(crate) commit_id: String,
+    pub(crate) root_id: TrackedStateRootId,
+}
+
+/// Materialized tracked-state commit-root row.
 ///
-/// Tracked rows are the projection that can be rebuilt from changelog facts.
+/// Tracked rows are the serving state that can be rebuilt from changelog facts.
 /// They intentionally do not carry an `untracked` flag: untracked local overlay
 /// data belongs to `untracked_state`, and the serving `live_state` facade is
 /// responsible for combining both sources.
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub(crate) struct MaterializedTrackedStateRow {
-    pub(crate) entity_id: EntityIdentity,
+    pub(crate) entity_pk: EntityPk,
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
     pub(crate) snapshot_content: Option<String>,
@@ -117,7 +133,7 @@ pub(crate) struct TrackedStateFilter {
     #[serde(default)]
     pub(crate) schema_keys: Vec<String>,
     #[serde(default)]
-    pub(crate) entity_ids: Vec<EntityIdentity>,
+    pub(crate) entity_pks: Vec<EntityPk>,
     #[serde(default)]
     pub(crate) file_ids: Vec<NullableKeyFilter<String>>,
     #[serde(default)]
@@ -126,30 +142,22 @@ pub(crate) struct TrackedStateFilter {
 
 /// Requested property set for a tracked-state scan.
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Default)]
-pub(crate) struct TrackedStateProjection {
+pub(crate) struct TrackedStateReadColumns {
     #[serde(default)]
     pub(crate) columns: Vec<String>,
 }
 
-/// Scan request for the tracked-state projection.
+/// Scan request for tracked-state commit roots.
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Default)]
 pub(crate) struct TrackedStateScanRequest {
     #[serde(default)]
     pub(crate) filter: TrackedStateFilter,
     #[serde(default)]
-    pub(crate) projection: TrackedStateProjection,
+    pub(crate) read_columns: TrackedStateReadColumns,
     #[serde(default)]
     pub(crate) limit: Option<usize>,
 }
 
-/// Point lookup request for one tracked-state row.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct TrackedStateRowRequest {
-    pub(crate) schema_key: String,
-    pub(crate) entity_id: EntityIdentity,
-    pub(crate) file_id: NullableKeyFilter<String>,
-}
-
 #[derive(Debug, PartialEq, Eq)]
 pub(crate) struct TrackedStateMutation {
     pub(crate) encoded_key: Vec<u8>,
@@ -168,7 +176,7 @@ impl TrackedStateMutation {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct TrackedStateTreeScanRequest {
     pub(crate) schema_keys: Vec<String>,
-    pub(crate) entity_ids: Vec<EntityIdentity>,
+    pub(crate) entity_pks: Vec<EntityPk>,
     pub(crate) file_ids: Vec<NullableKeyFilter<String>>,
     pub(crate) include_tombstones: bool,
     pub(crate) limit: Option<usize>,
@@ -178,7 +186,7 @@ impl Default for TrackedStateTreeScanRequest {
     fn default() -> Self {
         Self {
             schema_keys: Vec::new(),
-            entity_ids: Vec::new(),
+            entity_pks: Vec::new(),
             file_ids: Vec::new(),
             include_tombstones: true,
             limit: None,
@@ -198,7 +206,7 @@ impl TrackedStateTreeScanRequest {
         if !self.schema_keys.is_empty() && !self.schema_keys.contains(&key.schema_key) {
             return false;
         }
-        if !self.entity_ids.is_empty() && !self.entity_ids.contains(&key.entity_id) {
+        if !self.entity_pks.is_empty() && !self.entity_pks.contains(&key.entity_pk) {
             return false;
         }
         if !self.file_ids.is_empty()
@@ -221,7 +229,6 @@ pub(crate) struct TrackedStateApplyResult {
     pub(crate) tree_height: usize,
     pub(crate) chunk_count: usize,
     pub(crate) chunk_bytes: usize,
-    pub(crate) persisted_root: bool,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]

package/dist-engine-src/src/transaction/bench_support.rs

@@ -0,0 +1,407 @@
+use std::sync::Arc;
+
+use serde_json::{json, Value as JsonValue};
+
+use crate::binary_cas::BinaryCasContext;
+use crate::branch::BranchContext;
+use crate::catalog::CatalogContext;
+use crate::entity_pk::EntityPk;
+use crate::live_state::{
+    LiveStateContext, LiveStateFilter, LiveStateProjection, LiveStateRowRequest,
+    LiveStateScanRequest,
+};
+use crate::session::SessionMode;
+use crate::storage::{
+    StorageBackend, StorageBackendRead, StorageBackendReadOf, StorageContext, StorageRead,
+    StorageReadOptions, StorageReadScope, StorageWriteSet, StorageWriteSetStats,
+};
+use crate::tracked_state::TrackedStateContext;
+use crate::transaction::types::{TransactionJson, TransactionWriteRow};
+use crate::untracked_state::UntrackedStateContext;
+use crate::{NullableKeyFilter, GLOBAL_BRANCH_ID};
+
+const SCHEMA_FIXTURE_COMMIT_ID: &str = "tracked-crud-schema-fixture";
+const TIMESTAMP: &str = "2026-05-19T00:00:00.000Z";
+const BENCH_BRANCH_ID: &str = "tracked-crud-branch";
+
+#[derive(Clone)]
+pub struct BenchTransactionRow {
+    pub schema_key: String,
+    pub file_id: Option<String>,
+    pub entity_pk: String,
+    pub value: JsonValue,
+    pub updated_value: JsonValue,
+}
+
+pub struct BenchTransactionFixture<B: StorageBackend> {
+    storage: StorageContext<B>,
+    live_state: Arc<LiveStateContext>,
+    tracked_state: Arc<TrackedStateContext>,
+    binary_cas: Arc<BinaryCasContext>,
+    branch_ctx: Arc<BranchContext>,
+    catalog_context: Arc<CatalogContext>,
+    rows: Vec<BenchTransactionRow>,
+}
+
+struct BenchRead<R> {
+    inner: StorageReadScope<R>,
+}
+
+impl<R> BenchRead<R> {
+    fn new(inner: StorageReadScope<R>) -> Self {
+        Self { inner }
+    }
+}
+
+unsafe impl<R: Send> Send for BenchRead<R> {}
+unsafe impl<R: Send> Sync for BenchRead<R> {}
+
+impl<R> StorageRead for BenchRead<R>
+where
+    R: StorageBackendRead,
+{
+    type BackendRead = R;
+
+    fn backend_read(&self) -> &Self::BackendRead {
+        self.inner.backend_read()
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct BenchWriteAccounting {
+    pub logical_rows: usize,
+    pub staged_puts: u64,
+    pub staged_deletes: u64,
+    pub touched_spaces: u64,
+    pub backend_calls: u64,
+    pub put_batches: u64,
+    pub delete_batches: u64,
+    pub written_bytes: u64,
+}
+
+#[derive(Clone, Debug)]
+pub struct BenchLayoutAccounting {
+    pub space_id: u32,
+    pub space: &'static str,
+    pub rows: u64,
+    pub key_bytes: u64,
+    pub value_bytes: u64,
+}
+
+impl<B> BenchTransactionFixture<B>
+where
+    B: StorageBackend + Clone + Send + Sync + 'static,
+    for<'backend> B::Read<'backend>: Clone + Send + Sync + 'static,
+    for<'backend> B::Write<'backend>: Send,
+{
+    pub async fn new(storage: StorageContext<B>, rows: Vec<BenchTransactionRow>) -> Self {
+        let tracked_state = Arc::new(TrackedStateContext::new());
+        let live_state = Arc::new(LiveStateContext::new(
+            tracked_state.as_ref().clone(),
+            UntrackedStateContext::new(),
+            crate::commit_graph::CommitGraphContext::new(),
+        ));
+        let branch_ctx = Arc::new(BranchContext::new(Arc::new(UntrackedStateContext::new())));
+        seed_visible_schema_rows(storage.clone(), tracked_state.as_ref()).await;
+        Self {
+            storage,
+            live_state,
+            tracked_state,
+            binary_cas: Arc::new(BinaryCasContext::new()),
+            branch_ctx,
+            catalog_context: Arc::new(CatalogContext::new()),
+            rows,
+        }
+    }
+
+    pub async fn seed(&mut self) -> usize {
+        self.insert_all().await
+    }
+
+    pub async fn insert_all(&mut self) -> usize {
+        self.insert_all_accounting().await.logical_rows
+    }
+
+    pub async fn insert_all_accounting(&mut self) -> BenchWriteAccounting {
+        let rows = self
+            .rows
+            .iter()
+            .map(|row| transaction_row(row, &row.value))
+            .collect();
+        self.commit_rows(rows).await
+    }
+
+    pub async fn update_all(&mut self) -> usize {
+        self.update_all_accounting().await.logical_rows
+    }
+
+    pub async fn update_all_accounting(&mut self) -> BenchWriteAccounting {
+        let rows = self
+            .rows
+            .iter()
+            .map(|row| transaction_row(row, &row.updated_value))
+            .collect();
+        self.commit_rows(rows).await
+    }
+
+    pub async fn update_one_by_pk(&mut self) -> usize {
+        self.update_one_by_pk_accounting().await.logical_rows
+    }
+
+    pub async fn update_one_by_pk_accounting(&mut self) -> BenchWriteAccounting {
+        let row = &self.rows[self.rows.len() / 2];
+        self.commit_rows(vec![transaction_row(row, &row.updated_value)])
+            .await
+    }
+
+    pub async fn delete_all(&mut self) -> usize {
+        self.delete_all_accounting().await.logical_rows
+    }
+
+    pub async fn delete_all_accounting(&mut self) -> BenchWriteAccounting {
+        let rows = self.rows.iter().map(transaction_delete_row).collect();
+        self.commit_rows(rows).await
+    }
+
+    pub async fn delete_one_by_pk(&mut self) -> usize {
+        self.delete_one_by_pk_accounting().await.logical_rows
+    }
+
+    pub async fn delete_one_by_pk_accounting(&mut self) -> BenchWriteAccounting {
+        let row = &self.rows[self.rows.len() / 2];
+        self.commit_rows(vec![transaction_delete_row(row)]).await
+    }
+
+    pub async fn read_all(&self) -> usize {
+        let read = self
+            .storage
+            .begin_read(StorageReadOptions::default())
+            .expect("begin transaction bench read");
+        let rows = self
+            .live_state
+            .reader(&read)
+            .scan_rows(&LiveStateScanRequest {
+                filter: LiveStateFilter {
+                    schema_keys: vec!["json_pointer".to_string()],
+                    branch_ids: vec![BENCH_BRANCH_ID.to_string()],
+                    file_ids: vec![NullableKeyFilter::Null],
+                    include_tombstones: false,
+                    ..LiveStateFilter::default()
+                },
+                projection: LiveStateProjection::default(),
+                limit: None,
+            })
+            .await
+            .expect("scan transaction bench rows");
+        assert_eq!(rows.len(), self.rows.len());
+        rows.len()
+    }
+
+    pub async fn read_all_by_pk(&self) -> usize {
+        let mut count = 0;
+        for row in &self.rows {
+            count += self.read_one(row).await;
+        }
+        count
+    }
+
+    pub async fn read_many_by_pk(&self, count: usize) -> usize {
+        let count = count.min(self.rows.len());
+        let mut found = 0;
+        for row in &self.rows[..count] {
+            found += self.read_one(row).await;
+        }
+        found
+    }
+
+    pub async fn read_one_by_pk(&self) -> usize {
+        self.read_one(&self.rows[self.rows.len() / 2]).await
+    }
+
+    async fn read_one(&self, row: &BenchTransactionRow) -> usize {
+        let read = self
+            .storage
+            .begin_read(StorageReadOptions::default())
+            .expect("begin transaction bench read");
+        let row = self
+            .live_state
+            .reader(&read)
+            .load_row(&LiveStateRowRequest {
+                schema_key: "json_pointer".to_string(),
+                branch_id: BENCH_BRANCH_ID.to_string(),
+                entity_pk: EntityPk::single(row.entity_pk.clone()),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await
+            .expect("load transaction bench row");
+        assert!(row.is_some());
+        1
+    }
+
+    async fn commit_rows(&mut self, rows: Vec<TransactionWriteRow>) -> BenchWriteAccounting {
+        let logical_rows = rows.len();
+        let opened = super::open_transaction(
+            &SessionMode::Pinned {
+                branch_id: BENCH_BRANCH_ID.to_string(),
+            },
+            self.storage.clone(),
+            Arc::clone(&self.live_state),
+            Arc::clone(&self.tracked_state),
+            Arc::clone(&self.binary_cas),
+            Arc::clone(&self.branch_ctx),
+            Arc::clone(&self.catalog_context),
+        )
+        .await
+        .expect("open transaction bench transaction");
+        let mut transaction = opened.transaction;
+        transaction
+            .stage_rows(rows)
+            .await
+            .expect("stage transaction bench rows");
+        let outcome = transaction
+            .commit(&opened.runtime_functions)
+            .await
+            .expect("commit transaction bench rows");
+        write_accounting(logical_rows, outcome.storage_stats)
+    }
+
+    pub fn layout_accounting(&self) -> Vec<BenchLayoutAccounting> {
+        let read = self
+            .storage
+            .begin_read(StorageReadOptions::default())
+            .expect("begin transaction layout accounting read");
+        crate::storage_bench::layout_accounting(&read)
+            .into_iter()
+            .map(|space| BenchLayoutAccounting {
+                space_id: space.space_id,
+                space: space.space,
+                rows: space.rows,
+                key_bytes: space.key_bytes,
+                value_bytes: space.value_bytes,
+            })
+            .collect()
+    }
+}
+
+fn write_accounting(logical_rows: usize, stats: StorageWriteSetStats) -> BenchWriteAccounting {
+    BenchWriteAccounting {
+        logical_rows,
+        staged_puts: stats.staged_puts,
+        staged_deletes: stats.staged_deletes,
+        touched_spaces: stats.touched_spaces,
+        backend_calls: stats.backend_calls,
+        put_batches: stats.put_batches,
+        delete_batches: stats.delete_batches,
+        written_bytes: stats.written_bytes,
+    }
+}
+
+fn transaction_row(row: &BenchTransactionRow, value: &JsonValue) -> TransactionWriteRow {
+    TransactionWriteRow {
+        entity_pk: Some(EntityPk::single(row.entity_pk.clone())),
+        schema_key: row.schema_key.clone(),
+        file_id: row.file_id.clone(),
+        snapshot: Some(TransactionJson::from_value_unchecked(value.clone())),
+        metadata: None,
+        origin: None,
+        created_at: None,
+        updated_at: None,
+        global: false,
+        change_id: None,
+        commit_id: None,
+        untracked: false,
+        branch_id: BENCH_BRANCH_ID.to_string(),
+    }
+}
+
+fn transaction_delete_row(row: &BenchTransactionRow) -> TransactionWriteRow {
+    let mut out = transaction_row(row, &row.value);
+    out.snapshot = None;
+    out
+}
+
+async fn seed_visible_schema_rows<B>(
+    storage: StorageContext<B>,
+    tracked_state: &TrackedStateContext,
+) where
+    B: StorageBackend + Clone,
+    for<'a> StorageBackendReadOf<'a, B>: Send,
+{
+    let mut writes = StorageWriteSet::new();
+    let mut schemas = crate::schema::seed_schema_definitions()
+        .into_iter()
+        .cloned()
+        .collect::<Vec<_>>();
+    schemas.push(json_pointer_schema());
+    let rows = schemas
+        .iter()
+        .map(|schema| {
+            let key = crate::schema::schema_key_from_definition(schema)
+                .expect("seed schema key should derive");
+            let snapshot_content = json!({ "value": schema }).to_string();
+            crate::tracked_state::MaterializedTrackedStateRow {
+                entity_pk: crate::schema::registered_schema_entity_pk(&key.schema_key)
+                    .expect("registered schema identity should derive"),
+                schema_key: "lix_registered_schema".to_string(),
+                file_id: None,
+                snapshot_content: Some(snapshot_content),
+                metadata: None,
+                deleted: false,
+                created_at: TIMESTAMP.to_string(),
+                updated_at: TIMESTAMP.to_string(),
+                change_id: format!("schema-fixture-{}", key.schema_key),
+                commit_id: SCHEMA_FIXTURE_COMMIT_ID.to_string(),
+            }
+        })
+        .collect::<Vec<_>>();
+    let global_branch_ref_row = crate::transaction::prepare_branch_ref_row(
+        GLOBAL_BRANCH_ID,
+        SCHEMA_FIXTURE_COMMIT_ID,
+        TIMESTAMP,
+    )
+    .expect("schema fixture branch ref should stage");
+    let bench_branch_ref_row = crate::transaction::prepare_branch_ref_row(
+        BENCH_BRANCH_ID,
+        SCHEMA_FIXTURE_COMMIT_ID,
+        TIMESTAMP,
+    )
+    .expect("bench fixture branch ref should stage");
+    let mut read = BenchRead::new(
+        storage
+            .begin_read(StorageReadOptions::default())
+            .expect("schema fixture read should open"),
+    );
+    crate::test_support::stage_tracked_root_from_materialized(
+        &mut read,
+        &mut writes,
+        tracked_state,
+        SCHEMA_FIXTURE_COMMIT_ID,
+        None,
+        &rows,
+    )
+    .await
+    .expect("schema fixture rows should stage");
+    UntrackedStateContext::new()
+        .writer(&mut writes)
+        .stage_rows([
+            global_branch_ref_row.row.as_ref(),
+            bench_branch_ref_row.row.as_ref(),
+        ])
+        .expect("schema fixture branch ref should stage");
+    crate::storage_bench::commit_write_set_for_bench(&storage, writes)
+        .expect("schema fixture transaction should commit");
+}
+
+fn json_pointer_schema() -> JsonValue {
+    json!({
+        "x-lix-key": "json_pointer",
+        "x-lix-primary-key": ["/path"],
+        "type": "object",
+        "properties": {
+            "path": { "type": "string" },
+            "value": true
+        },
+        "required": ["path", "value"],
+        "additionalProperties": false
+    })
+}