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

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

@@ -1,79 +1,91 @@
 use std::collections::BTreeSet;
 
+use crate::changelog::{
+    ChangeLoadRequest, ChangeRecord, ChangelogContext, ChangelogReader, CommitLoadEntry,
+    CommitLoadRequest, CommitProjection, CommitRecord, CommitScanRequest,
+};
 use crate::commit_graph::walker::{best_common_ancestors, walk_reachable_commits};
 use crate::commit_graph::{
-    CommitGraphChangeHistoryEntry, CommitGraphChangeHistoryRequest, CommitGraphCommit,
-    CommitGraphEdge, CommitGraphReader, ReachableCommitGraphCommit,
+    CommitGraphChange, CommitGraphChangeHistoryEntry, CommitGraphChangeHistoryRequest,
+    CommitGraphCommit, CommitGraphEdge, CommitGraphReader, ReachableCommitGraphCommit,
 };
-use crate::commit_store::{Change, Commit, CommitStoreContext, CommitStoreReader, LocatedChange};
-use crate::entity_identity::EntityIdentity;
-use crate::storage::StorageReader;
-use crate::storage::{ScopedStorageReader, StorageReadScope};
+use crate::entity_pk::EntityPk;
+use crate::storage::StorageRead;
 use crate::LixError;
 
 const COMMIT_SCHEMA_KEY: &str = "lix_commit";
 
-/// Read model for resolving commit-store commits into entity state at a head.
+/// Read model for resolving changelog commits into entity state at a head.
 ///
-/// This module does not own durable storage. It reads immutable commit-store
+/// This module does not own durable storage. It reads immutable changelog
 /// facts through a caller-provided KV store and applies commit graph rules on
 /// top.
 #[derive(Clone)]
-pub(crate) struct CommitGraphContext {
-    commit_store: CommitStoreContext,
-}
+pub(crate) struct CommitGraphContext;
 
 impl CommitGraphContext {
     pub(crate) fn new() -> Self {
-        Self {
-            commit_store: CommitStoreContext::new(),
-        }
+        Self
     }
 
     /// Creates a graph reader over a caller-provided KV store.
     pub(crate) fn reader<S>(&self, store: S) -> CommitGraphStoreReader<S>
     where
-        S: StorageReader,
+        S: StorageRead + Send + Sync,
     {
-        let read_scope = StorageReadScope::new(store);
-        CommitGraphStoreReader {
-            commit_store_reader: self.commit_store.reader(read_scope.store()),
-        }
+        CommitGraphStoreReader { store }
     }
 }
 
-/// Commit-graph reader that resolves commit-store entities at a commit head.
+/// Commit-graph reader that resolves changelog entities at a commit head.
 pub(crate) struct CommitGraphStoreReader<S>
 where
-    S: StorageReader,
+    S: StorageRead + Send + Sync,
 {
-    commit_store_reader: CommitStoreReader<ScopedStorageReader<S>>,
+    store: S,
 }
 
 impl<S> CommitGraphStoreReader<S>
 where
-    S: StorageReader,
+    S: StorageRead + Send + Sync,
 {
     /// Loads and parses a `lix_commit` canonical change by commit id.
     pub(crate) async fn load_commit(
         &mut self,
         commit_id: &str,
     ) -> Result<Option<CommitGraphCommit>, LixError> {
-        let Some(commit) = self.commit_store_reader.load_commit(commit_id).await? else {
-            return Ok(None);
-        };
-        self.graph_commit_from_store_commit(commit).await.map(Some)
+        self.load_changelog_commit(commit_id).await
     }
 
-    /// Loads every commit fact from the commit store.
+    /// Loads every direct commit fact from the changelog.
     ///
     /// This is used by global commit surfaces where the caller wants the durable
-    /// graph facts themselves, not reachability from a particular version head.
+    /// graph facts themselves, not reachability from a particular branch head.
     pub(crate) async fn all_commits(&mut self) -> Result<Vec<CommitGraphCommit>, LixError> {
-        let stored_commits = self.commit_store_reader.scan_commits().await?;
         let mut commits = Vec::new();
-        for commit in stored_commits {
-            commits.push(self.graph_commit_from_store_commit(commit).await?);
+        let mut start_after = None::<String>;
+        loop {
+            let mut reader = ChangelogContext::new().reader(&self.store);
+            let scan = reader
+                .scan_commits(CommitScanRequest {
+                    start_after: start_after.as_deref(),
+                    limit: Some(1024),
+                    projection: CommitProjection::Record,
+                })
+                .await?;
+            for entry in scan.entries {
+                let CommitLoadEntry::Record(record) = entry else {
+                    return Err(LixError::new(
+                        LixError::CODE_INTERNAL_ERROR,
+                        "changelog commit scan returned non-record entry",
+                    ));
+                };
+                commits.push(commit_graph_commit_from_commit_record(record, Vec::new()));
+            }
+            let Some(next) = scan.next_start_after else {
+                break;
+            };
+            start_after = Some(next);
         }
         commits.sort_by(|left, right| left.commit_id.cmp(&right.commit_id));
         Ok(commits)
@@ -150,9 +162,10 @@ where
 
     /// Returns canonical changes reachable from `start_commit_id`.
     ///
-    /// This is the primitive history API. It reports the commit/depth where
-    /// each matching canonical change was introduced or adopted during graph
-    /// traversal and leaves row shaping to callers such as SQL providers.
+    /// This is the primitive history API. It reports the commit/depth where a
+    /// reachable commit's change-ref set first exposes each matching canonical
+    /// change during graph traversal and leaves row shaping to callers such as
+    /// SQL providers.
     pub(crate) async fn change_history_from_commit(
         &mut self,
         start_commit_id: &str,
@@ -168,16 +181,26 @@ where
             }
 
             let commit_id = reachable.commit.commit_id;
+            let canonical_change = reachable.commit.canonical_change;
+            if seen_change_ids.insert(canonical_change.id.clone())
+                && change_matches_history_request(&canonical_change, request)
+            {
+                entries.push(CommitGraphChangeHistoryEntry {
+                    change: canonical_change,
+                    observed_commit_id: commit_id.clone(),
+                    start_commit_id: start_commit_id.to_string(),
+                    depth: reachable.depth,
+                });
+            }
+
             for change_id in reachable.commit.change_ids {
                 if !seen_change_ids.insert(change_id.clone()) {
                     continue;
                 }
-                let change = self
-                    .load_member_canonical_change(&change_id, &commit_id)
-                    .await?;
-                if change_matches_history_request(&change.record, request) {
+                let change = self.load_member_canonical_change(&change_id).await?;
+                if change_matches_history_request(&change, request) {
                     entries.push(CommitGraphChangeHistoryEntry {
-                        located_change: change,
+                        change,
                         observed_commit_id: commit_id.clone(),
                         start_commit_id: start_commit_id.to_string(),
                         depth: reachable.depth,
@@ -192,8 +215,7 @@ where
     async fn load_member_canonical_change(
         &mut self,
         change_id: &str,
-        source_commit_id: &str,
-    ) -> Result<LocatedChange, LixError> {
+    ) -> Result<CommitGraphChange, LixError> {
         let change_ids = vec![change_id.to_string()];
         self.load_canonical_changes(&change_ids)
             .await?
@@ -203,72 +225,77 @@ where
             .ok_or_else(|| {
                 LixError::new(
                     "LIX_ERROR_UNKNOWN",
-                    format!(
-                        "commit_graph commit '{source_commit_id}' references missing change '{change_id}'"
-                    ),
+                    format!("commit_graph references missing change '{change_id}'"),
                 )
             })
     }
 
-    async fn graph_commit_from_store_commit(
+    async fn load_changelog_commit(
         &mut self,
-        commit: Commit,
-    ) -> Result<CommitGraphCommit, LixError> {
-        let change_ids = self.load_commit_change_ids(&commit).await?;
-        Ok(commit_graph_commit_from_store_commit(commit, change_ids)?)
-    }
-
-    async fn load_commit_change_ids(&self, commit: &Commit) -> Result<Vec<String>, LixError> {
-        let mut change_ids = Vec::new();
-        for pack_id in 0..commit.change_pack_count {
-            let Some(changes) = self
-                .commit_store_reader
-                .load_change_pack(&commit.id, pack_id)
-                .await?
-            else {
-                return Err(missing_pack_error("change", &commit.id, pack_id));
-            };
-            change_ids.extend(changes.into_iter().map(|change| change.id));
-        }
-        for pack_id in 0..commit.membership_pack_count {
-            let Some(members) = self
-                .commit_store_reader
-                .load_membership_pack(&commit.id, pack_id)
-                .await?
-            else {
-                return Err(missing_pack_error("membership", &commit.id, pack_id));
-            };
-            change_ids.extend(members.into_iter().map(|locator| locator.change_id));
+        commit_id: &str,
+    ) -> Result<Option<CommitGraphCommit>, LixError> {
+        let mut reader = ChangelogContext::new().reader(&self.store);
+        let batch = reader
+            .load_commits(CommitLoadRequest {
+                commit_ids: &[commit_id.to_string()],
+                projection: CommitProjection::Full,
+            })
+            .await?;
+        let Some(entry) = batch.entries.into_iter().next().flatten() else {
+            return Ok(None);
+        };
+        match entry {
+            CommitLoadEntry::Full {
+                record,
+                change_ref_chunks,
+            } => {
+                let change_ids = change_ref_chunks
+                    .into_iter()
+                    .flat_map(|chunk| chunk.entries.into_iter().map(|entry| entry.change_id))
+                    .collect::<Vec<_>>();
+                Ok(Some(commit_graph_commit_from_commit_record(
+                    record, change_ids,
+                )))
+            }
+            _ => Err(LixError::new(
+                LixError::CODE_INTERNAL_ERROR,
+                "changelog full commit projection returned non-full entry",
+            )),
         }
-        Ok(change_ids)
     }
 
     async fn load_canonical_changes(
         &self,
         change_ids: &[String],
-    ) -> Result<Vec<Option<LocatedChange>>, LixError> {
-        self.commit_store_reader
-            .load_located_changes(change_ids)
-            .await
-            .map(|changes| {
-                changes
-                    .into_iter()
-                    .map(|located| {
-                        located.map(|located| LocatedChange {
-                            record: canonical_change_from_store_change(located.record),
-                            source_commit_id: located.source_commit_id,
-                            source_pack_id: located.source_pack_id,
-                        })
-                    })
-                    .collect()
-            })
+    ) -> Result<Vec<Option<CommitGraphChange>>, LixError> {
+        let mut reader = ChangelogContext::new().reader(&self.store);
+        let batch = reader
+            .load_changes(ChangeLoadRequest { change_ids })
+            .await?;
+        batch
+            .entries
+            .into_iter()
+            .map(|entry| Ok(entry.map(commit_graph_change_from_change_record)))
+            .collect()
+    }
+}
+
+fn commit_graph_change_from_change_record(change: ChangeRecord) -> CommitGraphChange {
+    CommitGraphChange {
+        id: change.change_id,
+        entity_pk: change.entity_pk,
+        schema_key: change.schema_key,
+        file_id: change.file_id,
+        snapshot_ref: change.snapshot_ref,
+        metadata_ref: change.metadata_ref,
+        created_at: change.created_at,
     }
 }
 
 #[async_trait::async_trait]
 impl<S> CommitGraphReader for CommitGraphStoreReader<S>
 where
-    S: StorageReader,
+    S: StorageRead + Send + Sync,
 {
     async fn load_commit(
         &mut self,
@@ -277,10 +304,6 @@ where
         CommitGraphStoreReader::load_commit(self, commit_id).await
     }
 
-    async fn all_commits(&mut self) -> Result<Vec<CommitGraphCommit>, LixError> {
-        CommitGraphStoreReader::all_commits(self).await
-    }
-
     async fn reachable_commits(
         &mut self,
         head_commit_id: &str,
@@ -288,26 +311,6 @@ where
         CommitGraphStoreReader::reachable_commits(self, head_commit_id).await
     }
 
-    async fn best_common_ancestors(
-        &mut self,
-        left_commit_id: &str,
-        right_commit_id: &str,
-    ) -> Result<Vec<CommitGraphCommit>, LixError> {
-        CommitGraphStoreReader::best_common_ancestors(self, left_commit_id, right_commit_id).await
-    }
-
-    async fn merge_base(
-        &mut self,
-        left_commit_id: &str,
-        right_commit_id: &str,
-    ) -> Result<CommitGraphCommit, LixError> {
-        CommitGraphStoreReader::merge_base(self, left_commit_id, right_commit_id).await
-    }
-
-    fn commit_edges(&self, commits: &[CommitGraphCommit]) -> Vec<CommitGraphEdge> {
-        CommitGraphStoreReader::commit_edges(self, commits)
-    }
-
     async fn change_history_from_commit(
         &mut self,
         start_commit_id: &str,
@@ -323,11 +326,11 @@ fn depth_matches(depth: u32, request: &CommitGraphChangeHistoryRequest) -> bool
 }
 
 fn change_matches_history_request(
-    change: &Change,
+    change: &CommitGraphChange,
     request: &CommitGraphChangeHistoryRequest,
 ) -> bool {
     (request.include_tombstones || change.snapshot_ref.is_some())
-        && (request.entity_ids.is_empty() || request.entity_ids.contains(&change.entity_id))
+        && (request.entity_pks.is_empty() || request.entity_pks.contains(&change.entity_pk))
         && (request.schema_keys.is_empty() || request.schema_keys.contains(&change.schema_key))
         && (request.file_ids.is_empty()
             || change
@@ -336,81 +339,76 @@ fn change_matches_history_request(
                 .is_some_and(|file_id| request.file_ids.contains(file_id)))
 }
 
-fn commit_graph_commit_from_store_commit(
-    commit: Commit,
+fn commit_graph_commit_from_commit_record(
+    record: CommitRecord,
     change_ids: Vec<String>,
-) -> Result<CommitGraphCommit, LixError> {
-    let change = commit_header_canonical_change(commit.clone());
-    Ok(CommitGraphCommit {
+) -> CommitGraphCommit {
+    let change = commit_record_canonical_change(&record);
+    CommitGraphCommit {
         canonical_change: change.clone(),
         change,
-        commit_id: commit.id,
+        commit_id: record.commit_id,
         change_ids,
-        author_account_ids: commit.author_account_ids,
-        parent_commit_ids: commit.parent_ids,
-    })
+        author_account_ids: record.author_account_ids,
+        parent_commit_ids: record.parent_commit_ids,
+    }
 }
 
-fn commit_header_canonical_change(commit: Commit) -> Change {
-    Change {
-        id: commit.change_id,
-        entity_id: EntityIdentity::single(&commit.id),
+fn commit_record_canonical_change(record: &CommitRecord) -> CommitGraphChange {
+    let snapshot_content = serde_json::to_string(&serde_json::json!({
+        "id": record.commit_id,
+    }))
+    .expect("lix_commit snapshot serialization should not fail");
+    CommitGraphChange {
+        id: record.change_id.clone(),
+        entity_pk: EntityPk::single(&record.commit_id),
         schema_key: COMMIT_SCHEMA_KEY.to_string(),
         file_id: None,
-        snapshot_ref: None,
+        snapshot_ref: Some(crate::json_store::JsonRef::for_content(
+            snapshot_content.as_bytes(),
+        )),
         metadata_ref: None,
-        created_at: commit.created_at,
-    }
-}
-
-fn canonical_change_from_store_change(change: Change) -> Change {
-    Change {
-        id: change.id,
-        entity_id: change.entity_id,
-        schema_key: change.schema_key,
-        file_id: change.file_id,
-        snapshot_ref: change.snapshot_ref,
-        metadata_ref: change.metadata_ref,
-        created_at: change.created_at,
+        created_at: record.created_at.clone(),
     }
 }
 
-fn missing_pack_error(label: &str, commit_id: &str, pack_id: u32) -> LixError {
-    LixError::new(
-        LixError::CODE_INTERNAL_ERROR,
-        format!("commit_graph missing {label} pack ({commit_id}, {pack_id})"),
-    )
-}
-
 #[cfg(test)]
 mod tests {
     use std::collections::{BTreeMap, BTreeSet};
-    use std::sync::Arc;
 
-    use crate::backend::testing::UnitTestBackend;
-    use crate::commit_graph::{CommitGraphChangeHistoryRequest, CommitGraphContext};
-    use crate::commit_store::{
-        Change, ChangeLocator, ChangeRef, CommitDraftRef, CommitStoreContext,
+    use crate::changelog::{
+        ChangeRecord, ChangelogAppend, ChangelogContext, ChangelogWriter, CommitChangeRef,
+        CommitChangeRefSet, CommitRecord,
     };
-    use crate::storage::{StorageContext, StorageWriteSet};
+    use crate::commit_graph::{
+        CommitGraphChange, CommitGraphChangeHistoryRequest, CommitGraphContext,
+    };
+    use crate::storage::StorageContext;
+    use crate::storage::{InMemoryStorageBackend, StorageReadOptions, StorageWriteOptions};
 
     #[tokio::test]
     async fn load_commit_parses_commit_snapshot() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         append_changes(
-            storage.clone(),
-            &[commit_change(
-                "commit-1-change",
-                "commit-1",
-                &["change-1", "change-2"],
-                &["parent-1"],
-            )],
+            &storage,
+            &[
+                entity_change("change-1", "entity-1", "example", "{}"),
+                entity_change("change-2", "entity-2", "example", "{}"),
+                commit_change(
+                    "commit-1-change",
+                    "commit-1",
+                    &["change-1", "change-2"],
+                    &["parent-1"],
+                ),
+            ],
         )
         .await;
 
         let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut reader = graph.reader(read);
         let commit = reader
             .load_commit("commit-1")
             .await
@@ -425,10 +423,12 @@ mod tests {
 
     #[tokio::test]
     async fn load_commit_returns_none_for_missing_commit() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut reader = graph.reader(read);
 
         let commit = reader
             .load_commit("missing")
@@ -440,10 +440,9 @@ mod tests {
 
     #[tokio::test]
     async fn all_commits_returns_parsed_commits_sorted_by_id() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         append_changes(
-            storage.clone(),
+            &storage,
             &[
                 commit_change("commit-b-change", "commit-b", &[], &[]),
                 entity_change("change-1", "entity-1", "example", "{}"),
@@ -453,7 +452,10 @@ mod tests {
         .await;
 
         let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut reader = graph.reader(read);
         let commits = reader
             .all_commits()
             .await
@@ -471,7 +473,11 @@ mod tests {
     #[tokio::test]
     async fn commit_edges_are_derived_from_parent_commit_ids() {
         let graph = CommitGraphContext::new();
-        let reader = graph.reader(StorageContext::new(Arc::new(UnitTestBackend::new())));
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let reader = graph.reader(read);
         let commits = vec![parsed_commit(
             "commit-head",
             &[],
@@ -498,10 +504,9 @@ mod tests {
 
     #[tokio::test]
     async fn change_history_from_commit_reports_matching_canonical_changes_with_depth() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         append_changes(
-            storage.clone(),
+            &storage,
             &[
                 entity_change("change-root", "entity-root", "test_schema", "{}"),
                 entity_change("change-head", "entity-head", "test_schema", "{}"),
@@ -517,7 +522,10 @@ mod tests {
         .await;
 
         let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut reader = graph.reader(read);
         let history = reader
             .change_history_from_commit(
                 "commit-head",
@@ -534,7 +542,7 @@ mod tests {
             history
                 .iter()
                 .map(|entry| (
-                    entry.located_change.record.id.as_str(),
+                    entry.change.id.as_str(),
                     entry.observed_commit_id.as_str(),
                     entry.start_commit_id.as_str(),
                     entry.depth
@@ -549,10 +557,9 @@ mod tests {
 
     #[tokio::test]
     async fn change_history_from_commit_filters_depth_entity_file_and_tombstones() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         append_changes(
-            storage.clone(),
+            &storage,
             &[
                 entity_change_with_file(
                     "change-file-a",
@@ -581,12 +588,15 @@ mod tests {
         .await;
 
         let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut reader = graph.reader(read);
         let history = reader
             .change_history_from_commit(
                 "commit-head",
                 &CommitGraphChangeHistoryRequest {
-                    entity_ids: vec![crate::entity_identity::EntityIdentity::single("entity-1")],
+                    entity_pks: vec![crate::entity_pk::EntityPk::single("entity-1")],
                     file_ids: vec!["file-a".to_string()],
                     min_depth: Some(1),
                     max_depth: Some(1),
@@ -598,16 +608,15 @@ mod tests {
             .expect("history should resolve");
 
         assert_eq!(history.len(), 1);
-        assert_eq!(history[0].located_change.record.id, "change-file-a");
+        assert_eq!(history[0].change.id, "change-file-a");
         assert_eq!(history[0].depth, 1);
     }
 
     #[tokio::test]
     async fn change_history_from_commit_includes_tombstones_when_requested() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
+        let storage = StorageContext::new(InMemoryStorageBackend::new());
         append_changes(
-            storage.clone(),
+            &storage,
             &[
                 entity_tombstone("change-deleted", "entity-1", "test_schema"),
                 commit_change(
@@ -621,15 +630,25 @@ mod tests {
         .await;
 
         let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
+        let read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut reader = graph.reader(read);
         let hidden = reader
-            .change_history_from_commit("commit-head", &CommitGraphChangeHistoryRequest::default())
+            .change_history_from_commit(
+                "commit-head",
+                &CommitGraphChangeHistoryRequest {
+                    schema_keys: vec!["test_schema".to_string()],
+                    ..CommitGraphChangeHistoryRequest::default()
+                },
+            )
             .await
             .expect("history should resolve");
         let visible = reader
             .change_history_from_commit(
                 "commit-head",
                 &CommitGraphChangeHistoryRequest {
+                    schema_keys: vec!["test_schema".to_string()],
                     include_tombstones: true,
                     ..CommitGraphChangeHistoryRequest::default()
                 },
@@ -639,12 +658,12 @@ mod tests {
 
         assert!(hidden.is_empty());
         assert_eq!(visible.len(), 1);
-        assert_eq!(visible[0].located_change.record.id, "change-deleted");
+        assert_eq!(visible[0].change.id, "change-deleted");
     }
 
     #[derive(Clone)]
     struct TestChange {
-        change: Change,
+        change: CommitGraphChange,
         commit_change_ids: Vec<String>,
         parent_commit_ids: Vec<String>,
         author_account_ids: Vec<String>,
@@ -658,9 +677,9 @@ mod tests {
             parent_commit_ids: &[&str],
         ) -> Self {
             Self {
-                change: Change {
+                change: CommitGraphChange {
                     id: change_id.to_string(),
-                    entity_id: crate::entity_identity::EntityIdentity::single(commit_id),
+                    entity_pk: crate::entity_pk::EntityPk::single(commit_id),
                     schema_key: super::COMMIT_SCHEMA_KEY.to_string(),
                     file_id: None,
                     snapshot_ref: None,
@@ -675,16 +694,16 @@ mod tests {
 
         fn entity(
             change_id: &str,
-            entity_id: &str,
+            entity_pk: &str,
             schema_key: &str,
             file_id: Option<&str>,
             snapshot_content: Option<&str>,
             created_at: &str,
         ) -> Self {
             Self {
-                change: Change {
+                change: CommitGraphChange {
                     id: change_id.to_string(),
-                    entity_id: crate::entity_identity::EntityIdentity::single(entity_id),
+                    entity_pk: crate::entity_pk::EntityPk::single(entity_pk),
                     schema_key: schema_key.to_string(),
                     file_id: file_id.map(str::to_string),
                     snapshot_ref: snapshot_content.map(|content| {
@@ -704,102 +723,126 @@ mod tests {
         }
     }
 
-    async fn append_changes(storage: StorageContext, changes: &[TestChange]) {
-        let mut tx = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        let mut writes = StorageWriteSet::new();
+    async fn append_changes(storage: &StorageContext, changes: &[TestChange]) {
+        let mut read = storage
+            .begin_read(StorageReadOptions::default())
+            .expect("read should open");
+        let mut writes = storage.new_write_set();
         let canonical_changes = changes
             .iter()
             .filter(|change| !change.is_commit())
-            .map(|change| change.change.clone())
+            .cloned()
             .collect::<Vec<_>>();
-        let changes_by_id: BTreeMap<&str, &Change> = canonical_changes
+        let changes_by_id: BTreeMap<&str, &TestChange> = canonical_changes
             .iter()
-            .map(|change| (change.id.as_str(), change))
+            .map(|change| (change.change.id.as_str(), change))
             .collect::<BTreeMap<_, _>>();
         let mut authored_change_ids = BTreeSet::new();
-        let commit_store = CommitStoreContext::new();
+        let provided_commit_ids = changes
+            .iter()
+            .filter(|change| change.is_commit())
+            .map(|change| {
+                change
+                    .change
+                    .entity_pk
+                    .as_single_string()
+                    .expect("commit fixture should use single entity pk")
+                    .to_string()
+            })
+            .collect::<BTreeSet<_>>();
+        let mut staged_commit_ids = BTreeSet::new();
+        let changelog = ChangelogContext::new();
+        let mut writer = changelog.writer(&mut read, &mut writes);
+        let mut append = ChangelogAppend::default();
         for change in changes.iter().filter(|change| change.is_commit()) {
             let commit = crate::commit_graph::CommitGraphCommit {
                 canonical_change: change.change.clone(),
                 change: change.change.clone(),
                 commit_id: change
                     .change
-                    .entity_id
+                    .entity_pk
                     .as_single_string()
-                    .expect("commit fixture should use single entity id")
+                    .expect("commit fixture should use single entity pk")
                     .to_string(),
                 change_ids: change.commit_change_ids.clone(),
                 author_account_ids: change.author_account_ids.clone(),
                 parent_commit_ids: change.parent_commit_ids.clone(),
             };
-            let parent_commit_ids = commit.parent_commit_ids.clone();
-            let author_account_ids = commit.author_account_ids.clone();
-            let commit_draft = CommitDraftRef {
-                id: &commit.commit_id,
-                change_id: &commit.canonical_change.id,
-                parent_ids: &parent_commit_ids,
-                author_account_ids: &author_account_ids,
-                created_at: &commit.canonical_change.created_at,
-            };
-
-            let mut authored_changes = Vec::new();
-            let mut adopted_changes = Vec::new();
-            let mut corrupt_missing_members = Vec::new();
+            for parent_commit_id in &commit.parent_commit_ids {
+                if !provided_commit_ids.contains(parent_commit_id)
+                    && staged_commit_ids.insert(parent_commit_id.clone())
+                {
+                    append_empty_commit(&mut append, parent_commit_id);
+                }
+            }
+            let mut refs = Vec::new();
             for change_id in &commit.change_ids {
                 if let Some(change) = changes_by_id.get(change_id.as_str()) {
                     if authored_change_ids.insert(change_id.clone()) {
-                        authored_changes.push(change_ref_from_canonical(change.as_ref()));
-                    } else {
-                        adopted_changes.push(change_ref_from_canonical(change.as_ref()));
+                        append.changes.push(change_record_from_test_change(change));
                     }
-                } else {
-                    corrupt_missing_members.push(change_id.clone());
+                    refs.push(commit_change_ref_from_test_change(change));
                 }
             }
 
-            if corrupt_missing_members.is_empty() {
-                commit_store
-                    .writer(tx.as_mut(), &mut writes)
-                    .stage_commit_draft(commit_draft, authored_changes, adopted_changes)
-                    .await
-                    .expect("commit-store append should succeed");
-            } else {
-                crate::commit_store::storage::stage_commit(
-                    &mut writes,
-                    commit_draft,
-                    authored_changes,
-                    corrupt_missing_members
-                        .into_iter()
-                        .map(|change_id| ChangeLocator {
-                            source_commit_id: "missing-source-commit".to_string(),
-                            source_pack_id: 0,
-                            source_ordinal: 0,
-                            change_id,
-                        })
-                        .collect(),
-                )
-                .expect("corrupt commit-store fixture should stage");
-            }
+            append.commits.push(CommitRecord {
+                format_version: 1,
+                commit_id: commit.commit_id.clone(),
+                parent_commit_ids: commit.parent_commit_ids.clone(),
+                change_id: commit.canonical_change.id.clone(),
+                author_account_ids: commit.author_account_ids.clone(),
+                created_at: commit.canonical_change.created_at.clone(),
+            });
+            append.commit_change_refs.push(CommitChangeRefSet {
+                commit_id: commit.commit_id.clone(),
+                entries: refs,
+            });
+            staged_commit_ids.insert(commit.commit_id.clone());
         }
-        writes
-            .apply(&mut tx.as_mut())
+        writer
+            .stage_append(append)
             .await
-            .expect("writes should apply");
-        tx.commit().await.expect("commit should succeed");
-    }
-
-    fn change_ref_from_canonical<'a>(change: crate::commit_store::ChangeRef<'a>) -> ChangeRef<'a> {
-        ChangeRef {
-            id: change.id,
-            entity_id: change.entity_id,
-            schema_key: change.schema_key,
-            file_id: change.file_id,
-            snapshot_ref: change.snapshot_ref,
-            metadata_ref: change.metadata_ref,
-            created_at: change.created_at,
+            .expect("changelog append should stage");
+        storage
+            .commit_write_set(writes, StorageWriteOptions::default())
+            .expect("commit should succeed");
+    }
+
+    fn append_empty_commit(append: &mut ChangelogAppend, commit_id: &str) {
+        let change_id = format!("{commit_id}-change");
+        append.commits.push(CommitRecord {
+            format_version: 1,
+            commit_id: commit_id.to_string(),
+            parent_commit_ids: Vec::new(),
+            change_id: change_id.clone(),
+            author_account_ids: Vec::new(),
+            created_at: "2026-01-01T00:00:00Z".to_string(),
+        });
+        append.commit_change_refs.push(CommitChangeRefSet {
+            commit_id: commit_id.to_string(),
+            entries: Vec::new(),
+        });
+    }
+
+    fn change_record_from_test_change(change: &TestChange) -> ChangeRecord {
+        ChangeRecord {
+            format_version: 1,
+            change_id: change.change.id.clone(),
+            entity_pk: change.change.entity_pk.clone(),
+            schema_key: change.change.schema_key.clone(),
+            file_id: change.change.file_id.clone(),
+            snapshot_ref: change.change.snapshot_ref,
+            metadata_ref: change.change.metadata_ref,
+            created_at: change.change.created_at.clone(),
+        }
+    }
+
+    fn commit_change_ref_from_test_change(change: &TestChange) -> CommitChangeRef {
+        CommitChangeRef {
+            schema_key: change.change.schema_key.clone(),
+            file_id: change.change.file_id.clone(),
+            entity_pk: change.change.entity_pk.clone(),
+            change_id: change.change.id.clone(),
         }
     }
 
@@ -841,13 +884,13 @@ mod tests {
 
     fn entity_change(
         change_id: &str,
-        entity_id: &str,
+        entity_pk: &str,
         schema_key: &str,
         snapshot_content: &str,
     ) -> TestChange {
         entity_change_at(
             change_id,
-            entity_id,
+            entity_pk,
             schema_key,
             snapshot_content,
             "2026-01-01T00:00:00Z",
@@ -856,14 +899,14 @@ mod tests {
 
     fn entity_change_at(
         change_id: &str,
-        entity_id: &str,
+        entity_pk: &str,
         schema_key: &str,
         snapshot_content: &str,
         created_at: &str,
     ) -> TestChange {
         TestChange::entity(
             change_id,
-            entity_id,
+            entity_pk,
             schema_key,
             None,
             Some(snapshot_content),
@@ -873,14 +916,14 @@ mod tests {
 
     fn entity_change_with_file(
         change_id: &str,
-        entity_id: &str,
+        entity_pk: &str,
         schema_key: &str,
         file_id: Option<&str>,
         snapshot_content: &str,
     ) -> TestChange {
         TestChange::entity(
             change_id,
-            entity_id,
+            entity_pk,
             schema_key,
             file_id,
             Some(snapshot_content),
@@ -888,10 +931,10 @@ mod tests {
         )
     }
 
-    fn entity_tombstone(change_id: &str, entity_id: &str, schema_key: &str) -> TestChange {
+    fn entity_tombstone(change_id: &str, entity_pk: &str, schema_key: &str) -> TestChange {
         TestChange::entity(
             change_id,
-            entity_id,
+            entity_pk,
             schema_key,
             None,
             None,