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

package/dist-engine-src/src/sql2/exec/bound_public_write.rs

@@ -1,1593 +0,0 @@
-use serde_json::Value as JsonValue;
-
-use crate::common::validate_row_metadata;
-use crate::entity_pk::EntityPk;
-use crate::live_state::{LiveStateFilter, LiveStateScanRequest};
-use crate::sql2::bind::expr::{BoundExpr, BoundLiteral};
-use crate::sql2::bind::write::{
-    BoundInsertValues, BoundWriteInput, BoundWriteOp, BoundWriteTarget, EntityWriteSurface,
-};
-use crate::sql2::catalog::entity_surface::EntitySurfaceColumn;
-use crate::sql2::catalog::{
-    derive_entity_surface_spec_from_schema, EntityColumnType, EntitySurfaceSpec,
-};
-use crate::sql2::plan::branch_scope::BranchScope;
-use crate::sql2::plan::predicate::FilterSet;
-use crate::sql2::plan::LogicalWritePlan;
-use crate::sql2::read_only::reject_read_only_entity_surface;
-use crate::sql2::SqlWriteExecutionContext;
-use crate::transaction::types::{
-    TransactionJson, TransactionWrite, TransactionWriteMode, TransactionWriteRow,
-};
-use crate::{parse_row_metadata_value, LixError, Value};
-
-pub(crate) fn supports_bound_public_write(plan: &LogicalWritePlan) -> bool {
-    matches!(plan.bound.target, BoundWriteTarget::Entity(_))
-        && bound_public_write_shape_supported(plan)
-}
-
-pub(crate) async fn execute_bound_public_write(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    plan: &LogicalWritePlan,
-    params: &[Value],
-) -> Result<u64, LixError> {
-    match &plan.bound.target {
-        BoundWriteTarget::Entity(surface) => execute_entity_write(ctx, plan, surface, params).await,
-        _ => Err(LixError::new(
-            LixError::CODE_UNSUPPORTED_SQL,
-            "bound public write executor does not support this target yet",
-        )),
-    }
-}
-
-async fn execute_entity_write(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    plan: &LogicalWritePlan,
-    surface: &EntityWriteSurface,
-    params: &[Value],
-) -> Result<u64, LixError> {
-    let schema_key = match surface {
-        EntityWriteSurface::Base { schema_key } | EntityWriteSurface::ByBranch { schema_key } => {
-            schema_key
-        }
-    };
-    reject_read_only_entity_surface(schema_key, entity_action(&plan.bound.op))
-        .map_err(crate::sql2::error::datafusion_error_to_lix_error)?;
-
-    if schema_key == "lix_registered_schema" && plan.bound.op == BoundWriteOp::Delete {
-        return Err(LixError::new(
-            LixError::CODE_UNSUPPORTED_SQL,
-            "delete lix_registered_schema is not supported",
-        ));
-    }
-
-    let spec = entity_spec(ctx, schema_key)?;
-    validate_bound_write_supported(plan, &spec)?;
-    let active_branch_commit_id = load_active_branch_commit_id(ctx).await?;
-    let no_op = matches!(plan.bound.branch_scope, BranchScope::Empty)
-        || matches!(plan.filters.rows, FilterSet::None);
-    match plan.bound.op {
-        BoundWriteOp::Insert => {
-            if no_op {
-                entity_insert_rows(ctx, plan, &spec, params, active_branch_commit_id.as_deref())?;
-                return Ok(0);
-            }
-            entity_insert(ctx, plan, &spec, params, active_branch_commit_id.as_deref()).await
-        }
-        BoundWriteOp::Update => {
-            if no_op {
-                return Ok(0);
-            }
-            entity_update(ctx, plan, &spec, params, active_branch_commit_id.as_deref()).await
-        }
-        BoundWriteOp::Delete => {
-            if no_op {
-                return Ok(0);
-            }
-            entity_delete(ctx, plan, &spec, params, active_branch_commit_id.as_deref()).await
-        }
-    }
-}
-
-async fn load_active_branch_commit_id(
-    ctx: &mut dyn SqlWriteExecutionContext,
-) -> Result<Option<String>, LixError> {
-    let active_branch_id = ctx.active_branch_id().to_string();
-    ctx.load_branch_head(&active_branch_id)
-        .await?
-        .map(Some)
-        .ok_or_else(|| {
-            LixError::branch_not_found(
-                active_branch_id,
-                "execute bound public write",
-                "active branch",
-            )
-        })
-}
-
-async fn entity_insert(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    plan: &LogicalWritePlan,
-    spec: &EntitySurfaceSpec,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<u64, LixError> {
-    let write_rows = entity_insert_rows(ctx, plan, spec, params, active_branch_commit_id)?;
-    stage_rows(ctx, TransactionWriteMode::Insert, write_rows).await
-}
-
-fn entity_insert_rows(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    plan: &LogicalWritePlan,
-    spec: &EntitySurfaceSpec,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<Vec<TransactionWriteRow>, LixError> {
-    let BoundWriteInput::Values(values) = &plan.bound.input else {
-        return Err(LixError::new(
-            LixError::CODE_UNSUPPORTED_SQL,
-            "bound entity INSERT supports VALUES only",
-        ));
-    };
-
-    let layout = InsertRowLayout::from_values(spec, values)?;
-    let mut write_rows = Vec::with_capacity(values.rows.len());
-    for row in &values.rows {
-        write_rows.push(entity_insert_row(
-            ctx,
-            plan,
-            &layout,
-            row,
-            params,
-            active_branch_commit_id,
-        )?);
-    }
-    Ok(write_rows)
-}
-
-async fn entity_update(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    plan: &LogicalWritePlan,
-    spec: &EntitySurfaceSpec,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<u64, LixError> {
-    let candidates = scan_entity_candidates(ctx, plan, spec).await?;
-    let mut write_rows = Vec::new();
-    for candidate in candidates {
-        let Some(snapshot) = candidate_snapshot(&candidate)? else {
-            continue;
-        };
-        let original_context = EntityEvalContext::live(&snapshot, &candidate, spec);
-        if !predicate_matches(
-            &plan.bound.predicate,
-            &original_context,
-            spec,
-            ctx,
-            params,
-            active_branch_commit_id,
-        )? {
-            continue;
-        }
-        reject_projected_global_write(plan, &candidate, "UPDATE")?;
-        let mut updated = snapshot.clone();
-        let mut visible_assignments = Vec::new();
-        for assignment in &plan.bound.assignments {
-            if let Some(column) = spec.visible_column(&assignment.column.name) {
-                reject_direct_blob_json_value(&assignment.value, column.column_type, params)?;
-                let value = eval_expr_value(
-                    &assignment.value,
-                    &original_context,
-                    ctx,
-                    params,
-                    active_branch_commit_id,
-                )?;
-                visible_assignments.push((
-                    column.name.clone(),
-                    entity_json_value(value, column.column_type)?,
-                ));
-            } else if assignment.column.name == "lixcol_metadata" {
-                // handled below from the assignment list
-            } else {
-                return Err(LixError::new(
-                    LixError::CODE_UNSUPPORTED_SQL,
-                    format!(
-                        "bound entity UPDATE does not support assignment to '{}'",
-                        assignment.column.name
-                    ),
-                ));
-            }
-        }
-        for (column_name, value) in visible_assignments {
-            updated[&column_name] = value;
-        }
-        write_rows.push(entity_replace_row_from_live(
-            ctx,
-            spec,
-            &candidate,
-            Some(updated),
-            plan,
-            params,
-            active_branch_commit_id,
-        )?);
-    }
-    stage_rows(ctx, TransactionWriteMode::Replace, write_rows).await
-}
-
-async fn entity_delete(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    plan: &LogicalWritePlan,
-    spec: &EntitySurfaceSpec,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<u64, LixError> {
-    let candidates = scan_entity_candidates(ctx, plan, spec).await?;
-    let mut write_rows = Vec::new();
-    for candidate in candidates {
-        let Some(snapshot) = candidate_snapshot(&candidate)? else {
-            continue;
-        };
-        let context = EntityEvalContext::live(&snapshot, &candidate, spec);
-        if predicate_matches(
-            &plan.bound.predicate,
-            &context,
-            spec,
-            ctx,
-            params,
-            active_branch_commit_id,
-        )? {
-            reject_projected_global_write(plan, &candidate, "DELETE")?;
-            write_rows.push(entity_replace_row_from_live(
-                ctx,
-                spec,
-                &candidate,
-                None,
-                plan,
-                params,
-                active_branch_commit_id,
-            )?);
-        }
-    }
-    stage_rows(ctx, TransactionWriteMode::Replace, write_rows).await
-}
-
-async fn stage_rows(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    mode: TransactionWriteMode,
-    rows: Vec<TransactionWriteRow>,
-) -> Result<u64, LixError> {
-    if rows.is_empty() {
-        return Ok(0);
-    }
-    let outcome = ctx
-        .stage_write(TransactionWrite::Rows { mode, rows })
-        .await?;
-    Ok(outcome.count)
-}
-
-async fn scan_entity_candidates(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    plan: &LogicalWritePlan,
-    spec: &EntitySurfaceSpec,
-) -> Result<Vec<crate::live_state::MaterializedLiveStateRow>, LixError> {
-    let branch_ids = scan_branch_ids(&plan.bound.branch_scope)?;
-    let request = LiveStateScanRequest {
-        filter: LiveStateFilter {
-            schema_keys: vec![spec.schema_key.clone()],
-            branch_ids,
-            include_tombstones: false,
-            ..LiveStateFilter::default()
-        },
-        ..LiveStateScanRequest::default()
-    };
-    ctx.scan_live_state(&request).await
-}
-
-struct InsertRowLayout {
-    schema_key: String,
-    visible_columns: Vec<EntitySurfaceColumn>,
-    snapshot_context: String,
-    snapshot_capacity: usize,
-    columns: Vec<InsertColumnTarget>,
-}
-
-#[derive(Clone)]
-enum InsertColumnTarget {
-    Visible {
-        name: String,
-        column_type: EntityColumnType,
-    },
-    EntityPk,
-    FileId,
-    Metadata,
-    Global,
-    Untracked,
-    BranchId,
-}
-
-impl InsertRowLayout {
-    fn from_values(spec: &EntitySurfaceSpec, values: &BoundInsertValues) -> Result<Self, LixError> {
-        let mut snapshot_capacity = 0;
-        let mut seen_columns = std::collections::BTreeSet::new();
-        let columns = values
-            .columns
-            .iter()
-            .map(|column| {
-                if !seen_columns.insert(column.name.clone()) {
-                    return Err(LixError::new(
-                        LixError::CODE_UNSUPPORTED_SQL,
-                        format!("duplicate entity INSERT column '{}'", column.name),
-                    ));
-                }
-                if let Some(surface_column) = spec.visible_column(&column.name) {
-                    snapshot_capacity += 1;
-                    return Ok(InsertColumnTarget::Visible {
-                        name: surface_column.name.clone(),
-                        column_type: surface_column.column_type,
-                    });
-                }
-                Ok(match column.name.as_str() {
-                    "lixcol_entity_pk" => InsertColumnTarget::EntityPk,
-                    "lixcol_file_id" => InsertColumnTarget::FileId,
-                    "lixcol_metadata" => InsertColumnTarget::Metadata,
-                    "lixcol_global" => InsertColumnTarget::Global,
-                    "lixcol_untracked" => InsertColumnTarget::Untracked,
-                    "lixcol_branch_id" => InsertColumnTarget::BranchId,
-                    _ => {
-                        return Err(LixError::new(
-                            LixError::CODE_UNSUPPORTED_SQL,
-                            format!(
-                                "bound entity INSERT does not support column '{}'",
-                                column.name
-                            ),
-                        ));
-                    }
-                })
-            })
-            .collect::<Result<Vec<_>, LixError>>()?;
-        Ok(Self {
-            schema_key: spec.schema_key.clone(),
-            visible_columns: spec.columns.clone(),
-            snapshot_context: format!("{} insert snapshot_content", spec.schema_key),
-            snapshot_capacity,
-            columns,
-        })
-    }
-}
-
-fn entity_insert_row(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    plan: &LogicalWritePlan,
-    layout: &InsertRowLayout,
-    row: &[BoundExpr],
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<TransactionWriteRow, LixError> {
-    if row.len() != layout.columns.len() {
-        return Err(LixError::new(
-            LixError::CODE_UNSUPPORTED_SQL,
-            "entity INSERT rows must have a consistent column layout",
-        ));
-    }
-
-    let mut snapshot = serde_json::Map::with_capacity(layout.snapshot_capacity);
-    let mut entity_pk = None;
-    let mut file_id = None;
-    let mut metadata = None;
-    let mut global = None;
-    let mut untracked = None;
-    let mut explicit_branch_id = None;
-    let context = EntityEvalContext::insert(&JsonValue::Null, &layout.visible_columns);
-
-    for (expr, target) in row.iter().zip(layout.columns.iter()) {
-        if let InsertColumnTarget::Visible { column_type, .. } = target {
-            reject_direct_blob_json_value(expr, *column_type, params)?;
-        }
-        let eval_value = eval_expr_value(expr, &context, ctx, params, active_branch_commit_id)?;
-        if matches!(target, InsertColumnTarget::Metadata) {
-            metadata = optional_metadata_from_eval_value(
-                eval_value,
-                "lixcol_metadata",
-                &layout.schema_key,
-            )?;
-            continue;
-        }
-        match target {
-            InsertColumnTarget::Visible { name, column_type } => {
-                snapshot.insert(name.clone(), entity_json_value(eval_value, *column_type)?);
-                continue;
-            }
-            _ => {}
-        }
-        let value = eval_value.into_json();
-        match target {
-            InsertColumnTarget::Visible { .. } => unreachable!("visible columns handled above"),
-            InsertColumnTarget::EntityPk => {
-                entity_pk = Some(entity_pk_from_value(&value, "lixcol_entity_pk")?);
-            }
-            InsertColumnTarget::FileId => {
-                file_id = text_value(value, "lixcol_file_id")?;
-            }
-            InsertColumnTarget::Metadata => {
-                unreachable!("metadata handled before JSON value coercion")
-            }
-            InsertColumnTarget::Global => {
-                global = bool_value(value, "lixcol_global")?;
-            }
-            InsertColumnTarget::Untracked => {
-                untracked = bool_value(value, "lixcol_untracked")?;
-            }
-            InsertColumnTarget::BranchId => {
-                explicit_branch_id = text_value(value, "lixcol_branch_id")?;
-            }
-        }
-    }
-
-    let snapshot = JsonValue::Object(snapshot);
-    let global = global.unwrap_or(false);
-    let branch_id = entity_row_branch_id(plan, explicit_branch_id, global)?;
-    Ok(TransactionWriteRow {
-        entity_pk,
-        schema_key: layout.schema_key.clone(),
-        file_id,
-        snapshot: Some(TransactionJson::from_value(
-            snapshot,
-            &layout.snapshot_context,
-        )?),
-        metadata,
-        origin: None,
-        created_at: None,
-        updated_at: None,
-        global,
-        change_id: None,
-        commit_id: None,
-        untracked: untracked.unwrap_or(false),
-        branch_id,
-    })
-}
-
-fn reject_projected_global_write(
-    plan: &LogicalWritePlan,
-    row: &crate::live_state::MaterializedLiveStateRow,
-    action: &str,
-) -> Result<(), LixError> {
-    let target_is_by_branch = matches!(
-        &plan.bound.target,
-        BoundWriteTarget::Entity(EntityWriteSurface::ByBranch { .. })
-    );
-    if target_is_by_branch && row.global && row.branch_id != crate::GLOBAL_BRANCH_ID {
-        return Err(LixError::new(
-            LixError::CODE_UNSUPPORTED_SQL,
-            format!(
-                "{action} through an entity by-branch surface cannot mutate a projected global row"
-            ),
-        ));
-    }
-    Ok(())
-}
-
-fn entity_replace_row_from_live(
-    ctx: &mut dyn SqlWriteExecutionContext,
-    spec: &EntitySurfaceSpec,
-    row: &crate::live_state::MaterializedLiveStateRow,
-    snapshot: Option<JsonValue>,
-    plan: &LogicalWritePlan,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<TransactionWriteRow, LixError> {
-    let metadata = if let Some(expr) = assignment_value(plan, "lixcol_metadata") {
-        let snapshot_for_eval = candidate_snapshot(row)?.unwrap_or(JsonValue::Null);
-        let context = EntityEvalContext::live(&snapshot_for_eval, row, spec);
-        let value = eval_expr_value(expr, &context, ctx, params, active_branch_commit_id)?;
-        optional_metadata_from_eval_value(value, "lixcol_metadata", &spec.schema_key)?
-    } else {
-        inherited_metadata(row, spec)?
-    };
-
-    Ok(TransactionWriteRow {
-        entity_pk: Some(row.entity_pk.clone()),
-        schema_key: spec.schema_key.clone(),
-        file_id: row.file_id.clone(),
-        snapshot: snapshot
-            .map(|snapshot| {
-                TransactionJson::from_value(
-                    snapshot,
-                    &format!("{} update snapshot_content", spec.schema_key),
-                )
-            })
-            .transpose()?,
-        metadata,
-        origin: None,
-        created_at: None,
-        updated_at: None,
-        global: row.global,
-        change_id: None,
-        commit_id: None,
-        untracked: row.untracked,
-        branch_id: if row.global {
-            crate::GLOBAL_BRANCH_ID.to_string()
-        } else {
-            row.branch_id.clone()
-        },
-    })
-}
-
-fn inherited_metadata(
-    row: &crate::live_state::MaterializedLiveStateRow,
-    spec: &EntitySurfaceSpec,
-) -> Result<Option<TransactionJson>, LixError> {
-    row.metadata
-        .as_ref()
-        .map(|metadata| {
-            let metadata = parse_row_metadata_value(metadata, &spec.schema_key)?;
-            TransactionJson::from_value(metadata, &format!("{} metadata", spec.schema_key))
-        })
-        .transpose()
-}
-
-struct EntityEvalContext<'a> {
-    snapshot: &'a JsonValue,
-    row: Option<&'a crate::live_state::MaterializedLiveStateRow>,
-    visible_columns: &'a [EntitySurfaceColumn],
-}
-
-impl<'a> EntityEvalContext<'a> {
-    fn insert(snapshot: &'a JsonValue, visible_columns: &'a [EntitySurfaceColumn]) -> Self {
-        Self {
-            snapshot,
-            row: None,
-            visible_columns,
-        }
-    }
-
-    fn live(
-        snapshot: &'a JsonValue,
-        row: &'a crate::live_state::MaterializedLiveStateRow,
-        spec: &'a EntitySurfaceSpec,
-    ) -> Self {
-        Self {
-            snapshot,
-            row: Some(row),
-            visible_columns: &spec.columns,
-        }
-    }
-}
-
-fn entity_spec(
-    ctx: &dyn SqlWriteExecutionContext,
-    schema_key: &str,
-) -> Result<EntitySurfaceSpec, LixError> {
-    ctx.list_visible_schemas()?
-        .into_iter()
-        .filter_map(|schema| derive_entity_surface_spec_from_schema(&schema).ok())
-        .find(|spec| spec.schema_key == schema_key)
-        .ok_or_else(|| {
-            LixError::new(
-                LixError::CODE_SCHEMA_DEFINITION,
-                format!("entity surface '{schema_key}' is not visible"),
-            )
-        })
-}
-
-#[derive(Clone, Debug)]
-enum EntityEvalValue {
-    SqlNull,
-    SqlText(String),
-    Json(JsonValue),
-}
-
-impl EntityEvalValue {
-    fn into_json(self) -> JsonValue {
-        match self {
-            Self::SqlNull => JsonValue::Null,
-            Self::SqlText(value) => JsonValue::String(value),
-            Self::Json(value) => value,
-        }
-    }
-}
-
-fn eval_expr(
-    expr: &BoundExpr,
-    context: &EntityEvalContext<'_>,
-    ctx: &mut dyn SqlWriteExecutionContext,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<JsonValue, LixError> {
-    eval_expr_value(expr, context, ctx, params, active_branch_commit_id)
-        .map(EntityEvalValue::into_json)
-}
-
-fn eval_expr_value(
-    expr: &BoundExpr,
-    context: &EntityEvalContext<'_>,
-    ctx: &mut dyn SqlWriteExecutionContext,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<EntityEvalValue, LixError> {
-    match expr {
-        BoundExpr::Literal(BoundLiteral::Null) => Ok(EntityEvalValue::SqlNull),
-        BoundExpr::Literal(BoundLiteral::Text(value)) => {
-            Ok(EntityEvalValue::SqlText(value.clone()))
-        }
-        BoundExpr::Literal(literal) => Ok(EntityEvalValue::Json(literal_json(literal))),
-        BoundExpr::Param(param) => params
-            .get(param.index.saturating_sub(1))
-            .map(value_eval)
-            .ok_or_else(|| {
-                LixError::new(
-                    LixError::CODE_INVALID_PARAM,
-                    format!("missing SQL parameter ${}", param.index),
-                )
-            }),
-        BoundExpr::Column(column) => column_eval_value(context, &column.name),
-        BoundExpr::Function { name, args } if name == "lix_json" && args.len() == 1 => {
-            let raw = eval_expr_value(&args[0], context, ctx, params, active_branch_commit_id)?;
-            let raw = match raw {
-                EntityEvalValue::SqlNull => return Ok(EntityEvalValue::Json(JsonValue::Null)),
-                EntityEvalValue::SqlText(value) => JsonValue::String(value),
-                EntityEvalValue::Json(value) => value,
-            };
-            let JsonValue::String(raw) = raw else {
-                return Err(LixError::new(
-                    LixError::CODE_TYPE_MISMATCH,
-                    "lix_json expects a text argument",
-                ));
-            };
-            serde_json::from_str(&raw)
-                .map_err(|error| {
-                    LixError::new(
-                        LixError::CODE_TYPE_MISMATCH,
-                        format!("lix_json argument is not valid JSON: {error}"),
-                    )
-                })
-                .map(EntityEvalValue::Json)
-        }
-        BoundExpr::Function { name, args } if name == "lix_uuid_v7" && args.is_empty() => {
-            Ok(EntityEvalValue::SqlText(ctx.functions().call_uuid_v7()))
-        }
-        BoundExpr::Function { name, args } if name == "lix_timestamp" && args.is_empty() => {
-            Ok(EntityEvalValue::SqlText(ctx.functions().call_timestamp()))
-        }
-        BoundExpr::Function { name, args } if name == "lix_empty_blob" && args.is_empty() => {
-            Ok(EntityEvalValue::Json(JsonValue::Array(Vec::new())))
-        }
-        BoundExpr::Function { name, args }
-            if name == "lix_active_branch_commit_id" && args.is_empty() =>
-        {
-            Ok(active_branch_commit_id
-                .map(|commit_id| EntityEvalValue::SqlText(commit_id.to_string()))
-                .unwrap_or(EntityEvalValue::SqlNull))
-        }
-        BoundExpr::Function { name, args }
-            if (name == "lix_json_get" || name == "lix_json_get_text") && args.len() >= 2 =>
-        {
-            let root = eval_expr_value(&args[0], context, ctx, params, active_branch_commit_id)?;
-            let mut current = match root {
-                EntityEvalValue::SqlNull => return Ok(EntityEvalValue::SqlNull),
-                EntityEvalValue::SqlText(raw) => {
-                    serde_json::from_str::<JsonValue>(&raw).map_err(|error| {
-                        LixError::new(
-                            LixError::CODE_TYPE_MISMATCH,
-                            format!(
-                                "{name} expected valid JSON text in its first argument: {error}"
-                            ),
-                        )
-                    })?
-                }
-                EntityEvalValue::Json(root) => match root {
-                    JsonValue::Null => return Ok(EntityEvalValue::SqlNull),
-                    value => value,
-                },
-            };
-            for arg in &args[1..] {
-                let segment = eval_expr(arg, context, ctx, params, active_branch_commit_id)?;
-                let Some(next) = json_path_get(&current, &segment, name)? else {
-                    return Ok(EntityEvalValue::SqlNull);
-                };
-                current = next;
-            }
-            if name == "lix_json_get_text" {
-                if current.is_null() {
-                    return Ok(EntityEvalValue::SqlNull);
-                }
-                Ok(EntityEvalValue::SqlText(json_text_value(&current)?))
-            } else {
-                Ok(EntityEvalValue::Json(current))
-            }
-        }
-        BoundExpr::Function { name, args }
-            if (name == "lix_text_encode" || name == "lix_text_decode")
-                && (1..=2).contains(&args.len()) =>
-        {
-            if args.len() == 2 {
-                validate_utf8_encoding(
-                    eval_expr(&args[1], context, ctx, params, active_branch_commit_id)?,
-                    name,
-                )?;
-            }
-            let value = eval_expr(&args[0], context, ctx, params, active_branch_commit_id)?;
-            if name == "lix_text_encode" {
-                Ok(EntityEvalValue::Json(JsonValue::Array(
-                    text_like_bytes(&value, name)?
-                        .into_iter()
-                        .map(JsonValue::from)
-                        .collect(),
-                )))
-            } else {
-                let bytes = binary_like_bytes(&value, name)?;
-                String::from_utf8(bytes)
-                    .map_err(|error| {
-                        LixError::new(
-                            LixError::CODE_TYPE_MISMATCH,
-                            format!("lix_text_decode() expected valid UTF8 bytes: {error}"),
-                        )
-                    })
-                    .map(EntityEvalValue::SqlText)
-            }
-        }
-        BoundExpr::Function { name, .. } => Err(LixError::new(
-            LixError::CODE_UNSUPPORTED_SQL,
-            format!("bound entity write does not support function '{name}' yet"),
-        )),
-    }
-}
-
-fn predicate_matches(
-    predicate: &crate::sql2::plan::predicate::BoundPredicate,
-    context: &EntityEvalContext<'_>,
-    spec: &EntitySurfaceSpec,
-    ctx: &mut dyn SqlWriteExecutionContext,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<bool, LixError> {
-    use crate::sql2::plan::predicate::BoundPredicate;
-    match predicate {
-        BoundPredicate::True => Ok(true),
-        BoundPredicate::False => Ok(false),
-        BoundPredicate::And(predicates) => {
-            for predicate in predicates {
-                if !predicate_matches(
-                    predicate,
-                    context,
-                    spec,
-                    ctx,
-                    params,
-                    active_branch_commit_id,
-                )? {
-                    return Ok(false);
-                }
-            }
-            Ok(true)
-        }
-        BoundPredicate::Or(predicates) => {
-            for predicate in predicates {
-                if predicate_matches(
-                    predicate,
-                    context,
-                    spec,
-                    ctx,
-                    params,
-                    active_branch_commit_id,
-                )? {
-                    return Ok(true);
-                }
-            }
-            Ok(false)
-        }
-        BoundPredicate::Eq(left, right) => {
-            let (left, right) = eval_comparison_operands(
-                left,
-                right,
-                context,
-                spec,
-                ctx,
-                params,
-                active_branch_commit_id,
-            )?;
-            Ok(!left.is_null() && !right.is_null() && left == right)
-        }
-        BoundPredicate::IsNull(expr) => {
-            let value = eval_expr(expr, context, ctx, params, active_branch_commit_id)?;
-            Ok(value.is_null())
-        }
-        BoundPredicate::IsNotNull(expr) => {
-            let value = eval_expr(expr, context, ctx, params, active_branch_commit_id)?;
-            Ok(!value.is_null())
-        }
-        BoundPredicate::In { expr, values } => {
-            let candidate = eval_expr(expr, context, ctx, params, active_branch_commit_id)?;
-            if candidate.is_null() {
-                return Ok(false);
-            }
-            for value_expr in values {
-                let value = eval_expr(value_expr, context, ctx, params, active_branch_commit_id)?;
-                let (candidate, value) = normalize_comparison_operands(
-                    expr,
-                    candidate.clone(),
-                    value_expr,
-                    value,
-                    spec,
-                )?;
-                if !value.is_null() && candidate == value {
-                    return Ok(true);
-                }
-            }
-            Ok(false)
-        }
-    }
-}
-
-fn eval_comparison_operands(
-    left: &BoundExpr,
-    right: &BoundExpr,
-    context: &EntityEvalContext<'_>,
-    spec: &EntitySurfaceSpec,
-    ctx: &mut dyn SqlWriteExecutionContext,
-    params: &[Value],
-    active_branch_commit_id: Option<&str>,
-) -> Result<(JsonValue, JsonValue), LixError> {
-    let left_value = eval_expr(left, context, ctx, params, active_branch_commit_id)?;
-    let right_value = eval_expr(right, context, ctx, params, active_branch_commit_id)?;
-    normalize_comparison_operands(left, left_value, right, right_value, spec)
-}
-
-fn normalize_comparison_operands(
-    left_expr: &BoundExpr,
-    left_value: JsonValue,
-    right_expr: &BoundExpr,
-    right_value: JsonValue,
-    spec: &EntitySurfaceSpec,
-) -> Result<(JsonValue, JsonValue), LixError> {
-    let left_is_json = bound_expr_is_json(left_expr, spec);
-    let right_is_json = bound_expr_is_json(right_expr, spec);
-    Ok((
-        normalize_json_comparison_value(
-            left_expr,
-            left_value,
-            right_is_json,
-            is_identity_json_expr(right_expr),
-        )?,
-        normalize_json_comparison_value(
-            right_expr,
-            right_value,
-            left_is_json,
-            is_identity_json_expr(left_expr),
-        )?,
-    ))
-}
-
-fn normalize_json_comparison_value(
-    expr: &BoundExpr,
-    value: JsonValue,
-    other_side_is_json: bool,
-    other_side_is_identity_json: bool,
-) -> Result<JsonValue, LixError> {
-    if !other_side_is_json {
-        return Ok(value);
-    }
-    let should_parse = matches!(expr, BoundExpr::Param(_))
-        || (other_side_is_identity_json
-            && matches!(expr, BoundExpr::Literal(BoundLiteral::Text(_))));
-    if !should_parse {
-        return Ok(value);
-    }
-    let JsonValue::String(raw) = value else {
-        return Ok(value);
-    };
-    serde_json::from_str(&raw).map_err(|error| {
-        LixError::new(
-            LixError::CODE_TYPE_MISMATCH,
-            format!("JSON comparison parameter is not valid JSON: {error}"),
-        )
-    })
-}
-
-fn validate_bound_write_supported(
-    plan: &LogicalWritePlan,
-    spec: &EntitySurfaceSpec,
-) -> Result<(), LixError> {
-    validate_predicate_supported(&plan.bound.predicate)?;
-    validate_json_predicate_types(&plan.bound.predicate, spec)?;
-    match &plan.bound.input {
-        BoundWriteInput::Values(values) => {
-            for row in &values.rows {
-                for expr in row {
-                    validate_expr_supported(expr)?;
-                }
-            }
-        }
-        BoundWriteInput::Query { .. } | BoundWriteInput::None => {}
-    }
-    for assignment in &plan.bound.assignments {
-        validate_expr_supported(&assignment.value)?;
-    }
-    Ok(())
-}
-
-fn bound_public_write_shape_supported(plan: &LogicalWritePlan) -> bool {
-    let input_supported = match (&plan.bound.op, &plan.bound.input) {
-        (BoundWriteOp::Insert, BoundWriteInput::Values(values)) => values
-            .rows
-            .iter()
-            .flatten()
-            .all(|expr| validate_expr_supported(expr).is_ok()),
-        (BoundWriteOp::Update | BoundWriteOp::Delete, BoundWriteInput::None) => true,
-        _ => false,
-    };
-    input_supported
-        && validate_predicate_supported(&plan.bound.predicate).is_ok()
-        && plan
-            .bound
-            .assignments
-            .iter()
-            .all(|assignment| validate_expr_supported(&assignment.value).is_ok())
-}
-
-fn validate_predicate_supported(
-    predicate: &crate::sql2::plan::predicate::BoundPredicate,
-) -> Result<(), LixError> {
-    use crate::sql2::plan::predicate::BoundPredicate;
-    match predicate {
-        BoundPredicate::True | BoundPredicate::False => Ok(()),
-        BoundPredicate::And(predicates) => {
-            for predicate in predicates {
-                validate_predicate_supported(predicate)?;
-            }
-            Ok(())
-        }
-        BoundPredicate::Or(predicates) => {
-            for predicate in predicates {
-                validate_predicate_supported(predicate)?;
-            }
-            Ok(())
-        }
-        BoundPredicate::Eq(left, right) => {
-            validate_expr_supported(left)?;
-            validate_expr_supported(right)
-        }
-        BoundPredicate::IsNull(expr) | BoundPredicate::IsNotNull(expr) => {
-            validate_expr_supported(expr)
-        }
-        BoundPredicate::In { expr, values } => {
-            validate_expr_supported(expr)?;
-            for value in values {
-                validate_expr_supported(value)?;
-            }
-            Ok(())
-        }
-    }
-}
-
-fn validate_json_predicate_types(
-    predicate: &crate::sql2::plan::predicate::BoundPredicate,
-    spec: &EntitySurfaceSpec,
-) -> Result<(), LixError> {
-    use crate::sql2::plan::predicate::BoundPredicate;
-    match predicate {
-        BoundPredicate::True | BoundPredicate::False => Ok(()),
-        BoundPredicate::And(predicates) => {
-            for predicate in predicates {
-                validate_json_predicate_types(predicate, spec)?;
-            }
-            Ok(())
-        }
-        BoundPredicate::Or(predicates) => {
-            for predicate in predicates {
-                validate_json_predicate_types(predicate, spec)?;
-            }
-            Ok(())
-        }
-        BoundPredicate::Eq(left, right) => validate_json_comparison_operands(left, right, spec),
-        BoundPredicate::IsNull(_) | BoundPredicate::IsNotNull(_) => Ok(()),
-        BoundPredicate::In { expr, values } => {
-            if bound_expr_is_json(expr, spec) {
-                for value in values {
-                    if is_identity_json_expr(expr) && is_parseable_json_text_literal(value) {
-                        continue;
-                    }
-                    require_json_comparison_operand(value, spec)?;
-                }
-            }
-            for value in values {
-                if bound_expr_is_json(value, spec) {
-                    if is_identity_json_expr(value) && is_parseable_json_text_literal(expr) {
-                        continue;
-                    }
-                    require_json_comparison_operand(expr, spec)?;
-                }
-            }
-            Ok(())
-        }
-    }
-}
-
-fn validate_json_comparison_operands(
-    left: &BoundExpr,
-    right: &BoundExpr,
-    spec: &EntitySurfaceSpec,
-) -> Result<(), LixError> {
-    if bound_expr_is_json(left, spec) {
-        if is_identity_json_expr(left) && is_parseable_json_text_literal(right) {
-            return Ok(());
-        }
-        require_json_comparison_operand(right, spec)?;
-    }
-    if bound_expr_is_json(right, spec) {
-        if is_identity_json_expr(right) && is_parseable_json_text_literal(left) {
-            return Ok(());
-        }
-        require_json_comparison_operand(left, spec)?;
-    }
-    Ok(())
-}
-
-fn require_json_comparison_operand(
-    expr: &BoundExpr,
-    spec: &EntitySurfaceSpec,
-) -> Result<(), LixError> {
-    if bound_expr_is_json(expr, spec)
-        || matches!(expr, BoundExpr::Param(_))
-        || matches!(expr, BoundExpr::Literal(BoundLiteral::Null))
-    {
-        return Ok(());
-    }
-    Err(LixError::new(
-        LixError::CODE_TYPE_MISMATCH,
-        "JSON columns can only be compared with JSON expressions",
-    )
-    .with_hint("Wrap JSON text with lix_json(...), use lix_json_get(...) for JSON values, or use IS NULL for null checks."))
-}
-
-fn is_identity_json_expr(expr: &BoundExpr) -> bool {
-    matches!(
-        expr,
-        BoundExpr::Column(column)
-            if matches!(column.name.as_str(), "entity_pk" | "lixcol_entity_pk")
-    )
-}
-
-fn is_parseable_json_text_literal(expr: &BoundExpr) -> bool {
-    match expr {
-        BoundExpr::Literal(BoundLiteral::Text(value)) => {
-            serde_json::from_str::<JsonValue>(value).is_ok()
-        }
-        _ => false,
-    }
-}
-
-fn bound_expr_is_json(expr: &BoundExpr, spec: &EntitySurfaceSpec) -> bool {
-    match expr {
-        BoundExpr::Column(column) => {
-            spec.visible_column(&column.name)
-                .is_some_and(|column| column.column_type == EntityColumnType::Json)
-                || matches!(
-                    column.name.as_str(),
-                    "lixcol_entity_pk" | "lixcol_metadata" | "lixcol_snapshot_content"
-                )
-        }
-        BoundExpr::Literal(BoundLiteral::Json(_)) => true,
-        BoundExpr::Function { name, .. } => matches!(name.as_str(), "lix_json" | "lix_json_get"),
-        _ => false,
-    }
-}
-
-fn validate_expr_supported(expr: &BoundExpr) -> Result<(), LixError> {
-    match expr {
-        BoundExpr::Column(_) | BoundExpr::Param(_) | BoundExpr::Literal(_) => Ok(()),
-        BoundExpr::Function { name, args } => {
-            match name.as_str() {
-                "lix_json" if args.len() == 1 => {}
-                "lix_empty_blob"
-                | "lix_uuid_v7"
-                | "lix_timestamp"
-                | "lix_active_branch_commit_id"
-                    if args.is_empty() => {}
-                "lix_json_get" | "lix_json_get_text" if args.len() >= 2 => {}
-                "lix_text_encode" | "lix_text_decode" if (1..=2).contains(&args.len()) => {}
-                _ => {
-                    return Err(LixError::new(
-                        LixError::CODE_UNSUPPORTED_SQL,
-                        format!("bound entity write does not support function '{name}' yet"),
-                    ));
-                }
-            }
-            for arg in args {
-                validate_expr_supported(arg)?;
-            }
-            Ok(())
-        }
-    }
-}
-
-fn candidate_snapshot(
-    row: &crate::live_state::MaterializedLiveStateRow,
-) -> Result<Option<JsonValue>, LixError> {
-    row.snapshot_content
-        .as_deref()
-        .map(|snapshot| {
-            serde_json::from_str(snapshot).map_err(|error| {
-                LixError::new(
-                    LixError::CODE_TYPE_MISMATCH,
-                    format!("entity row snapshot_content is not valid JSON: {error}"),
-                )
-            })
-        })
-        .transpose()
-}
-
-fn entity_json_value(
-    value: EntityEvalValue,
-    column_type: EntityColumnType,
-) -> Result<JsonValue, LixError> {
-    Ok(match (value, column_type) {
-        (EntityEvalValue::SqlNull, _) => JsonValue::Null,
-        (EntityEvalValue::SqlText(value), EntityColumnType::Json) => {
-            serde_json::from_str(&value).unwrap_or(JsonValue::String(value))
-        }
-        (EntityEvalValue::SqlText(value), _) => JsonValue::String(value),
-        (EntityEvalValue::Json(value), EntityColumnType::Json) => value,
-        (EntityEvalValue::Json(JsonValue::String(value)), EntityColumnType::String) => {
-            JsonValue::String(value)
-        }
-        (EntityEvalValue::Json(JsonValue::Number(value)), EntityColumnType::Integer)
-            if value.is_i64() =>
-        {
-            JsonValue::Number(value)
-        }
-        (
-            EntityEvalValue::Json(JsonValue::Number(value)),
-            EntityColumnType::Number | EntityColumnType::Integer,
-        ) => JsonValue::Number(value),
-        (EntityEvalValue::Json(JsonValue::Bool(value)), EntityColumnType::Boolean) => {
-            JsonValue::Bool(value)
-        }
-        (EntityEvalValue::Json(value), _) => value,
-    })
-}
-
-fn reject_direct_blob_json_value(
-    expr: &BoundExpr,
-    column_type: EntityColumnType,
-    params: &[Value],
-) -> Result<(), LixError> {
-    if column_type != EntityColumnType::Json {
-        return Ok(());
-    }
-    let is_blob = match expr {
-        BoundExpr::Literal(BoundLiteral::Blob(_)) => true,
-        BoundExpr::Param(param) => params
-            .get(param.index.saturating_sub(1))
-            .is_some_and(|value| matches!(value, Value::Blob(_))),
-        _ => false,
-    };
-    if is_blob {
-        return Err(LixError::new(
-            LixError::CODE_INVALID_PARAM,
-            "cannot store blob values directly in JSON entity columns",
-        ));
-    }
-    Ok(())
-}
-
-fn literal_json(literal: &BoundLiteral) -> JsonValue {
-    match literal {
-        BoundLiteral::Null => JsonValue::Null,
-        BoundLiteral::Bool(value) => JsonValue::Bool(*value),
-        BoundLiteral::Integer(value) => JsonValue::from(*value),
-        BoundLiteral::Text(value) => JsonValue::String(value.clone()),
-        BoundLiteral::Json(value) => value.clone(),
-        BoundLiteral::Blob(value) => {
-            JsonValue::Array(value.iter().copied().map(JsonValue::from).collect())
-        }
-    }
-}
-
-fn value_eval(value: &Value) -> EntityEvalValue {
-    match value {
-        Value::Null => EntityEvalValue::SqlNull,
-        Value::Text(value) => EntityEvalValue::SqlText(value.clone()),
-        _ => EntityEvalValue::Json(value_json(value)),
-    }
-}
-
-fn value_json(value: &Value) -> JsonValue {
-    match value {
-        Value::Null => JsonValue::Null,
-        Value::Boolean(value) => JsonValue::Bool(*value),
-        Value::Integer(value) => JsonValue::from(*value),
-        Value::Real(value) => serde_json::Number::from_f64(*value)
-            .map(JsonValue::Number)
-            .unwrap_or(JsonValue::Null),
-        Value::Text(value) => JsonValue::String(value.clone()),
-        Value::Json(value) => value.clone(),
-        Value::Blob(value) => {
-            JsonValue::Array(value.iter().copied().map(JsonValue::from).collect())
-        }
-    }
-}
-
-fn json_path_get(
-    value: &JsonValue,
-    segment: &JsonValue,
-    fn_name: &str,
-) -> Result<Option<JsonValue>, LixError> {
-    match segment {
-        JsonValue::String(key) => {
-            if key == "$" || key.starts_with("$.") || key.starts_with("$[") || key.starts_with('/')
-            {
-                return Err(LixError::new(
-                    LixError::CODE_TYPE_MISMATCH,
-                    format!(
-                        "{fn_name}() uses variadic path segments, not JSONPath or JSON Pointer; got '{key}'"
-                    ),
-                ));
-            }
-            Ok(value.get(key).cloned())
-        }
-        JsonValue::Number(number) => {
-            let Some(index) = number
-                .as_u64()
-                .and_then(|value| usize::try_from(value).ok())
-            else {
-                return Err(LixError::new(
-                    LixError::CODE_TYPE_MISMATCH,
-                    format!("{fn_name}() path indexes must be non-negative integers"),
-                ));
-            };
-            Ok(value
-                .as_array()
-                .and_then(|values| values.get(index))
-                .cloned())
-        }
-        JsonValue::Null => Ok(None),
-        other => Err(LixError::new(
-            LixError::CODE_TYPE_MISMATCH,
-            format!(
-                "{fn_name}() path arguments must be strings or non-negative integers, got {other}"
-            ),
-        )),
-    }
-}
-
-fn json_text_value(value: &JsonValue) -> Result<String, LixError> {
-    match value {
-        JsonValue::String(text) => Ok(text.clone()),
-        JsonValue::Number(number) => Ok(number.to_string()),
-        JsonValue::Bool(boolean) => Ok(boolean.to_string()),
-        JsonValue::Array(_) | JsonValue::Object(_) => {
-            serde_json::to_string(value).map_err(|error| {
-                LixError::new(
-                    LixError::CODE_TYPE_MISMATCH,
-                    format!("lix_json_get_text() could not render JSON value: {error}"),
-                )
-            })
-        }
-        JsonValue::Null => Ok("null".to_string()),
-    }
-}
-
-fn validate_utf8_encoding(value: JsonValue, fn_name: &str) -> Result<(), LixError> {
-    let value = json_text_value(&value)?;
-    let normalized = value.trim().to_ascii_uppercase().replace('-', "");
-    if normalized == "UTF8" {
-        Ok(())
-    } else {
-        Err(LixError::new(
-            LixError::CODE_TYPE_MISMATCH,
-            format!("{fn_name}() only supports UTF8 encoding, got '{value}'"),
-        ))
-    }
-}
-
-fn text_like_bytes(value: &JsonValue, fn_name: &str) -> Result<Vec<u8>, LixError> {
-    Ok(match value {
-        JsonValue::String(value) => value.as_bytes().to_vec(),
-        JsonValue::Number(value) => value.to_string().into_bytes(),
-        JsonValue::Bool(value) => value.to_string().into_bytes(),
-        JsonValue::Array(values) => values
-            .iter()
-            .map(byte_from_json_value)
-            .collect::<Result<Vec<_>, _>>()?,
-        JsonValue::Null => Vec::new(),
-        other => {
-            return Err(LixError::new(
-                LixError::CODE_TYPE_MISMATCH,
-                format!("{fn_name}() expected text or binary-compatible input, got {other}"),
-            ));
-        }
-    })
-}
-
-fn binary_like_bytes(value: &JsonValue, fn_name: &str) -> Result<Vec<u8>, LixError> {
-    match value {
-        JsonValue::Array(values) => values.iter().map(byte_from_json_value).collect(),
-        JsonValue::String(value) => Ok(value.as_bytes().to_vec()),
-        JsonValue::Null => Ok(Vec::new()),
-        other => Err(LixError::new(
-            LixError::CODE_TYPE_MISMATCH,
-            format!("{fn_name}() expected binary or text-compatible input, got {other}"),
-        )),
-    }
-}
-
-fn byte_from_json_value(value: &JsonValue) -> Result<u8, LixError> {
-    value
-        .as_u64()
-        .and_then(|value| u8::try_from(value).ok())
-        .ok_or_else(|| {
-            LixError::new(
-                LixError::CODE_TYPE_MISMATCH,
-                format!("binary value must contain integer bytes, got {value}"),
-            )
-        })
-}
-
-fn column_eval_value(
-    context: &EntityEvalContext<'_>,
-    column_name: &str,
-) -> Result<EntityEvalValue, LixError> {
-    if let Some(value) = context.snapshot.get(column_name) {
-        return Ok(visible_column_eval_value(
-            context
-                .visible_columns
-                .iter()
-                .find(|column| column.name == column_name),
-            value,
-        ));
-    }
-    let Some(row) = context.row else {
-        return Ok(EntityEvalValue::SqlNull);
-    };
-    match column_name {
-        "lixcol_entity_pk" => row
-            .entity_pk
-            .as_json_array_value()
-            .map(EntityEvalValue::Json),
-        "lixcol_schema_key" => Ok(EntityEvalValue::Json(JsonValue::String(
-            row.schema_key.clone(),
-        ))),
-        "lixcol_file_id" => Ok(row
-            .file_id
-            .as_ref()
-            .map(|value| EntityEvalValue::Json(JsonValue::String(value.clone())))
-            .unwrap_or(EntityEvalValue::SqlNull)),
-        "lixcol_metadata" => row
-            .metadata
-            .as_ref()
-            .map(|metadata| parse_row_metadata_value(metadata, &row.schema_key))
-            .transpose()
-            .map(|metadata| {
-                metadata
-                    .map(EntityEvalValue::Json)
-                    .unwrap_or(EntityEvalValue::SqlNull)
-            }),
-        "lixcol_change_id" => Ok(row
-            .change_id
-            .as_ref()
-            .map(|value| EntityEvalValue::Json(JsonValue::String(value.clone())))
-            .unwrap_or(EntityEvalValue::SqlNull)),
-        "lixcol_created_at" => Ok(EntityEvalValue::Json(JsonValue::String(
-            row.created_at.clone(),
-        ))),
-        "lixcol_updated_at" => Ok(EntityEvalValue::Json(JsonValue::String(
-            row.updated_at.clone(),
-        ))),
-        "lixcol_commit_id" => Ok(row
-            .commit_id
-            .as_ref()
-            .map(|value| EntityEvalValue::Json(JsonValue::String(value.clone())))
-            .unwrap_or(EntityEvalValue::SqlNull)),
-        "lixcol_global" => Ok(EntityEvalValue::Json(JsonValue::Bool(row.global))),
-        "lixcol_untracked" => Ok(EntityEvalValue::Json(JsonValue::Bool(row.untracked))),
-        "lixcol_branch_id" => Ok(EntityEvalValue::Json(JsonValue::String(
-            row.branch_id.clone(),
-        ))),
-        _ => Ok(EntityEvalValue::SqlNull),
-    }
-}
-
-fn visible_column_eval_value(
-    column: Option<&EntitySurfaceColumn>,
-    value: &JsonValue,
-) -> EntityEvalValue {
-    match (column.map(|column| column.column_type), value) {
-        (Some(EntityColumnType::String), JsonValue::String(value)) => {
-            EntityEvalValue::SqlText(value.clone())
-        }
-        _ => EntityEvalValue::Json(value.clone()),
-    }
-}
-
-fn scan_branch_ids(scope: &BranchScope) -> Result<Vec<String>, LixError> {
-    Ok(match scope {
-        BranchScope::Active { branch_id } => vec![branch_id.clone()],
-        BranchScope::Explicit { branch_ids } | BranchScope::ExplicitRequired { branch_ids } => {
-            branch_ids.iter().cloned().collect()
-        }
-        BranchScope::ExplicitDynamic { .. } | BranchScope::ExplicitRequiredDynamic { .. } => {
-            return Err(LixError::new(
-                LixError::CODE_INVALID_PARAM,
-                "parameterized branch scope was not resolved before write execution",
-            ));
-        }
-        BranchScope::Global => vec![crate::GLOBAL_BRANCH_ID.to_string()],
-        BranchScope::Empty => Vec::new(),
-    })
-}
-
-fn entity_row_branch_id(
-    plan: &LogicalWritePlan,
-    explicit_branch_id: Option<String>,
-    global: bool,
-) -> Result<String, LixError> {
-    if global {
-        let target_branch_ids = insert_target_branch_ids(&plan.bound.branch_scope);
-        let target_is_by_branch = matches!(
-            &plan.bound.target,
-            BoundWriteTarget::Entity(EntityWriteSurface::ByBranch { .. })
-        );
-        if explicit_branch_id
-            .as_deref()
-            .is_some_and(|branch_id| branch_id != crate::GLOBAL_BRANCH_ID)
-        {
-            return Err(LixError::new(
-                LixError::CODE_TYPE_MISMATCH,
-                "entity INSERT cannot combine lixcol_global = true with a non-global lixcol_branch_id",
-            ));
-        }
-        if target_is_by_branch
-            && target_branch_ids.iter().any(|branch_ids| {
-                !branch_ids
-                    .iter()
-                    .any(|branch_id| branch_id == crate::GLOBAL_BRANCH_ID)
-            })
-        {
-            return Err(LixError::new(
-                LixError::CODE_TYPE_MISMATCH,
-                "entity INSERT cannot combine lixcol_global = true with a non-global target branch",
-            ));
-        }
-        return Ok(crate::GLOBAL_BRANCH_ID.to_string());
-    }
-    if explicit_branch_id.as_deref() == Some(crate::GLOBAL_BRANCH_ID) {
-        return Err(LixError::new(
-            LixError::CODE_TYPE_MISMATCH,
-            "entity INSERT with lixcol_branch_id = 'global' must also set lixcol_global = true",
-        ));
-    }
-    let target_is_by_branch = matches!(
-        &plan.bound.target,
-        BoundWriteTarget::Entity(EntityWriteSurface::ByBranch { .. })
-    );
-    if target_is_by_branch && matches!(plan.bound.branch_scope, BranchScope::Global) {
-        return Err(LixError::new(
-            LixError::CODE_TYPE_MISMATCH,
-            "entity INSERT into the global scope must set lixcol_global = true",
-        ));
-    }
-    if let Some(branch_id) = explicit_branch_id {
-        if target_is_by_branch {
-            let target_branch_ids = insert_target_branch_ids(&plan.bound.branch_scope);
-            if let Some(target_branch_ids) = &target_branch_ids {
-                if !target_branch_ids.contains(&branch_id) {
-                    return Err(LixError::new(
-                        LixError::CODE_TYPE_MISMATCH,
-                        format!(
-                            "entity INSERT lixcol_branch_id '{branch_id}' does not match the target branch scope"
-                        ),
-                    ));
-                }
-            } else {
-                return Err(LixError::new(
-                    LixError::CODE_TYPE_MISMATCH,
-                    "entity INSERT has no target branch scope",
-                ));
-            }
-        }
-        return Ok(branch_id);
-    }
-    match &plan.bound.branch_scope {
-        BranchScope::Active { branch_id } => Ok(branch_id.clone()),
-        BranchScope::ExplicitRequired { branch_ids } if branch_ids.len() == 1 => {
-            Ok(branch_ids.iter().next().expect("len checked").clone())
-        }
-        BranchScope::Explicit { branch_ids } if branch_ids.len() == 1 => {
-            Ok(branch_ids.iter().next().expect("len checked").clone())
-        }
-        BranchScope::ExplicitDynamic { .. } | BranchScope::ExplicitRequiredDynamic { .. } => {
-            Err(LixError::new(
-                LixError::CODE_INVALID_PARAM,
-                "parameterized branch scope was not resolved before write execution",
-            ))
-        }
-        BranchScope::Global => Ok(crate::GLOBAL_BRANCH_ID.to_string()),
-        BranchScope::Empty => Ok(crate::GLOBAL_BRANCH_ID.to_string()),
-        _ => Err(LixError::new(
-            LixError::CODE_UNSUPPORTED_SQL,
-            "entity write requires exactly one target branch",
-        )),
-    }
-}
-
-fn insert_target_branch_ids(scope: &BranchScope) -> Option<Vec<String>> {
-    match scope {
-        BranchScope::Active { branch_id } => Some(vec![branch_id.clone()]),
-        BranchScope::Explicit { branch_ids } | BranchScope::ExplicitRequired { branch_ids } => {
-            Some(branch_ids.iter().cloned().collect())
-        }
-        BranchScope::ExplicitDynamic { .. } | BranchScope::ExplicitRequiredDynamic { .. } => None,
-        BranchScope::Global => Some(vec![crate::GLOBAL_BRANCH_ID.to_string()]),
-        BranchScope::Empty => Some(Vec::new()),
-    }
-}
-
-fn assignment_value<'a>(plan: &'a LogicalWritePlan, column_name: &str) -> Option<&'a BoundExpr> {
-    plan.bound
-        .assignments
-        .iter()
-        .find(|assignment| assignment.column.name == column_name)
-        .map(|assignment| &assignment.value)
-}
-
-fn optional_metadata_from_eval_value(
-    value: EntityEvalValue,
-    column_name: &str,
-    context: &str,
-) -> Result<Option<TransactionJson>, LixError> {
-    let metadata = match value {
-        EntityEvalValue::SqlNull => return Ok(None),
-        EntityEvalValue::SqlText(value) => parse_row_metadata_value(&value, context)?,
-        EntityEvalValue::Json(value) => {
-            validate_row_metadata(&value, context)?;
-            value
-        }
-    };
-    TransactionJson::from_value(metadata, &format!("{context} {column_name}")).map(Some)
-}
-
-fn text_value(value: JsonValue, column_name: &str) -> Result<Option<String>, LixError> {
-    match value {
-        JsonValue::Null => Ok(None),
-        JsonValue::String(value) => Ok(Some(value)),
-        other => Err(LixError::new(
-            LixError::CODE_TYPE_MISMATCH,
-            format!("entity write expected text-compatible column '{column_name}', got {other}"),
-        )),
-    }
-}
-
-fn bool_value(value: JsonValue, column_name: &str) -> Result<Option<bool>, LixError> {
-    match value {
-        JsonValue::Null => Ok(None),
-        JsonValue::Bool(value) => Ok(Some(value)),
-        other => Err(LixError::new(
-            LixError::CODE_TYPE_MISMATCH,
-            format!("entity write expected boolean column '{column_name}', got {other}"),
-        )),
-    }
-}
-
-fn entity_pk_from_value(value: &JsonValue, column_name: &str) -> Result<EntityPk, LixError> {
-    match value {
-        JsonValue::String(value) => EntityPk::from_json_array_text(value).map_err(|error| {
-            LixError::new(
-                LixError::CODE_TYPE_MISMATCH,
-                format!("entity write has invalid {column_name}: {error}"),
-            )
-        }),
-        value => EntityPk::from_json_array_value(value).map_err(|error| {
-            LixError::new(
-                LixError::CODE_TYPE_MISMATCH,
-                format!("entity write has invalid {column_name}: {error}"),
-            )
-        }),
-    }
-}
-
-fn entity_action(op: &BoundWriteOp) -> &'static str {
-    match op {
-        BoundWriteOp::Insert => "INSERT into entity surface",
-        BoundWriteOp::Update => "UPDATE entity surface",
-        BoundWriteOp::Delete => "DELETE from entity surface",
-    }
-}