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

package/dist-engine-src/src/sql2/{directory_provider.rs → providers/directory.rs}

@@ -10,7 +10,7 @@ use datafusion::arrow::compute::{and, filter_record_batch};
 use datafusion::arrow::datatypes::{DataType, Field, Schema, SchemaRef};
 use datafusion::arrow::record_batch::RecordBatch;
 use datafusion::catalog::{Session, TableProvider};
-use datafusion::common::{not_impl_err, DFSchema, DataFusionError, Result, ScalarValue};
+use datafusion::common::{not_impl_err, DFSchema, DataFusionError, Result, ScalarValue, SchemaExt};
 use datafusion::datasource::TableType;
 use datafusion::execution::TaskContext;
 use datafusion::logical_expr::dml::InsertOp;
@@ -25,90 +25,108 @@ use datafusion::prelude::SessionContext;
 use futures_util::{stream, TryStreamExt};
 use serde::Deserialize;
 
+use crate::branch::BranchRefReader;
 use crate::functions::FunctionProviderHandle;
 use crate::live_state::MaterializedLiveStateRow;
 use crate::live_state::{
     LiveStateFilter, LiveStateProjection, LiveStateReader, LiveStateScanRequest,
 };
+use crate::sql2::branch_scope::{
+    explicit_branch_ids_from_dml_filters, resolve_provider_branch_ids, resolve_write_branch_scope,
+    BranchBinding,
+};
 use crate::sql2::dml::{InsertExec, InsertSink};
 use crate::sql2::filesystem_predicates::{
     canonicalize_filesystem_path_filters, FilesystemPathKind,
 };
-use crate::sql2::predicate_typecheck::validate_json_predicate_filters;
-use crate::sql2::version_scope::{
-    explicit_version_ids_from_dml_filters, resolve_provider_version_ids,
-    resolve_write_version_scope, VersionBinding,
+use crate::sql2::predicate_typecheck::{
+    canonicalize_json_identity_text_filters, validate_json_predicate_filters,
 };
 use crate::sql2::write_normalization::{InsertCell, SqlCell, UpdateAssignmentValues};
 use crate::transaction::types::{
     LogicalPrimaryKey, TransactionJson, TransactionWriteOperation, TransactionWriteOrigin,
     TransactionWriteRow,
 };
-use crate::version::VersionRefReader;
 use crate::{parse_row_metadata_value, serialize_row_metadata, LixError};
 
-use super::filesystem_planner::{
+use crate::sql2::filesystem_planner::{
     directory_descriptor_write_row, directory_path_resolvers_from_state_rows,
     filesystem_storage_scope_key, plan_recursive_directory_delete, DirectoryDescriptorWriteIntent,
     DirectoryPathResolver, FilesystemDeletePlan, FilesystemRowContext,
 };
-use super::filesystem_visibility::VisibleFilesystem;
-use super::result_metadata::json_field;
+use crate::sql2::filesystem_visibility::VisibleFilesystem;
+use crate::sql2::result_metadata::json_field;
 use crate::sql2::{
-    SqlWriteContext, WriteAccess, WriteContextLiveStateReader, WriteContextVersionRefReader,
+    SqlWriteContext, WriteAccess, WriteContextBranchRefReader, WriteContextLiveStateReader,
 };
 use crate::transaction::types::{TransactionWrite, TransactionWriteMode};
 
 const DIRECTORY_SCHEMA_KEY: &str = "lix_directory_descriptor";
 const FILE_DESCRIPTOR_SCHEMA_KEY: &str = "lix_file_descriptor";
 
-pub(crate) async fn register_lix_directory_providers(
+pub(super) async fn register_lix_directory_active_provider(
     session: &SessionContext,
-    active_version_id: &str,
+    surface_name: &str,
+    active_branch_id: &str,
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
     functions: FunctionProviderHandle,
 ) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_directory_by_version",
-            Arc::new(LixDirectoryProvider::by_version(
-                Arc::clone(&live_state),
-                Arc::clone(&version_ref),
-                functions.clone(),
+            surface_name,
+            Arc::new(LixDirectoryProvider::active_branch(
+                active_branch_id,
+                live_state,
+                branch_ref,
+                functions,
             )),
         )
         .map_err(datafusion_error_to_lix_error)?;
+    Ok(())
+}
+
+pub(super) async fn register_lix_directory_by_branch_provider(
+    session: &SessionContext,
+    surface_name: &str,
+    live_state: Arc<dyn LiveStateReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
+    functions: FunctionProviderHandle,
+) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_directory",
-            Arc::new(LixDirectoryProvider::active_version(
-                active_version_id,
-                live_state,
-                version_ref,
-                functions,
+            surface_name,
+            Arc::new(LixDirectoryProvider::by_branch(
+                live_state, branch_ref, functions,
             )),
         )
         .map_err(datafusion_error_to_lix_error)?;
     Ok(())
 }
 
-pub(crate) async fn register_lix_directory_write_providers(
+pub(super) async fn register_by_branch_write_provider(
     session: &SessionContext,
+    surface_name: &str,
     write_ctx: SqlWriteContext,
 ) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_directory_by_version",
-            Arc::new(LixDirectoryProvider::by_version_with_write(
-                write_ctx.clone(),
-            )),
+            surface_name,
+            Arc::new(LixDirectoryProvider::by_branch_with_write(write_ctx)),
         )
         .map_err(datafusion_error_to_lix_error)?;
+    Ok(())
+}
+
+pub(super) async fn register_active_write_provider(
+    session: &SessionContext,
+    surface_name: &str,
+    write_ctx: SqlWriteContext,
+) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_directory",
-            Arc::new(LixDirectoryProvider::active_version_with_write(write_ctx)),
+            surface_name,
+            Arc::new(LixDirectoryProvider::active_branch_with_write(write_ctx)),
         )
         .map_err(datafusion_error_to_lix_error)?;
     Ok(())
@@ -117,10 +135,10 @@ pub(crate) async fn register_lix_directory_write_providers(
 pub(crate) struct LixDirectoryProvider {
     schema: SchemaRef,
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
     write_access: WriteAccess,
     functions: FunctionProviderHandle,
-    version_binding: VersionBinding,
+    branch_binding: BranchBinding,
 }
 
 impl std::fmt::Debug for LixDirectoryProvider {
@@ -130,63 +148,63 @@ impl std::fmt::Debug for LixDirectoryProvider {
 }
 
 impl LixDirectoryProvider {
-    fn active_version(
-        active_version_id: impl Into<String>,
+    fn active_branch(
+        active_branch_id: impl Into<String>,
         live_state: Arc<dyn LiveStateReader>,
-        version_ref: Arc<dyn VersionRefReader>,
+        branch_ref: Arc<dyn BranchRefReader>,
         functions: FunctionProviderHandle,
     ) -> Self {
         Self {
             schema: lix_directory_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::read_only(),
             functions,
-            version_binding: VersionBinding::active(active_version_id),
+            branch_binding: BranchBinding::active(active_branch_id),
         }
     }
 
-    fn active_version_with_write(write_ctx: SqlWriteContext) -> Self {
-        let active_version_id = write_ctx.active_version_id();
+    fn active_branch_with_write(write_ctx: SqlWriteContext) -> Self {
+        let active_branch_id = write_ctx.active_branch_id();
         let functions = write_ctx.functions();
         let live_state = Arc::new(WriteContextLiveStateReader::new(write_ctx.clone()));
-        let version_ref = Arc::new(WriteContextVersionRefReader::new(write_ctx.clone()));
+        let branch_ref = Arc::new(WriteContextBranchRefReader::new(write_ctx.clone()));
         Self {
             schema: lix_directory_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::write(write_ctx),
             functions,
-            version_binding: VersionBinding::active(active_version_id),
+            branch_binding: BranchBinding::active(active_branch_id),
         }
     }
 
-    fn by_version(
+    fn by_branch(
         live_state: Arc<dyn LiveStateReader>,
-        version_ref: Arc<dyn VersionRefReader>,
+        branch_ref: Arc<dyn BranchRefReader>,
         functions: FunctionProviderHandle,
     ) -> Self {
         Self {
-            schema: lix_directory_by_version_schema(),
+            schema: lix_directory_by_branch_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::read_only(),
             functions,
-            version_binding: VersionBinding::explicit(),
+            branch_binding: BranchBinding::explicit(),
         }
     }
 
-    fn by_version_with_write(write_ctx: SqlWriteContext) -> Self {
+    fn by_branch_with_write(write_ctx: SqlWriteContext) -> Self {
         let functions = write_ctx.functions();
         let live_state = Arc::new(WriteContextLiveStateReader::new(write_ctx.clone()));
-        let version_ref = Arc::new(WriteContextVersionRefReader::new(write_ctx.clone()));
+        let branch_ref = Arc::new(WriteContextBranchRefReader::new(write_ctx.clone()));
         Self {
-            schema: lix_directory_by_version_schema(),
+            schema: lix_directory_by_branch_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::write(write_ctx),
             functions,
-            version_binding: VersionBinding::explicit(),
+            branch_binding: BranchBinding::explicit(),
         }
     }
 }
@@ -225,24 +243,14 @@ impl TableProvider for LixDirectoryProvider {
         let projected_schema = projected_schema(&self.schema, projection)?;
         let scan_limit = if filters.is_empty() { limit } else { None };
         let mut request = lix_directory_scan_request(
-            self.version_binding.active_version_id(),
+            self.branch_binding.active_branch_id(),
             Some(projected_schema.as_ref()),
             scan_limit,
         );
-        if self.write_access.is_write() && matches!(self.version_binding, VersionBinding::Explicit)
-        {
-            request.filter.version_ids = explicit_version_ids_from_dml_filters(filters);
-            if request.filter.version_ids.is_empty() {
-                return Err(DataFusionError::Plan(
-                    "DELETE FROM lix_directory_by_version requires an explicit lixcol_version_id predicate"
-                        .to_string(),
-                ));
-            }
-        }
-        request.filter.version_ids = resolve_provider_version_ids(
-            self.version_ref.as_ref(),
-            &self.version_binding,
-            request.filter.version_ids,
+        request.filter.branch_ids = resolve_provider_branch_ids(
+            self.branch_ref.as_ref(),
+            &self.branch_binding,
+            request.filter.branch_ids,
         )
         .await
         .map_err(lix_error_to_datafusion_error)?;
@@ -273,16 +281,15 @@ impl TableProvider for LixDirectoryProvider {
         if insert_op != InsertOp::Append {
             return not_impl_err!("{insert_op} not implemented for lix_directory yet");
         }
-
         let write_ctx = self
             .write_access
             .require_write("INSERT into lix_directory")?;
-
+        self.schema
+            .logically_equivalent_names_and_types(&input.schema())?;
         let sink = LixDirectoryInsertSink::new(
-            input.schema(),
-            write_ctx.clone(),
+            write_ctx,
             self.functions.clone(),
-            self.version_binding.clone(),
+            self.branch_binding.clone(),
         );
         Ok(Arc::new(InsertExec::new(input, Arc::new(sink))))
     }
@@ -295,31 +302,29 @@ impl TableProvider for LixDirectoryProvider {
         let write_ctx = self
             .write_access
             .require_write("DELETE FROM lix_directory")?;
-
-        let df_schema = DFSchema::try_from(Arc::clone(&self.schema))?;
         let filters =
             canonicalize_filesystem_path_filters(&filters, FilesystemPathKind::Directory)?;
+        let filters = canonicalize_json_identity_text_filters(self.schema.as_ref(), &filters)?;
+        let df_schema = DFSchema::try_from(Arc::clone(&self.schema))?;
         validate_json_predicate_filters(self.schema.as_ref(), &filters)?;
         let physical_filters = filters
             .iter()
             .map(|expr| create_physical_expr(expr, &df_schema, state.execution_props()))
             .collect::<Result<Vec<_>>>()?;
         let mut request =
-            lix_directory_scan_request(self.version_binding.active_version_id(), None, None);
-        if matches!(self.version_binding, VersionBinding::Explicit) {
-            request.filter.version_ids = explicit_version_ids_from_dml_filters(&filters);
-            if request.filter.version_ids.is_empty() {
-                return Err(DataFusionError::Plan(
-                    "DELETE FROM lix_directory_by_version requires an explicit lixcol_version_id predicate"
-                        .to_string(),
-                ));
-            }
-        }
-
+            lix_directory_scan_request(self.branch_binding.active_branch_id(), None, None);
+        request.filter.branch_ids = explicit_branch_ids_from_dml_filters(&filters);
+        request.filter.branch_ids = resolve_provider_branch_ids(
+            self.branch_ref.as_ref(),
+            &self.branch_binding,
+            request.filter.branch_ids,
+        )
+        .await
+        .map_err(lix_error_to_datafusion_error)?;
         Ok(Arc::new(LixDirectoryDeleteExec::new(
-            write_ctx.clone(),
+            write_ctx,
             Arc::clone(&self.schema),
-            self.version_binding.clone(),
+            self.branch_binding.clone(),
             request,
             physical_filters,
         )))
@@ -332,10 +337,12 @@ impl TableProvider for LixDirectoryProvider {
         filters: Vec<Expr>,
     ) -> Result<Arc<dyn ExecutionPlan>> {
         let write_ctx = self.write_access.require_write("UPDATE lix_directory")?;
-
         validate_lix_directory_update_assignments(&self.schema, &assignments)?;
-
+        let filters =
+            canonicalize_filesystem_path_filters(&filters, FilesystemPathKind::Directory)?;
+        let filters = canonicalize_json_identity_text_filters(self.schema.as_ref(), &filters)?;
         let df_schema = DFSchema::try_from(Arc::clone(&self.schema))?;
+        validate_json_predicate_filters(self.schema.as_ref(), &filters)?;
         let physical_assignments = assignments
             .iter()
             .map(|(column_name, expr)| {
@@ -345,20 +352,24 @@ impl TableProvider for LixDirectoryProvider {
                 ))
             })
             .collect::<Result<Vec<_>>>()?;
-        let filters =
-            canonicalize_filesystem_path_filters(&filters, FilesystemPathKind::Directory)?;
-        validate_json_predicate_filters(self.schema.as_ref(), &filters)?;
         let physical_filters = filters
             .iter()
             .map(|expr| create_physical_expr(expr, &df_schema, state.execution_props()))
             .collect::<Result<Vec<_>>>()?;
-        let request =
-            lix_directory_scan_request(self.version_binding.active_version_id(), None, None);
-
+        let mut request =
+            lix_directory_scan_request(self.branch_binding.active_branch_id(), None, None);
+        request.filter.branch_ids = explicit_branch_ids_from_dml_filters(&filters);
+        request.filter.branch_ids = resolve_provider_branch_ids(
+            self.branch_ref.as_ref(),
+            &self.branch_binding,
+            request.filter.branch_ids,
+        )
+        .await
+        .map_err(lix_error_to_datafusion_error)?;
         Ok(Arc::new(LixDirectoryUpdateExec::new(
-            write_ctx.clone(),
+            write_ctx,
             Arc::clone(&self.schema),
-            self.version_binding.clone(),
+            self.branch_binding.clone(),
             request,
             physical_assignments,
             physical_filters,
@@ -369,7 +380,7 @@ impl TableProvider for LixDirectoryProvider {
 struct LixDirectoryInsertSink {
     write_ctx: SqlWriteContext,
     functions: FunctionProviderHandle,
-    version_binding: VersionBinding,
+    branch_binding: BranchBinding,
     surface_name: &'static str,
 }
 
@@ -381,16 +392,15 @@ impl std::fmt::Debug for LixDirectoryInsertSink {
 
 impl LixDirectoryInsertSink {
     fn new(
-        _schema: SchemaRef,
         write_ctx: SqlWriteContext,
         functions: FunctionProviderHandle,
-        version_binding: VersionBinding,
+        branch_binding: BranchBinding,
     ) -> Self {
-        let surface_name = lix_directory_surface_name(&version_binding);
+        let surface_name = lix_directory_surface_name(&branch_binding);
         Self {
             write_ctx,
             functions,
-            version_binding,
+            branch_binding,
             surface_name,
         }
     }
@@ -422,7 +432,7 @@ impl InsertSink for LixDirectoryInsertSink {
                 path_resolvers = Some(
                     directory_path_resolvers_from_live_state(
                         Arc::new(WriteContextLiveStateReader::new(self.write_ctx.clone())),
-                        self.version_binding.active_version_id(),
+                        self.branch_binding.active_branch_id(),
                     )
                     .await
                     .map_err(lix_error_to_datafusion_error)?,
@@ -438,7 +448,7 @@ impl InsertSink for LixDirectoryInsertSink {
             if record_batch_has_non_null_column(&batch, "path")? {
                 rows.extend(lix_directory_write_rows_from_batch_with_path_resolvers(
                     &batch,
-                    self.version_binding.active_version_id(),
+                    self.branch_binding.active_branch_id(),
                     self.surface_name,
                     path_resolvers
                         .as_mut()
@@ -449,7 +459,7 @@ impl InsertSink for LixDirectoryInsertSink {
                 rows.extend(
                     lix_directory_write_rows_from_batch_with_options_and_path_resolvers(
                         &batch,
-                        self.version_binding.active_version_id(),
+                        self.branch_binding.active_branch_id(),
                         self.surface_name,
                         true,
                         path_resolvers.as_mut(),
@@ -471,10 +481,10 @@ impl InsertSink for LixDirectoryInsertSink {
     }
 }
 
-fn lix_directory_surface_name(version_binding: &VersionBinding) -> &'static str {
-    match version_binding {
-        VersionBinding::Active { .. } => "lix_directory",
-        VersionBinding::Explicit => "lix_directory_by_version",
+fn lix_directory_surface_name(branch_binding: &BranchBinding) -> &'static str {
+    match branch_binding {
+        BranchBinding::Active { .. } => "lix_directory",
+        BranchBinding::Explicit => "lix_directory_by_branch",
     }
 }
 
@@ -482,7 +492,7 @@ fn lix_directory_surface_name(version_binding: &VersionBinding) -> &'static str
 struct LixDirectoryDeleteExec {
     write_ctx: SqlWriteContext,
     table_schema: SchemaRef,
-    version_binding: VersionBinding,
+    branch_binding: BranchBinding,
     request: LiveStateScanRequest,
     filters: Vec<Arc<dyn PhysicalExpr>>,
     result_schema: SchemaRef,
@@ -499,7 +509,7 @@ impl LixDirectoryDeleteExec {
     fn new(
         write_ctx: SqlWriteContext,
         table_schema: SchemaRef,
-        version_binding: VersionBinding,
+        branch_binding: BranchBinding,
         request: LiveStateScanRequest,
         filters: Vec<Arc<dyn PhysicalExpr>>,
     ) -> Self {
@@ -513,7 +523,7 @@ impl LixDirectoryDeleteExec {
         Self {
             write_ctx,
             table_schema,
-            version_binding,
+            branch_binding,
             request,
             filters,
             result_schema,
@@ -574,7 +584,7 @@ impl ExecutionPlan for LixDirectoryDeleteExec {
         }
         let write_ctx = self.write_ctx.clone();
         let table_schema = Arc::clone(&self.table_schema);
-        let version_binding = self.version_binding.clone();
+        let branch_binding = self.branch_binding.clone();
         let request = self.request.clone();
         let filters = self.filters.clone();
         let result_schema = Arc::clone(&self.result_schema);
@@ -588,17 +598,15 @@ impl ExecutionPlan for LixDirectoryDeleteExec {
             let source_batch = lix_directory_record_batch(&table_schema, rows)
                 .map_err(lix_error_to_datafusion_error)?;
             let matched_batch = filter_lix_directory_batch(source_batch, &filters)?;
-            let version_ids = directory_version_ids_from_batch(
-                &matched_batch,
-                version_binding.active_version_id(),
-            )?;
+            let branch_ids =
+                directory_branch_ids_from_batch(&matched_batch, branch_binding.active_branch_id())?;
             let mut visible_filesystems = BTreeMap::new();
-            for version_id in version_ids {
+            for branch_id in branch_ids {
                 visible_filesystems.insert(
-                    version_id.clone(),
+                    branch_id.clone(),
                     VisibleFilesystem::load(
                         Arc::new(WriteContextLiveStateReader::new(write_ctx.clone())),
-                        &version_id,
+                        &branch_id,
                     )
                     .await
                     .map_err(lix_error_to_datafusion_error)?,
@@ -606,7 +614,7 @@ impl ExecutionPlan for LixDirectoryDeleteExec {
             }
             let (write_rows, count) = lix_directory_recursive_delete_rows_from_batch(
                 &matched_batch,
-                version_binding.active_version_id(),
+                branch_binding.active_branch_id(),
                 &visible_filesystems,
             )?;
 
@@ -637,7 +645,7 @@ impl ExecutionPlan for LixDirectoryDeleteExec {
 struct LixDirectoryUpdateExec {
     write_ctx: SqlWriteContext,
     table_schema: SchemaRef,
-    version_binding: VersionBinding,
+    branch_binding: BranchBinding,
     request: LiveStateScanRequest,
     assignments: Vec<(String, Arc<dyn PhysicalExpr>)>,
     filters: Vec<Arc<dyn PhysicalExpr>>,
@@ -655,7 +663,7 @@ impl LixDirectoryUpdateExec {
     fn new(
         write_ctx: SqlWriteContext,
         table_schema: SchemaRef,
-        version_binding: VersionBinding,
+        branch_binding: BranchBinding,
         request: LiveStateScanRequest,
         assignments: Vec<(String, Arc<dyn PhysicalExpr>)>,
         filters: Vec<Arc<dyn PhysicalExpr>>,
@@ -670,7 +678,7 @@ impl LixDirectoryUpdateExec {
         Self {
             write_ctx,
             table_schema,
-            version_binding,
+            branch_binding,
             request,
             assignments,
             filters,
@@ -737,7 +745,7 @@ impl ExecutionPlan for LixDirectoryUpdateExec {
         }
         let write_ctx = self.write_ctx.clone();
         let table_schema = Arc::clone(&self.table_schema);
-        let version_binding = self.version_binding.clone();
+        let branch_binding = self.branch_binding.clone();
         let request = self.request.clone();
         let assignments = self.assignments.clone();
         let filters = self.filters.clone();
@@ -754,14 +762,14 @@ impl ExecutionPlan for LixDirectoryUpdateExec {
             let matched_batch = filter_lix_directory_batch(source_batch, &filters)?;
             let mut path_resolvers = directory_path_resolvers_from_live_state(
                 Arc::new(WriteContextLiveStateReader::new(write_ctx.clone())),
-                version_binding.active_version_id(),
+                branch_binding.active_branch_id(),
             )
             .await
             .map_err(lix_error_to_datafusion_error)?;
             let write_rows = lix_directory_update_write_rows_from_batch(
                 &matched_batch,
                 &assignments,
-                version_binding.active_version_id(),
+                branch_binding.active_branch_id(),
                 &mut path_resolvers,
             )?;
             let count = u64::try_from(write_rows.len()).map_err(|_| {
@@ -942,21 +950,21 @@ struct DirectoryDescriptorSnapshot {
 #[cfg(test)]
 fn lix_directory_write_rows_from_batch(
     batch: &RecordBatch,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
 ) -> Result<Vec<TransactionWriteRow>> {
-    lix_directory_write_rows_from_batch_with_options(batch, version_binding, "lix_directory", true)
+    lix_directory_write_rows_from_batch_with_options(batch, branch_binding, "lix_directory", true)
 }
 
 fn lix_directory_write_rows_from_batch_with_path_resolvers(
     batch: &RecordBatch,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
     surface_name: &str,
     path_resolvers: &mut BTreeMap<String, DirectoryPathResolver>,
     generate_directory_id: &mut dyn FnMut() -> String,
 ) -> Result<Vec<TransactionWriteRow>> {
     lix_directory_write_rows_from_batch_with_options_and_path_resolvers(
         batch,
-        version_binding,
+        branch_binding,
         surface_name,
         true,
         Some(path_resolvers),
@@ -967,7 +975,7 @@ fn lix_directory_write_rows_from_batch_with_path_resolvers(
 fn lix_directory_update_write_rows_from_batch(
     batch: &RecordBatch,
     assignments: &[(String, Arc<dyn PhysicalExpr>)],
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
     path_resolvers: &mut BTreeMap<String, DirectoryPathResolver>,
 ) -> Result<Vec<TransactionWriteRow>> {
     let assignment_values = UpdateAssignmentValues::evaluate(batch, assignments)?;
@@ -978,7 +986,7 @@ fn lix_directory_update_write_rows_from_batch(
             batch,
             &assignment_values,
             row_index,
-            version_binding,
+            branch_binding,
         )?;
         let parent_id =
             update_optional_string_value(batch, &assignment_values, row_index, "parent_id")?;
@@ -1004,22 +1012,21 @@ fn lix_directory_update_write_rows_from_batch(
     Ok(rows)
 }
 
-fn directory_version_ids_from_batch(
+fn directory_branch_ids_from_batch(
     batch: &RecordBatch,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
 ) -> Result<BTreeSet<String>> {
-    let mut version_ids = BTreeSet::new();
+    let mut branch_ids = BTreeSet::new();
     for row_index in 0..batch.num_rows() {
-        version_ids.insert(
-            directory_row_context_from_batch(batch, row_index, version_binding)?.version_id,
-        );
+        branch_ids
+            .insert(directory_row_context_from_batch(batch, row_index, branch_binding)?.branch_id);
     }
-    Ok(version_ids)
+    Ok(branch_ids)
 }
 
 fn lix_directory_recursive_delete_rows_from_batch(
     batch: &RecordBatch,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
     visible_filesystems: &BTreeMap<String, VisibleFilesystem>,
 ) -> Result<(Vec<TransactionWriteRow>, u64)> {
     let mut rows = Vec::new();
@@ -1027,15 +1034,13 @@ fn lix_directory_recursive_delete_rows_from_batch(
     let mut count = 0u64;
     for row_index in 0..batch.num_rows() {
         let directory_id = required_string_value(batch, row_index, "id")?;
-        let context = directory_row_context_from_batch(batch, row_index, version_binding)?;
-        let visible_filesystem = visible_filesystems
-            .get(&context.version_id)
-            .ok_or_else(|| {
-                DataFusionError::Execution(format!(
-                    "DELETE FROM lix_directory missing visible filesystem for version '{}'",
-                    context.version_id
-                ))
-            })?;
+        let context = directory_row_context_from_batch(batch, row_index, branch_binding)?;
+        let visible_filesystem = visible_filesystems.get(&context.branch_id).ok_or_else(|| {
+            DataFusionError::Execution(format!(
+                "DELETE FROM lix_directory missing visible filesystem for branch '{}'",
+                context.branch_id
+            ))
+        })?;
         append_deduped_delete_plan(
             &mut rows,
             &mut seen,
@@ -1071,10 +1076,10 @@ fn is_user_visible_filesystem_delete_row(row: &TransactionWriteRow) -> bool {
 
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 struct StateRowDedupeKey {
-    entity_id: String,
+    entity_pk: String,
     schema_key: String,
     file_id: Option<String>,
-    version_id: String,
+    branch_id: String,
     global: bool,
     untracked: bool,
 }
@@ -1082,15 +1087,15 @@ struct StateRowDedupeKey {
 impl From<&TransactionWriteRow> for StateRowDedupeKey {
     fn from(row: &TransactionWriteRow) -> Self {
         Self {
-            entity_id: row
-                .entity_id
+            entity_pk: row
+                .entity_pk
                 .as_ref()
-                .expect("directory provider staged row should carry entity_id")
+                .expect("directory provider staged row should carry entity_pk")
                 .as_single_string_owned()
-                .expect("directory provider staged row entity identity should project"),
+                .expect("directory provider staged row entity primary key should project"),
             schema_key: row.schema_key.clone(),
             file_id: row.file_id.clone(),
-            version_id: row.version_id.clone(),
+            branch_id: row.branch_id.clone(),
             global: row.global,
             untracked: row.untracked,
         }
@@ -1100,13 +1105,13 @@ impl From<&TransactionWriteRow> for StateRowDedupeKey {
 #[cfg(test)]
 fn lix_directory_write_rows_from_batch_with_options(
     batch: &RecordBatch,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
     surface_name: &str,
     reject_read_only_fields: bool,
 ) -> Result<Vec<TransactionWriteRow>> {
     lix_directory_write_rows_from_batch_with_options_and_path_resolvers(
         batch,
-        version_binding,
+        branch_binding,
         surface_name,
         reject_read_only_fields,
         None,
@@ -1116,7 +1121,7 @@ fn lix_directory_write_rows_from_batch_with_options(
 
 fn lix_directory_write_rows_from_batch_with_options_and_path_resolvers(
     batch: &RecordBatch,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
     surface_name: &str,
     reject_read_only_fields: bool,
     mut path_resolvers: Option<&mut BTreeMap<String, DirectoryPathResolver>>,
@@ -1125,7 +1130,7 @@ fn lix_directory_write_rows_from_batch_with_options_and_path_resolvers(
     let mut rows = Vec::new();
     for row_index in 0..batch.num_rows() {
         if reject_read_only_fields {
-            reject_read_only_lix_directory_insert_field(batch, row_index, "lixcol_entity_id")?;
+            reject_read_only_lix_directory_insert_field(batch, row_index, "lixcol_entity_pk")?;
             reject_read_only_lix_directory_insert_field(batch, row_index, "lixcol_schema_key")?;
             reject_read_only_lix_directory_insert_field(batch, row_index, "lixcol_change_id")?;
             reject_read_only_lix_directory_insert_field(batch, row_index, "lixcol_created_at")?;
@@ -1136,7 +1141,7 @@ fn lix_directory_write_rows_from_batch_with_options_and_path_resolvers(
         let path = optional_string_value(batch, row_index, "path")?;
         let id = optional_string_value(batch, row_index, "id")?;
         let hidden = optional_bool_value(batch, row_index, "hidden")?;
-        let context = directory_row_context_from_batch(batch, row_index, version_binding)?;
+        let context = directory_row_context_from_batch(batch, row_index, branch_binding)?;
 
         if let Some(path) = path.filter(|_| reject_read_only_fields) {
             reject_read_only_lix_directory_insert_field(batch, row_index, "parent_id")?;
@@ -1209,14 +1214,14 @@ fn attach_lix_directory_insert_origin(
         if row.schema_key != DIRECTORY_SCHEMA_KEY {
             continue;
         }
-        let Some(entity_id) = row
-            .entity_id
+        let Some(entity_pk) = row
+            .entity_pk
             .as_ref()
-            .and_then(|entity_id| entity_id.as_single_string_owned().ok())
+            .and_then(|entity_pk| entity_pk.as_single_string_owned().ok())
         else {
             continue;
         };
-        if entity_id == directory_id {
+        if entity_pk == directory_id {
             row.origin = Some(origin.clone());
         }
     }
@@ -1236,18 +1241,18 @@ fn lix_directory_insert_origin(surface_name: &str, directory_id: &str) -> Transa
 fn directory_row_context_from_batch(
     batch: &RecordBatch,
     row_index: usize,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
 ) -> Result<FilesystemRowContext> {
-    let scope = resolve_write_version_scope(
+    let scope = resolve_write_branch_scope(
         optional_bool_value(batch, row_index, "lixcol_global")?,
-        optional_string_value(batch, row_index, "lixcol_version_id")?,
-        version_binding,
-        "INSERT into lix_directory_by_version",
+        optional_string_value(batch, row_index, "lixcol_branch_id")?,
+        branch_binding,
+        "INSERT into lix_directory_by_branch",
         "lix_directory",
     )?;
 
     Ok(FilesystemRowContext {
-        version_id: scope.version_id,
+        branch_id: scope.branch_id,
         global: scope.global,
         untracked: optional_bool_value(batch, row_index, "lixcol_untracked")?.unwrap_or(false),
         file_id: optional_string_value(batch, row_index, "lixcol_file_id")?,
@@ -1259,18 +1264,18 @@ fn directory_row_context_from_update(
     batch: &RecordBatch,
     assignment_values: &UpdateAssignmentValues,
     row_index: usize,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
 ) -> Result<FilesystemRowContext> {
-    let scope = resolve_write_version_scope(
+    let scope = resolve_write_branch_scope(
         optional_bool_value(batch, row_index, "lixcol_global")?,
-        optional_string_value(batch, row_index, "lixcol_version_id")?,
-        version_binding,
-        "UPDATE into lix_directory_by_version",
+        optional_string_value(batch, row_index, "lixcol_branch_id")?,
+        branch_binding,
+        "UPDATE into lix_directory_by_branch",
         "lix_directory",
     )?;
 
     Ok(FilesystemRowContext {
-        version_id: scope.version_id,
+        branch_id: scope.branch_id,
         global: scope.global,
         untracked: optional_bool_value(batch, row_index, "lixcol_untracked")?.unwrap_or(false),
         file_id: optional_string_value(batch, row_index, "lixcol_file_id")?,
@@ -1286,7 +1291,7 @@ fn directory_row_context_from_update(
 
 fn directory_path_resolver_key(context: &FilesystemRowContext) -> String {
     filesystem_storage_scope_key(
-        &context.version_id,
+        &context.branch_id,
         context.global,
         context.untracked,
         context.file_id.as_deref(),
@@ -1295,7 +1300,7 @@ fn directory_path_resolver_key(context: &FilesystemRowContext) -> String {
 
 async fn directory_path_resolvers_from_live_state(
     live_state: Arc<dyn LiveStateReader>,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
 ) -> std::result::Result<BTreeMap<String, DirectoryPathResolver>, LixError> {
     let rows = live_state
         .scan_rows(&LiveStateScanRequest {
@@ -1304,8 +1309,8 @@ async fn directory_path_resolvers_from_live_state(
                     DIRECTORY_SCHEMA_KEY.to_string(),
                     FILE_DESCRIPTOR_SCHEMA_KEY.to_string(),
                 ],
-                version_ids: version_binding
-                    .map(|version_id| vec![version_id.to_string()])
+                branch_ids: branch_binding
+                    .map(|branch_id| vec![branch_id.to_string()])
                     .unwrap_or_default(),
                 ..Default::default()
             },
@@ -1313,8 +1318,8 @@ async fn directory_path_resolvers_from_live_state(
         })
         .await?;
     let mut resolvers = directory_path_resolvers_from_state_rows(rows)?;
-    if let Some(version_id) = version_binding {
-        let key = filesystem_storage_scope_key(version_id, false, false, None);
+    if let Some(branch_id) = branch_binding {
+        let key = filesystem_storage_scope_key(branch_id, false, false, None);
         resolvers
             .entry(key)
             .or_insert_with(DirectoryPathResolver::default);
@@ -1357,7 +1362,7 @@ fn lix_directory_record_batch(
     let mut parent_ids = Vec::new();
     let mut names = Vec::new();
     let mut hiddens = Vec::new();
-    let mut entity_ids = Vec::new();
+    let mut entity_pks = Vec::new();
     let mut schema_keys = Vec::new();
     let mut file_ids = Vec::new();
     let mut globals = Vec::new();
@@ -1367,19 +1372,19 @@ fn lix_directory_record_batch(
     let mut commit_ids = Vec::new();
     let mut untracked_values = Vec::new();
     let mut metadata_values = Vec::new();
-    let mut version_ids = Vec::new();
+    let mut branch_ids = Vec::new();
 
     for directory in directory_rows {
         ids.push(Some(directory.id.clone()));
         paths.push(
             directory_paths
-                .get(&(directory.live.version_id.clone(), directory.id.clone()))
+                .get(&(directory.live.branch_id.clone(), directory.id.clone()))
                 .cloned(),
         );
         parent_ids.push(directory.parent_id);
         names.push(Some(directory.name));
         hiddens.push(Some(directory.hidden));
-        entity_ids.push(Some(directory.live.entity_id.as_json_array_text()?));
+        entity_pks.push(Some(directory.live.entity_pk.as_json_array_text()?));
         schema_keys.push(Some(directory.live.schema_key));
         file_ids.push(directory.live.file_id);
         globals.push(Some(directory.live.global));
@@ -1389,7 +1394,7 @@ fn lix_directory_record_batch(
         commit_ids.push(directory.live.commit_id);
         untracked_values.push(Some(directory.live.untracked));
         metadata_values.push(directory.live.metadata.as_ref().map(serialize_row_metadata));
-        version_ids.push(Some(directory.live.version_id));
+        branch_ids.push(Some(directory.live.branch_id));
     }
 
     let mut columns = Vec::<ArrayRef>::with_capacity(schema.fields().len());
@@ -1400,7 +1405,7 @@ fn lix_directory_record_batch(
             "parent_id" => Arc::new(StringArray::from(parent_ids.clone())),
             "name" => Arc::new(StringArray::from(names.clone())),
             "hidden" => Arc::new(BooleanArray::from(hiddens.clone())),
-            "lixcol_entity_id" => Arc::new(StringArray::from(entity_ids.clone())),
+            "lixcol_entity_pk" => Arc::new(StringArray::from(entity_pks.clone())),
             "lixcol_schema_key" => Arc::new(StringArray::from(schema_keys.clone())),
             "lixcol_file_id" => Arc::new(StringArray::from(file_ids.clone())),
             "lixcol_global" => Arc::new(BooleanArray::from(globals.clone())),
@@ -1410,7 +1415,7 @@ fn lix_directory_record_batch(
             "lixcol_commit_id" => Arc::new(StringArray::from(commit_ids.clone())),
             "lixcol_untracked" => Arc::new(BooleanArray::from(untracked_values.clone())),
             "lixcol_metadata" => Arc::new(StringArray::from(metadata_values.clone())),
-            "lixcol_version_id" => Arc::new(StringArray::from(version_ids.clone())),
+            "lixcol_branch_id" => Arc::new(StringArray::from(branch_ids.clone())),
             other => {
                 return Err(LixError::new(
                     "LIX_ERROR_UNKNOWN",
@@ -1435,19 +1440,19 @@ fn lix_directory_record_batch(
 fn derive_directory_paths(
     rows: &[DirectoryDescriptorRecord],
 ) -> std::result::Result<BTreeMap<(String, String), String>, LixError> {
-    let mut by_version = BTreeMap::<String, BTreeMap<String, &DirectoryDescriptorRecord>>::new();
+    let mut by_branch = BTreeMap::<String, BTreeMap<String, &DirectoryDescriptorRecord>>::new();
     for row in rows {
-        by_version
-            .entry(row.live.version_id.clone())
+        by_branch
+            .entry(row.live.branch_id.clone())
             .or_default()
             .insert(row.id.clone(), row);
     }
 
     let mut paths = BTreeMap::<(String, String), String>::new();
-    for (version_id, records) in by_version {
+    for (branch_id, records) in by_branch {
         for directory_id in records.keys() {
             derive_directory_path_for(
-                &version_id,
+                &branch_id,
                 directory_id,
                 &records,
                 &mut paths,
@@ -1459,17 +1464,17 @@ fn derive_directory_paths(
 }
 
 fn derive_directory_path_for(
-    version_id: &str,
+    branch_id: &str,
     directory_id: &str,
     records: &BTreeMap<String, &DirectoryDescriptorRecord>,
     paths: &mut BTreeMap<(String, String), String>,
     visiting: &mut BTreeSet<String>,
 ) -> std::result::Result<Option<String>, LixError> {
-    if let Some(path) = paths.get(&(version_id.to_string(), directory_id.to_string())) {
+    if let Some(path) = paths.get(&(branch_id.to_string(), directory_id.to_string())) {
         return Ok(Some(path.clone()));
     }
     if !visiting.insert(directory_id.to_string()) {
-        return Err(directory_parent_cycle_error(version_id, directory_id));
+        return Err(directory_parent_cycle_error(branch_id, directory_id));
     }
     let Some(row) = records.get(directory_id) else {
         visiting.remove(directory_id);
@@ -1478,7 +1483,7 @@ fn derive_directory_path_for(
     let path = match row.parent_id.as_deref() {
         Some(parent_id) => {
             let Some(parent_path) =
-                derive_directory_path_for(version_id, parent_id, records, paths, visiting)?
+                derive_directory_path_for(branch_id, parent_id, records, paths, visiting)?
             else {
                 visiting.remove(directory_id);
                 return Ok(None);
@@ -1489,17 +1494,17 @@ fn derive_directory_path_for(
     };
     visiting.remove(directory_id);
     paths.insert(
-        (version_id.to_string(), directory_id.to_string()),
+        (branch_id.to_string(), directory_id.to_string()),
         path.clone(),
     );
     Ok(Some(path))
 }
 
-fn directory_parent_cycle_error(version_id: &str, directory_id: &str) -> LixError {
+fn directory_parent_cycle_error(branch_id: &str, directory_id: &str) -> LixError {
     LixError::new(
         LixError::CODE_CONSTRAINT_VIOLATION,
         format!(
-            "lix_directory_descriptor parent_id cycle in version '{version_id}' while resolving directory '{directory_id}'"
+            "lix_directory_descriptor parent_id cycle in branch '{branch_id}' while resolving directory '{directory_id}'"
         ),
     )
 }
@@ -1520,15 +1525,15 @@ fn projected_schema(base_schema: &SchemaRef, projection: Option<&Vec<usize>>) ->
 }
 
 fn lix_directory_scan_request(
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
     projected_schema: Option<&Schema>,
     limit: Option<usize>,
 ) -> LiveStateScanRequest {
     LiveStateScanRequest {
         filter: LiveStateFilter {
             schema_keys: vec![DIRECTORY_SCHEMA_KEY.to_string()],
-            version_ids: version_binding
-                .map(|version_id| vec![version_id.to_string()])
+            branch_ids: branch_binding
+                .map(|branch_id| vec![branch_id.to_string()])
                 .unwrap_or_default(),
             ..LiveStateFilter::default()
         },
@@ -1717,9 +1722,9 @@ fn update_optional_metadata_value(
     update_optional_string_value(batch, assignment_values, row_index, column_name)?
         .map(|value| {
             let metadata = parse_row_metadata_value(&value, context)
-                .map_err(super::error::lix_error_to_datafusion_error)?;
+                .map_err(crate::sql2::error::lix_error_to_datafusion_error)?;
             TransactionJson::from_value(metadata, &format!("{context} metadata"))
-                .map_err(super::error::lix_error_to_datafusion_error)
+                .map_err(crate::sql2::error::lix_error_to_datafusion_error)
         })
         .transpose()
 }
@@ -1768,9 +1773,9 @@ fn optional_metadata_value(
     optional_string_value(batch, row_index, column_name)?
         .map(|value| {
             let metadata = parse_row_metadata_value(&value, context)
-                .map_err(super::error::lix_error_to_datafusion_error)?;
+                .map_err(crate::sql2::error::lix_error_to_datafusion_error)?;
             TransactionJson::from_value(metadata, &format!("{context} metadata"))
-                .map_err(super::error::lix_error_to_datafusion_error)
+                .map_err(crate::sql2::error::lix_error_to_datafusion_error)
         })
         .transpose()
 }
@@ -1814,14 +1819,14 @@ fn optional_scalar_value(
         })
 }
 
-fn lix_directory_schema() -> SchemaRef {
+pub(super) fn lix_directory_schema() -> SchemaRef {
     Arc::new(Schema::new(vec![
         Field::new("id", DataType::Utf8, true),
         Field::new("path", DataType::Utf8, true),
         Field::new("parent_id", DataType::Utf8, true),
         Field::new("name", DataType::Utf8, false),
         Field::new("hidden", DataType::Boolean, true),
-        json_field("lixcol_entity_id", false),
+        json_field("lixcol_entity_pk", false),
         Field::new("lixcol_schema_key", DataType::Utf8, false),
         Field::new("lixcol_file_id", DataType::Utf8, true),
         Field::new("lixcol_global", DataType::Boolean, true),
@@ -1834,22 +1839,22 @@ fn lix_directory_schema() -> SchemaRef {
     ]))
 }
 
-fn lix_directory_by_version_schema() -> SchemaRef {
+pub(super) fn lix_directory_by_branch_schema() -> SchemaRef {
     let mut fields = lix_directory_schema()
         .fields()
         .iter()
         .map(|field| field.as_ref().clone())
         .collect::<Vec<_>>();
-    fields.push(Field::new("lixcol_version_id", DataType::Utf8, false));
+    fields.push(Field::new("lixcol_branch_id", DataType::Utf8, false));
     Arc::new(Schema::new(fields))
 }
 
 fn datafusion_error_to_lix_error(error: DataFusionError) -> LixError {
-    super::error::datafusion_error_to_lix_error(error)
+    crate::sql2::error::datafusion_error_to_lix_error(error)
 }
 
 fn lix_error_to_datafusion_error(error: LixError) -> DataFusionError {
-    super::error::lix_error_to_datafusion_error(error)
+    crate::sql2::error::lix_error_to_datafusion_error(error)
 }
 
 #[cfg(test)]
@@ -1868,9 +1873,7 @@ mod tests {
     use crate::functions::{
         FunctionProvider, FunctionProviderHandle, SharedFunctionProvider, SystemFunctionProvider,
     };
-    use crate::live_state::{
-        LiveStateReader, LiveStateRowRequest, LiveStateScanRequest, MaterializedLiveStateRow,
-    };
+    use crate::live_state::{LiveStateScanRequest, MaterializedLiveStateRow};
     use crate::sql2::dml::InsertSink;
     use crate::sql2::{SqlWriteContext, SqlWriteExecutionContext};
     use crate::transaction::types::{
@@ -1881,10 +1884,10 @@ mod tests {
 
     use super::{
         derive_directory_path_for, directory_path_resolvers_from_state_rows,
-        lix_directory_by_version_schema, lix_directory_insert_origin, lix_directory_record_batch,
+        lix_directory_by_branch_schema, lix_directory_insert_origin, lix_directory_record_batch,
         lix_directory_recursive_delete_rows_from_batch, lix_directory_write_rows_from_batch,
-        lix_directory_write_rows_from_batch_with_path_resolvers, DirectoryDescriptorRecord,
-        LixDirectoryInsertSink, VersionBinding,
+        lix_directory_write_rows_from_batch_with_path_resolvers, BranchBinding,
+        DirectoryDescriptorRecord, LixDirectoryInsertSink,
     };
     use crate::sql2::filesystem_visibility::VisibleFilesystem;
 
@@ -1920,8 +1923,8 @@ mod tests {
 
     #[async_trait]
     impl SqlWriteExecutionContext for CapturingWriteContext {
-        fn active_version_id(&self) -> &str {
-            "version-a"
+        fn active_branch_id(&self) -> &str {
+            "branch-a"
         }
 
         fn functions(&self) -> FunctionProviderHandle {
@@ -1946,14 +1949,11 @@ mod tests {
             Ok(self.rows.clone())
         }
 
-        async fn load_version_head(
-            &mut self,
-            version_id: &str,
-        ) -> Result<Option<String>, LixError> {
-            if version_id == "ghost-version" {
+        async fn load_branch_head(&mut self, branch_id: &str) -> Result<Option<String>, LixError> {
+            if branch_id == "ghost-branch" {
                 return Ok(None);
             }
-            Ok(Some(format!("commit-{version_id}")))
+            Ok(Some(format!("commit-{branch_id}")))
         }
 
         async fn stage_write(
@@ -1965,60 +1965,37 @@ mod tests {
         }
     }
 
-    #[derive(Default)]
-    #[allow(dead_code)]
-    struct RowsLiveStateReader {
-        rows: Vec<MaterializedLiveStateRow>,
-    }
-
-    #[async_trait]
-    impl LiveStateReader for RowsLiveStateReader {
-        async fn scan_rows(
-            &self,
-            _request: &LiveStateScanRequest,
-        ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
-            Ok(self.rows.clone())
-        }
-
-        async fn load_row(
-            &self,
-            _request: &LiveStateRowRequest,
-        ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
-            Ok(None)
-        }
-    }
-
     fn live_row(
-        entity_id: &str,
-        version_id: &str,
+        entity_pk: &str,
+        branch_id: &str,
         snapshot_content: &str,
     ) -> MaterializedLiveStateRow {
         live_filesystem_row(
-            entity_id,
+            entity_pk,
             super::DIRECTORY_SCHEMA_KEY,
             None,
-            version_id,
+            branch_id,
             snapshot_content,
         )
     }
 
     fn live_filesystem_row(
-        entity_id: &str,
+        entity_pk: &str,
         schema_key: &str,
         file_id: Option<&str>,
-        version_id: &str,
+        branch_id: &str,
         snapshot_content: &str,
     ) -> MaterializedLiveStateRow {
         MaterializedLiveStateRow {
-            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(ToOwned::to_owned),
             snapshot_content: Some(snapshot_content.to_string()),
             metadata: Some(json!({"source": "test"}).to_string()),
             deleted: false,
-            version_id: version_id.to_string(),
-            change_id: Some(format!("change-{entity_id}")),
-            commit_id: Some(format!("commit-{entity_id}")),
+            branch_id: branch_id.to_string(),
+            change_id: Some(format!("change-{entity_pk}")),
+            commit_id: Some(format!("commit-{entity_pk}")),
             global: false,
             untracked: false,
             created_at: "2026-04-23T00:00:00Z".to_string(),
@@ -2032,35 +2009,35 @@ mod tests {
                 "dir-docs",
                 "lix_directory_descriptor",
                 None,
-                "version-a",
+                "branch-a",
                 r#"{"id":"dir-docs","parent_id":null,"name":"docs","hidden":false}"#,
             ),
             live_filesystem_row(
                 "dir-guides",
                 "lix_directory_descriptor",
                 None,
-                "version-a",
+                "branch-a",
                 r#"{"id":"dir-guides","parent_id":"dir-docs","name":"guides","hidden":false}"#,
             ),
             live_filesystem_row(
                 "file-index",
                 "lix_file_descriptor",
                 None,
-                "version-a",
+                "branch-a",
                 r#"{"id":"file-index","directory_id":"dir-docs","name":"index.md","hidden":false}"#,
             ),
             live_filesystem_row(
                 "file-readme",
                 "lix_file_descriptor",
                 None,
-                "version-a",
+                "branch-a",
                 r#"{"id":"file-readme","directory_id":"dir-guides","name":"readme.md","hidden":false}"#,
             ),
             live_filesystem_row(
                 "file-readme",
                 "lix_binary_blob_ref",
                 Some("file-readme"),
-                "version-a",
+                "branch-a",
                 r#"{"id":"file-readme","blob_hash":"abc123","size_bytes":5}"#,
             ),
         ]
@@ -2070,7 +2047,7 @@ mod tests {
         Arc::new(StringArray::from(values)) as ArrayRef
     }
 
-    fn directory_insert_batch(include_version: bool, global: bool) -> RecordBatch {
+    fn directory_insert_batch(include_branch: bool, global: bool) -> RecordBatch {
         let mut fields = vec![
             Field::new("id", DataType::Utf8, false),
             Field::new("parent_id", DataType::Utf8, true),
@@ -2087,9 +2064,9 @@ mod tests {
             Arc::new(BooleanArray::from(vec![global])) as ArrayRef,
             string_column(vec![Some("{\"source\":\"directory\"}")]),
         ];
-        if include_version {
-            fields.push(Field::new("lixcol_version_id", DataType::Utf8, false));
-            columns.push(string_column(vec![Some("version-a")]));
+        if include_branch {
+            fields.push(Field::new("lixcol_branch_id", DataType::Utf8, false));
+            columns.push(string_column(vec![Some("branch-a")]));
         }
         RecordBatch::try_new(Arc::new(Schema::new(fields)), columns)
             .expect("directory insert batch should build")
@@ -2101,13 +2078,13 @@ mod tests {
                 Field::new("id", DataType::Utf8, false),
                 Field::new("path", DataType::Utf8, true),
                 Field::new("hidden", DataType::Boolean, false),
-                Field::new("lixcol_version_id", DataType::Utf8, false),
+                Field::new("lixcol_branch_id", DataType::Utf8, false),
             ])),
             vec![
                 string_column(vec![Some("dir-nested")]),
                 string_column(vec![Some(path)]),
                 Arc::new(BooleanArray::from(vec![false])) as ArrayRef,
-                string_column(vec![Some("version-a")]),
+                string_column(vec![Some("branch-a")]),
             ],
         )
         .expect("directory path insert batch should build")
@@ -2117,11 +2094,11 @@ mod tests {
         RecordBatch::try_new(
             Arc::new(Schema::new(vec![
                 Field::new("id", DataType::Utf8, false),
-                Field::new("lixcol_version_id", DataType::Utf8, false),
+                Field::new("lixcol_branch_id", DataType::Utf8, false),
             ])),
             vec![
                 string_column(ids.iter().copied().map(Some).collect::<Vec<_>>()),
-                string_column(vec![Some("version-a"); ids.len()]),
+                string_column(vec![Some("branch-a"); ids.len()]),
             ],
         )
         .expect("directory delete batch should build")
@@ -2136,7 +2113,7 @@ mod tests {
             hidden: false,
             live: live_row(
                 "dir-docs",
-                "version-a",
+                "branch-a",
                 "{\"id\":\"dir-docs\",\"parent_id\":null,\"name\":\"docs\",\"hidden\":false}",
             ),
         };
@@ -2147,7 +2124,7 @@ mod tests {
             hidden: false,
             live: live_row(
                 "dir-guides",
-                "version-a",
+                "branch-a",
                 "{\"id\":\"dir-guides\",\"parent_id\":\"dir-docs\",\"name\":\"guides\",\"hidden\":false}",
             ),
         };
@@ -2158,7 +2135,7 @@ mod tests {
 
         assert_eq!(
             derive_directory_path_for(
-                "version-a",
+                "branch-a",
                 "dir-guides",
                 &records,
                 &mut paths,
@@ -2174,17 +2151,17 @@ mod tests {
         let rows = vec![
             live_row(
                 "dir-docs",
-                "version-a",
+                "branch-a",
                 "{\"id\":\"dir-docs\",\"parent_id\":null,\"name\":\"docs\",\"hidden\":false}",
             ),
             live_row(
                 "dir-guides",
-                "version-a",
+                "branch-a",
                 "{\"id\":\"dir-guides\",\"parent_id\":\"dir-docs\",\"name\":\"guides\",\"hidden\":true}",
             ),
         ];
 
-        let batch = lix_directory_record_batch(&lix_directory_by_version_schema(), rows)
+        let batch = lix_directory_record_batch(&lix_directory_by_branch_schema(), rows)
             .expect("directory batch should build");
 
         assert_eq!(batch.num_rows(), 2);
@@ -2200,13 +2177,13 @@ mod tests {
         );
         assert_eq!(
             batch
-                .column_by_name("lixcol_version_id")
-                .expect("version column")
+                .column_by_name("lixcol_branch_id")
+                .expect("branch column")
                 .as_any()
                 .downcast_ref::<StringArray>()
-                .expect("version is string")
+                .expect("branch is string")
                 .value(1),
-            "version-a"
+            "branch-a"
         );
     }
 
@@ -2218,7 +2195,7 @@ mod tests {
         assert_eq!(
             rows,
             vec![TransactionWriteRow {
-                entity_id: Some(crate::entity_identity::EntityIdentity::single("dir-docs")),
+                entity_pk: Some(crate::entity_pk::EntityPk::single("dir-docs")),
                 schema_key: super::DIRECTORY_SCHEMA_KEY.to_string(),
                 file_id: None,
                 snapshot: Some(TransactionJson::from_value_for_test(
@@ -2234,43 +2211,43 @@ mod tests {
                 change_id: None,
                 commit_id: None,
                 untracked: false,
-                version_id: "version-a".to_string(),
+                branch_id: "branch-a".to_string(),
             }]
         );
     }
 
     #[test]
-    fn active_directory_insert_defaults_version_id() {
+    fn active_directory_insert_defaults_branch_id() {
         let rows = lix_directory_write_rows_from_batch(
             &directory_insert_batch(false, false),
-            Some("version-active"),
+            Some("branch-active"),
         )
         .expect("active directory batch should decode");
 
-        assert_eq!(rows[0].version_id, "version-active");
+        assert_eq!(rows[0].branch_id, "branch-active");
     }
 
     #[test]
-    fn by_version_directory_insert_requires_version_id_for_non_global_rows() {
+    fn by_branch_directory_insert_requires_branch_id_for_non_global_rows() {
         let error =
             lix_directory_write_rows_from_batch(&directory_insert_batch(false, false), None)
-                .expect_err("by-version insert should require version id");
+                .expect_err("by-branch insert should require branch id");
 
         assert!(
-            error.to_string().contains("requires lixcol_version_id"),
+            error.to_string().contains("requires lixcol_branch_id"),
             "unexpected error: {error}"
         );
     }
 
     #[test]
-    fn directory_insert_rejects_global_with_non_global_version_id() {
+    fn directory_insert_rejects_global_with_non_global_branch_id() {
         let error = lix_directory_write_rows_from_batch(&directory_insert_batch(true, true), None)
-            .expect_err("global directory write should reject conflicting version id");
+            .expect_err("global directory write should reject conflicting branch id");
 
         assert!(
             error
                 .to_string()
-                .contains("cannot set lixcol_global=true with non-global lixcol_version_id"),
+                .contains("cannot set lixcol_global=true with non-global lixcol_branch_id"),
             "unexpected error: {error}"
         );
     }
@@ -2279,7 +2256,7 @@ mod tests {
     fn directory_path_insert_reuses_existing_parent_descriptor() {
         let existing_rows = vec![live_row(
             "dir-docs",
-            "version-a",
+            "branch-a",
             "{\"id\":\"dir-docs\",\"parent_id\":null,\"name\":\"docs\",\"hidden\":false}",
         )];
         let mut resolvers = directory_path_resolvers_from_state_rows(existing_rows)
@@ -2306,7 +2283,7 @@ mod tests {
         let visible_filesystem = VisibleFilesystem::from_live_rows(filesystem_rows())
             .expect("visible filesystem should build");
         let mut visible_filesystems = BTreeMap::new();
-        visible_filesystems.insert("version-a".to_string(), visible_filesystem);
+        visible_filesystems.insert("branch-a".to_string(), visible_filesystem);
 
         let (rows, count) = lix_directory_recursive_delete_rows_from_batch(
             &directory_delete_batch(&["dir-docs"]),
@@ -2321,11 +2298,11 @@ mod tests {
                 .map(|row| {
                     (
                         row.schema_key.as_str(),
-                        row.entity_id
+                        row.entity_pk
                             .as_ref()
-                            .expect("planned delete row should carry entity_id")
+                            .expect("planned delete row should carry entity_pk")
                             .as_single_string_owned()
-                            .expect("planned delete row should project entity_id"),
+                            .expect("planned delete row should project entity_pk"),
                     )
                 })
                 .collect::<Vec<_>>(),
@@ -2345,7 +2322,7 @@ mod tests {
         let visible_filesystem = VisibleFilesystem::from_live_rows(filesystem_rows())
             .expect("visible filesystem should build");
         let mut visible_filesystems = BTreeMap::new();
-        visible_filesystems.insert("version-a".to_string(), visible_filesystem);
+        visible_filesystems.insert("branch-a".to_string(), visible_filesystem);
 
         let (rows, count) = lix_directory_recursive_delete_rows_from_batch(
             &directory_delete_batch(&["dir-docs", "dir-guides"]),
@@ -2360,9 +2337,9 @@ mod tests {
             .map(|row| {
                 (
                     row.schema_key.clone(),
-                    row.entity_id.clone(),
+                    row.entity_pk.clone(),
                     row.file_id.clone(),
-                    row.version_id.clone(),
+                    row.branch_id.clone(),
                 )
             })
             .collect::<std::collections::BTreeSet<_>>();
@@ -2375,12 +2352,8 @@ mod tests {
         let mut write_context = CapturingWriteContext::default();
         let write_ctx = SqlWriteContext::new(&mut write_context);
         let batch = directory_insert_batch(true, false);
-        let sink = LixDirectoryInsertSink::new(
-            batch.schema(),
-            write_ctx,
-            test_functions(),
-            VersionBinding::explicit(),
-        );
+        let sink =
+            LixDirectoryInsertSink::new(write_ctx, test_functions(), BranchBinding::explicit());
         let count = sink
             .write_batches(vec![batch], &Arc::new(TaskContext::default()))
             .await
@@ -2392,7 +2365,7 @@ mod tests {
             &[TransactionWrite::Rows {
                 mode: TransactionWriteMode::Insert,
                 rows: vec![TransactionWriteRow {
-                    entity_id: Some(crate::entity_identity::EntityIdentity::single("dir-docs")),
+                    entity_pk: Some(crate::entity_pk::EntityPk::single("dir-docs")),
                     schema_key: super::DIRECTORY_SCHEMA_KEY.to_string(),
                     file_id: None,
                     snapshot: Some(TransactionJson::from_value_for_test(
@@ -2402,7 +2375,7 @@ mod tests {
                         json!({"source": "directory"})
                     )),
                     origin: Some(lix_directory_insert_origin(
-                        "lix_directory_by_version",
+                        "lix_directory_by_branch",
                         "dir-docs"
                     )),
                     created_at: None,
@@ -2411,7 +2384,7 @@ mod tests {
                     change_id: None,
                     commit_id: None,
                     untracked: false,
-                    version_id: "version-a".to_string(),
+                    branch_id: "branch-a".to_string(),
                 }]
             }]
         );
@@ -2422,19 +2395,15 @@ mod tests {
         let mut write_context = CapturingWriteContext {
             rows: vec![live_row(
                 "dir-docs",
-                "version-a",
+                "branch-a",
                 "{\"id\":\"dir-docs\",\"parent_id\":null,\"name\":\"docs\",\"hidden\":false}",
             )],
             writes: Vec::new(),
         };
         let write_ctx = SqlWriteContext::new(&mut write_context);
         let batch = directory_path_insert_batch("/docs/nested/");
-        let sink = LixDirectoryInsertSink::new(
-            batch.schema(),
-            write_ctx,
-            test_functions(),
-            VersionBinding::explicit(),
-        );
+        let sink =
+            LixDirectoryInsertSink::new(write_ctx, test_functions(), BranchBinding::explicit());
         let count = sink
             .write_batches(vec![batch], &Arc::new(TaskContext::default()))
             .await