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

package/dist-engine-src/src/sql2/{lix_state_provider.rs → providers/lix_state.rs}

@@ -25,70 +25,88 @@ use datafusion::scalar::ScalarValue;
 use futures_util::{stream, TryStreamExt};
 use serde_json::Value as JsonValue;
 
-use crate::entity_identity::EntityIdentity;
+use crate::branch::BranchRefReader;
+use crate::entity_pk::EntityPk;
 use crate::live_state::MaterializedLiveStateRow;
 use crate::live_state::{
-    LiveStateFilter, LiveStateProjection, LiveStateReader, LiveStateScanRequest,
+    LiveStateFilter, LiveStateProjection, LiveStateReader, LiveStateRowFilter, LiveStateScanRequest,
 };
+use crate::sql2::branch_scope::{resolve_provider_branch_ids, BranchBinding};
 use crate::sql2::dml::{InsertExec, InsertSink};
 use crate::sql2::read_only::reject_read_only_stage_rows;
-use crate::sql2::version_scope::{resolve_provider_version_ids, VersionBinding};
 use crate::sql2::write_normalization::{InsertCell, SqlCell, UpdateAssignmentValues};
 use crate::transaction::types::{TransactionJson, TransactionWriteRow};
-use crate::version::VersionRefReader;
-use crate::GLOBAL_VERSION_ID;
+use crate::GLOBAL_BRANCH_ID;
 use crate::{parse_row_metadata_value, serialize_row_metadata, LixError, NullableKeyFilter};
 
 use crate::sql2::{
-    SqlWriteContext, WriteAccess, WriteContextLiveStateReader, WriteContextVersionRefReader,
+    SqlWriteContext, WriteAccess, WriteContextBranchRefReader, WriteContextLiveStateReader,
 };
 use crate::transaction::types::{TransactionWrite, TransactionWriteMode};
 
-use super::predicate_typecheck::validate_json_predicate_filters;
-use super::result_metadata::json_field;
+use crate::sql2::predicate_typecheck::{
+    canonicalize_json_identity_text_filters, validate_json_predicate_filters,
+};
+use crate::sql2::result_metadata::json_field;
 
-pub(crate) async fn register_lix_state_providers(
+pub(super) async fn register_lix_state_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>,
 ) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_state_by_version",
-            Arc::new(LixStateProvider::by_version(
-                Arc::clone(&live_state),
-                Arc::clone(&version_ref),
+            surface_name,
+            Arc::new(LixStateProvider::active_branch(
+                active_branch_id,
+                live_state,
+                branch_ref,
             )),
         )
         .map_err(datafusion_error_to_lix_error)?;
+    Ok(())
+}
+
+pub(super) async fn register_lix_state_by_branch_provider(
+    session: &SessionContext,
+    surface_name: &str,
+    live_state: Arc<dyn LiveStateReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
+) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_state",
-            Arc::new(LixStateProvider::active_version(
-                active_version_id,
-                live_state,
-                version_ref,
-            )),
+            surface_name,
+            Arc::new(LixStateProvider::by_branch(live_state, branch_ref)),
         )
         .map_err(datafusion_error_to_lix_error)?;
     Ok(())
 }
 
-pub(crate) async fn register_lix_state_write_providers(
+pub(super) async fn register_lix_state_by_branch_write_provider(
     session: &SessionContext,
+    surface_name: &str,
     write_ctx: SqlWriteContext,
 ) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_state_by_version",
-            Arc::new(LixStateProvider::by_version_with_write(write_ctx.clone())),
+            surface_name,
+            Arc::new(LixStateProvider::by_branch_with_write(write_ctx)),
         )
         .map_err(datafusion_error_to_lix_error)?;
+    Ok(())
+}
+
+pub(super) async fn register_lix_state_active_write_provider(
+    session: &SessionContext,
+    surface_name: &str,
+    write_ctx: SqlWriteContext,
+) -> Result<(), LixError> {
     session
         .register_table(
-            "lix_state",
-            Arc::new(LixStateProvider::active_version_with_write(write_ctx)),
+            surface_name,
+            Arc::new(LixStateProvider::active_branch_with_write(write_ctx)),
         )
         .map_err(datafusion_error_to_lix_error)?;
     Ok(())
@@ -97,9 +115,9 @@ pub(crate) async fn register_lix_state_write_providers(
 pub(crate) struct LixStateProvider {
     schema: SchemaRef,
     live_state: Arc<dyn LiveStateReader>,
-    version_ref: Arc<dyn VersionRefReader>,
+    branch_ref: Arc<dyn BranchRefReader>,
     write_access: WriteAccess,
-    version_binding: VersionBinding,
+    branch_binding: BranchBinding,
 }
 
 impl std::fmt::Debug for LixStateProvider {
@@ -111,55 +129,55 @@ impl std::fmt::Debug for LixStateProvider {
 }
 
 impl LixStateProvider {
-    pub(crate) fn active_version(
-        active_version_id: impl Into<String>,
+    pub(crate) fn active_branch(
+        active_branch_id: impl Into<String>,
         live_state: Arc<dyn LiveStateReader>,
-        version_ref: Arc<dyn VersionRefReader>,
+        branch_ref: Arc<dyn BranchRefReader>,
     ) -> Self {
         Self {
             schema: lix_state_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::read_only(),
-            version_binding: VersionBinding::active(active_version_id),
+            branch_binding: BranchBinding::active(active_branch_id),
         }
     }
 
-    pub(crate) fn active_version_with_write(write_ctx: SqlWriteContext) -> Self {
-        let active_version_id = write_ctx.active_version_id();
+    pub(crate) fn active_branch_with_write(write_ctx: SqlWriteContext) -> Self {
+        let active_branch_id = write_ctx.active_branch_id();
         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_state_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::write(write_ctx),
-            version_binding: VersionBinding::active(active_version_id),
+            branch_binding: BranchBinding::active(active_branch_id),
         }
     }
 
-    pub(crate) fn by_version(
+    pub(crate) fn by_branch(
         live_state: Arc<dyn LiveStateReader>,
-        version_ref: Arc<dyn VersionRefReader>,
+        branch_ref: Arc<dyn BranchRefReader>,
     ) -> Self {
         Self {
-            schema: lix_state_by_version_schema(),
+            schema: lix_state_by_branch_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::read_only(),
-            version_binding: VersionBinding::explicit(),
+            branch_binding: BranchBinding::explicit(),
         }
     }
 
-    pub(crate) fn by_version_with_write(write_ctx: SqlWriteContext) -> Self {
+    pub(crate) fn by_branch_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_state_by_version_schema(),
+            schema: lix_state_by_branch_schema(),
             live_state,
-            version_ref,
+            branch_ref,
             write_access: WriteAccess::write(write_ctx),
-            version_binding: VersionBinding::explicit(),
+            branch_binding: BranchBinding::explicit(),
         }
     }
 }
@@ -201,24 +219,22 @@ impl TableProvider for LixStateProvider {
         filters: &[Expr],
         limit: Option<usize>,
     ) -> Result<Arc<dyn datafusion::physical_plan::ExecutionPlan>> {
-        let route = LixStateByVersionRoute::from_filters(filters);
+        let route = LixStateByBranchRoute::from_filters(filters);
         let projected_schema = projected_schema(&self.schema, projection)?;
         let mut request = lix_state_scan_request(
             &self.schema,
-            self.version_binding.active_version_id(),
+            self.branch_binding.active_branch_id(),
             projection,
             &route,
             limit,
         );
-        if !route.contradictory {
-            request.filter.version_ids = resolve_provider_version_ids(
-                self.version_ref.as_ref(),
-                &self.version_binding,
-                request.filter.version_ids,
-            )
-            .await
-            .map_err(lix_error_to_datafusion_error)?;
-        }
+        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(LixStateScanExec::new(
             Arc::clone(&self.live_state),
             projected_schema,
@@ -236,21 +252,13 @@ impl TableProvider for LixStateProvider {
             return not_impl_err!("{insert_op} not implemented for lix_state yet");
         }
 
-        let active_version_id = self
-            .version_binding
-            .require_active_version_id("INSERT")
-            .map_err(lix_error_to_datafusion_error)?;
-
         let write_ctx = self.write_access.require_write("INSERT into lix_state")?;
+        let branch_binding = self.branch_binding.active_branch_id().map(str::to_owned);
 
         self.schema
             .logically_equivalent_names_and_types(&input.schema())?;
 
-        let sink = LixStateInsertSink::new(
-            Arc::clone(&self.schema),
-            write_ctx.clone(),
-            active_version_id,
-        );
+        let sink = LixStateInsertSink::new(write_ctx.clone(), branch_binding);
         Ok(Arc::new(InsertExec::new(input, Arc::new(sink))))
     }
 
@@ -259,28 +267,25 @@ impl TableProvider for LixStateProvider {
         state: &dyn Session,
         filters: Vec<Expr>,
     ) -> Result<Arc<dyn ExecutionPlan>> {
-        let active_version_id = self
-            .version_binding
-            .require_active_version_id("DELETE")
-            .map_err(lix_error_to_datafusion_error)?;
-
         let write_ctx = self.write_access.require_write("DELETE FROM lix_state")?;
 
         let df_schema = DFSchema::try_from(Arc::clone(&self.schema))?;
+        let filters = canonicalize_json_identity_text_filters(self.schema.as_ref(), &filters)?;
         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 route = LixStateByVersionRoute::from_filters(&filters);
+        let route = LixStateByBranchRoute::from_filters(&filters);
+        let branch_binding = self.branch_binding.active_branch_id().map(str::to_owned);
         let request =
-            lix_state_scan_request(&self.schema, Some(&active_version_id), None, &route, None);
+            lix_state_scan_request(&self.schema, branch_binding.as_deref(), None, &route, None);
 
         Ok(Arc::new(LixStateDeleteExec::new(
             write_ctx.clone(),
             Arc::clone(&self.schema),
-            active_version_id,
+            branch_binding,
             request,
             physical_filters,
         )))
@@ -292,16 +297,11 @@ impl TableProvider for LixStateProvider {
         assignments: Vec<(String, Expr)>,
         filters: Vec<Expr>,
     ) -> Result<Arc<dyn ExecutionPlan>> {
-        let active_version_id = self
-            .version_binding
-            .require_active_version_id("UPDATE")
-            .map_err(lix_error_to_datafusion_error)?;
-
         let write_ctx = self.write_access.require_write("UPDATE lix_state")?;
-
         validate_lix_state_update_assignments(&self.schema, &assignments)?;
 
         let df_schema = DFSchema::try_from(Arc::clone(&self.schema))?;
+        let filters = canonicalize_json_identity_text_filters(self.schema.as_ref(), &filters)?;
         validate_json_predicate_filters(self.schema.as_ref(), &filters)?;
         let physical_assignments = assignments
             .iter()
@@ -317,14 +317,15 @@ impl TableProvider for LixStateProvider {
             .map(|expr| create_physical_expr(expr, &df_schema, state.execution_props()))
             .collect::<Result<Vec<_>>>()?;
 
-        let route = LixStateByVersionRoute::from_filters(&filters);
+        let route = LixStateByBranchRoute::from_filters(&filters);
+        let branch_binding = self.branch_binding.active_branch_id().map(str::to_owned);
         let request =
-            lix_state_scan_request(&self.schema, Some(&active_version_id), None, &route, None);
+            lix_state_scan_request(&self.schema, branch_binding.as_deref(), None, &route, None);
 
         Ok(Arc::new(LixStateUpdateExec::new(
             write_ctx.clone(),
             Arc::clone(&self.schema),
-            active_version_id,
+            branch_binding,
             request,
             physical_assignments,
             physical_filters,
@@ -334,7 +335,7 @@ impl TableProvider for LixStateProvider {
 
 struct LixStateInsertSink {
     write_ctx: SqlWriteContext,
-    version_binding: String,
+    branch_binding: Option<String>,
 }
 
 impl std::fmt::Debug for LixStateInsertSink {
@@ -344,10 +345,10 @@ impl std::fmt::Debug for LixStateInsertSink {
 }
 
 impl LixStateInsertSink {
-    fn new(_schema: SchemaRef, write_ctx: SqlWriteContext, version_binding: String) -> Self {
+    fn new(write_ctx: SqlWriteContext, branch_binding: Option<String>) -> Self {
         Self {
             write_ctx,
-            version_binding,
+            branch_binding,
         }
     }
 }
@@ -374,7 +375,8 @@ impl InsertSink for LixStateInsertSink {
         for batch in batches {
             rows.extend(lix_state_write_rows_from_batch(
                 &batch,
-                &self.version_binding,
+                self.branch_binding.as_deref(),
+                "INSERT into lix_state",
             )?);
         }
         reject_read_only_stage_rows(&rows, "INSERT into lix_state")?;
@@ -397,7 +399,7 @@ impl InsertSink for LixStateInsertSink {
 struct LixStateDeleteExec {
     write_ctx: SqlWriteContext,
     table_schema: SchemaRef,
-    version_binding: String,
+    branch_binding: Option<String>,
     request: LiveStateScanRequest,
     filters: Vec<Arc<dyn PhysicalExpr>>,
     result_schema: SchemaRef,
@@ -414,7 +416,7 @@ impl LixStateDeleteExec {
     fn new(
         write_ctx: SqlWriteContext,
         table_schema: SchemaRef,
-        version_binding: String,
+        branch_binding: Option<String>,
         request: LiveStateScanRequest,
         filters: Vec<Arc<dyn PhysicalExpr>>,
     ) -> Self {
@@ -428,7 +430,7 @@ impl LixStateDeleteExec {
         Self {
             write_ctx,
             table_schema,
-            version_binding,
+            branch_binding,
             request,
             filters,
             result_schema,
@@ -489,26 +491,24 @@ impl ExecutionPlan for LixStateDeleteExec {
         }
         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);
         let stream_schema = Arc::clone(&result_schema);
 
         let stream = stream::once(async move {
-            let rows = if request.limit == Some(0) {
-                Vec::new()
-            } else {
-                write_ctx
-                    .scan_live_state(&request)
-                    .await
-                    .map_err(lix_error_to_datafusion_error)?
-            };
+            let rows = write_ctx
+                .scan_live_state(&request)
+                .await
+                .map_err(lix_error_to_datafusion_error)?;
             let source_batch = lix_state_record_batch(Arc::clone(&table_schema), &rows)
                 .map_err(lix_error_to_datafusion_error)?;
             let matched_batch = filter_lix_state_batch(source_batch, &filters)?;
-            let write_rows =
-                lix_state_deletable_write_rows_from_batch(&matched_batch, &version_binding)?;
+            let write_rows = lix_state_deletable_write_rows_from_batch(
+                &matched_batch,
+                branch_binding.as_deref(),
+            )?;
             reject_read_only_stage_rows(&write_rows, "DELETE FROM lix_state")?;
             let count = u64::try_from(write_rows.len())
                 .map_err(|_| DataFusionError::Execution("DELETE row count overflow".to_string()))?;
@@ -539,7 +539,7 @@ impl ExecutionPlan for LixStateDeleteExec {
 struct LixStateUpdateExec {
     write_ctx: SqlWriteContext,
     table_schema: SchemaRef,
-    version_binding: String,
+    branch_binding: Option<String>,
     request: LiveStateScanRequest,
     assignments: Vec<(String, Arc<dyn PhysicalExpr>)>,
     filters: Vec<Arc<dyn PhysicalExpr>>,
@@ -557,7 +557,7 @@ impl LixStateUpdateExec {
     fn new(
         write_ctx: SqlWriteContext,
         table_schema: SchemaRef,
-        version_binding: String,
+        branch_binding: Option<String>,
         request: LiveStateScanRequest,
         assignments: Vec<(String, Arc<dyn PhysicalExpr>)>,
         filters: Vec<Arc<dyn PhysicalExpr>>,
@@ -572,7 +572,7 @@ impl LixStateUpdateExec {
         Self {
             write_ctx,
             table_schema,
-            version_binding,
+            branch_binding,
             request,
             assignments,
             filters,
@@ -639,7 +639,7 @@ impl ExecutionPlan for LixStateUpdateExec {
         }
         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();
@@ -647,21 +647,17 @@ impl ExecutionPlan for LixStateUpdateExec {
         let stream_schema = Arc::clone(&result_schema);
 
         let stream = stream::once(async move {
-            let rows = if request.limit == Some(0) {
-                Vec::new()
-            } else {
-                write_ctx
-                    .scan_live_state(&request)
-                    .await
-                    .map_err(lix_error_to_datafusion_error)?
-            };
+            let rows = write_ctx
+                .scan_live_state(&request)
+                .await
+                .map_err(lix_error_to_datafusion_error)?;
             let source_batch = lix_state_record_batch(Arc::clone(&table_schema), &rows)
                 .map_err(lix_error_to_datafusion_error)?;
             let matched_batch = filter_lix_state_batch(source_batch, &filters)?;
             let write_rows = lix_state_update_write_rows_from_batch(
                 &matched_batch,
                 &assignments,
-                &version_binding,
+                branch_binding.as_deref(),
             )?;
             reject_read_only_stage_rows(&write_rows, "UPDATE lix_state")?;
             let count = u64::try_from(write_rows.len())
@@ -689,25 +685,6 @@ impl ExecutionPlan for LixStateUpdateExec {
     }
 }
 
-fn validate_lix_state_update_assignments(
-    schema: &SchemaRef,
-    assignments: &[(String, Expr)],
-) -> Result<()> {
-    for (column_name, _) in assignments {
-        schema.field_with_name(column_name).map_err(|_| {
-            DataFusionError::Plan(format!(
-                "UPDATE lix_state failed: column '{column_name}' does not exist"
-            ))
-        })?;
-        if !matches!(column_name.as_str(), "snapshot_content" | "metadata") {
-            return Err(DataFusionError::Execution(format!(
-                "UPDATE lix_state cannot stage read-only column '{column_name}'"
-            )));
-        }
-    }
-    Ok(())
-}
-
 fn filter_lix_state_batch(
     batch: RecordBatch,
     filters: &[Arc<dyn PhysicalExpr>],
@@ -750,9 +727,10 @@ fn evaluate_lix_state_filters(
 
 fn lix_state_stageable_write_rows_from_batch(
     batch: &RecordBatch,
-    version_binding: &str,
+    branch_binding: Option<&str>,
+    action: &str,
 ) -> Result<Vec<TransactionWriteRow>> {
-    let mut rows = lix_state_write_rows_from_batch(batch, version_binding)?;
+    let mut rows = lix_state_write_rows_from_batch(batch, branch_binding, action)?;
     for row in &mut rows {
         row.created_at = None;
         row.updated_at = None;
@@ -765,31 +743,36 @@ fn lix_state_stageable_write_rows_from_batch(
 fn lix_state_update_write_rows_from_batch(
     batch: &RecordBatch,
     assignments: &[(String, Arc<dyn PhysicalExpr>)],
-    version_binding: &str,
+    branch_binding: Option<&str>,
 ) -> Result<Vec<TransactionWriteRow>> {
     let assignment_values = UpdateAssignmentValues::evaluate(batch, assignments)?;
     (0..batch.num_rows())
         .map(|row_index| {
             let global = optional_bool_value(batch, row_index, "global")?.unwrap_or(false);
-            let version_id =
-                optional_string_value(batch, row_index, "version_id")?.unwrap_or_else(|| {
+            let branch_id =
+                optional_string_value(batch, row_index, "branch_id")?.unwrap_or_else(|| {
                     if global {
-                        GLOBAL_VERSION_ID.to_string()
+                        GLOBAL_BRANCH_ID.to_string()
                     } else {
-                        version_binding.to_string()
+                        branch_binding.unwrap_or_default().to_string()
                     }
                 });
+            if !global && branch_id.is_empty() {
+                return Err(DataFusionError::Execution(
+                    "UPDATE lix_state_by_branch requires branch_id".to_string(),
+                ));
+            }
 
             Ok(TransactionWriteRow {
-                entity_id: Some(
-                    EntityIdentity::from_json_array_text(&required_string_value(
+                entity_pk: Some(
+                    EntityPk::from_json_array_text(&required_string_value(
                         batch,
                         row_index,
-                        "entity_id",
+                        "entity_pk",
                     )?)
                     .map_err(|error| {
                         DataFusionError::Execution(format!(
-                            "lix_state UPDATE has invalid entity_id: {error}"
+                            "lix_state UPDATE has invalid entity_pk: {error}"
                         ))
                     })?,
                 ),
@@ -815,7 +798,7 @@ fn lix_state_update_write_rows_from_batch(
                 change_id: None,
                 commit_id: None,
                 untracked: optional_bool_value(batch, row_index, "untracked")?.unwrap_or(false),
-                version_id,
+                branch_id,
             })
         })
         .collect()
@@ -823,9 +806,10 @@ fn lix_state_update_write_rows_from_batch(
 
 fn lix_state_deletable_write_rows_from_batch(
     batch: &RecordBatch,
-    version_binding: &str,
+    branch_binding: Option<&str>,
 ) -> Result<Vec<TransactionWriteRow>> {
-    let mut rows = lix_state_stageable_write_rows_from_batch(batch, version_binding)?;
+    let mut rows =
+        lix_state_stageable_write_rows_from_batch(batch, branch_binding, "DELETE FROM lix_state")?;
     for row in &mut rows {
         row.snapshot = None;
     }
@@ -861,9 +845,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()
 }
@@ -897,30 +881,36 @@ fn dml_count_batch(schema: SchemaRef, count: u64) -> Result<RecordBatch> {
 
 fn lix_state_write_rows_from_batch(
     batch: &RecordBatch,
-    version_binding: &str,
+    branch_binding: Option<&str>,
+    action: &str,
 ) -> Result<Vec<TransactionWriteRow>> {
     (0..batch.num_rows())
         .map(|row_index| {
             let global = optional_bool_value(batch, row_index, "global")?.unwrap_or(false);
-            let version_id =
-                optional_string_value(batch, row_index, "version_id")?.unwrap_or_else(|| {
+            let branch_id =
+                optional_string_value(batch, row_index, "branch_id")?.unwrap_or_else(|| {
                     if global {
-                        GLOBAL_VERSION_ID.to_string()
+                        GLOBAL_BRANCH_ID.to_string()
                     } else {
-                        version_binding.to_string()
+                        branch_binding.unwrap_or_default().to_string()
                     }
                 });
+            if !global && branch_id.is_empty() {
+                return Err(DataFusionError::Execution(format!(
+                    "{action} requires branch_id"
+                )));
+            }
 
             Ok(TransactionWriteRow {
-                entity_id: Some(
-                    EntityIdentity::from_json_array_text(&required_string_value(
+                entity_pk: Some(
+                    EntityPk::from_json_array_text(&required_string_value(
                         batch,
                         row_index,
-                        "entity_id",
+                        "entity_pk",
                     )?)
                     .map_err(|error| {
                         DataFusionError::Execution(format!(
-                            "lix_state INSERT has invalid entity_id: {error}"
+                            "lix_state INSERT has invalid entity_pk: {error}"
                         ))
                     })?,
                 ),
@@ -935,12 +925,34 @@ fn lix_state_write_rows_from_batch(
                 change_id: optional_string_value(batch, row_index, "change_id")?,
                 commit_id: optional_string_value(batch, row_index, "commit_id")?,
                 untracked: optional_bool_value(batch, row_index, "untracked")?.unwrap_or(false),
-                version_id,
+                branch_id,
             })
         })
         .collect()
 }
 
+fn validate_lix_state_update_assignments(
+    schema: &SchemaRef,
+    assignments: &[(String, Expr)],
+) -> Result<()> {
+    for (column_name, _) in assignments {
+        schema.field_with_name(column_name).map_err(|_| {
+            DataFusionError::Plan(format!(
+                "UPDATE lix_state failed: column '{column_name}' does not exist"
+            ))
+        })?;
+        if !matches!(
+            column_name.as_str(),
+            "snapshot_content" | "metadata" | "global" | "untracked"
+        ) {
+            return Err(DataFusionError::Execution(format!(
+                "UPDATE lix_state cannot stage read-only column '{column_name}'"
+            )));
+        }
+    }
+    Ok(())
+}
+
 fn required_string_value(
     batch: &RecordBatch,
     row_index: usize,
@@ -982,9 +994,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()
 }
@@ -1006,7 +1018,7 @@ fn parse_snapshot_json(value: &str, column_name: &str) -> Result<TransactionJson
         ))
     })?;
     TransactionJson::from_value(parsed, &format!("lix_state {column_name}"))
-        .map_err(super::error::lix_error_to_datafusion_error)
+        .map_err(crate::sql2::error::lix_error_to_datafusion_error)
 }
 
 fn optional_bool_value(
@@ -1140,14 +1152,10 @@ impl ExecutionPlan for LixStateScanExec {
         let request = self.request.clone();
         let stream_schema = Arc::clone(&schema);
         let stream = stream::once(async move {
-            let rows = if request.limit == Some(0) {
-                Vec::new()
-            } else {
-                live_state
-                    .scan_rows(&request)
-                    .await
-                    .map_err(lix_error_to_datafusion_error)?
-            };
+            let rows = live_state
+                .scan_rows(&request)
+                .await
+                .map_err(lix_error_to_datafusion_error)?;
             let batch = lix_state_record_batch(Arc::clone(&stream_schema), &rows)
                 .map_err(lix_error_to_datafusion_error)?;
             Ok::<_, DataFusionError>(stream::iter(vec![Ok::<RecordBatch, DataFusionError>(
@@ -1159,9 +1167,9 @@ impl ExecutionPlan for LixStateScanExec {
     }
 }
 
-fn lix_state_schema() -> SchemaRef {
+pub(super) fn lix_state_schema() -> SchemaRef {
     Arc::new(Schema::new(vec![
-        json_field("entity_id", false),
+        json_field("entity_pk", false),
         Field::new("schema_key", DataType::Utf8, false),
         Field::new("file_id", DataType::Utf8, true),
         json_field("snapshot_content", true),
@@ -1175,9 +1183,9 @@ fn lix_state_schema() -> SchemaRef {
     ]))
 }
 
-fn lix_state_by_version_schema() -> SchemaRef {
+pub(super) fn lix_state_by_branch_schema() -> SchemaRef {
     Arc::new(Schema::new(vec![
-        json_field("entity_id", false),
+        json_field("entity_pk", false),
         Field::new("schema_key", DataType::Utf8, false),
         Field::new("file_id", DataType::Utf8, true),
         json_field("snapshot_content", true),
@@ -1188,20 +1196,20 @@ fn lix_state_by_version_schema() -> SchemaRef {
         Field::new("change_id", DataType::Utf8, true),
         Field::new("commit_id", DataType::Utf8, true),
         Field::new("untracked", DataType::Boolean, true),
-        Field::new("version_id", DataType::Utf8, false),
+        Field::new("branch_id", DataType::Utf8, false),
     ]))
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
-struct LixStateByVersionRoute {
+struct LixStateByBranchRoute {
     schema_keys: Option<BTreeSet<String>>,
-    version_ids: Option<BTreeSet<String>>,
-    entity_ids: Option<BTreeSet<String>>,
+    branch_ids: Option<BTreeSet<String>>,
+    entity_pks: Option<BTreeSet<String>>,
     file_id: Option<NullableKeyFilter<String>>,
     contradictory: bool,
 }
 
-impl LixStateByVersionRoute {
+impl LixStateByBranchRoute {
     fn from_filters(filters: &[Expr]) -> Self {
         let mut route = Self::default();
         for filter in filters {
@@ -1217,16 +1225,16 @@ impl LixStateByVersionRoute {
                             &mut route.contradictory,
                         );
                     }
-                    LixStateFilterPredicate::VersionIds(values) => {
+                    LixStateFilterPredicate::BranchIds(values) => {
                         merge_string_route_slot(
-                            &mut route.version_ids,
+                            &mut route.branch_ids,
                             values,
                             &mut route.contradictory,
                         );
                     }
-                    LixStateFilterPredicate::EntityIds(values) => {
+                    LixStateFilterPredicate::EntityPks(values) => {
                         merge_string_route_slot(
-                            &mut route.entity_ids,
+                            &mut route.entity_pks,
                             values,
                             &mut route.contradictory,
                         );
@@ -1248,16 +1256,16 @@ impl LixStateByVersionRoute {
 #[derive(Debug, Clone, PartialEq, Eq)]
 enum LixStateFilterPredicate {
     SchemaKeys(BTreeSet<String>),
-    VersionIds(BTreeSet<String>),
-    EntityIds(BTreeSet<String>),
+    BranchIds(BTreeSet<String>),
+    EntityPks(BTreeSet<String>),
     FileId(NullableKeyFilter<String>),
 }
 
 fn lix_state_scan_request(
     schema: &SchemaRef,
-    version_binding: Option<&str>,
+    branch_binding: Option<&str>,
     projection: Option<&Vec<usize>>,
-    route: &LixStateByVersionRoute,
+    route: &LixStateByBranchRoute,
     limit: Option<usize>,
 ) -> LiveStateScanRequest {
     let projection = LiveStateProjection {
@@ -1269,21 +1277,21 @@ fn lix_state_scan_request(
             .as_ref()
             .map(|values| values.iter().cloned().collect())
             .unwrap_or_default(),
-        entity_ids: route
-            .entity_ids
+        entity_pks: route
+            .entity_pks
             .as_ref()
             .map(|values| {
                 values
                     .iter()
-                    .filter_map(|value| EntityIdentity::from_json_array_text(value).ok())
+                    .filter_map(|value| EntityPk::from_json_array_text(value).ok())
                     .collect()
             })
             .unwrap_or_default(),
-        version_ids: version_binding
+        branch_ids: branch_binding
             .map(|value| vec![value.to_string()])
             .or_else(|| {
                 route
-                    .version_ids
+                    .branch_ids
                     .as_ref()
                     .map(|values| values.iter().cloned().collect())
             })
@@ -1294,10 +1302,14 @@ fn lix_state_scan_request(
         filter.file_ids.push(file_id);
     }
 
+    if route.contradictory {
+        filter.rows = LiveStateRowFilter::None;
+    }
+
     LiveStateScanRequest {
         filter,
         projection,
-        limit: route.contradictory.then_some(0).or(limit),
+        limit,
     }
 }
 
@@ -1396,8 +1408,8 @@ fn parse_lix_state_in_list_filter(in_list: &InList) -> Option<LixStateFilterPred
     let values = values.into_iter().collect::<BTreeSet<_>>();
     match column.name.as_str() {
         "schema_key" => Some(LixStateFilterPredicate::SchemaKeys(values)),
-        "version_id" => Some(LixStateFilterPredicate::VersionIds(values)),
-        "entity_id" => canonical_entity_id_values(values).map(LixStateFilterPredicate::EntityIds),
+        "branch_id" => Some(LixStateFilterPredicate::BranchIds(values)),
+        "entity_pk" => canonical_entity_pk_values(values).map(LixStateFilterPredicate::EntityPks),
         _ => None,
     }
 }
@@ -1424,25 +1436,25 @@ fn parse_lix_state_column_literal_filter(
     match column.name.as_str() {
         "schema_key" => string_expr_literal(literal_expr)
             .map(|value| LixStateFilterPredicate::SchemaKeys(BTreeSet::from([value]))),
-        "version_id" => string_expr_literal(literal_expr)
-            .map(|value| LixStateFilterPredicate::VersionIds(BTreeSet::from([value]))),
-        "entity_id" => string_expr_literal(literal_expr)
-            .and_then(|value| canonical_entity_id_value(&value))
-            .map(|value| LixStateFilterPredicate::EntityIds(BTreeSet::from([value]))),
+        "branch_id" => string_expr_literal(literal_expr)
+            .map(|value| LixStateFilterPredicate::BranchIds(BTreeSet::from([value]))),
+        "entity_pk" => string_expr_literal(literal_expr)
+            .and_then(|value| canonical_entity_pk_value(&value))
+            .map(|value| LixStateFilterPredicate::EntityPks(BTreeSet::from([value]))),
         "file_id" => nullable_key_literal(literal_expr).map(LixStateFilterPredicate::FileId),
         _ => None,
     }
 }
 
-fn canonical_entity_id_values(values: BTreeSet<String>) -> Option<BTreeSet<String>> {
+fn canonical_entity_pk_values(values: BTreeSet<String>) -> Option<BTreeSet<String>> {
     values
         .into_iter()
-        .map(|value| canonical_entity_id_value(&value))
+        .map(|value| canonical_entity_pk_value(&value))
         .collect()
 }
 
-fn canonical_entity_id_value(value: &str) -> Option<String> {
-    EntityIdentity::from_json_array_text(value)
+fn canonical_entity_pk_value(value: &str) -> Option<String> {
+    EntityPk::from_json_array_text(value)
         .ok()?
         .as_json_array_text()
         .ok()
@@ -1490,9 +1502,9 @@ fn lix_state_record_batch(
         .iter()
         .map(|field| {
             Ok(match field.name().as_str() {
-                "entity_id" => Arc::new(StringArray::from(
+                "entity_pk" => Arc::new(StringArray::from(
                     rows.iter()
-                        .map(|row| row.entity_id.as_json_array_text().map(Some))
+                        .map(|row| row.entity_pk.as_json_array_text().map(Some))
                         .collect::<std::result::Result<Vec<_>, LixError>>()?,
                 )) as ArrayRef,
                 "schema_key" => string_array(rows.iter().map(|row| Some(row.schema_key.as_str()))),
@@ -1515,7 +1527,7 @@ fn lix_state_record_batch(
                 "untracked" => Arc::new(BooleanArray::from(
                     rows.iter().map(|row| row.untracked).collect::<Vec<_>>(),
                 )) as ArrayRef,
-                "version_id" => string_array(rows.iter().map(|row| Some(row.version_id.as_str()))),
+                "branch_id" => string_array(rows.iter().map(|row| Some(row.branch_id.as_str()))),
                 other => {
                     return Err(LixError::new(
                         "LIX_ERROR_UNKNOWN",
@@ -1529,7 +1541,7 @@ fn lix_state_record_batch(
     RecordBatch::try_new(schema, columns).map_err(|error| {
         LixError::new(
             "LIX_ERROR_UNKNOWN",
-            format!("sql2 failed to build lix_state_by_version batch: {error}"),
+            format!("sql2 failed to build lix_state_by_branch batch: {error}"),
         )
     })
 }
@@ -1553,22 +1565,23 @@ fn projected_schema(schema: &SchemaRef, projection: Option<&Vec<usize>>) -> Resu
 }
 
 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)]
 mod tests {
     use super::{
         lix_state_scan_request, lix_state_schema, lix_state_write_rows_from_batch,
-        parse_lix_state_filter, register_lix_state_write_providers, LixStateByVersionRoute,
-        LixStateDeleteExec, LixStateFilterPredicate, LixStateInsertSink, LixStateProvider,
-        LixStateUpdateExec,
+        parse_lix_state_filter, register_lix_state_active_write_provider,
+        register_lix_state_by_branch_write_provider, LixStateByBranchRoute, LixStateDeleteExec,
+        LixStateFilterPredicate, LixStateInsertSink, LixStateProvider, LixStateUpdateExec,
     };
     use crate::binary_cas::BlobDataReader;
+    use crate::branch::{BranchHead, BranchRefReader};
     use crate::functions::{
         FunctionProvider, FunctionProviderHandle, SharedFunctionProvider, SystemFunctionProvider,
     };
@@ -1578,9 +1591,8 @@ mod tests {
         TransactionJson, TransactionWrite, TransactionWriteMode, TransactionWriteOutcome,
         TransactionWriteRow,
     };
-    use crate::version::{VersionHead, VersionRefReader};
     use crate::{
-        entity_identity::EntityIdentity,
+        entity_pk::EntityPk,
         live_state::{
             LiveStateReader, LiveStateRowRequest, LiveStateScanRequest, MaterializedLiveStateRow,
         },
@@ -1611,11 +1623,7 @@ mod tests {
     use std::sync::Arc;
 
     struct EmptyLiveStateReader;
-    struct EmptyVersionRefReader;
-    #[allow(dead_code)]
-    struct RowsLiveStateReader {
-        rows: Vec<MaterializedLiveStateRow>,
-    }
+    struct EmptyBranchRefReader;
     struct DummyBlobReader;
 
     #[derive(Default)]
@@ -1730,35 +1738,18 @@ mod tests {
     }
 
     #[async_trait]
-    impl VersionRefReader for EmptyVersionRefReader {
-        async fn load_head(&self, _version_id: &str) -> Result<Option<VersionHead>, LixError> {
+    impl BranchRefReader for EmptyBranchRefReader {
+        async fn load_head(&self, _branch_id: &str) -> Result<Option<BranchHead>, LixError> {
             Ok(None)
         }
 
-        async fn scan_heads(&self) -> Result<Vec<VersionHead>, LixError> {
+        async fn scan_heads(&self) -> Result<Vec<BranchHead>, LixError> {
             Ok(Vec::new())
         }
     }
 
-    fn empty_version_ref() -> Arc<dyn VersionRefReader> {
-        Arc::new(EmptyVersionRefReader)
-    }
-
-    #[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 empty_branch_ref() -> Arc<dyn BranchRefReader> {
+        Arc::new(EmptyBranchRefReader)
     }
 
     fn test_functions() -> FunctionProviderHandle {
@@ -1782,8 +1773,8 @@ mod tests {
 
     #[async_trait]
     impl SqlWriteExecutionContext for DummyWriteContext {
-        fn active_version_id(&self) -> &str {
-            "version-a"
+        fn active_branch_id(&self) -> &str {
+            "branch-a"
         }
 
         fn functions(&self) -> FunctionProviderHandle {
@@ -1808,14 +1799,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(
@@ -1828,8 +1816,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 {
@@ -1854,14 +1842,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(
@@ -1937,17 +1922,17 @@ mod tests {
         .expect("valid stageable lix_state batch")
     }
 
-    fn live_row(entity_id: &str, metadata: Option<&str>) -> MaterializedLiveStateRow {
+    fn live_row(entity_pk: &str, metadata: Option<&str>) -> MaterializedLiveStateRow {
         MaterializedLiveStateRow {
-            entity_id: EntityIdentity::single(entity_id),
+            entity_pk: EntityPk::single(entity_pk),
             schema_key: "lix_key_value".to_string(),
             file_id: None,
             snapshot_content: Some("{\"key\":\"hello\",\"value\":\"world\"}".to_string()),
             metadata: metadata.map(str::to_string),
             deleted: false,
-            version_id: "version-a".to_string(),
-            change_id: Some(format!("change-{entity_id}")),
-            commit_id: Some(format!("commit-{entity_id}")),
+            branch_id: "branch-a".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(),
@@ -1972,16 +1957,16 @@ mod tests {
     }
 
     #[test]
-    fn parses_in_list_filter_for_version_id() {
+    fn parses_in_list_filter_for_branch_id() {
         let expr = Expr::InList(InList::new(
-            Box::new(col("version_id")),
+            Box::new(col("branch_id")),
             vec![str_lit("a"), str_lit("b")],
             false,
         ));
 
         assert_eq!(
             parse_lix_state_filter(&expr),
-            Some(LixStateFilterPredicate::VersionIds(BTreeSet::from([
+            Some(LixStateFilterPredicate::BranchIds(BTreeSet::from([
                 "a".to_string(),
                 "b".to_string(),
             ])))
@@ -1990,15 +1975,15 @@ mod tests {
 
     #[test]
     fn builds_scan_request_from_route_and_projection() {
-        let schema = super::lix_state_by_version_schema();
-        let route = LixStateByVersionRoute::from_filters(&[
+        let schema = super::lix_state_by_branch_schema();
+        let route = LixStateByBranchRoute::from_filters(&[
             Expr::BinaryExpr(BinaryExpr::new(
                 Box::new(col("schema_key")),
                 Operator::Eq,
                 Box::new(str_lit("profile")),
             )),
             Expr::BinaryExpr(BinaryExpr::new(
-                Box::new(col("version_id")),
+                Box::new(col("branch_id")),
                 Operator::Eq,
                 Box::new(str_lit("v1")),
             )),
@@ -2009,14 +1994,14 @@ mod tests {
             lix_state_scan_request(&schema, None, Some(&vec![0, 1, 11]), &route, Some(10));
 
         assert_eq!(request.filter.schema_keys, vec!["profile".to_string()]);
-        assert_eq!(request.filter.version_ids, vec!["v1".to_string()]);
+        assert_eq!(request.filter.branch_ids, vec!["v1".to_string()]);
         assert_eq!(request.filter.file_ids, vec![NullableKeyFilter::Null]);
         assert_eq!(
             request.projection.columns,
             vec![
-                "entity_id".to_string(),
+                "entity_pk".to_string(),
                 "schema_key".to_string(),
-                "version_id".to_string()
+                "branch_id".to_string()
             ]
         );
         assert_eq!(request.limit, Some(10));
@@ -2024,37 +2009,37 @@ mod tests {
 
     #[test]
     fn builds_route_from_and_filter_tree() {
-        let route = LixStateByVersionRoute::from_filters(&[Expr::BinaryExpr(BinaryExpr::new(
+        let route = LixStateByBranchRoute::from_filters(&[Expr::BinaryExpr(BinaryExpr::new(
             Box::new(Expr::BinaryExpr(BinaryExpr::new(
-                Box::new(col("entity_id")),
+                Box::new(col("entity_pk")),
                 Operator::Eq,
                 Box::new(str_lit("[\"entity-a\"]")),
             ))),
             Operator::And,
             Box::new(Expr::InList(InList::new(
-                Box::new(col("version_id")),
-                vec![str_lit("version-a"), str_lit("global")],
+                Box::new(col("branch_id")),
+                vec![str_lit("branch-a"), str_lit("global")],
                 false,
             ))),
         ))]);
 
         assert_eq!(
-            route.entity_ids,
+            route.entity_pks,
             Some(BTreeSet::from(["[\"entity-a\"]".to_string()]))
         );
         assert_eq!(
-            route.version_ids,
+            route.branch_ids,
             Some(BTreeSet::from([
                 "global".to_string(),
-                "version-a".to_string()
+                "branch-a".to_string()
             ]))
         );
     }
 
     #[test]
     fn contradictory_filters_turn_into_zero_limit_request() {
-        let schema = super::lix_state_by_version_schema();
-        let route = LixStateByVersionRoute::from_filters(&[
+        let schema = super::lix_state_by_branch_schema();
+        let route = LixStateByBranchRoute::from_filters(&[
             Expr::BinaryExpr(BinaryExpr::new(
                 Box::new(col("schema_key")),
                 Operator::Eq,
@@ -2069,23 +2054,60 @@ mod tests {
 
         let request = lix_state_scan_request(&schema, None, None, &route, None);
 
-        assert_eq!(request.limit, Some(0));
+        assert_eq!(
+            request.filter.rows,
+            crate::live_state::LiveStateRowFilter::None
+        );
+        assert_eq!(request.limit, None);
         assert!(request.filter.schema_keys.is_empty());
     }
 
+    #[tokio::test]
+    async fn active_provider_contradictory_filters_still_validate_active_head() {
+        let provider = LixStateProvider::active_branch(
+            "missing-branch",
+            Arc::new(EmptyLiveStateReader),
+            empty_branch_ref(),
+        );
+        let session = SessionContext::new();
+        let filters = vec![
+            Expr::BinaryExpr(BinaryExpr::new(
+                Box::new(col("schema_key")),
+                Operator::Eq,
+                Box::new(str_lit("a")),
+            )),
+            Expr::BinaryExpr(BinaryExpr::new(
+                Box::new(col("schema_key")),
+                Operator::Eq,
+                Box::new(str_lit("b")),
+            )),
+        ];
+
+        let error = provider
+            .scan(&session.state(), None, &filters, None)
+            .await
+            .expect_err("missing active branch should be checked before zero-row scan");
+        let error = super::datafusion_error_to_lix_error(error);
+
+        assert_eq!(error.code, LixError::CODE_BRANCH_NOT_FOUND);
+        assert!(error
+            .message
+            .contains("branch 'missing-branch' was not found"));
+    }
+
     #[test]
-    fn active_version_view_pins_version_filter() {
+    fn active_branch_view_pins_branch_filter() {
         let schema = super::lix_state_schema();
-        let route = LixStateByVersionRoute::from_filters(&[Expr::BinaryExpr(BinaryExpr::new(
+        let route = LixStateByBranchRoute::from_filters(&[Expr::BinaryExpr(BinaryExpr::new(
             Box::new(col("schema_key")),
             Operator::Eq,
             Box::new(str_lit("profile")),
         ))]);
 
-        let request = lix_state_scan_request(&schema, Some("version-a"), None, &route, None);
+        let request = lix_state_scan_request(&schema, Some("branch-a"), None, &route, None);
 
         assert_eq!(request.filter.schema_keys, vec!["profile".to_string()]);
-        assert_eq!(request.filter.version_ids, vec!["version-a".to_string()]);
+        assert_eq!(request.filter.branch_ids, vec!["branch-a".to_string()]);
     }
 
     #[tokio::test]
@@ -2094,9 +2116,12 @@ mod tests {
         let mut write_context = DummyWriteContext::default();
         let write_ctx = SqlWriteContext::new(&mut write_context);
 
-        register_lix_state_write_providers(&session, write_ctx)
+        register_lix_state_active_write_provider(&session, "lix_state", write_ctx.clone())
+            .await
+            .expect("lix_state provider should register");
+        register_lix_state_by_branch_write_provider(&session, "lix_state_by_branch", write_ctx)
             .await
-            .expect("lix_state providers should register");
+            .expect("lix_state_by_branch provider should register");
 
         let lix_state = session
             .table_provider("lix_state")
@@ -2108,23 +2133,22 @@ mod tests {
             .expect("lix_state should be a LixStateProvider");
         assert!(lix_state.write_access.is_write());
 
-        let by_version = session
-            .table_provider("lix_state_by_version")
+        let by_branch = session
+            .table_provider("lix_state_by_branch")
             .await
-            .expect("lix_state_by_version provider should exist");
-        let by_version = by_version
+            .expect("lix_state_by_branch provider should exist");
+        let by_branch = by_branch
             .as_any()
             .downcast_ref::<LixStateProvider>()
-            .expect("lix_state_by_version should be a LixStateProvider");
-        assert!(by_version.write_access.is_write());
+            .expect("lix_state_by_branch should be a LixStateProvider");
+        assert!(by_branch.write_access.is_write());
     }
 
     #[tokio::test]
     async fn insert_into_requires_write_transaction() {
         let session = SessionContext::new();
         let live_state = Arc::new(EmptyLiveStateReader) as Arc<dyn LiveStateReader>;
-        let provider =
-            LixStateProvider::active_version("version-a", live_state, empty_version_ref());
+        let provider = LixStateProvider::active_branch("branch-a", live_state, empty_branch_ref());
         let input = Arc::new(EmptyExec::new(provider.schema())) as Arc<dyn ExecutionPlan>;
 
         let error = provider
@@ -2142,8 +2166,7 @@ mod tests {
     async fn update_requires_write_transaction() {
         let session = SessionContext::new();
         let live_state = Arc::new(EmptyLiveStateReader) as Arc<dyn LiveStateReader>;
-        let provider =
-            LixStateProvider::active_version("version-a", live_state, empty_version_ref());
+        let provider = LixStateProvider::active_branch("branch-a", live_state, empty_branch_ref());
 
         let error = provider
             .update(
@@ -2164,8 +2187,7 @@ mod tests {
     async fn delete_requires_write_transaction() {
         let session = SessionContext::new();
         let live_state = Arc::new(EmptyLiveStateReader) as Arc<dyn LiveStateReader>;
-        let provider =
-            LixStateProvider::active_version("version-a", live_state, empty_version_ref());
+        let provider = LixStateProvider::active_branch("branch-a", live_state, empty_branch_ref());
 
         let error = provider
             .delete_from(&session.state(), vec![])
@@ -2183,7 +2205,7 @@ mod tests {
         let session = SessionContext::new();
         let mut write_context = DummyWriteContext::default();
         let write_ctx = SqlWriteContext::new(&mut write_context);
-        let provider = LixStateProvider::active_version_with_write(write_ctx);
+        let provider = LixStateProvider::active_branch_with_write(write_ctx);
 
         let plan = provider
             .delete_from(&session.state(), vec![])
@@ -2198,19 +2220,19 @@ mod tests {
         let session = SessionContext::new();
         let mut write_context = DummyWriteContext::default();
         let write_ctx = SqlWriteContext::new(&mut write_context);
-        let provider = LixStateProvider::active_version_with_write(write_ctx);
+        let provider = LixStateProvider::active_branch_with_write(write_ctx);
 
         let error = provider
             .update(
                 &session.state(),
-                vec![("entity_id".to_string(), str_lit("entity-2"))],
+                vec![("entity_pk".to_string(), str_lit("entity-2"))],
                 vec![],
             )
             .await
             .expect_err("updating a read-only field should fail");
 
         assert!(
-            error.to_string().contains("read-only column 'entity_id'"),
+            error.to_string().contains("read-only column 'entity_pk'"),
             "unexpected error: {error}"
         );
     }
@@ -2220,7 +2242,7 @@ mod tests {
         let session = SessionContext::new();
         let mut write_context = DummyWriteContext::default();
         let write_ctx = SqlWriteContext::new(&mut write_context);
-        let provider = LixStateProvider::active_version_with_write(write_ctx);
+        let provider = LixStateProvider::active_branch_with_write(write_ctx);
 
         let plan = provider
             .update(
@@ -2239,7 +2261,7 @@ mod tests {
         let session = SessionContext::new();
         let mut write_context = DummyWriteContext::default();
         let write_ctx = SqlWriteContext::new(&mut write_context);
-        let provider = LixStateProvider::active_version_with_write(write_ctx);
+        let provider = LixStateProvider::active_branch_with_write(write_ctx);
         let input = Arc::new(EmptyExec::new(provider.schema())) as Arc<dyn ExecutionPlan>;
 
         let plan = provider
@@ -2252,13 +2274,17 @@ mod tests {
 
     #[test]
     fn decodes_lix_state_batch_into_write_rows() {
-        let rows = lix_state_write_rows_from_batch(&one_row_lix_state_batch(false), "version-a")
-            .expect("batch should decode");
+        let rows = lix_state_write_rows_from_batch(
+            &one_row_lix_state_batch(false),
+            Some("branch-a"),
+            "INSERT into lix_state",
+        )
+        .expect("batch should decode");
 
         assert_eq!(
             rows,
             vec![TransactionWriteRow {
-                entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
+                entity_pk: Some(crate::entity_pk::EntityPk::single("entity-1")),
                 schema_key: "lix_key_value".to_string(),
                 file_id: None,
                 snapshot: Some(TransactionJson::from_value_for_test(
@@ -2274,17 +2300,21 @@ mod tests {
                 change_id: Some("change-a".to_string()),
                 commit_id: None,
                 untracked: false,
-                version_id: "version-a".to_string(),
+                branch_id: "branch-a".to_string(),
             }]
         );
     }
 
     #[test]
-    fn decodes_global_lix_state_batch_into_global_version() {
-        let rows = lix_state_write_rows_from_batch(&one_row_lix_state_batch(true), "version-a")
-            .expect("batch should decode");
+    fn decodes_global_lix_state_batch_into_global_branch() {
+        let rows = lix_state_write_rows_from_batch(
+            &one_row_lix_state_batch(true),
+            Some("branch-a"),
+            "INSERT into lix_state",
+        )
+        .expect("batch should decode");
 
-        assert_eq!(rows[0].version_id, "global");
+        assert_eq!(rows[0].branch_id, "global");
         assert!(rows[0].global);
     }
 
@@ -2292,7 +2322,7 @@ mod tests {
     async fn insert_sink_stages_decoded_lix_state_rows() {
         let mut write_context = CapturingWriteContext::default();
         let write_ctx = SqlWriteContext::new(&mut write_context);
-        let sink = LixStateInsertSink::new(lix_state_schema(), write_ctx, "version-a".to_string());
+        let sink = LixStateInsertSink::new(write_ctx, Some("branch-a".to_string()));
         let batch = one_row_lix_state_batch(false);
         let count = sink
             .write_batches(vec![batch], &Arc::new(TaskContext::default()))
@@ -2305,7 +2335,7 @@ mod tests {
             &[TransactionWrite::Rows {
                 mode: TransactionWriteMode::Insert,
                 rows: vec![TransactionWriteRow {
-                    entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
+                    entity_pk: Some(crate::entity_pk::EntityPk::single("entity-1")),
                     schema_key: "lix_key_value".to_string(),
                     file_id: None,
                     snapshot: Some(TransactionJson::from_value_for_test(
@@ -2321,7 +2351,7 @@ mod tests {
                     change_id: Some("change-a".to_string()),
                     commit_id: None,
                     untracked: false,
-                    version_id: "version-a".to_string(),
+                    branch_id: "branch-a".to_string(),
                 }]
             }]
         );
@@ -2332,7 +2362,7 @@ mod tests {
         let session = SessionContext::new();
         let mut write_context = CapturingWriteContext::default();
         let write_ctx = SqlWriteContext::new(&mut write_context);
-        let provider = LixStateProvider::active_version_with_write(write_ctx);
+        let provider = LixStateProvider::active_branch_with_write(write_ctx);
         let input = Arc::new(SingleBatchExec::new(one_row_stageable_lix_state_batch()))
             as Arc<dyn ExecutionPlan>;
 
@@ -2371,7 +2401,7 @@ mod tests {
             writes: Vec::new(),
         };
         let write_ctx = SqlWriteContext::new(&mut write_context);
-        let provider = LixStateProvider::active_version_with_write(write_ctx);
+        let provider = LixStateProvider::active_branch_with_write(write_ctx);
 
         let plan = provider
             .update(
@@ -2413,7 +2443,7 @@ mod tests {
             &[TransactionWrite::Rows {
                 mode: TransactionWriteMode::Replace,
                 rows: vec![TransactionWriteRow {
-                    entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
+                    entity_pk: Some(crate::entity_pk::EntityPk::single("entity-1")),
                     schema_key: "lix_key_value".to_string(),
                     file_id: None,
                     snapshot: Some(TransactionJson::from_value_for_test(
@@ -2429,7 +2459,7 @@ mod tests {
                     change_id: None,
                     commit_id: None,
                     untracked: false,
-                    version_id: "version-a".to_string(),
+                    branch_id: "branch-a".to_string(),
                 }]
             }]
         );
@@ -2446,7 +2476,7 @@ mod tests {
             writes: Vec::new(),
         };
         let write_ctx = SqlWriteContext::new(&mut write_context);
-        let provider = LixStateProvider::active_version_with_write(write_ctx);
+        let provider = LixStateProvider::active_branch_with_write(write_ctx);
 
         let plan = provider
             .delete_from(&session.state(), vec![])
@@ -2472,7 +2502,7 @@ mod tests {
                 mode: TransactionWriteMode::Replace,
                 rows: vec![
                     TransactionWriteRow {
-                        entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
+                        entity_pk: Some(crate::entity_pk::EntityPk::single("entity-1")),
                         schema_key: "lix_key_value".to_string(),
                         file_id: None,
                         snapshot: None,
@@ -2486,10 +2516,10 @@ mod tests {
                         change_id: None,
                         commit_id: None,
                         untracked: false,
-                        version_id: "version-a".to_string(),
+                        branch_id: "branch-a".to_string(),
                     },
                     TransactionWriteRow {
-                        entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-2")),
+                        entity_pk: Some(crate::entity_pk::EntityPk::single("entity-2")),
                         schema_key: "lix_key_value".to_string(),
                         file_id: None,
                         snapshot: None,
@@ -2503,7 +2533,7 @@ mod tests {
                         change_id: None,
                         commit_id: None,
                         untracked: false,
-                        version_id: "version-a".to_string(),
+                        branch_id: "branch-a".to_string(),
                     },
                 ]
             }]