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

package/dist-engine-src/src/sql2/lix_state_provider.rs

@@ -0,0 +1,2512 @@
+use std::any::Any;
+use std::collections::BTreeSet;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use datafusion::arrow::array::{ArrayRef, BooleanArray, StringArray, UInt64Array};
+use datafusion::arrow::compute::{and, filter_record_batch};
+use datafusion::arrow::datatypes::{DataType, Field, Schema, SchemaRef};
+use datafusion::arrow::record_batch::{RecordBatch, RecordBatchOptions};
+use datafusion::catalog::{Session, TableProvider};
+use datafusion::common::{not_impl_err, DFSchema, DataFusionError, Result, SchemaExt};
+use datafusion::datasource::TableType;
+use datafusion::execution::TaskContext;
+use datafusion::logical_expr::dml::InsertOp;
+use datafusion::logical_expr::expr::InList;
+use datafusion::logical_expr::{BinaryExpr, Expr, Operator, TableProviderFilterPushDown};
+use datafusion::physical_expr::{create_physical_expr, EquivalenceProperties, PhysicalExpr};
+use datafusion::physical_plan::execution_plan::{Boundedness, EmissionType, PlanProperties};
+use datafusion::physical_plan::stream::RecordBatchStreamAdapter;
+use datafusion::physical_plan::{
+    DisplayAs, DisplayFormatType, ExecutionPlan, Partitioning, SendableRecordBatchStream,
+};
+use datafusion::prelude::SessionContext;
+use datafusion::scalar::ScalarValue;
+use futures_util::{stream, TryStreamExt};
+use serde_json::Value as JsonValue;
+
+use crate::entity_identity::EntityIdentity;
+use crate::live_state::MaterializedLiveStateRow;
+use crate::live_state::{
+    LiveStateFilter, LiveStateProjection, LiveStateReader, LiveStateScanRequest,
+};
+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::{parse_row_metadata_value, serialize_row_metadata, LixError, NullableKeyFilter};
+
+use crate::sql2::{
+    SqlWriteContext, WriteAccess, WriteContextLiveStateReader, WriteContextVersionRefReader,
+};
+use crate::transaction::types::{TransactionWrite, TransactionWriteMode};
+
+use super::predicate_typecheck::validate_json_predicate_filters;
+use super::result_metadata::json_field;
+
+pub(crate) async fn register_lix_state_providers(
+    session: &SessionContext,
+    active_version_id: &str,
+    live_state: Arc<dyn LiveStateReader>,
+    version_ref: Arc<dyn VersionRefReader>,
+) -> Result<(), LixError> {
+    session
+        .register_table(
+            "lix_state_by_version",
+            Arc::new(LixStateProvider::by_version(
+                Arc::clone(&live_state),
+                Arc::clone(&version_ref),
+            )),
+        )
+        .map_err(datafusion_error_to_lix_error)?;
+    session
+        .register_table(
+            "lix_state",
+            Arc::new(LixStateProvider::active_version(
+                active_version_id,
+                live_state,
+                version_ref,
+            )),
+        )
+        .map_err(datafusion_error_to_lix_error)?;
+    Ok(())
+}
+
+pub(crate) async fn register_lix_state_write_providers(
+    session: &SessionContext,
+    write_ctx: SqlWriteContext,
+) -> Result<(), LixError> {
+    session
+        .register_table(
+            "lix_state_by_version",
+            Arc::new(LixStateProvider::by_version_with_write(write_ctx.clone())),
+        )
+        .map_err(datafusion_error_to_lix_error)?;
+    session
+        .register_table(
+            "lix_state",
+            Arc::new(LixStateProvider::active_version_with_write(write_ctx)),
+        )
+        .map_err(datafusion_error_to_lix_error)?;
+    Ok(())
+}
+
+pub(crate) struct LixStateProvider {
+    schema: SchemaRef,
+    live_state: Arc<dyn LiveStateReader>,
+    version_ref: Arc<dyn VersionRefReader>,
+    write_access: WriteAccess,
+    version_binding: VersionBinding,
+}
+
+impl std::fmt::Debug for LixStateProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixStateProvider")
+            .field("write_access", &self.write_access.is_write())
+            .finish()
+    }
+}
+
+impl LixStateProvider {
+    pub(crate) fn active_version(
+        active_version_id: impl Into<String>,
+        live_state: Arc<dyn LiveStateReader>,
+        version_ref: Arc<dyn VersionRefReader>,
+    ) -> Self {
+        Self {
+            schema: lix_state_schema(),
+            live_state,
+            version_ref,
+            write_access: WriteAccess::read_only(),
+            version_binding: VersionBinding::active(active_version_id),
+        }
+    }
+
+    pub(crate) fn active_version_with_write(write_ctx: SqlWriteContext) -> Self {
+        let active_version_id = write_ctx.active_version_id();
+        let live_state = Arc::new(WriteContextLiveStateReader::new(write_ctx.clone()));
+        let version_ref = Arc::new(WriteContextVersionRefReader::new(write_ctx.clone()));
+        Self {
+            schema: lix_state_schema(),
+            live_state,
+            version_ref,
+            write_access: WriteAccess::write(write_ctx),
+            version_binding: VersionBinding::active(active_version_id),
+        }
+    }
+
+    pub(crate) fn by_version(
+        live_state: Arc<dyn LiveStateReader>,
+        version_ref: Arc<dyn VersionRefReader>,
+    ) -> Self {
+        Self {
+            schema: lix_state_by_version_schema(),
+            live_state,
+            version_ref,
+            write_access: WriteAccess::read_only(),
+            version_binding: VersionBinding::explicit(),
+        }
+    }
+
+    pub(crate) fn by_version_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()));
+        Self {
+            schema: lix_state_by_version_schema(),
+            live_state,
+            version_ref,
+            write_access: WriteAccess::write(write_ctx),
+            version_binding: VersionBinding::explicit(),
+        }
+    }
+}
+
+#[async_trait]
+impl TableProvider for LixStateProvider {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn schema(&self) -> SchemaRef {
+        Arc::clone(&self.schema)
+    }
+
+    fn table_type(&self) -> TableType {
+        TableType::Base
+    }
+
+    fn supports_filters_pushdown(
+        &self,
+        filters: &[&Expr],
+    ) -> Result<Vec<TableProviderFilterPushDown>> {
+        Ok(filters
+            .iter()
+            .map(|filter| {
+                if parse_lix_state_filter(filter).is_some() {
+                    TableProviderFilterPushDown::Exact
+                } else {
+                    TableProviderFilterPushDown::Unsupported
+                }
+            })
+            .collect())
+    }
+
+    async fn scan(
+        &self,
+        _state: &dyn Session,
+        projection: Option<&Vec<usize>>,
+        filters: &[Expr],
+        limit: Option<usize>,
+    ) -> Result<Arc<dyn datafusion::physical_plan::ExecutionPlan>> {
+        let route = LixStateByVersionRoute::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(),
+            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)?;
+        }
+        Ok(Arc::new(LixStateScanExec::new(
+            Arc::clone(&self.live_state),
+            projected_schema,
+            request,
+        )))
+    }
+
+    async fn insert_into(
+        &self,
+        _state: &dyn Session,
+        input: Arc<dyn ExecutionPlan>,
+        insert_op: InsertOp,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        if insert_op != InsertOp::Append {
+            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")?;
+
+        self.schema
+            .logically_equivalent_names_and_types(&input.schema())?;
+
+        let sink = LixStateInsertSink::new(
+            Arc::clone(&self.schema),
+            write_ctx.clone(),
+            active_version_id,
+        );
+        Ok(Arc::new(InsertExec::new(input, Arc::new(sink))))
+    }
+
+    async fn delete_from(
+        &self,
+        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))?;
+        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 request =
+            lix_state_scan_request(&self.schema, Some(&active_version_id), None, &route, None);
+
+        Ok(Arc::new(LixStateDeleteExec::new(
+            write_ctx.clone(),
+            Arc::clone(&self.schema),
+            active_version_id,
+            request,
+            physical_filters,
+        )))
+    }
+
+    async fn update(
+        &self,
+        state: &dyn Session,
+        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))?;
+        validate_json_predicate_filters(self.schema.as_ref(), &filters)?;
+        let physical_assignments = assignments
+            .iter()
+            .map(|(column_name, expr)| {
+                Ok((
+                    column_name.clone(),
+                    create_physical_expr(expr, &df_schema, state.execution_props())?,
+                ))
+            })
+            .collect::<Result<Vec<_>>>()?;
+        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 request =
+            lix_state_scan_request(&self.schema, Some(&active_version_id), None, &route, None);
+
+        Ok(Arc::new(LixStateUpdateExec::new(
+            write_ctx.clone(),
+            Arc::clone(&self.schema),
+            active_version_id,
+            request,
+            physical_assignments,
+            physical_filters,
+        )))
+    }
+}
+
+struct LixStateInsertSink {
+    write_ctx: SqlWriteContext,
+    version_binding: String,
+}
+
+impl std::fmt::Debug for LixStateInsertSink {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixStateInsertSink").finish()
+    }
+}
+
+impl LixStateInsertSink {
+    fn new(_schema: SchemaRef, write_ctx: SqlWriteContext, version_binding: String) -> Self {
+        Self {
+            write_ctx,
+            version_binding,
+        }
+    }
+}
+
+impl DisplayAs for LixStateInsertSink {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => {
+                write!(f, "LixStateInsertSink")
+            }
+            DisplayFormatType::TreeRender => write!(f, "LixStateInsertSink"),
+        }
+    }
+}
+
+#[async_trait]
+impl InsertSink for LixStateInsertSink {
+    async fn write_batches(
+        &self,
+        batches: Vec<RecordBatch>,
+        _context: &Arc<TaskContext>,
+    ) -> Result<u64> {
+        let mut rows = Vec::new();
+        for batch in batches {
+            rows.extend(lix_state_write_rows_from_batch(
+                &batch,
+                &self.version_binding,
+            )?);
+        }
+        reject_read_only_stage_rows(&rows, "INSERT into lix_state")?;
+        let count = u64::try_from(rows.len())
+            .map_err(|_| DataFusionError::Execution("INSERT row count overflow".into()))?;
+
+        self.write_ctx
+            .stage_write(TransactionWrite::Rows {
+                mode: TransactionWriteMode::Insert,
+                rows,
+            })
+            .await
+            .map_err(lix_error_to_datafusion_error)?;
+
+        Ok(count)
+    }
+}
+
+#[allow(dead_code)]
+struct LixStateDeleteExec {
+    write_ctx: SqlWriteContext,
+    table_schema: SchemaRef,
+    version_binding: String,
+    request: LiveStateScanRequest,
+    filters: Vec<Arc<dyn PhysicalExpr>>,
+    result_schema: SchemaRef,
+    properties: Arc<PlanProperties>,
+}
+
+impl std::fmt::Debug for LixStateDeleteExec {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixStateDeleteExec").finish()
+    }
+}
+
+impl LixStateDeleteExec {
+    fn new(
+        write_ctx: SqlWriteContext,
+        table_schema: SchemaRef,
+        version_binding: String,
+        request: LiveStateScanRequest,
+        filters: Vec<Arc<dyn PhysicalExpr>>,
+    ) -> Self {
+        let result_schema = dml_count_schema();
+        let properties = PlanProperties::new(
+            EquivalenceProperties::new(Arc::clone(&result_schema)),
+            Partitioning::UnknownPartitioning(1),
+            EmissionType::Final,
+            Boundedness::Bounded,
+        );
+        Self {
+            write_ctx,
+            table_schema,
+            version_binding,
+            request,
+            filters,
+            result_schema,
+            properties: Arc::new(properties),
+        }
+    }
+}
+
+impl DisplayAs for LixStateDeleteExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => {
+                write!(f, "LixStateDeleteExec(filters={})", self.filters.len())
+            }
+            DisplayFormatType::TreeRender => write!(f, "LixStateDeleteExec"),
+        }
+    }
+}
+
+impl ExecutionPlan for LixStateDeleteExec {
+    fn name(&self) -> &str {
+        "LixStateDeleteExec"
+    }
+
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.properties
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        Vec::new()
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        if !children.is_empty() {
+            return Err(DataFusionError::Execution(
+                "LixStateDeleteExec does not accept children".to_string(),
+            ));
+        }
+        Ok(self)
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        _context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        if partition != 0 {
+            return Err(DataFusionError::Execution(format!(
+                "LixStateDeleteExec only exposes one partition, got {partition}"
+            )));
+        }
+        let write_ctx = self.write_ctx.clone();
+        let table_schema = Arc::clone(&self.table_schema);
+        let version_binding = self.version_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 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)?;
+            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()))?;
+
+            if count > 0 {
+                write_ctx
+                    .stage_write(TransactionWrite::Rows {
+                        mode: TransactionWriteMode::Replace,
+                        rows: write_rows,
+                    })
+                    .await
+                    .map_err(lix_error_to_datafusion_error)?;
+            }
+
+            Ok::<_, DataFusionError>(stream::iter(vec![Ok::<RecordBatch, DataFusionError>(
+                dml_count_batch(Arc::clone(&stream_schema), count)?,
+            )]))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            result_schema,
+            stream,
+        )))
+    }
+}
+
+#[allow(dead_code)]
+struct LixStateUpdateExec {
+    write_ctx: SqlWriteContext,
+    table_schema: SchemaRef,
+    version_binding: String,
+    request: LiveStateScanRequest,
+    assignments: Vec<(String, Arc<dyn PhysicalExpr>)>,
+    filters: Vec<Arc<dyn PhysicalExpr>>,
+    result_schema: SchemaRef,
+    properties: Arc<PlanProperties>,
+}
+
+impl std::fmt::Debug for LixStateUpdateExec {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixStateUpdateExec").finish()
+    }
+}
+
+impl LixStateUpdateExec {
+    fn new(
+        write_ctx: SqlWriteContext,
+        table_schema: SchemaRef,
+        version_binding: String,
+        request: LiveStateScanRequest,
+        assignments: Vec<(String, Arc<dyn PhysicalExpr>)>,
+        filters: Vec<Arc<dyn PhysicalExpr>>,
+    ) -> Self {
+        let result_schema = dml_count_schema();
+        let properties = PlanProperties::new(
+            EquivalenceProperties::new(Arc::clone(&result_schema)),
+            Partitioning::UnknownPartitioning(1),
+            EmissionType::Final,
+            Boundedness::Bounded,
+        );
+        Self {
+            write_ctx,
+            table_schema,
+            version_binding,
+            request,
+            assignments,
+            filters,
+            result_schema,
+            properties: Arc::new(properties),
+        }
+    }
+}
+
+impl DisplayAs for LixStateUpdateExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => {
+                write!(
+                    f,
+                    "LixStateUpdateExec(assignments={}, filters={})",
+                    self.assignments.len(),
+                    self.filters.len()
+                )
+            }
+            DisplayFormatType::TreeRender => write!(f, "LixStateUpdateExec"),
+        }
+    }
+}
+
+impl ExecutionPlan for LixStateUpdateExec {
+    fn name(&self) -> &str {
+        "LixStateUpdateExec"
+    }
+
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.properties
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        Vec::new()
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        if !children.is_empty() {
+            return Err(DataFusionError::Execution(
+                "LixStateUpdateExec does not accept children".to_string(),
+            ));
+        }
+        Ok(self)
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        _context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        if partition != 0 {
+            return Err(DataFusionError::Execution(format!(
+                "LixStateUpdateExec only exposes one partition, got {partition}"
+            )));
+        }
+        let write_ctx = self.write_ctx.clone();
+        let table_schema = Arc::clone(&self.table_schema);
+        let version_binding = self.version_binding.clone();
+        let request = self.request.clone();
+        let assignments = self.assignments.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 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,
+            )?;
+            reject_read_only_stage_rows(&write_rows, "UPDATE lix_state")?;
+            let count = u64::try_from(write_rows.len())
+                .map_err(|_| DataFusionError::Execution("UPDATE row count overflow".to_string()))?;
+
+            if count > 0 {
+                write_ctx
+                    .stage_write(TransactionWrite::Rows {
+                        mode: TransactionWriteMode::Replace,
+                        rows: write_rows,
+                    })
+                    .await
+                    .map_err(lix_error_to_datafusion_error)?;
+            }
+
+            Ok::<_, DataFusionError>(stream::iter(vec![Ok::<RecordBatch, DataFusionError>(
+                dml_count_batch(Arc::clone(&stream_schema), count)?,
+            )]))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            result_schema,
+            stream,
+        )))
+    }
+}
+
+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>],
+) -> Result<RecordBatch> {
+    let Some(mask) = evaluate_lix_state_filters(&batch, filters)? else {
+        return Ok(batch);
+    };
+    Ok(filter_record_batch(&batch, &mask)?)
+}
+
+fn evaluate_lix_state_filters(
+    batch: &RecordBatch,
+    filters: &[Arc<dyn PhysicalExpr>],
+) -> Result<Option<BooleanArray>> {
+    if filters.is_empty() {
+        return Ok(None);
+    }
+
+    let mut combined_mask: Option<BooleanArray> = None;
+    for filter in filters {
+        let result = filter.evaluate(batch)?;
+        let array = result.into_array(batch.num_rows())?;
+        let bool_array = array
+            .as_any()
+            .downcast_ref::<BooleanArray>()
+            .ok_or_else(|| {
+                DataFusionError::Execution("UPDATE lix_state filter was not boolean".to_string())
+            })?;
+        let normalized = bool_array
+            .iter()
+            .map(|value| Some(value == Some(true)))
+            .collect::<BooleanArray>();
+        combined_mask = Some(match combined_mask {
+            Some(existing) => and(&existing, &normalized)?,
+            None => normalized,
+        });
+    }
+    Ok(combined_mask)
+}
+
+fn lix_state_stageable_write_rows_from_batch(
+    batch: &RecordBatch,
+    version_binding: &str,
+) -> Result<Vec<TransactionWriteRow>> {
+    let mut rows = lix_state_write_rows_from_batch(batch, version_binding)?;
+    for row in &mut rows {
+        row.created_at = None;
+        row.updated_at = None;
+        row.change_id = None;
+        row.commit_id = None;
+    }
+    Ok(rows)
+}
+
+fn lix_state_update_write_rows_from_batch(
+    batch: &RecordBatch,
+    assignments: &[(String, Arc<dyn PhysicalExpr>)],
+    version_binding: &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(|| {
+                    if global {
+                        GLOBAL_VERSION_ID.to_string()
+                    } else {
+                        version_binding.to_string()
+                    }
+                });
+
+            Ok(TransactionWriteRow {
+                entity_id: Some(
+                    EntityIdentity::from_json_array_text(&required_string_value(
+                        batch,
+                        row_index,
+                        "entity_id",
+                    )?)
+                    .map_err(|error| {
+                        DataFusionError::Execution(format!(
+                            "lix_state UPDATE has invalid entity_id: {error}"
+                        ))
+                    })?,
+                ),
+                schema_key: required_string_value(batch, row_index, "schema_key")?,
+                file_id: optional_string_value(batch, row_index, "file_id")?,
+                snapshot: update_optional_json_value(
+                    batch,
+                    &assignment_values,
+                    row_index,
+                    "snapshot_content",
+                )?,
+                metadata: update_optional_metadata_value(
+                    batch,
+                    &assignment_values,
+                    row_index,
+                    "metadata",
+                    "lix_state",
+                )?,
+                origin: None,
+                created_at: None,
+                updated_at: None,
+                global,
+                change_id: None,
+                commit_id: None,
+                untracked: optional_bool_value(batch, row_index, "untracked")?.unwrap_or(false),
+                version_id,
+            })
+        })
+        .collect()
+}
+
+fn lix_state_deletable_write_rows_from_batch(
+    batch: &RecordBatch,
+    version_binding: &str,
+) -> Result<Vec<TransactionWriteRow>> {
+    let mut rows = lix_state_stageable_write_rows_from_batch(batch, version_binding)?;
+    for row in &mut rows {
+        row.snapshot = None;
+    }
+    Ok(rows)
+}
+
+fn update_optional_string_value(
+    batch: &RecordBatch,
+    assignment_values: &UpdateAssignmentValues,
+    row_index: usize,
+    column_name: &str,
+) -> Result<Option<String>> {
+    match assignment_values.assigned_or_existing_cell(batch, row_index, column_name)? {
+        InsertCell::Omitted | InsertCell::Provided(SqlCell::Null) => Ok(None),
+        InsertCell::Provided(SqlCell::Value(
+            ScalarValue::Utf8(Some(value))
+            | ScalarValue::Utf8View(Some(value))
+            | ScalarValue::LargeUtf8(Some(value)),
+        )) => Ok(Some(value)),
+        InsertCell::Provided(SqlCell::Value(other)) => Err(DataFusionError::Execution(format!(
+            "UPDATE lix_state expected text-compatible column '{column_name}', got {other:?}"
+        ))),
+    }
+}
+
+fn update_optional_metadata_value(
+    batch: &RecordBatch,
+    assignment_values: &UpdateAssignmentValues,
+    row_index: usize,
+    column_name: &str,
+    context: &str,
+) -> Result<Option<TransactionJson>> {
+    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)?;
+            TransactionJson::from_value(metadata, &format!("{context} metadata"))
+                .map_err(super::error::lix_error_to_datafusion_error)
+        })
+        .transpose()
+}
+
+fn update_optional_json_value(
+    batch: &RecordBatch,
+    assignment_values: &UpdateAssignmentValues,
+    row_index: usize,
+    column_name: &str,
+) -> Result<Option<TransactionJson>> {
+    update_optional_string_value(batch, assignment_values, row_index, column_name)?
+        .map(|value| parse_snapshot_json(&value, column_name))
+        .transpose()
+}
+
+fn dml_count_schema() -> SchemaRef {
+    Arc::new(Schema::new(vec![Field::new(
+        "count",
+        DataType::UInt64,
+        false,
+    )]))
+}
+
+fn dml_count_batch(schema: SchemaRef, count: u64) -> Result<RecordBatch> {
+    RecordBatch::try_new(
+        schema,
+        vec![Arc::new(UInt64Array::from(vec![count])) as ArrayRef],
+    )
+    .map_err(DataFusionError::from)
+}
+
+fn lix_state_write_rows_from_batch(
+    batch: &RecordBatch,
+    version_binding: &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(|| {
+                    if global {
+                        GLOBAL_VERSION_ID.to_string()
+                    } else {
+                        version_binding.to_string()
+                    }
+                });
+
+            Ok(TransactionWriteRow {
+                entity_id: Some(
+                    EntityIdentity::from_json_array_text(&required_string_value(
+                        batch,
+                        row_index,
+                        "entity_id",
+                    )?)
+                    .map_err(|error| {
+                        DataFusionError::Execution(format!(
+                            "lix_state INSERT has invalid entity_id: {error}"
+                        ))
+                    })?,
+                ),
+                schema_key: required_string_value(batch, row_index, "schema_key")?,
+                file_id: optional_string_value(batch, row_index, "file_id")?,
+                snapshot: optional_json_value(batch, row_index, "snapshot_content")?,
+                metadata: optional_metadata_value(batch, row_index, "metadata", "lix_state")?,
+                origin: None,
+                created_at: optional_string_value(batch, row_index, "created_at")?,
+                updated_at: optional_string_value(batch, row_index, "updated_at")?,
+                global,
+                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,
+            })
+        })
+        .collect()
+}
+
+fn required_string_value(
+    batch: &RecordBatch,
+    row_index: usize,
+    column_name: &str,
+) -> Result<String> {
+    optional_string_value(batch, row_index, column_name)?.ok_or_else(|| {
+        DataFusionError::Execution(format!(
+            "INSERT into lix_state requires non-null text column '{column_name}'"
+        ))
+    })
+}
+
+fn optional_string_value(
+    batch: &RecordBatch,
+    row_index: usize,
+    column_name: &str,
+) -> Result<Option<String>> {
+    match optional_scalar_value(batch, row_index, column_name)? {
+        None
+        | Some(ScalarValue::Null)
+        | Some(ScalarValue::Utf8(None))
+        | Some(ScalarValue::Utf8View(None))
+        | Some(ScalarValue::LargeUtf8(None)) => Ok(None),
+        Some(ScalarValue::Utf8(Some(value)))
+        | Some(ScalarValue::Utf8View(Some(value)))
+        | Some(ScalarValue::LargeUtf8(Some(value))) => Ok(Some(value)),
+        Some(other) => Err(DataFusionError::Execution(format!(
+            "INSERT into lix_state expected text-compatible column '{column_name}', got {other:?}"
+        ))),
+    }
+}
+
+fn optional_metadata_value(
+    batch: &RecordBatch,
+    row_index: usize,
+    column_name: &str,
+    context: &str,
+) -> Result<Option<TransactionJson>> {
+    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)?;
+            TransactionJson::from_value(metadata, &format!("{context} metadata"))
+                .map_err(super::error::lix_error_to_datafusion_error)
+        })
+        .transpose()
+}
+
+fn optional_json_value(
+    batch: &RecordBatch,
+    row_index: usize,
+    column_name: &str,
+) -> Result<Option<TransactionJson>> {
+    optional_string_value(batch, row_index, column_name)?
+        .map(|value| parse_snapshot_json(&value, column_name))
+        .transpose()
+}
+
+fn parse_snapshot_json(value: &str, column_name: &str) -> Result<TransactionJson> {
+    let parsed = serde_json::from_str::<JsonValue>(value).map_err(|error| {
+        DataFusionError::Execution(format!(
+            "lix_state expected valid JSON in column '{column_name}': {error}"
+        ))
+    })?;
+    TransactionJson::from_value(parsed, &format!("lix_state {column_name}"))
+        .map_err(super::error::lix_error_to_datafusion_error)
+}
+
+fn optional_bool_value(
+    batch: &RecordBatch,
+    row_index: usize,
+    column_name: &str,
+) -> Result<Option<bool>> {
+    match optional_scalar_value(batch, row_index, column_name)? {
+        Some(ScalarValue::Boolean(Some(value))) => Ok(Some(value)),
+        None | Some(ScalarValue::Null) | Some(ScalarValue::Boolean(None)) => Ok(None),
+        Some(other) => Err(DataFusionError::Execution(format!(
+            "INSERT into lix_state expected boolean column '{column_name}', got {other:?}"
+        ))),
+    }
+}
+
+fn optional_scalar_value(
+    batch: &RecordBatch,
+    row_index: usize,
+    column_name: &str,
+) -> Result<Option<ScalarValue>> {
+    let schema = batch.schema();
+    let column_index = match schema.index_of(column_name) {
+        Ok(column_index) => column_index,
+        Err(_) => return Ok(None),
+    };
+
+    if row_index >= batch.num_rows() {
+        return Err(DataFusionError::Execution(format!(
+            "row index {row_index} out of bounds for lix_state batch with {} rows",
+            batch.num_rows()
+        )));
+    }
+
+    ScalarValue::try_from_array(batch.column(column_index).as_ref(), row_index)
+        .map(Some)
+        .map_err(|error| {
+            DataFusionError::Execution(format!(
+                "failed to decode lix_state column '{column_name}' at row {row_index}: {error}"
+            ))
+        })
+}
+
+struct LixStateScanExec {
+    live_state: Arc<dyn LiveStateReader>,
+    schema: SchemaRef,
+    request: LiveStateScanRequest,
+    properties: Arc<PlanProperties>,
+}
+
+impl std::fmt::Debug for LixStateScanExec {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixStateScanExec").finish()
+    }
+}
+
+impl LixStateScanExec {
+    fn new(
+        live_state: Arc<dyn LiveStateReader>,
+        schema: SchemaRef,
+        request: LiveStateScanRequest,
+    ) -> Self {
+        let properties = PlanProperties::new(
+            EquivalenceProperties::new(schema.clone()),
+            Partitioning::UnknownPartitioning(1),
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        );
+        Self {
+            live_state,
+            schema,
+            request,
+            properties: Arc::new(properties),
+        }
+    }
+}
+
+impl DisplayAs for LixStateScanExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => {
+                write!(f, "LixStateScanExec(limit={:?})", self.request.limit)
+            }
+            DisplayFormatType::TreeRender => write!(f, "LixStateScanExec"),
+        }
+    }
+}
+
+impl ExecutionPlan for LixStateScanExec {
+    fn name(&self) -> &str {
+        "LixStateScanExec"
+    }
+
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.properties
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        Vec::new()
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        if !children.is_empty() {
+            return Err(DataFusionError::Execution(
+                "LixStateScanExec does not accept children".to_string(),
+            ));
+        }
+        Ok(self)
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        _context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        if partition != 0 {
+            return Err(DataFusionError::Execution(format!(
+                "LixStateScanExec only exposes one partition, got {partition}"
+            )));
+        }
+
+        let live_state = Arc::clone(&self.live_state);
+        let schema = Arc::clone(&self.schema);
+        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 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>(
+                batch,
+            )]))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(schema, stream)))
+    }
+}
+
+fn lix_state_schema() -> SchemaRef {
+    Arc::new(Schema::new(vec![
+        json_field("entity_id", false),
+        Field::new("schema_key", DataType::Utf8, false),
+        Field::new("file_id", DataType::Utf8, true),
+        json_field("snapshot_content", true),
+        json_field("metadata", true),
+        Field::new("created_at", DataType::Utf8, true),
+        Field::new("updated_at", DataType::Utf8, true),
+        Field::new("global", DataType::Boolean, true),
+        Field::new("change_id", DataType::Utf8, true),
+        Field::new("commit_id", DataType::Utf8, true),
+        Field::new("untracked", DataType::Boolean, true),
+    ]))
+}
+
+fn lix_state_by_version_schema() -> SchemaRef {
+    Arc::new(Schema::new(vec![
+        json_field("entity_id", false),
+        Field::new("schema_key", DataType::Utf8, false),
+        Field::new("file_id", DataType::Utf8, true),
+        json_field("snapshot_content", true),
+        json_field("metadata", true),
+        Field::new("created_at", DataType::Utf8, true),
+        Field::new("updated_at", DataType::Utf8, true),
+        Field::new("global", DataType::Boolean, true),
+        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),
+    ]))
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+struct LixStateByVersionRoute {
+    schema_keys: Option<BTreeSet<String>>,
+    version_ids: Option<BTreeSet<String>>,
+    entity_ids: Option<BTreeSet<String>>,
+    file_id: Option<NullableKeyFilter<String>>,
+    contradictory: bool,
+}
+
+impl LixStateByVersionRoute {
+    fn from_filters(filters: &[Expr]) -> Self {
+        let mut route = Self::default();
+        for filter in filters {
+            let Some(predicates) = parse_lix_state_filters(filter) else {
+                continue;
+            };
+            for predicate in predicates {
+                match predicate {
+                    LixStateFilterPredicate::SchemaKeys(values) => {
+                        merge_string_route_slot(
+                            &mut route.schema_keys,
+                            values,
+                            &mut route.contradictory,
+                        );
+                    }
+                    LixStateFilterPredicate::VersionIds(values) => {
+                        merge_string_route_slot(
+                            &mut route.version_ids,
+                            values,
+                            &mut route.contradictory,
+                        );
+                    }
+                    LixStateFilterPredicate::EntityIds(values) => {
+                        merge_string_route_slot(
+                            &mut route.entity_ids,
+                            values,
+                            &mut route.contradictory,
+                        );
+                    }
+                    LixStateFilterPredicate::FileId(filter) => {
+                        merge_nullable_key_route_slot(
+                            &mut route.file_id,
+                            filter,
+                            &mut route.contradictory,
+                        );
+                    }
+                }
+            }
+        }
+        route
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum LixStateFilterPredicate {
+    SchemaKeys(BTreeSet<String>),
+    VersionIds(BTreeSet<String>),
+    EntityIds(BTreeSet<String>),
+    FileId(NullableKeyFilter<String>),
+}
+
+fn lix_state_scan_request(
+    schema: &SchemaRef,
+    version_binding: Option<&str>,
+    projection: Option<&Vec<usize>>,
+    route: &LixStateByVersionRoute,
+    limit: Option<usize>,
+) -> LiveStateScanRequest {
+    let projection = LiveStateProjection {
+        columns: projection_column_names(schema, projection),
+    };
+    let mut filter = LiveStateFilter {
+        schema_keys: route
+            .schema_keys
+            .as_ref()
+            .map(|values| values.iter().cloned().collect())
+            .unwrap_or_default(),
+        entity_ids: route
+            .entity_ids
+            .as_ref()
+            .map(|values| {
+                values
+                    .iter()
+                    .filter_map(|value| EntityIdentity::from_json_array_text(value).ok())
+                    .collect()
+            })
+            .unwrap_or_default(),
+        version_ids: version_binding
+            .map(|value| vec![value.to_string()])
+            .or_else(|| {
+                route
+                    .version_ids
+                    .as_ref()
+                    .map(|values| values.iter().cloned().collect())
+            })
+            .unwrap_or_default(),
+        ..LiveStateFilter::default()
+    };
+    if let Some(file_id) = route.file_id.clone() {
+        filter.file_ids.push(file_id);
+    }
+
+    LiveStateScanRequest {
+        filter,
+        projection,
+        limit: route.contradictory.then_some(0).or(limit),
+    }
+}
+
+fn projection_column_names(schema: &SchemaRef, projection: Option<&Vec<usize>>) -> Vec<String> {
+    projection
+        .map(|indices| {
+            indices
+                .iter()
+                .filter_map(|index| schema.fields().get(*index))
+                .map(|field| field.name().to_string())
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default()
+}
+
+fn merge_string_route_slot(
+    slot: &mut Option<BTreeSet<String>>,
+    values: BTreeSet<String>,
+    contradictory: &mut bool,
+) {
+    if values.is_empty() {
+        return;
+    }
+
+    match slot {
+        Some(existing) => {
+            existing.retain(|value| values.contains(value));
+            if existing.is_empty() {
+                *contradictory = true;
+            }
+        }
+        None => *slot = Some(values),
+    }
+}
+
+fn merge_nullable_key_route_slot(
+    slot: &mut Option<NullableKeyFilter<String>>,
+    value: NullableKeyFilter<String>,
+    contradictory: &mut bool,
+) {
+    match slot {
+        Some(existing) if *existing != value => *contradictory = true,
+        Some(_) => {}
+        None => *slot = Some(value),
+    }
+}
+
+fn parse_lix_state_filter(expr: &Expr) -> Option<LixStateFilterPredicate> {
+    parse_lix_state_filters(expr)?.into_iter().next()
+}
+
+fn parse_lix_state_filters(expr: &Expr) -> Option<Vec<LixStateFilterPredicate>> {
+    match expr {
+        Expr::BinaryExpr(binary_expr) if binary_expr.op == Operator::And => {
+            let mut predicates = parse_lix_state_filters(&binary_expr.left)?;
+            predicates.extend(parse_lix_state_filters(&binary_expr.right)?);
+            Some(predicates)
+        }
+        Expr::BinaryExpr(binary_expr) => {
+            parse_lix_state_binary_filter(binary_expr).map(|predicate| vec![predicate])
+        }
+        Expr::InList(in_list) => {
+            parse_lix_state_in_list_filter(in_list).map(|predicate| vec![predicate])
+        }
+        Expr::IsNull(expr) => parse_lix_state_null_filter(expr).map(|predicate| vec![predicate]),
+        _ => None,
+    }
+}
+
+fn parse_lix_state_binary_filter(binary_expr: &BinaryExpr) -> Option<LixStateFilterPredicate> {
+    if binary_expr.op != Operator::Eq {
+        return None;
+    }
+
+    parse_lix_state_column_literal_filter(&binary_expr.left, &binary_expr.right)
+        .or_else(|| parse_lix_state_column_literal_filter(&binary_expr.right, &binary_expr.left))
+}
+
+fn parse_lix_state_in_list_filter(in_list: &InList) -> Option<LixStateFilterPredicate> {
+    if in_list.negated {
+        return None;
+    }
+    let Expr::Column(column) = in_list.expr.as_ref() else {
+        return None;
+    };
+
+    let values = in_list
+        .list
+        .iter()
+        .map(string_expr_literal)
+        .collect::<Option<Vec<_>>>()?;
+    if values.is_empty() {
+        return None;
+    }
+
+    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),
+        _ => None,
+    }
+}
+
+fn parse_lix_state_null_filter(expr: &Expr) -> Option<LixStateFilterPredicate> {
+    let Expr::Column(column) = expr else {
+        return None;
+    };
+
+    match column.name.as_str() {
+        "file_id" => Some(LixStateFilterPredicate::FileId(NullableKeyFilter::Null)),
+        _ => None,
+    }
+}
+
+fn parse_lix_state_column_literal_filter(
+    column_expr: &Expr,
+    literal_expr: &Expr,
+) -> Option<LixStateFilterPredicate> {
+    let Expr::Column(column) = column_expr else {
+        return None;
+    };
+
+    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]))),
+        "file_id" => nullable_key_literal(literal_expr).map(LixStateFilterPredicate::FileId),
+        _ => None,
+    }
+}
+
+fn canonical_entity_id_values(values: BTreeSet<String>) -> Option<BTreeSet<String>> {
+    values
+        .into_iter()
+        .map(|value| canonical_entity_id_value(&value))
+        .collect()
+}
+
+fn canonical_entity_id_value(value: &str) -> Option<String> {
+    EntityIdentity::from_json_array_text(value)
+        .ok()?
+        .as_json_array_text()
+        .ok()
+}
+
+fn nullable_key_literal(expr: &Expr) -> Option<NullableKeyFilter<String>> {
+    if is_null_literal(expr) {
+        return Some(NullableKeyFilter::Null);
+    }
+    string_expr_literal(expr).map(NullableKeyFilter::Value)
+}
+
+fn string_expr_literal(expr: &Expr) -> Option<String> {
+    let Expr::Literal(literal, _) = expr else {
+        return None;
+    };
+    match literal {
+        ScalarValue::Utf8(Some(value))
+        | ScalarValue::Utf8View(Some(value))
+        | ScalarValue::LargeUtf8(Some(value)) => Some(value.clone()),
+        _ => None,
+    }
+}
+
+fn is_null_literal(expr: &Expr) -> bool {
+    matches!(expr, Expr::Literal(ScalarValue::Null, _))
+}
+
+fn lix_state_record_batch(
+    schema: SchemaRef,
+    rows: &[MaterializedLiveStateRow],
+) -> Result<RecordBatch, LixError> {
+    if schema.fields().is_empty() {
+        let options = RecordBatchOptions::new().with_row_count(Some(rows.len()));
+        return RecordBatch::try_new_with_options(schema, vec![], &options).map_err(|error| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("sql2 failed to build zero-column lix_state batch: {error}"),
+            )
+        });
+    }
+
+    let columns = schema
+        .fields()
+        .iter()
+        .map(|field| {
+            Ok(match field.name().as_str() {
+                "entity_id" => Arc::new(StringArray::from(
+                    rows.iter()
+                        .map(|row| row.entity_id.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()))),
+                "file_id" => string_array(rows.iter().map(|row| row.file_id.as_deref())),
+                "snapshot_content" => {
+                    string_array(rows.iter().map(|row| row.snapshot_content.as_deref()))
+                }
+                "metadata" => Arc::new(StringArray::from(
+                    rows.iter()
+                        .map(|row| row.metadata.as_ref().map(serialize_row_metadata))
+                        .collect::<Vec<_>>(),
+                )),
+                "created_at" => string_array(rows.iter().map(|row| Some(row.created_at.as_str()))),
+                "updated_at" => string_array(rows.iter().map(|row| Some(row.updated_at.as_str()))),
+                "global" => Arc::new(BooleanArray::from(
+                    rows.iter().map(|row| row.global).collect::<Vec<_>>(),
+                )) as ArrayRef,
+                "change_id" => string_array(rows.iter().map(|row| row.change_id.as_deref())),
+                "commit_id" => string_array(rows.iter().map(|row| row.commit_id.as_deref())),
+                "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()))),
+                other => {
+                    return Err(LixError::new(
+                        "LIX_ERROR_UNKNOWN",
+                        format!("sql2 does not support lix_state column '{other}'"),
+                    ))
+                }
+            })
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+
+    RecordBatch::try_new(schema, columns).map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("sql2 failed to build lix_state_by_version batch: {error}"),
+        )
+    })
+}
+
+fn string_array<'a>(values: impl Iterator<Item = Option<&'a str>>) -> ArrayRef {
+    let values = values
+        .map(|value| value.map(ToOwned::to_owned))
+        .collect::<Vec<_>>();
+    Arc::new(StringArray::from(values)) as ArrayRef
+}
+
+fn projected_schema(schema: &SchemaRef, projection: Option<&Vec<usize>>) -> Result<SchemaRef> {
+    let Some(projection) = projection else {
+        return Ok(Arc::clone(schema));
+    };
+
+    let projected = schema.project(projection).map_err(|error| {
+        DataFusionError::Execution(format!("sql2 failed to project lix_state schema: {error}"))
+    })?;
+    Ok(Arc::new(projected))
+}
+
+fn datafusion_error_to_lix_error(error: DataFusionError) -> LixError {
+    super::error::datafusion_error_to_lix_error(error)
+}
+
+fn lix_error_to_datafusion_error(error: LixError) -> DataFusionError {
+    super::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,
+    };
+    use crate::binary_cas::BlobDataReader;
+    use crate::functions::{
+        FunctionProvider, FunctionProviderHandle, SharedFunctionProvider, SystemFunctionProvider,
+    };
+    use crate::sql2::dml::{InsertExec, InsertSink};
+    use crate::sql2::{SqlWriteContext, SqlWriteExecutionContext};
+    use crate::transaction::types::{
+        TransactionJson, TransactionWrite, TransactionWriteMode, TransactionWriteOutcome,
+        TransactionWriteRow,
+    };
+    use crate::version::{VersionHead, VersionRefReader};
+    use crate::{
+        entity_identity::EntityIdentity,
+        live_state::{
+            LiveStateReader, LiveStateRowRequest, LiveStateScanRequest, MaterializedLiveStateRow,
+        },
+    };
+    use crate::{LixError, NullableKeyFilter};
+    use async_trait::async_trait;
+    use datafusion::arrow::array::{ArrayRef, BooleanArray, StringArray, UInt64Array};
+    use datafusion::arrow::datatypes::DataType;
+    use datafusion::arrow::record_batch::RecordBatch;
+    use datafusion::catalog::TableProvider;
+    use datafusion::common::{Column, DataFusionError};
+    use datafusion::execution::TaskContext;
+    use datafusion::logical_expr::dml::InsertOp;
+    use datafusion::logical_expr::expr::InList;
+    use datafusion::logical_expr::{BinaryExpr, Expr, Operator};
+    use datafusion::physical_expr::EquivalenceProperties;
+    use datafusion::physical_plan::empty::EmptyExec;
+    use datafusion::physical_plan::execution_plan::{Boundedness, EmissionType, PlanProperties};
+    use datafusion::physical_plan::stream::RecordBatchStreamAdapter;
+    use datafusion::physical_plan::{
+        DisplayAs, DisplayFormatType, ExecutionPlan, Partitioning, SendableRecordBatchStream,
+    };
+    use datafusion::prelude::SessionContext;
+    use datafusion::scalar::ScalarValue;
+    use futures_util::stream;
+    use serde_json::json;
+    use std::collections::BTreeSet;
+    use std::sync::Arc;
+
+    struct EmptyLiveStateReader;
+    struct EmptyVersionRefReader;
+    #[allow(dead_code)]
+    struct RowsLiveStateReader {
+        rows: Vec<MaterializedLiveStateRow>,
+    }
+    struct DummyBlobReader;
+
+    #[derive(Default)]
+    struct DummyWriteContext {
+        rows: Vec<MaterializedLiveStateRow>,
+    }
+
+    #[derive(Default)]
+    struct CapturingWriteContext {
+        rows: Vec<MaterializedLiveStateRow>,
+        writes: Vec<TransactionWrite>,
+    }
+
+    struct SingleBatchExec {
+        batch: RecordBatch,
+        properties: Arc<PlanProperties>,
+    }
+
+    impl std::fmt::Debug for SingleBatchExec {
+        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+            f.debug_struct("SingleBatchExec").finish()
+        }
+    }
+
+    impl SingleBatchExec {
+        fn new(batch: RecordBatch) -> Self {
+            let properties = PlanProperties::new(
+                EquivalenceProperties::new(batch.schema()),
+                Partitioning::UnknownPartitioning(1),
+                EmissionType::Incremental,
+                Boundedness::Bounded,
+            );
+            Self {
+                batch,
+                properties: Arc::new(properties),
+            }
+        }
+    }
+
+    impl DisplayAs for SingleBatchExec {
+        fn fmt_as(
+            &self,
+            _t: DisplayFormatType,
+            f: &mut std::fmt::Formatter<'_>,
+        ) -> std::fmt::Result {
+            write!(f, "SingleBatchExec")
+        }
+    }
+
+    impl ExecutionPlan for SingleBatchExec {
+        fn name(&self) -> &str {
+            "SingleBatchExec"
+        }
+
+        fn as_any(&self) -> &dyn std::any::Any {
+            self
+        }
+
+        fn properties(&self) -> &Arc<PlanProperties> {
+            &self.properties
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+            Vec::new()
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            children: Vec<Arc<dyn ExecutionPlan>>,
+        ) -> datafusion::common::Result<Arc<dyn ExecutionPlan>> {
+            if !children.is_empty() {
+                return Err(DataFusionError::Execution(
+                    "SingleBatchExec does not accept children".to_string(),
+                ));
+            }
+            Ok(self)
+        }
+
+        fn execute(
+            &self,
+            partition: usize,
+            _context: Arc<TaskContext>,
+        ) -> datafusion::common::Result<SendableRecordBatchStream> {
+            if partition != 0 {
+                return Err(DataFusionError::Execution(format!(
+                    "SingleBatchExec only exposes one partition, got {partition}"
+                )));
+            }
+
+            let batch = self.batch.clone();
+            let schema = batch.schema();
+            let stream = stream::iter(vec![Ok(batch)]);
+            Ok(Box::pin(RecordBatchStreamAdapter::new(schema, stream)))
+        }
+    }
+
+    #[async_trait]
+    impl LiveStateReader for EmptyLiveStateReader {
+        async fn scan_rows(
+            &self,
+            _request: &LiveStateScanRequest,
+        ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
+            Ok(vec![])
+        }
+
+        async fn load_row(
+            &self,
+            _request: &LiveStateRowRequest,
+        ) -> Result<Option<MaterializedLiveStateRow>, LixError> {
+            Ok(None)
+        }
+    }
+
+    #[async_trait]
+    impl VersionRefReader for EmptyVersionRefReader {
+        async fn load_head(&self, _version_id: &str) -> Result<Option<VersionHead>, LixError> {
+            Ok(None)
+        }
+
+        async fn scan_heads(&self) -> Result<Vec<VersionHead>, 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 test_functions() -> FunctionProviderHandle {
+        SharedFunctionProvider::new(
+            Box::new(SystemFunctionProvider) as Box<dyn FunctionProvider + Send>
+        )
+    }
+
+    #[async_trait]
+    impl BlobDataReader for DummyBlobReader {
+        async fn load_bytes_many(
+            &self,
+            hashes: &[crate::binary_cas::BlobHash],
+        ) -> Result<crate::binary_cas::BlobBytesBatch, LixError> {
+            Ok(crate::binary_cas::BlobBytesBatch::new(vec![
+                None;
+                hashes.len()
+            ]))
+        }
+    }
+
+    #[async_trait]
+    impl SqlWriteExecutionContext for DummyWriteContext {
+        fn active_version_id(&self) -> &str {
+            "version-a"
+        }
+
+        fn functions(&self) -> FunctionProviderHandle {
+            test_functions()
+        }
+
+        fn list_visible_schemas(&self) -> Result<Vec<serde_json::Value>, LixError> {
+            Ok(Vec::new())
+        }
+
+        async fn load_bytes_many(
+            &mut self,
+            hashes: &[crate::binary_cas::BlobHash],
+        ) -> Result<crate::binary_cas::BlobBytesBatch, LixError> {
+            DummyBlobReader.load_bytes_many(hashes).await
+        }
+
+        async fn scan_live_state(
+            &mut self,
+            _request: &LiveStateScanRequest,
+        ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
+            Ok(self.rows.clone())
+        }
+
+        async fn load_version_head(
+            &mut self,
+            version_id: &str,
+        ) -> Result<Option<String>, LixError> {
+            if version_id == "ghost-version" {
+                return Ok(None);
+            }
+            Ok(Some(format!("commit-{version_id}")))
+        }
+
+        async fn stage_write(
+            &mut self,
+            _write: TransactionWrite,
+        ) -> Result<TransactionWriteOutcome, LixError> {
+            Ok(TransactionWriteOutcome { count: 0 })
+        }
+    }
+
+    #[async_trait]
+    impl SqlWriteExecutionContext for CapturingWriteContext {
+        fn active_version_id(&self) -> &str {
+            "version-a"
+        }
+
+        fn functions(&self) -> FunctionProviderHandle {
+            test_functions()
+        }
+
+        fn list_visible_schemas(&self) -> Result<Vec<serde_json::Value>, LixError> {
+            Ok(Vec::new())
+        }
+
+        async fn load_bytes_many(
+            &mut self,
+            hashes: &[crate::binary_cas::BlobHash],
+        ) -> Result<crate::binary_cas::BlobBytesBatch, LixError> {
+            DummyBlobReader.load_bytes_many(hashes).await
+        }
+
+        async fn scan_live_state(
+            &mut self,
+            _request: &LiveStateScanRequest,
+        ) -> Result<Vec<MaterializedLiveStateRow>, LixError> {
+            Ok(self.rows.clone())
+        }
+
+        async fn load_version_head(
+            &mut self,
+            version_id: &str,
+        ) -> Result<Option<String>, LixError> {
+            if version_id == "ghost-version" {
+                return Ok(None);
+            }
+            Ok(Some(format!("commit-{version_id}")))
+        }
+
+        async fn stage_write(
+            &mut self,
+            write: TransactionWrite,
+        ) -> Result<TransactionWriteOutcome, LixError> {
+            self.writes.push(write);
+            Ok(TransactionWriteOutcome { count: 0 })
+        }
+    }
+
+    fn col(name: &str) -> Expr {
+        Expr::Column(Column::from_name(name))
+    }
+
+    fn str_lit(value: &str) -> Expr {
+        Expr::Literal(ScalarValue::Utf8(Some(value.to_string())), None)
+    }
+
+    fn json_lit(value: &str) -> Expr {
+        Expr::Literal(
+            ScalarValue::Utf8(Some(value.to_string())),
+            Some(datafusion::common::metadata::FieldMetadata::new(
+                std::collections::BTreeMap::from([(
+                    crate::sql2::result_metadata::LIX_VALUE_TYPE_METADATA_KEY.to_string(),
+                    crate::sql2::result_metadata::LIX_VALUE_TYPE_JSON.to_string(),
+                )]),
+            )),
+        )
+    }
+
+    fn string_column(values: Vec<Option<&str>>) -> ArrayRef {
+        Arc::new(StringArray::from(values)) as ArrayRef
+    }
+
+    fn one_row_lix_state_batch(global: bool) -> RecordBatch {
+        RecordBatch::try_new(
+            lix_state_schema(),
+            vec![
+                string_column(vec![Some("[\"entity-1\"]")]),
+                string_column(vec![Some("lix_key_value")]),
+                string_column(vec![None]),
+                string_column(vec![Some("{\"key\":\"hello\",\"value\":\"world\"}")]),
+                string_column(vec![Some("{\"source\":\"test\"}")]),
+                string_column(vec![Some("2026-04-23T00:00:00Z")]),
+                string_column(vec![Some("2026-04-23T01:00:00Z")]),
+                Arc::new(BooleanArray::from(vec![global])) as ArrayRef,
+                string_column(vec![Some("change-a")]),
+                string_column(vec![None]),
+                Arc::new(BooleanArray::from(vec![false])) as ArrayRef,
+            ],
+        )
+        .expect("valid lix_state batch")
+    }
+
+    fn one_row_stageable_lix_state_batch() -> RecordBatch {
+        RecordBatch::try_new(
+            lix_state_schema(),
+            vec![
+                string_column(vec![Some("[\"entity-1\"]")]),
+                string_column(vec![Some("lix_key_value")]),
+                string_column(vec![None]),
+                string_column(vec![Some("{\"key\":\"hello\",\"value\":\"world\"}")]),
+                string_column(vec![None]),
+                string_column(vec![None]),
+                string_column(vec![None]),
+                Arc::new(BooleanArray::from(vec![false])) as ArrayRef,
+                string_column(vec![None]),
+                string_column(vec![None]),
+                Arc::new(BooleanArray::from(vec![false])) as ArrayRef,
+            ],
+        )
+        .expect("valid stageable lix_state batch")
+    }
+
+    fn live_row(entity_id: &str, metadata: Option<&str>) -> MaterializedLiveStateRow {
+        MaterializedLiveStateRow {
+            entity_id: EntityIdentity::single(entity_id),
+            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}")),
+            global: false,
+            untracked: false,
+            created_at: "2026-04-23T00:00:00Z".to_string(),
+            updated_at: "2026-04-23T01:00:00Z".to_string(),
+        }
+    }
+
+    #[test]
+    fn parses_eq_filter_for_schema_key() {
+        let expr = Expr::BinaryExpr(BinaryExpr::new(
+            Box::new(col("schema_key")),
+            Operator::Eq,
+            Box::new(str_lit("profile")),
+        ));
+
+        assert_eq!(
+            parse_lix_state_filter(&expr),
+            Some(LixStateFilterPredicate::SchemaKeys(BTreeSet::from([
+                "profile".to_string(),
+            ])))
+        );
+    }
+
+    #[test]
+    fn parses_in_list_filter_for_version_id() {
+        let expr = Expr::InList(InList::new(
+            Box::new(col("version_id")),
+            vec![str_lit("a"), str_lit("b")],
+            false,
+        ));
+
+        assert_eq!(
+            parse_lix_state_filter(&expr),
+            Some(LixStateFilterPredicate::VersionIds(BTreeSet::from([
+                "a".to_string(),
+                "b".to_string(),
+            ])))
+        );
+    }
+
+    #[test]
+    fn builds_scan_request_from_route_and_projection() {
+        let schema = super::lix_state_by_version_schema();
+        let route = LixStateByVersionRoute::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")),
+                Operator::Eq,
+                Box::new(str_lit("v1")),
+            )),
+            Expr::IsNull(Box::new(col("file_id"))),
+        ]);
+
+        let request =
+            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.file_ids, vec![NullableKeyFilter::Null]);
+        assert_eq!(
+            request.projection.columns,
+            vec![
+                "entity_id".to_string(),
+                "schema_key".to_string(),
+                "version_id".to_string()
+            ]
+        );
+        assert_eq!(request.limit, Some(10));
+    }
+
+    #[test]
+    fn builds_route_from_and_filter_tree() {
+        let route = LixStateByVersionRoute::from_filters(&[Expr::BinaryExpr(BinaryExpr::new(
+            Box::new(Expr::BinaryExpr(BinaryExpr::new(
+                Box::new(col("entity_id")),
+                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")],
+                false,
+            ))),
+        ))]);
+
+        assert_eq!(
+            route.entity_ids,
+            Some(BTreeSet::from(["[\"entity-a\"]".to_string()]))
+        );
+        assert_eq!(
+            route.version_ids,
+            Some(BTreeSet::from([
+                "global".to_string(),
+                "version-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(&[
+            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 request = lix_state_scan_request(&schema, None, None, &route, None);
+
+        assert_eq!(request.limit, Some(0));
+        assert!(request.filter.schema_keys.is_empty());
+    }
+
+    #[test]
+    fn active_version_view_pins_version_filter() {
+        let schema = super::lix_state_schema();
+        let route = LixStateByVersionRoute::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);
+
+        assert_eq!(request.filter.schema_keys, vec!["profile".to_string()]);
+        assert_eq!(request.filter.version_ids, vec!["version-a".to_string()]);
+    }
+
+    #[tokio::test]
+    async fn registers_active_lix_state_with_write_context_only() {
+        let session = SessionContext::new();
+        let mut write_context = DummyWriteContext::default();
+        let write_ctx = SqlWriteContext::new(&mut write_context);
+
+        register_lix_state_write_providers(&session, write_ctx)
+            .await
+            .expect("lix_state providers should register");
+
+        let lix_state = session
+            .table_provider("lix_state")
+            .await
+            .expect("lix_state provider should exist");
+        let lix_state = lix_state
+            .as_any()
+            .downcast_ref::<LixStateProvider>()
+            .expect("lix_state should be a LixStateProvider");
+        assert!(lix_state.write_access.is_write());
+
+        let by_version = session
+            .table_provider("lix_state_by_version")
+            .await
+            .expect("lix_state_by_version provider should exist");
+        let by_version = by_version
+            .as_any()
+            .downcast_ref::<LixStateProvider>()
+            .expect("lix_state_by_version should be a LixStateProvider");
+        assert!(by_version.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 input = Arc::new(EmptyExec::new(provider.schema())) as Arc<dyn ExecutionPlan>;
+
+        let error = provider
+            .insert_into(&session.state(), input, InsertOp::Append)
+            .await
+            .expect_err("insert without a write context should fail");
+
+        assert!(
+            error.to_string().contains("requires a write transaction"),
+            "unexpected error: {error}"
+        );
+    }
+
+    #[tokio::test]
+    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 error = provider
+            .update(
+                &session.state(),
+                vec![("metadata".to_string(), str_lit("{\"source\":\"update\"}"))],
+                vec![],
+            )
+            .await
+            .expect_err("update without a write context should fail");
+
+        assert!(
+            error.to_string().contains("requires a write transaction"),
+            "unexpected error: {error}"
+        );
+    }
+
+    #[tokio::test]
+    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 error = provider
+            .delete_from(&session.state(), vec![])
+            .await
+            .expect_err("delete without a write context should fail");
+
+        assert!(
+            error.to_string().contains("requires a write transaction"),
+            "unexpected error: {error}"
+        );
+    }
+
+    #[tokio::test]
+    async fn delete_returns_lix_state_delete_exec_with_write_ctx() {
+        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 plan = provider
+            .delete_from(&session.state(), vec![])
+            .await
+            .expect("delete should produce a write plan");
+
+        assert!(plan.as_any().is::<LixStateDeleteExec>());
+    }
+
+    #[tokio::test]
+    async fn update_rejects_read_only_lix_state_columns() {
+        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 error = provider
+            .update(
+                &session.state(),
+                vec![("entity_id".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'"),
+            "unexpected error: {error}"
+        );
+    }
+
+    #[tokio::test]
+    async fn update_returns_lix_state_update_exec_with_write_ctx() {
+        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 plan = provider
+            .update(
+                &session.state(),
+                vec![("metadata".to_string(), str_lit("{\"source\":\"update\"}"))],
+                vec![],
+            )
+            .await
+            .expect("update should produce a write plan");
+
+        assert!(plan.as_any().is::<LixStateUpdateExec>());
+    }
+
+    #[tokio::test]
+    async fn insert_into_returns_data_sink_exec_with_write_ctx() {
+        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 input = Arc::new(EmptyExec::new(provider.schema())) as Arc<dyn ExecutionPlan>;
+
+        let plan = provider
+            .insert_into(&session.state(), input, InsertOp::Append)
+            .await
+            .expect("insert should produce a write plan");
+
+        assert!(plan.as_any().is::<InsertExec>());
+    }
+
+    #[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");
+
+        assert_eq!(
+            rows,
+            vec![TransactionWriteRow {
+                entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
+                schema_key: "lix_key_value".to_string(),
+                file_id: None,
+                snapshot: Some(TransactionJson::from_value_for_test(
+                    json!({"key":"hello","value":"world"})
+                )),
+                metadata: Some(TransactionJson::from_value_for_test(
+                    json!({"source": "test"})
+                )),
+                origin: None,
+                created_at: Some("2026-04-23T00:00:00Z".to_string()),
+                updated_at: Some("2026-04-23T01:00:00Z".to_string()),
+                global: false,
+                change_id: Some("change-a".to_string()),
+                commit_id: None,
+                untracked: false,
+                version_id: "version-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");
+
+        assert_eq!(rows[0].version_id, "global");
+        assert!(rows[0].global);
+    }
+
+    #[tokio::test]
+    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 batch = one_row_lix_state_batch(false);
+        let count = sink
+            .write_batches(vec![batch], &Arc::new(TaskContext::default()))
+            .await
+            .expect("sink should stage write");
+
+        assert_eq!(count, 1);
+        assert_eq!(
+            write_context.writes.as_slice(),
+            &[TransactionWrite::Rows {
+                mode: TransactionWriteMode::Insert,
+                rows: vec![TransactionWriteRow {
+                    entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
+                    schema_key: "lix_key_value".to_string(),
+                    file_id: None,
+                    snapshot: Some(TransactionJson::from_value_for_test(
+                        json!({"key":"hello","value":"world"})
+                    )),
+                    metadata: Some(TransactionJson::from_value_for_test(
+                        json!({"source": "test"})
+                    )),
+                    origin: None,
+                    created_at: Some("2026-04-23T00:00:00Z".to_string()),
+                    updated_at: Some("2026-04-23T01:00:00Z".to_string()),
+                    global: false,
+                    change_id: Some("change-a".to_string()),
+                    commit_id: None,
+                    untracked: false,
+                    version_id: "version-a".to_string(),
+                }]
+            }]
+        );
+    }
+
+    #[tokio::test]
+    async fn insert_plan_returns_datafusion_count_uint64() {
+        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 input = Arc::new(SingleBatchExec::new(one_row_stageable_lix_state_batch()))
+            as Arc<dyn ExecutionPlan>;
+
+        let plan = provider
+            .insert_into(&session.state(), input, InsertOp::Append)
+            .await
+            .expect("insert should produce a write plan");
+        let batches = datafusion::physical_plan::collect(plan, Arc::new(TaskContext::default()))
+            .await
+            .expect("insert write plan should execute");
+
+        assert_eq!(batches.len(), 1);
+        assert_eq!(batches[0].num_rows(), 1);
+        assert_eq!(batches[0].num_columns(), 1);
+        assert_eq!(batches[0].schema().field(0).name(), "count");
+        assert_eq!(batches[0].schema().field(0).data_type(), &DataType::UInt64);
+        assert!(!batches[0].schema().field(0).is_nullable());
+
+        let count = batches[0]
+            .column(0)
+            .as_any()
+            .downcast_ref::<UInt64Array>()
+            .expect("count should be UInt64");
+        assert_eq!(count.value(0), 1);
+        assert_eq!(write_context.writes.len(), 1);
+    }
+
+    #[tokio::test]
+    async fn update_plan_evaluates_filters_assignments_and_stages_rows() {
+        let session = SessionContext::new();
+        let mut write_context = CapturingWriteContext {
+            rows: vec![
+                live_row("entity-1", Some("{\"source\":\"match\"}")),
+                live_row("entity-2", Some("{\"source\":\"skip\"}")),
+            ],
+            writes: Vec::new(),
+        };
+        let write_ctx = SqlWriteContext::new(&mut write_context);
+        let provider = LixStateProvider::active_version_with_write(write_ctx);
+
+        let plan = provider
+            .update(
+                &session.state(),
+                vec![
+                    (
+                        "snapshot_content".to_string(),
+                        str_lit("{\"key\":\"hello\",\"value\":\"updated\"}"),
+                    ),
+                    (
+                        "metadata".to_string(),
+                        str_lit("{\"schema_key\":\"lix_key_value\"}"),
+                    ),
+                ],
+                vec![Expr::BinaryExpr(BinaryExpr::new(
+                    Box::new(col("metadata")),
+                    Operator::Eq,
+                    Box::new(json_lit("{\"source\":\"match\"}")),
+                ))],
+            )
+            .await
+            .expect("update should produce a write plan");
+        let batches = datafusion::physical_plan::collect(plan, Arc::new(TaskContext::default()))
+            .await
+            .expect("update write plan should execute");
+
+        assert_eq!(batches.len(), 1);
+        assert_eq!(batches[0].schema().field(0).name(), "count");
+        assert_eq!(batches[0].schema().field(0).data_type(), &DataType::UInt64);
+        let count = batches[0]
+            .column(0)
+            .as_any()
+            .downcast_ref::<UInt64Array>()
+            .expect("count should be UInt64");
+        assert_eq!(count.value(0), 1);
+
+        assert_eq!(
+            write_context.writes.as_slice(),
+            &[TransactionWrite::Rows {
+                mode: TransactionWriteMode::Replace,
+                rows: vec![TransactionWriteRow {
+                    entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
+                    schema_key: "lix_key_value".to_string(),
+                    file_id: None,
+                    snapshot: Some(TransactionJson::from_value_for_test(
+                        json!({"key":"hello","value":"updated"})
+                    )),
+                    metadata: Some(TransactionJson::from_value_for_test(
+                        json!({"schema_key": "lix_key_value"})
+                    )),
+                    origin: None,
+                    created_at: None,
+                    updated_at: None,
+                    global: false,
+                    change_id: None,
+                    commit_id: None,
+                    untracked: false,
+                    version_id: "version-a".to_string(),
+                }]
+            }]
+        );
+    }
+
+    #[tokio::test]
+    async fn delete_plan_with_empty_filters_stages_all_visible_rows() {
+        let session = SessionContext::new();
+        let mut write_context = CapturingWriteContext {
+            rows: vec![
+                live_row("entity-1", Some("{\"source\":\"one\"}")),
+                live_row("entity-2", Some("{\"source\":\"two\"}")),
+            ],
+            writes: Vec::new(),
+        };
+        let write_ctx = SqlWriteContext::new(&mut write_context);
+        let provider = LixStateProvider::active_version_with_write(write_ctx);
+
+        let plan = provider
+            .delete_from(&session.state(), vec![])
+            .await
+            .expect("delete should produce a write plan");
+        let batches = datafusion::physical_plan::collect(plan, Arc::new(TaskContext::default()))
+            .await
+            .expect("delete write plan should execute");
+
+        assert_eq!(batches.len(), 1);
+        assert_eq!(batches[0].schema().field(0).name(), "count");
+        assert_eq!(batches[0].schema().field(0).data_type(), &DataType::UInt64);
+        let count = batches[0]
+            .column(0)
+            .as_any()
+            .downcast_ref::<UInt64Array>()
+            .expect("count should be UInt64");
+        assert_eq!(count.value(0), 2);
+
+        assert_eq!(
+            write_context.writes.as_slice(),
+            &[TransactionWrite::Rows {
+                mode: TransactionWriteMode::Replace,
+                rows: vec![
+                    TransactionWriteRow {
+                        entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
+                        schema_key: "lix_key_value".to_string(),
+                        file_id: None,
+                        snapshot: None,
+                        metadata: Some(TransactionJson::from_value_for_test(
+                            json!({"source": "one"})
+                        )),
+                        origin: None,
+                        created_at: None,
+                        updated_at: None,
+                        global: false,
+                        change_id: None,
+                        commit_id: None,
+                        untracked: false,
+                        version_id: "version-a".to_string(),
+                    },
+                    TransactionWriteRow {
+                        entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-2")),
+                        schema_key: "lix_key_value".to_string(),
+                        file_id: None,
+                        snapshot: None,
+                        metadata: Some(TransactionJson::from_value_for_test(
+                            json!({"source": "two"})
+                        )),
+                        origin: None,
+                        created_at: None,
+                        updated_at: None,
+                        global: false,
+                        change_id: None,
+                        commit_id: None,
+                        untracked: false,
+                        version_id: "version-a".to_string(),
+                    },
+                ]
+            }]
+        );
+    }
+}