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

package/dist-engine-src/src/sql2/{version_provider.rs → providers/branch.rs}

@@ -7,7 +7,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;
@@ -21,6 +21,10 @@ use datafusion::physical_plan::{
 use futures_util::{stream, TryStreamExt};
 use serde_json::Value as JsonValue;
 
+use crate::branch::{
+    branch_descriptor_stage_row, branch_descriptor_tombstone_row, branch_ref_stage_row,
+    branch_ref_tombstone_row, BranchRefReader,
+};
 use crate::live_state::{
     LiveStateFilter, LiveStateReader, LiveStateScanRequest, MaterializedLiveStateRow,
 };
@@ -28,83 +32,81 @@ use crate::sql2::dml::{InsertExec, InsertSink};
 use crate::sql2::record_batch::record_batch_with_row_count;
 use crate::sql2::write_normalization::{InsertCell, SqlCell, UpdateAssignmentValues};
 use crate::sql2::{
-    SqlWriteContext, WriteAccess, WriteContextLiveStateReader, WriteContextVersionRefReader,
+    SqlWriteContext, WriteAccess, WriteContextBranchRefReader, WriteContextLiveStateReader,
 };
 use crate::transaction::types::{
     LogicalPrimaryKey, TransactionWrite, TransactionWriteMode, TransactionWriteOperation,
     TransactionWriteOrigin, TransactionWriteRow,
 };
-use crate::version::{
-    version_descriptor_stage_row, version_descriptor_tombstone_row, version_ref_stage_row,
-    version_ref_tombstone_row, VersionRefReader,
-};
 use crate::LixError;
-use crate::GLOBAL_VERSION_ID;
+use crate::GLOBAL_BRANCH_ID;
 
-pub(crate) async fn register_lix_version_provider(
+pub(super) async fn register_lix_branch_read_provider(
     session: &datafusion::prelude::SessionContext,
+    surface_name: &str,
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
 ) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_version",
-            Arc::new(LixVersionProvider::new(live_state, version_ref)),
+            surface_name,
+            Arc::new(LixBranchProvider::new(live_state, branch_ref)),
         )
         .map_err(datafusion_error_to_lix_error)?;
     Ok(())
 }
 
-pub(crate) async fn register_lix_version_write_provider(
+pub(super) async fn register_write_provider(
     session: &datafusion::prelude::SessionContext,
+    surface_name: &str,
     write_ctx: SqlWriteContext,
 ) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_version",
-            Arc::new(LixVersionProvider::with_write(write_ctx)),
+            surface_name,
+            Arc::new(LixBranchProvider::with_write(write_ctx)),
         )
         .map_err(datafusion_error_to_lix_error)?;
     Ok(())
 }
 
-struct LixVersionProvider {
+struct LixBranchProvider {
     schema: SchemaRef,
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
     write_access: WriteAccess,
 }
 
-impl std::fmt::Debug for LixVersionProvider {
+impl std::fmt::Debug for LixBranchProvider {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("LixVersionProvider").finish()
+        f.debug_struct("LixBranchProvider").finish()
     }
 }
 
-impl LixVersionProvider {
-    fn new(live_state: Arc<dyn LiveStateReader>, version_ref: Arc<dyn VersionRefReader>) -> Self {
+impl LixBranchProvider {
+    fn new(live_state: Arc<dyn LiveStateReader>, branch_ref: Arc<dyn BranchRefReader>) -> Self {
         Self {
-            schema: lix_version_schema(),
+            schema: lix_branch_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::read_only(),
         }
     }
 
     fn with_write(write_ctx: SqlWriteContext) -> Self {
         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_version_schema(),
+            schema: lix_branch_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::write(write_ctx),
         }
     }
 }
 
 #[async_trait]
-impl TableProvider for LixVersionProvider {
+impl TableProvider for LixBranchProvider {
     fn as_any(&self) -> &dyn Any {
         self
     }
@@ -134,9 +136,9 @@ impl TableProvider for LixVersionProvider {
         _filters: &[Expr],
         _limit: Option<usize>,
     ) -> Result<Arc<dyn ExecutionPlan>> {
-        Ok(Arc::new(LixVersionScanExec::new(
+        Ok(Arc::new(LixBranchScanExec::new(
             Arc::clone(&self.live_state),
-            Arc::clone(&self.version_ref),
+            Arc::clone(&self.branch_ref),
             projected_schema(&self.schema, projection),
             projection.cloned(),
         )))
@@ -149,11 +151,12 @@ impl TableProvider for LixVersionProvider {
         insert_op: InsertOp,
     ) -> Result<Arc<dyn ExecutionPlan>> {
         if insert_op != InsertOp::Append {
-            return not_impl_err!("{insert_op} not implemented for lix_version yet");
+            return not_impl_err!("{insert_op} not implemented for lix_branch yet");
         }
-
-        let write_ctx = self.write_access.require_write("INSERT into lix_version")?;
-        let sink = LixVersionInsertSink::new(input.schema(), write_ctx);
+        let write_ctx = self.write_access.require_write("INSERT into lix_branch")?;
+        self.schema
+            .logically_equivalent_names_and_types(&input.schema())?;
+        let sink = LixBranchInsertSink::new(write_ctx);
         Ok(Arc::new(InsertExec::new(input, Arc::new(sink))))
     }
 
@@ -162,17 +165,16 @@ impl TableProvider for LixVersionProvider {
         state: &dyn Session,
         filters: Vec<Expr>,
     ) -> Result<Arc<dyn ExecutionPlan>> {
-        let write_ctx = self.write_access.require_write("DELETE FROM lix_version")?;
+        let write_ctx = self.write_access.require_write("DELETE FROM lix_branch")?;
         let df_schema = DFSchema::try_from(Arc::clone(&self.schema))?;
         let physical_filters = filters
             .iter()
             .map(|expr| create_physical_expr(expr, &df_schema, state.execution_props()))
             .collect::<Result<Vec<_>>>()?;
-
-        Ok(Arc::new(LixVersionDeleteExec::new(
+        Ok(Arc::new(LixBranchDeleteExec::new(
             write_ctx,
             Arc::clone(&self.live_state),
-            Arc::clone(&self.version_ref),
+            Arc::clone(&self.branch_ref),
             Arc::clone(&self.schema),
             physical_filters,
         )))
@@ -184,9 +186,8 @@ impl TableProvider for LixVersionProvider {
         assignments: Vec<(String, Expr)>,
         filters: Vec<Expr>,
     ) -> Result<Arc<dyn ExecutionPlan>> {
-        let write_ctx = self.write_access.require_write("UPDATE lix_version")?;
-        validate_lix_version_update_assignments(&assignments)?;
-
+        let write_ctx = self.write_access.require_write("UPDATE lix_branch")?;
+        validate_lix_branch_update_assignments(&assignments)?;
         let df_schema = DFSchema::try_from(Arc::clone(&self.schema))?;
         let physical_assignments = assignments
             .iter()
@@ -201,11 +202,10 @@ impl TableProvider for LixVersionProvider {
             .iter()
             .map(|expr| create_physical_expr(expr, &df_schema, state.execution_props()))
             .collect::<Result<Vec<_>>>()?;
-
-        Ok(Arc::new(LixVersionUpdateExec::new(
+        Ok(Arc::new(LixBranchUpdateExec::new(
             write_ctx,
             Arc::clone(&self.live_state),
-            Arc::clone(&self.version_ref),
+            Arc::clone(&self.branch_ref),
             Arc::clone(&self.schema),
             physical_assignments,
             physical_filters,
@@ -213,35 +213,35 @@ impl TableProvider for LixVersionProvider {
     }
 }
 
-struct LixVersionInsertSink {
+struct LixBranchInsertSink {
     write_ctx: SqlWriteContext,
 }
 
-impl std::fmt::Debug for LixVersionInsertSink {
+impl std::fmt::Debug for LixBranchInsertSink {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("LixVersionInsertSink").finish()
+        f.debug_struct("LixBranchInsertSink").finish()
     }
 }
 
-impl LixVersionInsertSink {
-    fn new(_schema: SchemaRef, write_ctx: SqlWriteContext) -> Self {
+impl LixBranchInsertSink {
+    fn new(write_ctx: SqlWriteContext) -> Self {
         Self { write_ctx }
     }
 }
 
-impl DisplayAs for LixVersionInsertSink {
+impl DisplayAs for LixBranchInsertSink {
     fn fmt_as(&self, t: DisplayFormatType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match t {
             DisplayFormatType::Default | DisplayFormatType::Verbose => {
-                write!(f, "LixVersionInsertSink")
+                write!(f, "LixBranchInsertSink")
             }
-            DisplayFormatType::TreeRender => write!(f, "LixVersionInsertSink"),
+            DisplayFormatType::TreeRender => write!(f, "LixBranchInsertSink"),
         }
     }
 }
 
 #[async_trait]
-impl InsertSink for LixVersionInsertSink {
+impl InsertSink for LixBranchInsertSink {
     async fn write_batches(
         &self,
         batches: Vec<RecordBatch>,
@@ -249,24 +249,24 @@ impl InsertSink for LixVersionInsertSink {
     ) -> Result<u64> {
         let default_commit_id = self
             .write_ctx
-            .load_version_head(&self.write_ctx.active_version_id())
+            .load_branch_head(&self.write_ctx.active_branch_id())
             .await
             .map_err(lix_error_to_datafusion_error)?
             .ok_or_else(|| {
                 DataFusionError::Execution(
-                    "INSERT into lix_version could not resolve active version head".to_string(),
+                    "INSERT into lix_branch could not resolve active branch head".to_string(),
                 )
             })?;
         let mut rows = Vec::new();
         let mut count = 0u64;
         for batch in batches {
-            let version_rows = version_insert_rows_from_batch(&batch, &default_commit_id)?;
+            let branch_rows = branch_insert_rows_from_batch(&batch, &default_commit_id)?;
             count = count
-                .checked_add(u64::try_from(version_rows.len()).map_err(|_| {
+                .checked_add(u64::try_from(branch_rows.len()).map_err(|_| {
                     DataFusionError::Execution("INSERT row count overflow".to_string())
                 })?)
                 .ok_or_else(|| DataFusionError::Execution("INSERT row count overflow".into()))?;
-            rows.extend(version_rows.into_iter().flat_map(version_insert_stage_rows));
+            rows.extend(branch_rows.into_iter().flat_map(branch_insert_stage_rows));
         }
 
         if !rows.is_empty() {
@@ -283,39 +283,39 @@ impl InsertSink for LixVersionInsertSink {
     }
 }
 
-struct LixVersionDeleteExec {
+struct LixBranchDeleteExec {
     write_ctx: SqlWriteContext,
-    active_version_id: String,
+    active_branch_id: String,
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
     table_schema: SchemaRef,
     filters: Vec<Arc<dyn PhysicalExpr>>,
     result_schema: SchemaRef,
     properties: Arc<PlanProperties>,
 }
 
-impl std::fmt::Debug for LixVersionDeleteExec {
+impl std::fmt::Debug for LixBranchDeleteExec {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("LixVersionDeleteExec").finish()
+        f.debug_struct("LixBranchDeleteExec").finish()
     }
 }
 
-impl LixVersionDeleteExec {
+impl LixBranchDeleteExec {
     fn new(
         write_ctx: SqlWriteContext,
         live_state: Arc<dyn LiveStateReader>,
-        version_ref: Arc<dyn VersionRefReader>,
+        branch_ref: Arc<dyn BranchRefReader>,
         table_schema: SchemaRef,
         filters: Vec<Arc<dyn PhysicalExpr>>,
     ) -> Self {
         let result_schema = dml_count_schema();
         let properties = dml_plan_properties(Arc::clone(&result_schema));
-        let active_version_id = write_ctx.active_version_id();
+        let active_branch_id = write_ctx.active_branch_id();
         Self {
             write_ctx,
-            active_version_id,
+            active_branch_id,
             live_state,
-            version_ref,
+            branch_ref,
             table_schema,
             filters,
             result_schema,
@@ -324,20 +324,20 @@ impl LixVersionDeleteExec {
     }
 }
 
-impl DisplayAs for LixVersionDeleteExec {
+impl DisplayAs for LixBranchDeleteExec {
     fn fmt_as(&self, t: DisplayFormatType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match t {
             DisplayFormatType::Default | DisplayFormatType::Verbose => {
-                write!(f, "LixVersionDeleteExec(filters={})", self.filters.len())
+                write!(f, "LixBranchDeleteExec(filters={})", self.filters.len())
             }
-            DisplayFormatType::TreeRender => write!(f, "LixVersionDeleteExec"),
+            DisplayFormatType::TreeRender => write!(f, "LixBranchDeleteExec"),
         }
     }
 }
 
-impl ExecutionPlan for LixVersionDeleteExec {
+impl ExecutionPlan for LixBranchDeleteExec {
     fn name(&self) -> &str {
-        "LixVersionDeleteExec"
+        "LixBranchDeleteExec"
     }
 
     fn as_any(&self) -> &dyn Any {
@@ -358,7 +358,7 @@ impl ExecutionPlan for LixVersionDeleteExec {
     ) -> Result<Arc<dyn ExecutionPlan>> {
         if !children.is_empty() {
             return Err(DataFusionError::Execution(
-                "LixVersionDeleteExec does not accept children".to_string(),
+                "LixBranchDeleteExec does not accept children".to_string(),
             ));
         }
         Ok(self)
@@ -371,31 +371,31 @@ impl ExecutionPlan for LixVersionDeleteExec {
     ) -> Result<SendableRecordBatchStream> {
         if partition != 0 {
             return Err(DataFusionError::Execution(format!(
-                "LixVersionDeleteExec only exposes one partition, got {partition}"
+                "LixBranchDeleteExec only exposes one partition, got {partition}"
             )));
         }
         let write_ctx = self.write_ctx.clone();
-        let active_version_id = self.active_version_id.clone();
+        let active_branch_id = self.active_branch_id.clone();
         let live_state = Arc::clone(&self.live_state);
-        let version_ref = Arc::clone(&self.version_ref);
+        let branch_ref = Arc::clone(&self.branch_ref);
         let filters = self.filters.clone();
         let table_schema = Arc::clone(&self.table_schema);
         let result_schema = Arc::clone(&self.result_schema);
         let stream_schema = Arc::clone(&result_schema);
 
         let stream = stream::once(async move {
-            let rows = load_version_rows(live_state, version_ref)
+            let rows = load_branch_rows(live_state, branch_ref)
                 .await
                 .map_err(lix_error_to_datafusion_error)?;
-            let source_batch = version_record_batch(&version_projection_for_scan(None), &rows)?;
-            let matched_batch = filter_version_batch(source_batch, &filters)?;
-            let version_rows = version_rows_from_batch(&matched_batch)?;
-            reject_protected_version_deletes(&version_rows, &active_version_id)?;
-            let count = u64::try_from(version_rows.len())
+            let source_batch = branch_record_batch(&branch_projection_for_scan(None), &rows)?;
+            let matched_batch = filter_branch_batch(source_batch, &filters)?;
+            let branch_rows = branch_rows_from_batch(&matched_batch)?;
+            reject_protected_branch_deletes(&branch_rows, &active_branch_id)?;
+            let count = u64::try_from(branch_rows.len())
                 .map_err(|_| DataFusionError::Execution("DELETE row count overflow".to_string()))?;
-            let rows = version_rows
+            let rows = branch_rows
                 .into_iter()
-                .flat_map(version_tombstone_rows)
+                .flat_map(branch_tombstone_rows)
                 .collect::<Vec<_>>();
 
             if !rows.is_empty() {
@@ -421,10 +421,10 @@ impl ExecutionPlan for LixVersionDeleteExec {
     }
 }
 
-struct LixVersionUpdateExec {
+struct LixBranchUpdateExec {
     write_ctx: SqlWriteContext,
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
     table_schema: SchemaRef,
     assignments: Vec<(String, Arc<dyn PhysicalExpr>)>,
     filters: Vec<Arc<dyn PhysicalExpr>>,
@@ -432,17 +432,17 @@ struct LixVersionUpdateExec {
     properties: Arc<PlanProperties>,
 }
 
-impl std::fmt::Debug for LixVersionUpdateExec {
+impl std::fmt::Debug for LixBranchUpdateExec {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("LixVersionUpdateExec").finish()
+        f.debug_struct("LixBranchUpdateExec").finish()
     }
 }
 
-impl LixVersionUpdateExec {
+impl LixBranchUpdateExec {
     fn new(
         write_ctx: SqlWriteContext,
         live_state: Arc<dyn LiveStateReader>,
-        version_ref: Arc<dyn VersionRefReader>,
+        branch_ref: Arc<dyn BranchRefReader>,
         table_schema: SchemaRef,
         assignments: Vec<(String, Arc<dyn PhysicalExpr>)>,
         filters: Vec<Arc<dyn PhysicalExpr>>,
@@ -452,7 +452,7 @@ impl LixVersionUpdateExec {
         Self {
             write_ctx,
             live_state,
-            version_ref,
+            branch_ref,
             table_schema,
             assignments,
             filters,
@@ -462,25 +462,25 @@ impl LixVersionUpdateExec {
     }
 }
 
-impl DisplayAs for LixVersionUpdateExec {
+impl DisplayAs for LixBranchUpdateExec {
     fn fmt_as(&self, t: DisplayFormatType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match t {
             DisplayFormatType::Default | DisplayFormatType::Verbose => {
                 write!(
                     f,
-                    "LixVersionUpdateExec(assignments={}, filters={})",
+                    "LixBranchUpdateExec(assignments={}, filters={})",
                     self.assignments.len(),
                     self.filters.len()
                 )
             }
-            DisplayFormatType::TreeRender => write!(f, "LixVersionUpdateExec"),
+            DisplayFormatType::TreeRender => write!(f, "LixBranchUpdateExec"),
         }
     }
 }
 
-impl ExecutionPlan for LixVersionUpdateExec {
+impl ExecutionPlan for LixBranchUpdateExec {
     fn name(&self) -> &str {
-        "LixVersionUpdateExec"
+        "LixBranchUpdateExec"
     }
 
     fn as_any(&self) -> &dyn Any {
@@ -501,7 +501,7 @@ impl ExecutionPlan for LixVersionUpdateExec {
     ) -> Result<Arc<dyn ExecutionPlan>> {
         if !children.is_empty() {
             return Err(DataFusionError::Execution(
-                "LixVersionUpdateExec does not accept children".to_string(),
+                "LixBranchUpdateExec does not accept children".to_string(),
             ));
         }
         Ok(self)
@@ -514,12 +514,12 @@ impl ExecutionPlan for LixVersionUpdateExec {
     ) -> Result<SendableRecordBatchStream> {
         if partition != 0 {
             return Err(DataFusionError::Execution(format!(
-                "LixVersionUpdateExec only exposes one partition, got {partition}"
+                "LixBranchUpdateExec only exposes one partition, got {partition}"
             )));
         }
         let write_ctx = self.write_ctx.clone();
         let live_state = Arc::clone(&self.live_state);
-        let version_ref = Arc::clone(&self.version_ref);
+        let branch_ref = Arc::clone(&self.branch_ref);
         let table_schema = Arc::clone(&self.table_schema);
         let assignments = self.assignments.clone();
         let filters = self.filters.clone();
@@ -527,18 +527,19 @@ impl ExecutionPlan for LixVersionUpdateExec {
         let stream_schema = Arc::clone(&result_schema);
 
         let stream = stream::once(async move {
-            let rows = load_version_rows(live_state, version_ref)
+            let rows = load_branch_rows(live_state, branch_ref)
                 .await
                 .map_err(lix_error_to_datafusion_error)?;
-            let source_batch = version_record_batch(&version_projection_for_scan(None), &rows)?;
-            let matched_batch = filter_version_batch(source_batch, &filters)?;
-            let version_rows =
-                version_update_rows_from_batch(&matched_batch, &assignments, &table_schema)?;
-            let count = u64::try_from(version_rows.len())
+            let source_batch = branch_record_batch(&branch_projection_for_scan(None), &rows)?;
+            let matched_batch = filter_branch_batch(source_batch, &filters)?;
+            let branch_rows =
+                branch_update_rows_from_batch(&matched_batch, &assignments, &table_schema)?;
+            reject_protected_branch_updates(&branch_rows)?;
+            let count = u64::try_from(branch_rows.len())
                 .map_err(|_| DataFusionError::Execution("UPDATE row count overflow".to_string()))?;
-            let rows = version_rows
+            let rows = branch_rows
                 .into_iter()
-                .flat_map(version_update_stage_rows)
+                .flat_map(branch_update_stage_rows)
                 .collect::<Vec<_>>();
 
             if !rows.is_empty() {
@@ -563,24 +564,24 @@ impl ExecutionPlan for LixVersionUpdateExec {
     }
 }
 
-struct LixVersionScanExec {
+struct LixBranchScanExec {
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
     schema: SchemaRef,
     projection: Option<Vec<usize>>,
     properties: Arc<PlanProperties>,
 }
 
-impl std::fmt::Debug for LixVersionScanExec {
+impl std::fmt::Debug for LixBranchScanExec {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("LixVersionScanExec").finish()
+        f.debug_struct("LixBranchScanExec").finish()
     }
 }
 
-impl LixVersionScanExec {
+impl LixBranchScanExec {
     fn new(
         live_state: Arc<dyn LiveStateReader>,
-        version_ref: Arc<dyn VersionRefReader>,
+        branch_ref: Arc<dyn BranchRefReader>,
         schema: SchemaRef,
         projection: Option<Vec<usize>>,
     ) -> Self {
@@ -592,7 +593,7 @@ impl LixVersionScanExec {
         );
         Self {
             live_state,
-            version_ref,
+            branch_ref,
             schema,
             projection,
             properties: Arc::new(properties),
@@ -600,20 +601,20 @@ impl LixVersionScanExec {
     }
 }
 
-impl DisplayAs for LixVersionScanExec {
+impl DisplayAs for LixBranchScanExec {
     fn fmt_as(&self, t: DisplayFormatType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match t {
             DisplayFormatType::Default | DisplayFormatType::Verbose => {
-                write!(f, "LixVersionScanExec")
+                write!(f, "LixBranchScanExec")
             }
-            DisplayFormatType::TreeRender => write!(f, "LixVersionScanExec"),
+            DisplayFormatType::TreeRender => write!(f, "LixBranchScanExec"),
         }
     }
 }
 
-impl ExecutionPlan for LixVersionScanExec {
+impl ExecutionPlan for LixBranchScanExec {
     fn name(&self) -> &str {
-        "LixVersionScanExec"
+        "LixBranchScanExec"
     }
 
     fn as_any(&self) -> &dyn Any {
@@ -634,7 +635,7 @@ impl ExecutionPlan for LixVersionScanExec {
     ) -> Result<Arc<dyn ExecutionPlan>> {
         if !children.is_empty() {
             return Err(DataFusionError::Execution(
-                "LixVersionScanExec does not accept children".to_string(),
+                "LixBranchScanExec does not accept children".to_string(),
             ));
         }
         Ok(self)
@@ -647,26 +648,26 @@ impl ExecutionPlan for LixVersionScanExec {
     ) -> Result<SendableRecordBatchStream> {
         if partition != 0 {
             return Err(DataFusionError::Execution(format!(
-                "LixVersionScanExec only exposes one partition, got {partition}"
+                "LixBranchScanExec only exposes one partition, got {partition}"
             )));
         }
 
         let live_state = Arc::clone(&self.live_state);
-        let version_ref = Arc::clone(&self.version_ref);
-        let projection = version_projection_for_scan(self.projection.as_ref());
+        let branch_ref = Arc::clone(&self.branch_ref);
+        let projection = branch_projection_for_scan(self.projection.as_ref());
         let schema = Arc::clone(&self.schema);
         let stream = stream::once(async move {
-            let rows = load_version_rows(live_state, version_ref)
+            let rows = load_branch_rows(live_state, branch_ref)
                 .await
                 .map_err(lix_error_to_datafusion_error)?;
-            version_record_batch(&projection, &rows)
+            branch_record_batch(&projection, &rows)
         });
         Ok(Box::pin(RecordBatchStreamAdapter::new(schema, stream)))
     }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
-struct VersionRow {
+struct BranchRow {
     id: String,
     name: String,
     hidden: bool,
@@ -674,22 +675,22 @@ struct VersionRow {
 }
 
 #[derive(Debug, Clone, Copy)]
-enum VersionColumn {
+enum BranchColumn {
     Id,
     Name,
     Hidden,
     CommitId,
 }
 
-async fn load_version_rows(
+async fn load_branch_rows(
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
-) -> Result<Vec<VersionRow>, LixError> {
+    branch_ref: Arc<dyn BranchRefReader>,
+) -> Result<Vec<BranchRow>, LixError> {
     let descriptor_rows = live_state
         .scan_rows(&LiveStateScanRequest {
             filter: LiveStateFilter {
-                schema_keys: vec!["lix_version_descriptor".to_string()],
-                version_ids: vec![GLOBAL_VERSION_ID.to_string()],
+                schema_keys: vec!["lix_branch_descriptor".to_string()],
+                branch_ids: vec![GLOBAL_BRANCH_ID.to_string()],
                 ..LiveStateFilter::default()
             },
             projection: Default::default(),
@@ -700,10 +701,10 @@ async fn load_version_rows(
     let mut out = Vec::new();
     for descriptor_row in descriptor_rows {
         let descriptor = parse_descriptor(&descriptor_row)?;
-        let Some(commit_id) = version_ref.load_head_commit_id(&descriptor.id).await? else {
+        let Some(commit_id) = branch_ref.load_head_commit_id(&descriptor.id).await? else {
             continue;
         };
-        out.push(VersionRow {
+        out.push(BranchRow {
             commit_id,
             id: descriptor.id,
             name: descriptor.name,
@@ -714,34 +715,29 @@ async fn load_version_rows(
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
-struct VersionDescriptor {
+struct BranchDescriptor {
     id: String,
     name: String,
     hidden: bool,
 }
 
-fn parse_descriptor(row: &MaterializedLiveStateRow) -> Result<VersionDescriptor, LixError> {
-    let snapshot = parse_snapshot(row, "lix_version_descriptor")?;
+fn parse_descriptor(row: &MaterializedLiveStateRow) -> Result<BranchDescriptor, LixError> {
+    let snapshot = parse_snapshot(row, "lix_branch_descriptor")?;
     let id = snapshot
         .get("id")
         .and_then(JsonValue::as_str)
-        .ok_or_else(|| LixError::new("LIX_ERROR_UNKNOWN", "lix_version_descriptor is missing id"))?
+        .ok_or_else(|| LixError::new("LIX_ERROR_UNKNOWN", "lix_branch_descriptor is missing id"))?
         .to_string();
     let name = snapshot
         .get("name")
         .and_then(JsonValue::as_str)
-        .ok_or_else(|| {
-            LixError::new(
-                "LIX_ERROR_UNKNOWN",
-                "lix_version_descriptor is missing name",
-            )
-        })?
+        .ok_or_else(|| LixError::new("LIX_ERROR_UNKNOWN", "lix_branch_descriptor is missing name"))?
         .to_string();
     let hidden = snapshot
         .get("hidden")
         .and_then(JsonValue::as_bool)
         .unwrap_or(false);
-    Ok(VersionDescriptor { id, name, hidden })
+    Ok(BranchDescriptor { id, name, hidden })
 }
 
 fn parse_snapshot(row: &MaterializedLiveStateRow, schema_key: &str) -> Result<JsonValue, LixError> {
@@ -759,18 +755,18 @@ fn parse_snapshot(row: &MaterializedLiveStateRow, schema_key: &str) -> Result<Js
     })
 }
 
-fn validate_lix_version_update_assignments(assignments: &[(String, Expr)]) -> Result<()> {
+fn validate_lix_branch_update_assignments(assignments: &[(String, Expr)]) -> Result<()> {
     for (column_name, _) in assignments {
         match column_name.as_str() {
             "name" | "hidden" | "commit_id" => {}
             "id" => {
                 return Err(DataFusionError::Execution(
-                    "UPDATE lix_version cannot change immutable column 'id'".to_string(),
+                    "UPDATE lix_branch cannot change immutable column 'id'".to_string(),
                 ));
             }
             other => {
                 return Err(DataFusionError::Plan(format!(
-                    "UPDATE lix_version failed: column '{other}' does not exist"
+                    "UPDATE lix_branch failed: column '{other}' does not exist"
                 )));
             }
         }
@@ -778,17 +774,17 @@ fn validate_lix_version_update_assignments(assignments: &[(String, Expr)]) -> Re
     Ok(())
 }
 
-fn filter_version_batch(
+fn filter_branch_batch(
     batch: RecordBatch,
     filters: &[Arc<dyn PhysicalExpr>],
 ) -> Result<RecordBatch> {
-    let Some(mask) = evaluate_version_filters(&batch, filters)? else {
+    let Some(mask) = evaluate_branch_filters(&batch, filters)? else {
         return Ok(batch);
     };
     Ok(filter_record_batch(&batch, &mask)?)
 }
 
-fn evaluate_version_filters(
+fn evaluate_branch_filters(
     batch: &RecordBatch,
     filters: &[Arc<dyn PhysicalExpr>],
 ) -> Result<Option<BooleanArray>> {
@@ -804,7 +800,7 @@ fn evaluate_version_filters(
             .as_any()
             .downcast_ref::<BooleanArray>()
             .ok_or_else(|| {
-                DataFusionError::Execution("lix_version filter was not boolean".to_string())
+                DataFusionError::Execution("lix_branch filter was not boolean".to_string())
             })?;
         let normalized = bool_array
             .iter()
@@ -818,10 +814,10 @@ fn evaluate_version_filters(
     Ok(combined_mask)
 }
 
-fn version_insert_rows_from_batch(
+fn branch_insert_rows_from_batch(
     batch: &RecordBatch,
     default_commit_id: &str,
-) -> Result<Vec<VersionRow>> {
+) -> Result<Vec<BranchRow>> {
     (0..batch.num_rows())
         .map(|row_index| {
             let id = required_string_value(batch, row_index, "id", "INSERT")?;
@@ -830,7 +826,7 @@ fn version_insert_rows_from_batch(
                 optional_bool_value(batch, row_index, "hidden", "INSERT")?.unwrap_or(false);
             let commit_id = optional_string_value(batch, row_index, "commit_id", "INSERT")?
                 .unwrap_or_else(|| default_commit_id.to_string());
-            Ok(VersionRow {
+            Ok(BranchRow {
                 id,
                 name,
                 hidden,
@@ -840,10 +836,10 @@ fn version_insert_rows_from_batch(
         .collect()
 }
 
-fn version_rows_from_batch(batch: &RecordBatch) -> Result<Vec<VersionRow>> {
+fn branch_rows_from_batch(batch: &RecordBatch) -> Result<Vec<BranchRow>> {
     (0..batch.num_rows())
         .map(|row_index| {
-            Ok(VersionRow {
+            Ok(BranchRow {
                 id: required_string_value(batch, row_index, "id", "DELETE")?,
                 name: required_string_value(batch, row_index, "name", "DELETE")?,
                 hidden: required_bool_value(batch, row_index, "hidden", "DELETE")?,
@@ -853,16 +849,16 @@ fn version_rows_from_batch(batch: &RecordBatch) -> Result<Vec<VersionRow>> {
         .collect()
 }
 
-fn reject_protected_version_deletes(rows: &[VersionRow], active_version_id: &str) -> Result<()> {
+fn reject_protected_branch_deletes(rows: &[BranchRow], active_branch_id: &str) -> Result<()> {
     for row in rows {
-        if row.id == GLOBAL_VERSION_ID {
+        if row.id == GLOBAL_BRANCH_ID {
             return Err(DataFusionError::Execution(
-                "DELETE FROM lix_version cannot delete the global version".to_string(),
+                "DELETE FROM lix_branch cannot delete the global branch".to_string(),
             ));
         }
-        if row.id == active_version_id {
+        if row.id == active_branch_id {
             return Err(DataFusionError::Execution(format!(
-                "DELETE FROM lix_version cannot delete active version '{}'",
+                "DELETE FROM lix_branch cannot delete active branch '{}'",
                 row.id
             )));
         }
@@ -870,15 +866,26 @@ fn reject_protected_version_deletes(rows: &[VersionRow], active_version_id: &str
     Ok(())
 }
 
-fn version_update_rows_from_batch(
+fn reject_protected_branch_updates(rows: &[BranchRow]) -> Result<()> {
+    for row in rows {
+        if row.id == GLOBAL_BRANCH_ID {
+            return Err(DataFusionError::Execution(
+                "UPDATE lix_branch cannot update the global branch".to_string(),
+            ));
+        }
+    }
+    Ok(())
+}
+
+fn branch_update_rows_from_batch(
     batch: &RecordBatch,
     assignments: &[(String, Arc<dyn PhysicalExpr>)],
     table_schema: &SchemaRef,
-) -> Result<Vec<VersionRow>> {
+) -> Result<Vec<BranchRow>> {
     let assignment_values = UpdateAssignmentValues::evaluate(batch, assignments)?;
     (0..batch.num_rows())
         .map(|row_index| {
-            Ok(VersionRow {
+            Ok(BranchRow {
                 id: required_string_value(batch, row_index, "id", "UPDATE")?,
                 name: update_string_value(
                     batch,
@@ -906,38 +913,38 @@ fn version_update_rows_from_batch(
         .collect()
 }
 
-fn version_stage_rows(
-    row: VersionRow,
+fn branch_stage_rows(
+    row: BranchRow,
     origin: Option<TransactionWriteOrigin>,
 ) -> Vec<TransactionWriteRow> {
     vec![
         with_origin(
-            version_descriptor_stage_row(&row.id, &row.name, row.hidden),
+            branch_descriptor_stage_row(&row.id, &row.name, row.hidden),
             origin.clone(),
         ),
-        with_origin(version_ref_stage_row(&row.id, &row.commit_id), origin),
+        with_origin(branch_ref_stage_row(&row.id, &row.commit_id), origin),
     ]
 }
 
-fn version_tombstone_rows(row: VersionRow) -> Vec<TransactionWriteRow> {
-    let origin = Some(lix_version_origin(
+fn branch_tombstone_rows(row: BranchRow) -> Vec<TransactionWriteRow> {
+    let origin = Some(lix_branch_origin(
         TransactionWriteOperation::Delete,
         &row.id,
     ));
     vec![
-        with_origin(version_descriptor_tombstone_row(&row.id), origin.clone()),
-        with_origin(version_ref_tombstone_row(&row.id), origin),
+        with_origin(branch_descriptor_tombstone_row(&row.id), origin.clone()),
+        with_origin(branch_ref_tombstone_row(&row.id), origin),
     ]
 }
 
-fn version_insert_stage_rows(row: VersionRow) -> Vec<TransactionWriteRow> {
-    let origin = lix_version_origin(TransactionWriteOperation::Insert, &row.id);
-    version_stage_rows(row, Some(origin))
+fn branch_insert_stage_rows(row: BranchRow) -> Vec<TransactionWriteRow> {
+    let origin = lix_branch_origin(TransactionWriteOperation::Insert, &row.id);
+    branch_stage_rows(row, Some(origin))
 }
 
-fn version_update_stage_rows(row: VersionRow) -> Vec<TransactionWriteRow> {
-    let origin = lix_version_origin(TransactionWriteOperation::Update, &row.id);
-    version_stage_rows(row, Some(origin))
+fn branch_update_stage_rows(row: BranchRow) -> Vec<TransactionWriteRow> {
+    let origin = lix_branch_origin(TransactionWriteOperation::Update, &row.id);
+    branch_stage_rows(row, Some(origin))
 }
 
 fn with_origin(
@@ -948,16 +955,13 @@ fn with_origin(
     row
 }
 
-fn lix_version_origin(
-    action: TransactionWriteOperation,
-    version_id: &str,
-) -> TransactionWriteOrigin {
+fn lix_branch_origin(action: TransactionWriteOperation, branch_id: &str) -> TransactionWriteOrigin {
     TransactionWriteOrigin {
-        surface: "lix_version".to_string(),
+        surface: "lix_branch".to_string(),
         operation: action,
         primary_key: Some(LogicalPrimaryKey {
             columns: vec!["id".to_string()],
-            values: vec![version_id.to_string()],
+            values: vec![branch_id.to_string()],
         }),
     }
 }
@@ -978,16 +982,16 @@ fn update_string_value(
             | ScalarValue::LargeUtf8(Some(value)),
         )) => Ok(value),
         InsertCell::Provided(SqlCell::Null) => Err(DataFusionError::Execution(format!(
-            "UPDATE lix_version requires non-null text column '{column_name}'"
+            "UPDATE lix_branch requires non-null text column '{column_name}'"
         ))),
         InsertCell::Provided(SqlCell::Value(other)) => Err(DataFusionError::Execution(format!(
-            "UPDATE lix_version expected text-compatible column '{column_name}', got {other:?}"
+            "UPDATE lix_branch expected text-compatible column '{column_name}', got {other:?}"
         ))),
     }
     .or_else(|error| {
         if batch.column(column_index).is_null(row_index) {
             Err(DataFusionError::Execution(format!(
-                "UPDATE lix_version requires non-null text column '{column_name}'"
+                "UPDATE lix_branch requires non-null text column '{column_name}'"
             )))
         } else {
             Err(error)
@@ -1007,16 +1011,16 @@ fn update_bool_value(
         InsertCell::Omitted => required_bool_value(batch, row_index, column_name, "UPDATE"),
         InsertCell::Provided(SqlCell::Value(ScalarValue::Boolean(Some(value)))) => Ok(value),
         InsertCell::Provided(SqlCell::Null) => Err(DataFusionError::Execution(format!(
-            "UPDATE lix_version requires non-null boolean column '{column_name}'"
+            "UPDATE lix_branch requires non-null boolean column '{column_name}'"
         ))),
         InsertCell::Provided(SqlCell::Value(other)) => Err(DataFusionError::Execution(format!(
-            "UPDATE lix_version expected boolean column '{column_name}', got {other:?}"
+            "UPDATE lix_branch expected boolean column '{column_name}', got {other:?}"
         ))),
     }
     .or_else(|error| {
         if batch.column(column_index).is_null(row_index) {
             Err(DataFusionError::Execution(format!(
-                "UPDATE lix_version requires non-null boolean column '{column_name}'"
+                "UPDATE lix_branch requires non-null boolean column '{column_name}'"
             )))
         } else {
             Err(error)
@@ -1032,7 +1036,7 @@ fn required_string_value(
 ) -> Result<String> {
     optional_string_value(batch, row_index, column_name, action)?.ok_or_else(|| {
         DataFusionError::Execution(format!(
-            "{action} lix_version requires non-null text column '{column_name}'"
+            "{action} lix_branch requires non-null text column '{column_name}'"
         ))
     })
 }
@@ -1053,7 +1057,7 @@ fn optional_string_value(
         | Some(ScalarValue::Utf8View(Some(value)))
         | Some(ScalarValue::LargeUtf8(Some(value))) => Ok(Some(value)),
         Some(other) => Err(DataFusionError::Execution(format!(
-            "{action} lix_version expected text-compatible column '{column_name}', got {other:?}"
+            "{action} lix_branch expected text-compatible column '{column_name}', got {other:?}"
         ))),
     }
 }
@@ -1066,7 +1070,7 @@ fn required_bool_value(
 ) -> Result<bool> {
     optional_bool_value(batch, row_index, column_name, action)?.ok_or_else(|| {
         DataFusionError::Execution(format!(
-            "{action} lix_version requires non-null boolean column '{column_name}'"
+            "{action} lix_branch requires non-null boolean column '{column_name}'"
         ))
     })
 }
@@ -1081,7 +1085,7 @@ fn optional_bool_value(
         None | Some(ScalarValue::Null) | Some(ScalarValue::Boolean(None)) => Ok(None),
         Some(ScalarValue::Boolean(Some(value))) => Ok(Some(value)),
         Some(other) => Err(DataFusionError::Execution(format!(
-            "{action} lix_version expected boolean column '{column_name}', got {other:?}"
+            "{action} lix_branch expected boolean column '{column_name}', got {other:?}"
         ))),
     }
 }
@@ -1125,7 +1129,7 @@ fn dml_count_batch(schema: SchemaRef, count: u64) -> Result<RecordBatch> {
     .map_err(DataFusionError::from)
 }
 
-fn lix_version_schema() -> SchemaRef {
+pub(super) fn lix_branch_schema() -> SchemaRef {
     Arc::new(Schema::new(vec![
         Field::new("id", DataType::Utf8, false),
         Field::new("name", DataType::Utf8, false),
@@ -1134,12 +1138,12 @@ fn lix_version_schema() -> SchemaRef {
     ]))
 }
 
-fn version_projection_for_scan(projection: Option<&Vec<usize>>) -> Vec<VersionColumn> {
+fn branch_projection_for_scan(projection: Option<&Vec<usize>>) -> Vec<BranchColumn> {
     let all_columns = vec![
-        VersionColumn::Id,
-        VersionColumn::Name,
-        VersionColumn::Hidden,
-        VersionColumn::CommitId,
+        BranchColumn::Id,
+        BranchColumn::Name,
+        BranchColumn::Hidden,
+        BranchColumn::CommitId,
     ];
     projection.map_or(all_columns.clone(), |indices| {
         indices
@@ -1156,34 +1160,34 @@ fn projected_schema(schema: &SchemaRef, projection: Option<&Vec<usize>>) -> Sche
     }
 }
 
-fn version_record_batch(projection: &[VersionColumn], rows: &[VersionRow]) -> Result<RecordBatch> {
+fn branch_record_batch(projection: &[BranchColumn], rows: &[BranchRow]) -> Result<RecordBatch> {
     let arrays = projection
         .iter()
         .map(|column| match column {
-            VersionColumn::Id => string_array(rows.iter().map(|row| Some(row.id.as_str()))),
-            VersionColumn::Name => string_array(rows.iter().map(|row| Some(row.name.as_str()))),
-            VersionColumn::Hidden => Arc::new(BooleanArray::from(
+            BranchColumn::Id => string_array(rows.iter().map(|row| Some(row.id.as_str()))),
+            BranchColumn::Name => string_array(rows.iter().map(|row| Some(row.name.as_str()))),
+            BranchColumn::Hidden => Arc::new(BooleanArray::from(
                 rows.iter().map(|row| row.hidden).collect::<Vec<_>>(),
             )) as ArrayRef,
-            VersionColumn::CommitId => {
+            BranchColumn::CommitId => {
                 string_array(rows.iter().map(|row| Some(row.commit_id.as_str())))
             }
         })
         .collect::<Vec<_>>();
-    record_batch_with_row_count(version_schema(projection), arrays, rows.len()).map_err(|error| {
-        DataFusionError::Execution(format!("failed to build lix_version batch: {error}"))
+    record_batch_with_row_count(branch_schema(projection), arrays, rows.len()).map_err(|error| {
+        DataFusionError::Execution(format!("failed to build lix_branch batch: {error}"))
     })
 }
 
-fn version_schema(projection: &[VersionColumn]) -> SchemaRef {
+fn branch_schema(projection: &[BranchColumn]) -> SchemaRef {
     Arc::new(Schema::new(
         projection
             .iter()
             .map(|column| match column {
-                VersionColumn::Id => Field::new("id", DataType::Utf8, false),
-                VersionColumn::Name => Field::new("name", DataType::Utf8, false),
-                VersionColumn::Hidden => Field::new("hidden", DataType::Boolean, false),
-                VersionColumn::CommitId => Field::new("commit_id", DataType::Utf8, false),
+                BranchColumn::Id => Field::new("id", DataType::Utf8, false),
+                BranchColumn::Name => Field::new("name", DataType::Utf8, false),
+                BranchColumn::Hidden => Field::new("hidden", DataType::Boolean, false),
+                BranchColumn::CommitId => Field::new("commit_id", DataType::Utf8, false),
             })
             .collect::<Vec<_>>(),
     ))
@@ -1194,9 +1198,9 @@ fn string_array<'a>(values: impl Iterator<Item = Option<&'a str>>) -> ArrayRef {
 }
 
 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)
 }