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

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

@@ -7,11 +7,12 @@ use datafusion::logical_expr::{Expr, Operator};
 use tokio::sync::Mutex;
 
 use crate::commit_graph::{CommitGraphChangeHistoryRequest, CommitGraphReader};
-use crate::entity_identity::EntityIdentity;
+use crate::entity_pk::EntityPk;
 use crate::LixError;
 
 use super::SqlJsonReader;
-use crate::commit_store::{materialize_change, MaterializedChange};
+use crate::sql2::change_materialization::{materialize_located_history_change, MaterializedChange};
+use crate::storage::StorageRead;
 
 /// Shared routing state for commit-shaped history SQL surfaces.
 ///
@@ -21,7 +22,7 @@ use crate::commit_store::{materialize_change, MaterializedChange};
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub(crate) struct HistoryRoute {
     pub(crate) start_commit_ids: Vec<String>,
-    pub(crate) entity_ids: Vec<String>,
+    pub(crate) entity_pks: Vec<String>,
     pub(crate) schema_keys: Vec<String>,
     pub(crate) file_ids: Vec<String>,
     pub(crate) min_depth: Option<i64>,
@@ -82,7 +83,7 @@ impl HistoryRoute {
     pub(crate) fn matches_surface_row(
         &self,
         schema_key: &str,
-        entity_id: &str,
+        entity_pk: &str,
         file_id: Option<&str>,
         depth: u32,
     ) -> bool {
@@ -97,11 +98,11 @@ impl HistoryRoute {
         {
             return false;
         }
-        if !self.entity_ids.is_empty()
+        if !self.entity_pks.is_empty()
             && !self
-                .entity_ids
+                .entity_pks
                 .iter()
-                .any(|candidate| candidate == entity_id)
+                .any(|candidate| candidate == entity_pk)
         {
             return false;
         }
@@ -140,7 +141,7 @@ pub(crate) struct HistoryEntry {
     pub(crate) depth: u32,
 }
 
-pub(crate) const HISTORY_COL_ENTITY_ID: &str = "lixcol_entity_id";
+pub(crate) const HISTORY_COL_ENTITY_PK: &str = "lixcol_entity_pk";
 pub(crate) const HISTORY_COL_SCHEMA_KEY: &str = "lixcol_schema_key";
 pub(crate) const HISTORY_COL_FILE_ID: &str = "lixcol_file_id";
 pub(crate) const HISTORY_COL_SNAPSHOT_CONTENT: &str = "lixcol_snapshot_content";
@@ -187,10 +188,10 @@ pub(crate) fn commit_graph_history_request(
 ) -> Option<CommitGraphChangeHistoryRequest> {
     let schema_keys = effective_schema_keys(route, schema_keys)?;
     Some(CommitGraphChangeHistoryRequest {
-        entity_ids: route
-            .entity_ids
+        entity_pks: route
+            .entity_pks
             .iter()
-            .filter_map(|entity_id| EntityIdentity::from_json_array_text(entity_id).ok())
+            .filter_map(|entity_pk| EntityPk::from_json_array_text(entity_pk).ok())
             .collect(),
         schema_keys,
         file_ids: route.file_ids.clone(),
@@ -200,17 +201,20 @@ pub(crate) fn commit_graph_history_request(
     })
 }
 
-/// Loads commit-graph history once for all SQL history providers.
+/// Loads reachability-aware commit-graph history once for all SQL history providers.
 ///
 /// Providers pass the schema keys they know how to shape. An empty list means
 /// "do not constrain by provider schema"; this is what `lix_state_history` uses.
-pub(crate) async fn load_history_entries(
+pub(crate) async fn load_history_entries<S>(
     descriptor: HistoryViewDescriptor<'_>,
     commit_graph: Arc<Mutex<Box<dyn CommitGraphReader>>>,
-    mut json_reader: SqlJsonReader,
+    mut json_reader: SqlJsonReader<S>,
     route: &HistoryRoute,
     schema_keys: Vec<String>,
-) -> Result<Vec<HistoryEntry>, LixError> {
+) -> Result<Vec<HistoryEntry>, LixError>
+where
+    S: StorageRead + Clone + Send + Sync + 'static,
+{
     if route.is_contradictory() {
         return Ok(Vec::new());
     }
@@ -223,7 +227,7 @@ pub(crate) async fn load_history_entries(
             ),
         )
         .with_hint(format!(
-            "Use WHERE {} = lix_active_version_commit_id() to inspect {} from the active version head.",
+            "Use WHERE {} = lix_active_branch_commit_id() to inspect {} from the active branch head.",
             descriptor.start_commit_column, descriptor.view_name
         )));
     }
@@ -252,7 +256,7 @@ pub(crate) async fn load_history_entries(
             .collect::<BTreeMap<_, _>>();
 
         for entry in entries {
-            let change = materialize_change(&mut json_reader, entry.located_change).await?;
+            let change = materialize_located_history_change(&mut json_reader, entry.change).await?;
             rows.push(HistoryEntry {
                 commit_created_at: commit_created_at_by_id
                     .get(&entry.observed_commit_id)
@@ -366,7 +370,7 @@ fn parse_history_disjunction(
 #[derive(Debug, Clone, PartialEq, Eq)]
 enum HistoryFilterTerm {
     StartCommitIds(Vec<String>),
-    EntityIds(Vec<String>),
+    EntityPks(Vec<String>),
     SchemaKeys(Vec<String>),
     FileIds(Vec<String>),
     MinDepth(i64),
@@ -383,9 +387,9 @@ fn merge_history_disjunction_terms(
             extend_unique(&mut left, right);
             Some(HistoryFilterTerm::StartCommitIds(left))
         }
-        (HistoryFilterTerm::EntityIds(mut left), HistoryFilterTerm::EntityIds(right)) => {
+        (HistoryFilterTerm::EntityPks(mut left), HistoryFilterTerm::EntityPks(right)) => {
             extend_unique(&mut left, right);
-            Some(HistoryFilterTerm::EntityIds(left))
+            Some(HistoryFilterTerm::EntityPks(left))
         }
         (HistoryFilterTerm::FileIds(mut left), HistoryFilterTerm::FileIds(right)) => {
             extend_unique(&mut left, right);
@@ -419,8 +423,8 @@ fn parse_history_binary_filter(
                 _ => unreachable!(),
             })
         }
-        ("entity_id", Operator::Eq, Expr::Literal(ScalarValue::Utf8(Some(value)), _)) => {
-            canonical_entity_id_value(value).map(|value| HistoryFilterTerm::EntityIds(vec![value]))
+        ("entity_pk", Operator::Eq, Expr::Literal(ScalarValue::Utf8(Some(value)), _)) => {
+            canonical_entity_pk_value(value).map(|value| HistoryFilterTerm::EntityPks(vec![value]))
         }
         ("depth", Operator::Eq, depth_expr) => {
             scalar_i64_literal(depth_expr).map(HistoryFilterTerm::ExactDepth)
@@ -464,7 +468,7 @@ fn parse_history_in_list_filter(
 
     match column_name {
         "start_commit_id" => Some(HistoryFilterTerm::StartCommitIds(values)),
-        "entity_id" => canonical_entity_id_values(values).map(HistoryFilterTerm::EntityIds),
+        "entity_pk" => canonical_entity_pk_values(values).map(HistoryFilterTerm::EntityPks),
         "schema_key" => Some(HistoryFilterTerm::SchemaKeys(values)),
         "file_id" => Some(HistoryFilterTerm::FileIds(values)),
         _ => None,
@@ -478,9 +482,9 @@ fn apply_history_filter(expr: &Expr, route: &mut HistoryRoute, column_style: His
                 route.contradictory |=
                     apply_conjunctive_values_filter(&mut route.start_commit_ids, values)
             }
-            HistoryFilterTerm::EntityIds(values) => {
+            HistoryFilterTerm::EntityPks(values) => {
                 route.contradictory |=
-                    apply_conjunctive_values_filter(&mut route.entity_ids, values)
+                    apply_conjunctive_values_filter(&mut route.entity_pks, values)
             }
             HistoryFilterTerm::SchemaKeys(values) => {
                 route.contradictory |=
@@ -518,15 +522,15 @@ fn apply_conjunctive_values_filter(bucket: &mut Vec<String>, incoming_values: Ve
     bucket.is_empty()
 }
 
-fn canonical_entity_id_values(values: Vec<String>) -> Option<Vec<String>> {
+fn canonical_entity_pk_values(values: Vec<String>) -> Option<Vec<String>> {
     values
         .into_iter()
-        .map(|value| canonical_entity_id_value(&value))
+        .map(|value| canonical_entity_pk_value(&value))
         .collect()
 }
 
-fn canonical_entity_id_value(value: &str) -> Option<String> {
-    EntityIdentity::from_json_array_text(value)
+fn canonical_entity_pk_value(value: &str) -> Option<String> {
+    EntityPk::from_json_array_text(value)
         .ok()?
         .as_json_array_text()
         .ok()
@@ -536,8 +540,8 @@ fn canonical_history_column_name(name: &str, column_style: HistoryColumnStyle) -
     match (column_style, name) {
         (HistoryColumnStyle::Bare, "start_commit_id")
         | (HistoryColumnStyle::Prefixed, "lixcol_start_commit_id") => Some("start_commit_id"),
-        (HistoryColumnStyle::Bare, "entity_id")
-        | (HistoryColumnStyle::Prefixed, "lixcol_entity_id") => Some("entity_id"),
+        (HistoryColumnStyle::Bare, "entity_pk")
+        | (HistoryColumnStyle::Prefixed, "lixcol_entity_pk") => Some("entity_pk"),
         (HistoryColumnStyle::Bare, "schema_key")
         | (HistoryColumnStyle::Prefixed, "lixcol_schema_key") => Some("schema_key"),
         (HistoryColumnStyle::Bare, "file_id")

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

@@ -1,46 +1,52 @@
-mod change_provider;
-mod classify;
+mod bind;
+mod branch_scope;
+mod catalog;
+mod change_materialization;
 mod context;
-mod directory_history_provider;
-mod directory_provider;
 mod dml;
-mod entity_history_provider;
-mod entity_provider;
 mod error;
-mod execute;
-mod file_history_provider;
-mod file_provider;
+mod exec;
 mod filesystem_planner;
 mod filesystem_predicates;
 mod filesystem_visibility;
 mod history_projection;
-mod history_provider;
 mod history_route;
-mod lix_state_provider;
+mod optimize;
+mod parse;
+mod plan;
 mod predicate_typecheck;
-mod public_bind;
+mod providers;
 mod read_only;
 mod record_batch;
 mod result_metadata;
 mod runtime;
 mod session;
+pub(crate) mod storage;
+#[cfg(test)]
+mod test_support;
 mod udfs;
-mod version_provider;
-mod version_scope;
 mod write_normalization;
 
-pub(crate) use classify::{
-    classify_statement, datafusion_statement_dml_target_table_names,
-    validate_supported_datafusion_statement_ast, validate_supported_statement_ast,
-    SqlStatementKind,
+pub(crate) use bind::{
+    bind_read_statement, bind_statement, bind_statement_route,
+    statement_has_durable_runtime_function, BoundStatementRoute,
 };
 pub(crate) use context::{
-    CommitStoreQuerySource, SqlCommitStoreQuerySource, SqlExecutionContext, SqlJsonReader,
-    SqlWriteContext, SqlWriteExecutionContext, WriteAccess, WriteContextLiveStateReader,
-    WriteContextVersionRefReader,
+    ChangelogQuerySource, HistoryQuerySource, SqlChangelogQuerySource, SqlExecutionContext,
+    SqlHistoryQuerySource, SqlJsonReader, SqlWriteContext, SqlWriteExecutionContext, WriteAccess,
+    WriteContextBranchRefReader, WriteContextLiveStateReader,
 };
 #[allow(unused_imports)]
-pub(crate) use execute::{
-    create_logical_plan, create_write_logical_plan, execute_logical_plan, execute_sql,
-    SqlLogicalPlan,
+pub(crate) use exec::{
+    create_logical_plan, create_logical_plan_from_parsed,
+    create_transaction_read_logical_plan_from_parsed, create_write_logical_plan,
+    create_write_logical_plan_from_parsed, execute_logical_plan, execute_sql,
+    execute_write_logical_plan, SqlLogicalPlan,
 };
+#[cfg(test)]
+pub(crate) use exec::{
+    execute_write_logical_plan_with_mode, execute_write_logical_plan_with_mode_and_trace,
+    WriteExecutorMode, WriteExecutorPath,
+};
+pub(crate) use parse::parse_statement;
+pub(crate) use plan::plan_write;

package/dist-engine-src/src/sql2/optimize/datafusion.rs

@@ -0,0 +1 @@
+//! DataFusion optimization hooks for bound sql2 plans.

package/dist-engine-src/src/sql2/optimize/mod.rs

@@ -0,0 +1,2 @@
+pub(crate) mod datafusion;
+pub(crate) mod simple_write;

package/dist-engine-src/src/sql2/optimize/simple_write.rs

@@ -0,0 +1,116 @@
+use crate::sql2::bind::write::{BoundWriteOp, BoundWriteTarget};
+use crate::sql2::plan::branch_scope::BranchScope;
+use crate::sql2::plan::predicate::FilterSet;
+use crate::sql2::plan::LogicalWritePlan;
+use crate::LixError;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) enum FastWritePlan {
+    Update(FastUpdatePlan),
+    Delete(FastDeletePlan),
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) struct FastUpdatePlan;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) struct FastDeletePlan;
+
+pub(crate) fn try_make_fast_write_plan(
+    plan: &LogicalWritePlan,
+) -> Result<Option<FastWritePlan>, LixError> {
+    if !is_supported_fast_target(plan) || !is_known_no_match(plan) {
+        return Ok(None);
+    }
+
+    Ok(match plan.bound.op {
+        BoundWriteOp::Insert => None,
+        BoundWriteOp::Update => Some(FastWritePlan::Update(FastUpdatePlan)),
+        BoundWriteOp::Delete => Some(FastWritePlan::Delete(FastDeletePlan)),
+    })
+}
+
+fn is_supported_fast_target(plan: &LogicalWritePlan) -> bool {
+    matches!(
+        plan.bound.target,
+        BoundWriteTarget::LixState | BoundWriteTarget::LixStateByBranch
+    )
+}
+
+fn is_known_no_match(plan: &LogicalWritePlan) -> bool {
+    matches!(plan.bound.branch_scope, BranchScope::Empty)
+        || matches!(plan.filters.rows, FilterSet::None)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::sql2::bind::bind_statement;
+    use crate::sql2::parse_statement;
+    use crate::sql2::plan::plan_write;
+
+    #[test]
+    fn try_make_fast_write_plan_declines_column_contradictions() {
+        let plan = plan_sql(
+            "UPDATE lix_state SET metadata = '{}' \
+             WHERE schema_key = 'profile' AND schema_key = 'note'",
+        );
+
+        assert_eq!(
+            try_make_fast_write_plan(&plan).expect("optimization should not fail"),
+            None
+        );
+    }
+
+    #[test]
+    fn try_make_fast_write_plan_accepts_false_delete_as_noop() {
+        let plan = plan_sql("DELETE FROM lix_state WHERE false");
+
+        assert_eq!(
+            try_make_fast_write_plan(&plan).expect("optimization should not fail"),
+            Some(FastWritePlan::Delete(FastDeletePlan))
+        );
+    }
+
+    #[test]
+    fn try_make_fast_write_plan_declines_complex_update() {
+        let plan = plan_sql(
+            "UPDATE lix_state SET metadata = lix_json('{\"schema_key\":\"lix_key_value\"}') \
+             WHERE metadata = lix_json('{\"source\":\"match\"}')",
+        );
+
+        assert_eq!(
+            try_make_fast_write_plan(&plan).expect("optimization should not fail"),
+            None
+        );
+    }
+
+    #[test]
+    fn try_make_fast_write_plan_declines_literal_insert() {
+        let plan = plan_sql(
+            "INSERT INTO lix_state (entity_pk, schema_key, snapshot_content) \
+             VALUES (lix_json('[\"entity-1\"]'), 'lix_key_value', '{}')",
+        );
+
+        assert_eq!(
+            try_make_fast_write_plan(&plan).expect("optimization should not fail"),
+            None
+        );
+    }
+
+    #[test]
+    fn try_make_fast_write_plan_declines_unsupported_targets_even_when_no_match() {
+        let plan = plan_sql("DELETE FROM lix_branch WHERE false");
+
+        assert_eq!(
+            try_make_fast_write_plan(&plan).expect("optimization should not fail"),
+            None
+        );
+    }
+
+    fn plan_sql(sql: &str) -> LogicalWritePlan {
+        let statement = parse_statement(sql).expect("SQL parses");
+        let write = bind_statement(&statement, &[], "branch1").expect("SQL binds");
+        plan_write(write).expect("write plans")
+    }
+}

package/dist-engine-src/src/sql2/parse/mod.rs

@@ -0,0 +1,69 @@
+mod normalize;
+
+use datafusion::sql::parser::{DFParserBuilder, Statement as DataFusionStatement};
+use datafusion::sql::sqlparser::dialect::GenericDialect;
+use datafusion::sql::sqlparser::tokenizer::{Token, Tokenizer};
+use serde_json::json;
+
+use crate::LixError;
+
+pub(crate) fn parse_statement(sql: &str) -> Result<DataFusionStatement, LixError> {
+    let dialect = GenericDialect {};
+    let mut next_index = 1usize;
+    let mut has_anonymous = false;
+    let mut explicit_placeholders = Vec::new();
+
+    let mut tokens = Vec::new();
+    Tokenizer::new(&dialect, sql)
+        .tokenize_with_location_into_buf_with_mapper(&mut tokens, |mut token_span| {
+            if let Token::Placeholder(placeholder) = &token_span.token {
+                if placeholder == "?" {
+                    has_anonymous = true;
+                    token_span.token = Token::Placeholder(format!("${next_index}"));
+                    next_index += 1;
+                } else {
+                    explicit_placeholders.push(placeholder.clone());
+                }
+            }
+            token_span
+        })
+        .map_err(|error| {
+            LixError::new(
+                LixError::CODE_PARSE_ERROR,
+                format!("sql2 SQL tokenize error: {error}"),
+            )
+        })?;
+
+    if has_anonymous && !explicit_placeholders.is_empty() {
+        return Err(LixError::new(
+            LixError::CODE_PARSE_ERROR,
+            "SQL mixes anonymous and explicit parameter placeholders",
+        )
+        .with_hint("Use either anonymous placeholders like ?, ? or numbered placeholders like $1, $2, but not both.")
+        .with_details(json!({
+            "operation": "execute",
+            "explicit_placeholders": explicit_placeholders,
+        })));
+    }
+
+    let mut statements = DFParserBuilder::new(tokens)
+        .with_dialect(&dialect)
+        .build()
+        .map_err(crate::sql2::error::datafusion_error_to_lix_error)?
+        .parse_statements()
+        .map_err(crate::sql2::error::datafusion_error_to_lix_error)?;
+
+    if statements.len() > 1 {
+        return Err(LixError::new(
+            LixError::CODE_UNSUPPORTED_SQL,
+            "Lix SQL only supports one statement per execute() call",
+        ));
+    }
+
+    statements.pop_front().ok_or_else(|| {
+        LixError::new(
+            LixError::CODE_PARSE_ERROR,
+            "sql2 DataFusion error: No SQL statements were provided in the query string",
+        )
+    })
+}

package/dist-engine-src/src/sql2/parse/normalize.rs

@@ -0,0 +1 @@
+//! SQL text normalization belongs in parse-time code, before semantic binding.

package/dist-engine-src/src/sql2/plan/branch_scope.rs

@@ -0,0 +1,24 @@
+use std::collections::BTreeSet;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) enum BranchScope {
+    Active {
+        branch_id: String,
+    },
+    Explicit {
+        branch_ids: BTreeSet<String>,
+    },
+    ExplicitDynamic {
+        branch_ids: BTreeSet<String>,
+        param_indexes: BTreeSet<usize>,
+    },
+    ExplicitRequired {
+        branch_ids: BTreeSet<String>,
+    },
+    ExplicitRequiredDynamic {
+        branch_ids: BTreeSet<String>,
+        param_indexes: BTreeSet<usize>,
+    },
+    Global,
+    Empty,
+}

package/dist-engine-src/src/sql2/plan/mod.rs

@@ -0,0 +1,5 @@
+pub(crate) mod branch_scope;
+pub(crate) mod predicate;
+pub(crate) mod write;
+
+pub(crate) use write::{plan_write, LogicalWritePlan};

package/dist-engine-src/src/sql2/plan/predicate.rs

@@ -0,0 +1,22 @@
+use crate::sql2::bind::expr::BoundExpr;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) enum FilterSet {
+    All,
+    None,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) enum BoundPredicate {
+    True,
+    False,
+    And(Vec<BoundPredicate>),
+    Or(Vec<BoundPredicate>),
+    Eq(BoundExpr, BoundExpr),
+    IsNull(BoundExpr),
+    IsNotNull(BoundExpr),
+    In {
+        expr: BoundExpr,
+        values: Vec<BoundExpr>,
+    },
+}

package/dist-engine-src/src/sql2/plan/write.rs

@@ -0,0 +1,147 @@
+use crate::sql2::bind::write::BoundWrite;
+use crate::sql2::plan::predicate::{BoundPredicate, FilterSet};
+use crate::LixError;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) struct LogicalWritePlan {
+    pub(crate) bound: BoundWrite,
+    pub(crate) filters: PlannedWriteFilters,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) struct PlannedWriteFilters {
+    pub(crate) rows: FilterSet,
+}
+
+pub(crate) fn plan_write(bound: BoundWrite) -> Result<LogicalWritePlan, LixError> {
+    let mut filters = PlannedWriteFilters::default();
+    collect_predicate_filters(&bound.predicate, &mut filters)?;
+
+    Ok(LogicalWritePlan { bound, filters })
+}
+
+impl Default for PlannedWriteFilters {
+    fn default() -> Self {
+        Self {
+            rows: FilterSet::All,
+        }
+    }
+}
+
+impl PlannedWriteFilters {
+    fn set_none(&mut self) {
+        self.rows = FilterSet::None;
+    }
+}
+
+fn collect_predicate_filters(
+    predicate: &BoundPredicate,
+    filters: &mut PlannedWriteFilters,
+) -> Result<(), LixError> {
+    match predicate {
+        BoundPredicate::True => Ok(()),
+        BoundPredicate::False => {
+            filters.set_none();
+            Ok(())
+        }
+        BoundPredicate::And(predicates) => {
+            for predicate in predicates {
+                collect_predicate_filters(predicate, filters)?;
+            }
+            Ok(())
+        }
+        BoundPredicate::Or(_) => Ok(()),
+        BoundPredicate::Eq(_, _)
+        | BoundPredicate::IsNull(_)
+        | BoundPredicate::IsNotNull(_)
+        | BoundPredicate::In { .. } => Ok(()),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::sql2::bind::bind_statement;
+    use crate::sql2::parse_statement;
+    use crate::sql2::plan::branch_scope::BranchScope;
+    use std::collections::BTreeSet;
+
+    #[test]
+    fn plan_write_contradiction_does_not_drop_bound_params() {
+        let plan = plan_sql(
+            "UPDATE lix_state SET metadata = $1 WHERE schema_key IN ('profile') AND schema_key IN ('note') AND entity_pk = $2",
+        );
+
+        assert_eq!(
+            plan.bound.params.params.keys().copied().collect::<Vec<_>>(),
+            vec![1, 2]
+        );
+    }
+
+    #[test]
+    fn plan_write_applies_active_branch_scope_to_base_writes() {
+        let plan = plan_sql("DELETE FROM lix_state WHERE schema_key = 'profile'");
+
+        assert_eq!(
+            plan.bound.branch_scope,
+            BranchScope::Active {
+                branch_id: "branch1".to_string()
+            }
+        );
+    }
+
+    #[test]
+    fn plan_write_keeps_explicit_required_scope_for_by_branch_writes() {
+        let plan = plan_sql("DELETE FROM lix_state_by_branch WHERE branch_id IN ('v1', 'v2')");
+
+        assert_eq!(
+            plan.bound.branch_scope,
+            BranchScope::ExplicitRequired {
+                branch_ids: BTreeSet::from(["v1".to_string(), "v2".to_string()])
+            }
+        );
+    }
+
+    #[test]
+    fn plan_write_false_conjunct_sets_no_match_sentinel() {
+        let plan = plan_sql("UPDATE lix_file SET hidden = true WHERE id = 'file1' AND false");
+
+        assert_eq!(plan.filters.rows, FilterSet::None);
+    }
+
+    #[test]
+    fn plan_write_user_column_names_do_not_become_storage_filters() {
+        let plan = plan_sql_with_schemas(
+            "UPDATE app_doc SET title = 'new' WHERE schema_key = 'draft'",
+            &[serde_json::json!({
+                "x-lix-key": "app_doc",
+                "type": "object",
+                "properties": {
+                    "id": { "type": "string" },
+                    "schema_key": { "type": "string" },
+                    "title": { "type": "string" }
+                },
+                "x-lix-primary-key": ["/id"],
+                "required": ["id", "schema_key", "title"],
+                "additionalProperties": false
+            })],
+        );
+
+        assert_eq!(
+            plan.bound.branch_scope,
+            BranchScope::Active {
+                branch_id: "branch1".to_string()
+            }
+        );
+    }
+
+    fn plan_sql(sql: &str) -> LogicalWritePlan {
+        plan_sql_with_schemas(sql, &[])
+    }
+
+    fn plan_sql_with_schemas(sql: &str, schemas: &[serde_json::Value]) -> LogicalWritePlan {
+        let statement = parse_statement(sql).expect("parse SQL");
+        let write = bind_statement(&statement, schemas, "branch1").expect("bind SQL");
+        plan_write(write).expect("plan write")
+    }
+}