reddb_server/runtime/

impl_ddl.rs

//! DDL execution: CREATE TABLE, DROP TABLE, ALTER TABLE via SQL AST
//!
//! Translates DDL statements into collection-level operations on the
//! underlying `UnifiedStore`.  RedDB uses a flexible schema-on-read
//! model, so column definitions are advisory metadata rather than
//! rigid constraints.

use super::*;
use crate::catalog::CollectionModel;
use crate::runtime::audit_log::{AuditAuthSource, AuditEvent, AuditFieldEscaper, Outcome};
use crate::runtime::ddl::polymorphic_resolver;
use crate::storage::query::ast::{CreateVcsRefQuery, DropVcsRefQuery, VcsRefKind};
use crate::storage::query::{analyze_create_table, resolve_declared_data_type, CreateColumnDef};
use std::collections::{BTreeSet, HashMap, HashSet};

fn vault_master_key_ref(collection: &str) -> String {
    format!("red.vault.{collection}.master_key")
}

impl RedDBRuntime {
    /// Execute CREATE TABLE
    ///
    /// Creates a new collection in the store.  Column definitions are
    /// recorded for introspection but do not enforce rigid schema
    /// constraints.
    pub fn execute_create_table(
        &self,
        raw_query: &str,
        query: &CreateTableQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        if query.collection_model != CollectionModel::Table {
            return self.execute_create_keyed_collection(raw_query, query);
        }
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        let store = self.inner.db.store();
        analyze_create_table(query).map_err(|err| RedDBError::Query(err.to_string()))?;
        // Reject an AI policy that wires a provider/model to a modality it
        // cannot serve — fail at DDL time, before the collection exists,
        // using the capability matrix from #1269.
        if let Some(policy) = &query.ai_policy {
            validate_ai_policy_modalities(policy)?;
        }
        crate::reserved_fields::ensure_no_reserved_public_item_fields(
            query.columns.iter().map(|column| column.name.as_str()),
            &format!("table '{}'", query.name),
        )?;
        // Check if the collection already exists.
        let exists = store.get_collection(&query.name).is_some();
        if exists {
            if query.if_not_exists {
                return Ok(RuntimeQueryResult::ok_message(
                    raw_query.to_string(),
                    &format!("table '{}' already exists", query.name),
                    "create",
                ));
            }
            return Err(RedDBError::Query(format!(
                "table '{}' already exists",
                query.name
            )));
        }

        // Build and validate the contract before mutating storage so invalid
        // SQL types / duplicate columns do not leave partial side effects.
        let contract = collection_contract_from_create_table(query)?;
        validate_event_subscriptions(self, &query.name, &contract.subscriptions)?;
        // Create the collection.
        store
            .create_collection(&query.name)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        for subscription in &contract.subscriptions {
            ensure_event_target_queue(self, &subscription.target_queue)?;
        }
        if let Some(default_ttl_ms) = query.default_ttl_ms {
            self.inner
                .db
                .set_collection_default_ttl_ms(&query.name, default_ttl_ms);
        }
        self.inner
            .db
            .save_collection_contract(contract)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        if let Some(tenant_id) = crate::runtime::impl_core::current_tenant() {
            store.set_config_tree(
                &format!("red.collection_tenants.{}", query.name),
                &crate::serde_json::Value::String(tenant_id),
            );
        }
        self.inner
            .db
            .persist_metadata()
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.refresh_table_planner_stats(&query.name);
        self.invalidate_result_cache();
        // Issue #120 — feed the create into the schema-vocabulary
        // reverse index so AskPipeline (#121) sees this collection.
        let columns: Vec<String> = query.columns.iter().map(|col| col.name.clone()).collect();
        self.schema_vocabulary_apply(
            crate::runtime::schema_vocabulary::DdlEvent::CreateCollection {
                collection: query.name.clone(),
                columns,
                type_tags: Vec::new(),
                description: None,
            },
        );
        // Partition metadata (Phase 2.2 PG parity).
        //
        // When the CREATE TABLE carries a `PARTITION BY RANGE|LIST|HASH (col)`
        // clause, stamp the partition config into `red_config` under
        // `partition.{table}.{by,column}`. Children are registered separately
        // via `ALTER TABLE parent ATTACH PARTITION child ...`.
        if let Some(spec) = &query.partition_by {
            let kind_str = match spec.kind {
                crate::storage::query::ast::PartitionKind::Range => "range",
                crate::storage::query::ast::PartitionKind::List => "list",
                crate::storage::query::ast::PartitionKind::Hash => "hash",
            };
            store.set_config_tree(
                &format!("partition.{}.by", query.name),
                &crate::serde_json::Value::String(kind_str.to_string()),
            );
            store.set_config_tree(
                &format!("partition.{}.column", query.name),
                &crate::serde_json::Value::String(spec.column.clone()),
            );
        }

        // Table-scoped multi-tenancy (Phase 2.5.4).
        //
        // `CREATE TABLE t (...) TENANT BY (col)` declaration:
        //   1. Persists the `tenant_tables.{table}.column` marker so
        //      INSERTs can auto-fill and future opens re-hydrate.
        //   2. Registers the table in the in-memory `tenant_tables`
        //      HashMap used by the DML auto-fill path.
        //   3. Installs an implicit RLS policy equivalent to
        //      `USING (col = CURRENT_TENANT())` across all actions.
        //   4. Flips `rls_enabled_tables` on so the policy applies.
        if let Some(col) = &query.tenant_by {
            store.set_config_tree(
                &format!("tenant_tables.{}.column", query.name),
                &crate::serde_json::Value::String(col.clone()),
            );
            self.register_tenant_table(&query.name, col);
        }

        let ttl_suffix = query
            .default_ttl_ms
            .map(|ttl_ms| format!(" with default TTL {}ms", ttl_ms))
            .unwrap_or_default();

        let tenant_suffix = query
            .tenant_by
            .as_ref()
            .map(|col| format!(" (tenant-scoped by {col})"))
            .unwrap_or_default();

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!(
                "table '{}' created{}{}",
                query.name, ttl_suffix, tenant_suffix
            ),
            "create",
        ))
    }

    fn execute_create_keyed_collection(
        &self,
        raw_query: &str,
        query: &CreateTableQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        if is_system_schema_name(&query.name) {
            return Err(RedDBError::Query("system schema is read-only".to_string()));
        }
        let store = self.inner.db.store();
        let label = polymorphic_resolver::model_name(query.collection_model);
        if store.get_collection(&query.name).is_some() {
            if query.if_not_exists {
                return Ok(RuntimeQueryResult::ok_message(
                    raw_query.to_string(),
                    &format!("{label} '{}' already exists", query.name),
                    "create",
                ));
            }
            return Err(RedDBError::Query(format!(
                "{label} '{}' already exists",
                query.name
            )));
        }

        store
            .create_collection(&query.name)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        if query.collection_model == CollectionModel::Vault {
            self.provision_vault_key_material(&query.name, query.vault_own_master_key)?;
            let key_scope = if query.vault_own_master_key {
                "own"
            } else {
                "cluster"
            };
            store.set_config_tree(
                &format!("red.vault.{}.key_scope", query.name),
                &crate::serde_json::Value::String(key_scope.to_string()),
            );
            store.set_config_tree(
                &format!("red.vault.{}.status", query.name),
                &crate::serde_json::Value::String("sealed".to_string()),
            );
        }
        if query.collection_model == CollectionModel::Metrics {
            for spec in &query.metrics_rollup_policies {
                let policy = crate::storage::timeseries::retention::DownsamplePolicy::parse(spec)
                    .ok_or_else(|| {
                    RedDBError::Query(format!("invalid metrics rollup policy '{}'", spec))
                })?;
                if policy.source != "raw" {
                    return Err(RedDBError::Query(format!(
                        "invalid metrics rollup policy '{}': metrics v0 rollups must use raw as source",
                        spec
                    )));
                }
                if !matches!(
                    policy.aggregation.as_str(),
                    "avg" | "sum" | "min" | "max" | "count"
                ) {
                    return Err(RedDBError::Query(format!(
                        "invalid metrics rollup policy '{}': supported aggregations are avg, sum, min, max, count",
                        spec
                    )));
                }
            }
            if let Some(raw_retention_ms) = query.default_ttl_ms {
                self.inner
                    .db
                    .set_collection_default_ttl_ms(&query.name, raw_retention_ms);
                store.set_config_tree(
                    &format!("red.metrics.{}.raw_retention_ms", query.name),
                    &crate::serde_json::Value::Number(raw_retention_ms as f64),
                );
            }
            let tenant_identity = query
                .tenant_by
                .clone()
                .unwrap_or_else(|| "current_tenant".to_string());
            store.set_config_tree(
                &format!("red.metrics.{}.tenant_identity", query.name),
                &crate::serde_json::Value::String(tenant_identity),
            );
            store.set_config_tree(
                &format!("red.metrics.{}.namespace", query.name),
                &crate::serde_json::Value::String("default".to_string()),
            );
            if !query.metrics_rollup_policies.is_empty() {
                store.set_config_tree(
                    &format!("red.metrics.{}.rollup_policies", query.name),
                    &crate::serde_json::Value::Array(
                        query
                            .metrics_rollup_policies
                            .iter()
                            .cloned()
                            .map(crate::serde_json::Value::String)
                            .collect(),
                    ),
                );
            }
        }
        let contract = if query.collection_model == CollectionModel::Metrics {
            metrics_collection_contract(query)
        } else {
            keyed_collection_contract(
                &query.name,
                query.collection_model,
                query.analytics_config.clone(),
            )
        };
        self.inner
            .db
            .save_collection_contract(contract)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        if let Some(tenant_id) = crate::runtime::impl_core::current_tenant() {
            store.set_config_tree(
                &format!("red.collection_tenants.{}", query.name),
                &crate::serde_json::Value::String(tenant_id),
            );
        }
        self.inner
            .db
            .persist_metadata()
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.invalidate_result_cache();

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!("{label} '{}' created", query.name),
            "create",
        ))
    }

    /// Bootstrap an internal graph collection declared `WITH ANALYTICS`
    /// (issue #803). The SQL DDL path refuses `red.*` names via
    /// [`is_system_schema_name`], so built-ins like `red.topology.cluster`
    /// cannot be created through `CREATE GRAPH`; this method drives the same
    /// contract-build / save / persist path directly, bypassing only that
    /// guard. Idempotent: a no-op when the collection already exists (its
    /// analytics contract is recovered from the WAL on restart), so it is safe
    /// to call unconditionally on every boot.
    pub fn ensure_system_graph_with_analytics(
        &self,
        name: &str,
        outputs: &[crate::catalog::AnalyticsOutput],
    ) -> RedDBResult<()> {
        let store = self.inner.db.store();
        if store.get_collection(name).is_some() {
            return Ok(());
        }
        let analytics_config = outputs
            .iter()
            .map(|output| crate::catalog::AnalyticsViewDescriptor {
                output: *output,
                algorithm: None,
                resolution: None,
                max_iterations: None,
                tolerance: None,
            })
            .collect();
        store
            .create_collection(name)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        let contract = keyed_collection_contract(
            name,
            crate::catalog::CollectionModel::Graph,
            analytics_config,
        );
        self.inner
            .db
            .save_collection_contract(contract)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.inner
            .db
            .persist_metadata()
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.invalidate_result_cache_process_only();
        Ok(())
    }

    pub fn execute_create_collection(
        &self,
        raw_query: &str,
        query: &CreateCollectionQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        let model = match query.kind.as_str() {
            "graph" => CollectionModel::Graph,
            "document" => CollectionModel::Document,
            "metrics" => CollectionModel::Metrics,
            "vector.turbo" => {
                let dimension = query.vector_dimension.ok_or_else(|| {
                    RedDBError::Query(
                        "CREATE COLLECTION KIND vector.turbo requires DIM".to_string(),
                    )
                })?;
                let create = CreateVectorQuery {
                    name: query.name.clone(),
                    dimension,
                    metric: query
                        .vector_metric
                        .unwrap_or(crate::storage::engine::distance::DistanceMetric::Cosine),
                    if_not_exists: query.if_not_exists,
                };
                let result = self.execute_create_vector(raw_query, &create)?;
                // Issue #693 — durable kind marker that distinguishes
                // this collection from the legacy `vector` path on
                // every restart. Runtime state (TurboQuantIndex +
                // TurboExtent) is lazily materialised by
                // `RedDB::turbo_state` on first INSERT/SEARCH so the
                // marker is the only thing that needs to survive.
                let store = self.inner.db.store();
                crate::runtime::vector_turbo_kind::mark_as_turbo(&store, &query.name);
                self.inner
                    .db
                    .persist_metadata()
                    .map_err(|err| RedDBError::Internal(err.to_string()))?;
                // Eagerly construct the state so the TurboExtent (if
                // any) is reserved at creation time rather than on
                // first INSERT. Errors are swallowed: the lazy path in
                // `turbo_state` will retry on the next access.
                let _ = self.inner.db.turbo_state(&query.name);
                return Ok(result);
            }
            // KIND blockchain — issue #523 foundation: stored on top of a
            // Table-shaped collection. The `chain` marker + reserved-column
            // discipline make the difference. Schema validation, conflict
            // retries, and `verify_chain` come in later iterations.
            "blockchain" => CollectionModel::Table,
            other => {
                return Err(RedDBError::Query(format!(
                    "NOT_YET_SUPPORTED: CREATE COLLECTION KIND {other} is not implemented"
                )));
            }
        };
        let create = CreateTableQuery {
            collection_model: model,
            name: query.name.clone(),
            columns: Vec::new(),
            if_not_exists: query.if_not_exists,
            default_ttl_ms: None,
            metrics_rollup_policies: Vec::new(),
            context_index_fields: Vec::new(),
            context_index_enabled: false,
            timestamps: false,
            partition_by: None,
            tenant_by: None,
            append_only: false,
            subscriptions: Vec::new(),
            analytics_config: Vec::new(),
            vault_own_master_key: false,
            ai_policy: None,
        };
        let result = self.execute_create_table(raw_query, &create)?;
        if query.kind == "blockchain" {
            self.install_blockchain_kind(&query.name)?;
        }
        // Issue #522 — wire `SIGNED_BY (...)` into the runtime. The parser
        // already produces a validated 32-byte pubkey list; installing
        // the registry stamps the per-collection signer set into
        // `red_config` so the INSERT path can load it cheaply.
        if !query.allowed_signers.is_empty() {
            let actor = crate::runtime::impl_core::current_user_projected()
                .unwrap_or_else(|| "@system/create-collection".to_string());
            crate::runtime::signed_writes_kind::install(
                &self.inner.db.store(),
                &query.name,
                &query.allowed_signers,
                &actor,
            );
        }
        Ok(result)
    }

    /// Stamp `red.collection.{name}.kind = "chain"` and append the genesis
    /// row. Idempotent against `IF NOT EXISTS`: if the collection already
    /// has a row at height 0 we leave it.
    fn install_blockchain_kind(&self, name: &str) -> RedDBResult<()> {
        use crate::runtime::blockchain_kind;
        use crate::storage::unified::{EntityData, EntityId, EntityKind, RowData, UnifiedEntity};
        use std::sync::Arc;

        let store = self.inner.db.store();
        blockchain_kind::mark_as_chain(&store, name);

        let existing_tip = blockchain_kind::chain_tip(&store, name);
        if existing_tip.height.is_some() {
            return Ok(());
        }

        let fields = blockchain_kind::genesis_fields(blockchain_kind::now_ms());
        let named: std::collections::HashMap<String, crate::storage::schema::Value> =
            fields.into_iter().collect();
        let entity = UnifiedEntity::new(
            EntityId::new(0),
            EntityKind::TableRow {
                table: Arc::from(name),
                row_id: 0,
            },
            EntityData::Row(RowData {
                columns: Vec::new(),
                named: Some(named),
                schema: None,
            }),
        );
        store
            .insert_auto(name, entity)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        // #524: prime the in-memory tip cache so the chain-tip endpoint and
        // subsequent INSERTs don't have to scan the collection to find genesis.
        if let Some(tip) = blockchain_kind::chain_tip_full(&store, name) {
            self.inner
                .chain_tip_cache
                .lock()
                .insert(name.to_string(), tip);
        }
        Ok(())
    }

    pub fn execute_create_vector(
        &self,
        raw_query: &str,
        query: &CreateVectorQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        if is_system_schema_name(&query.name) {
            return Err(RedDBError::Query("system schema is read-only".to_string()));
        }
        let store = self.inner.db.store();
        if store.get_collection(&query.name).is_some() {
            if query.if_not_exists {
                return Ok(RuntimeQueryResult::ok_message(
                    raw_query.to_string(),
                    &format!("vector '{}' already exists", query.name),
                    "create",
                ));
            }
            return Err(RedDBError::Query(format!(
                "vector '{}' already exists",
                query.name
            )));
        }

        store
            .create_collection(&query.name)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.inner
            .db
            .save_collection_contract(vector_collection_contract(query))
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        if let Some(tenant_id) = crate::runtime::impl_core::current_tenant() {
            store.set_config_tree(
                &format!("red.collection_tenants.{}", query.name),
                &crate::serde_json::Value::String(tenant_id),
            );
        }
        // Slice G (#675) — register `vector.turbo` as the built-in
        // baseline for every newly-created vector collection. The
        // marker is the durable signal `RedDB::turbo_state` reads to
        // materialise the TurboQuantIndex + TurboExtent on first
        // INSERT/SEARCH. Pre-existing vector collections were created
        // without the marker and stay on the brute-force fallback path
        // until they are explicitly migrated — there is no implicit
        // backfill in this slice.
        crate::runtime::vector_turbo_kind::mark_as_turbo(&store, &query.name);
        self.inner
            .db
            .persist_metadata()
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        // Eagerly materialise the per-collection turbo state so the
        // TurboExtent (when the store is paged) is reserved at CREATE
        // time rather than on the first INSERT. Failures are swallowed
        // — the lazy path in `turbo_state` retries on next access.
        let _ = self.inner.db.turbo_state(&query.name);
        self.invalidate_result_cache();

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!("vector '{}' created", query.name),
            "create",
        ))
    }

    fn provision_vault_key_material(
        &self,
        collection: &str,
        own_master_key: bool,
    ) -> RedDBResult<()> {
        let auth_store = self.inner.auth_store.read().clone().ok_or_else(|| {
            RedDBError::Query("CREATE VAULT requires an enabled, unsealed vault".to_string())
        })?;
        if !auth_store.is_vault_backed() {
            return Err(RedDBError::Query(
                "CREATE VAULT requires an enabled, unsealed vault".to_string(),
            ));
        }

        if auth_store.vault_secret_key().is_none() {
            let key = crate::auth::store::random_bytes(32);
            auth_store
                .vault_kv_try_set("red.secret.aes_key".to_string(), hex::encode(key))
                .map_err(|err| RedDBError::Query(err.to_string()))?;
        }

        if own_master_key {
            let key = crate::auth::store::random_bytes(32);
            auth_store
                .vault_kv_try_set(vault_master_key_ref(collection), hex::encode(key))
                .map_err(|err| RedDBError::Query(err.to_string()))?;
        }

        Ok(())
    }

    /// Execute DROP TABLE
    ///
    /// Drops the collection and all its data from the store.
    pub fn execute_drop_table(
        &self,
        raw_query: &str,
        query: &DropTableQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        let store = self.inner.db.store();

        if is_system_schema_name(&query.name) {
            return Err(RedDBError::Query("system schema is read-only".to_string()));
        }

        let exists = store.get_collection(&query.name).is_some();
        if !exists {
            if query.if_exists {
                return Ok(RuntimeQueryResult::ok_message(
                    raw_query.to_string(),
                    &format!("table '{}' does not exist", query.name),
                    "drop",
                ));
            }
            return Err(RedDBError::NotFound(format!(
                "table '{}' not found",
                query.name
            )));
        }
        let actual =
            polymorphic_resolver::resolve(&query.name, &self.inner.db.catalog_model_snapshot())?;
        polymorphic_resolver::ensure_model_match(CollectionModel::Table, actual)?;

        // Emit 1 collection_dropped event before storage is wiped.
        // Queue is preserved; subscription is removed with the contract below.
        let final_count = store
            .get_collection(&query.name)
            .map(|manager| manager.query_all(|_| true).len() as u64)
            .unwrap_or(0);
        crate::runtime::mutation::emit_collection_dropped_event_for_collection(
            self,
            &query.name,
            final_count,
        )?;

        let orphaned_indices: Vec<String> = self
            .inner
            .index_store
            .list_indices(&query.name)
            .into_iter()
            .map(|index| index.name)
            .collect();
        for name in &orphaned_indices {
            self.inner.index_store.drop_index(name, &query.name);
        }

        store
            .drop_collection(&query.name)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.inner.db.invalidate_vector_index(&query.name);
        self.inner.db.clear_collection_default_ttl_ms(&query.name);
        self.inner
            .db
            .remove_collection_contract(&query.name)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.clear_table_planner_stats(&query.name);
        self.invalidate_result_cache();
        // Issue #119: a dropped collection vanishes from every
        // (tenant, role)'s visible-collections set. Auth is optional in
        // embedded mode so guard the call.
        if let Some(store) = self.inner.auth_store.read().clone() {
            store.invalidate_visible_collections_cache();
        }
        self.inner
            .db
            .persist_metadata()
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        // Issue #120 — drop both the collection entries *and* every
        // index entry that was scoped to this collection.  Dropping the
        // collection wipes columns + collection-name + type-tags +
        // index hits in one pass via `purge_collection_entries`, so
        // the explicit `DropIndex` calls would be redundant.
        self.schema_vocabulary_apply(
            crate::runtime::schema_vocabulary::DdlEvent::DropCollection {
                collection: query.name.clone(),
            },
        );

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!("table '{}' dropped", query.name),
            "drop",
        ))
    }

    pub fn execute_drop_graph(
        &self,
        raw_query: &str,
        query: &DropGraphQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.execute_drop_typed_collection(
            raw_query,
            &query.name,
            query.if_exists,
            CollectionModel::Graph,
            "graph",
        )
    }

    pub fn execute_drop_vector(
        &self,
        raw_query: &str,
        query: &DropVectorQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.execute_drop_typed_collection(
            raw_query,
            &query.name,
            query.if_exists,
            CollectionModel::Vector,
            "vector",
        )
    }

    pub fn execute_drop_document(
        &self,
        raw_query: &str,
        query: &DropDocumentQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.execute_drop_typed_collection(
            raw_query,
            &query.name,
            query.if_exists,
            CollectionModel::Document,
            "document",
        )
    }

    pub fn execute_drop_kv(
        &self,
        raw_query: &str,
        query: &DropKvQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        let label = polymorphic_resolver::model_name(query.model);
        self.execute_drop_typed_collection(
            raw_query,
            &query.name,
            query.if_exists,
            query.model,
            label,
        )
    }

    pub fn execute_drop_collection(
        &self,
        raw_query: &str,
        query: &DropCollectionQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        if is_system_schema_name(&query.name) {
            return Err(RedDBError::Query("system schema is read-only".to_string()));
        }
        let store = self.inner.db.store();
        if store.get_collection(&query.name).is_none() {
            if query.if_exists {
                return Ok(RuntimeQueryResult::ok_message(
                    raw_query.to_string(),
                    &format!("collection '{}' does not exist", query.name),
                    "drop",
                ));
            }
            return Err(RedDBError::NotFound(format!(
                "collection '{}' not found",
                query.name
            )));
        }

        let actual =
            polymorphic_resolver::resolve(&query.name, &self.inner.db.catalog_model_snapshot())?;
        if let Some(expected) = query.model {
            polymorphic_resolver::ensure_model_match(expected, actual)?;
        }

        match actual {
            CollectionModel::Table => self.execute_drop_table(
                raw_query,
                &DropTableQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::TimeSeries => self.execute_drop_timeseries(
                raw_query,
                &DropTimeSeriesQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::Queue => self.execute_drop_queue(
                raw_query,
                &DropQueueQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::Graph => self.execute_drop_graph(
                raw_query,
                &DropGraphQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::Vector => self.execute_drop_vector(
                raw_query,
                &DropVectorQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::Document => self.execute_drop_document(
                raw_query,
                &DropDocumentQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::Kv => self.execute_drop_kv(
                raw_query,
                &DropKvQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                    model: CollectionModel::Kv,
                },
            ),
            CollectionModel::Config => self.execute_drop_kv(
                raw_query,
                &DropKvQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                    model: CollectionModel::Config,
                },
            ),
            CollectionModel::Vault => self.execute_drop_kv(
                raw_query,
                &DropKvQuery {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                    model: CollectionModel::Vault,
                },
            ),
            CollectionModel::Hll => self.execute_probabilistic_command(
                raw_query,
                &ProbabilisticCommand::DropHll {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::Sketch => self.execute_probabilistic_command(
                raw_query,
                &ProbabilisticCommand::DropSketch {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::Filter => self.execute_probabilistic_command(
                raw_query,
                &ProbabilisticCommand::DropFilter {
                    name: query.name.clone(),
                    if_exists: query.if_exists,
                },
            ),
            CollectionModel::Metrics => self.execute_drop_typed_collection(
                raw_query,
                &query.name,
                query.if_exists,
                CollectionModel::Metrics,
                "metrics",
            ),
            CollectionModel::Mixed => self.execute_drop_typed_collection(
                raw_query,
                &query.name,
                query.if_exists,
                CollectionModel::Mixed,
                "collection",
            ),
        }
    }

    /// Issue #801 — guard `ALTER GRAPH ... ADD|DROP ANALYTICS` so analytics
    /// lifecycle mutations only land on a collection declared as a graph. The
    /// `<graph>.<output>` resolver only consults `analytics_config` on
    /// graph-model contracts, so allowing the op on any other model would write
    /// dead config the reader can never surface.
    fn require_graph_for_analytics(&self, name: &str) -> RedDBResult<()> {
        let is_graph = self
            .inner
            .db
            .collection_contract(name)
            .map(|c| c.declared_model == crate::catalog::CollectionModel::Graph)
            .unwrap_or(false);
        if !is_graph {
            return Err(RedDBError::Query(format!(
                "ALTER GRAPH ... ANALYTICS: '{name}' is not a graph collection"
            )));
        }
        Ok(())
    }

    /// Execute ALTER TABLE
    ///
    /// In RedDB's schema-on-read model, ALTER TABLE operations are advisory.
    /// ADD COLUMN records the schema intent, DROP COLUMN removes it, and
    /// RENAME COLUMN is a metadata rename.  Existing data is not rewritten.
    pub fn execute_alter_table(
        &self,
        raw_query: &str,
        query: &AlterTableQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        let store = self.inner.db.store();

        // Verify the table exists.
        if store.get_collection(&query.name).is_none() {
            return Err(RedDBError::NotFound(format!(
                "table '{}' not found",
                query.name
            )));
        }

        let mut messages = Vec::new();

        // Collect column-level changes upfront for schema-change event emission below.
        let fields_added: Vec<String> = query
            .operations
            .iter()
            .filter_map(|op| {
                if let AlterOperation::AddColumn(col) = op {
                    Some(col.name.clone())
                } else {
                    None
                }
            })
            .collect();
        let fields_removed: Vec<String> = query
            .operations
            .iter()
            .filter_map(|op| {
                if let AlterOperation::DropColumn(name) = op {
                    Some(name.clone())
                } else {
                    None
                }
            })
            .collect();

        for op in &query.operations {
            match op {
                AlterOperation::AddColumn(col) => {
                    // Schema-on-read: column will be available on next insert.
                    messages.push(format!("column '{}' added", col.name));
                }
                AlterOperation::DropColumn(name) => {
                    messages.push(format!("column '{}' dropped", name));
                }
                AlterOperation::RenameColumn { from, to } => {
                    messages.push(format!("column '{}' renamed to '{}'", from, to));
                }
                AlterOperation::AttachPartition { child, bound } => {
                    // Persist child → parent binding in red_config so the
                    // future planner-side pruner can enumerate children and
                    // evaluate their bounds.
                    store.set_config_tree(
                        &format!("partition.{}.children.{}", query.name, child),
                        &crate::serde_json::Value::String(bound.clone()),
                    );
                    messages.push(format!(
                        "partition '{child}' attached to '{}' ({bound})",
                        query.name
                    ));
                }
                AlterOperation::DetachPartition { child } => {
                    store.set_config_tree(
                        &format!("partition.{}.children.{}", query.name, child),
                        &crate::serde_json::Value::Null,
                    );
                    messages.push(format!(
                        "partition '{child}' detached from '{}'",
                        query.name
                    ));
                }
                AlterOperation::EnableRowLevelSecurity => {
                    self.inner
                        .rls_enabled_tables
                        .write()
                        .insert(query.name.clone());
                    // Persist flag so RLS survives restart via red_config.
                    store.set_config_tree(
                        &format!("rls.enabled.{}", query.name),
                        &crate::serde_json::Value::Bool(true),
                    );
                    self.invalidate_plan_cache();
                    messages.push(format!("row level security enabled on '{}'", query.name));
                }
                AlterOperation::DisableRowLevelSecurity => {
                    self.inner.rls_enabled_tables.write().remove(&query.name);
                    store.set_config_tree(
                        &format!("rls.enabled.{}", query.name),
                        &crate::serde_json::Value::Null,
                    );
                    self.invalidate_plan_cache();
                    messages.push(format!("row level security disabled on '{}'", query.name));
                }
                // Phase 2.5.4: retrofit tenancy onto an existing table.
                AlterOperation::EnableTenancy { column } => {
                    store.set_config_tree(
                        &format!("tenant_tables.{}.column", query.name),
                        &crate::serde_json::Value::String(column.clone()),
                    );
                    self.register_tenant_table(&query.name, column);
                    self.invalidate_plan_cache();
                    messages.push(format!(
                        "tenancy enabled on '{}' by column '{column}'",
                        query.name
                    ));
                }
                AlterOperation::DisableTenancy => {
                    store.set_config_tree(
                        &format!("tenant_tables.{}.column", query.name),
                        &crate::serde_json::Value::Null,
                    );
                    self.unregister_tenant_table(&query.name);
                    self.invalidate_plan_cache();
                    messages.push(format!("tenancy disabled on '{}'", query.name));
                }
                AlterOperation::SetAppendOnly(on) => {
                    // Contract is the single source of truth for the
                    // UPDATE/DELETE parse-time guard. The flag lands
                    // below via `apply_alter_operations_to_contract`;
                    // here we only publish the human-readable message.
                    messages.push(format!(
                        "append_only {} on '{}'",
                        if *on { "enabled" } else { "disabled" },
                        query.name
                    ));
                }
                AlterOperation::SetVersioned(on) => {
                    // Opt the collection into (or out of) Git-for-Data.
                    // Persists a row in red_vcs_settings; next AS OF /
                    // merge / diff against this table honours the
                    // flag. Retroactive: existing row versions whose
                    // xmins are still pinned by commits become
                    // reachable via AS OF COMMIT immediately.
                    self.vcs_set_versioned(&query.name, *on)?;
                    messages.push(format!(
                        "versioned {} on '{}'",
                        if *on { "enabled" } else { "disabled" },
                        query.name
                    ));
                }
                AlterOperation::EnableEvents(subscription) => {
                    let mut subscription = subscription.clone();
                    subscription.source = query.name.clone();
                    validate_event_subscriptions(
                        self,
                        &query.name,
                        std::slice::from_ref(&subscription),
                    )?;
                    ensure_event_target_queue(self, &subscription.target_queue)?;
                    messages.push(format!(
                        "events enabled on '{}' to '{}'",
                        query.name, subscription.target_queue
                    ));
                }
                AlterOperation::DisableEvents => {
                    messages.push(format!("events disabled on '{}'", query.name));
                }
                AlterOperation::AddSubscription { name, descriptor } => {
                    let mut sub = descriptor.clone();
                    sub.name = name.clone();
                    sub.source = query.name.clone();
                    validate_event_subscriptions(self, &query.name, std::slice::from_ref(&sub))?;
                    ensure_event_target_queue(self, &sub.target_queue)?;
                    messages.push(format!(
                        "subscription '{}' added on '{}' to '{}'",
                        name, query.name, sub.target_queue
                    ));
                }
                AlterOperation::DropSubscription { name } => {
                    messages.push(format!(
                        "subscription '{}' dropped on '{}'",
                        name, query.name
                    ));
                }
                AlterOperation::AddSigner { pubkey } => {
                    // Issue #522 — admin-gated registry mutation. The
                    // standard DDL `check_write` above gates by role; we
                    // additionally verify the collection actually has a
                    // signed-writes registry installed so this isn't a
                    // covert way to retrofit one (use `CREATE COLLECTION
                    // ... SIGNED_BY (...)` for that).
                    if !crate::runtime::signed_writes_kind::is_signed(&store, &query.name) {
                        return Err(RedDBError::Query(format!(
                            "ALTER COLLECTION ADD SIGNER: '{}' has no signer registry; \
                             recreate it with CREATE COLLECTION ... SIGNED_BY (...)",
                            query.name
                        )));
                    }
                    let actor = crate::runtime::impl_core::current_user_projected()
                        .unwrap_or_else(|| "@system/alter".to_string());
                    let changed = crate::runtime::signed_writes_kind::add_signer(
                        &store,
                        &query.name,
                        *pubkey,
                        &actor,
                    );
                    messages.push(format!(
                        "signer {} on '{}'",
                        if changed { "added" } else { "already present" },
                        query.name
                    ));
                }
                AlterOperation::RevokeSigner { pubkey } => {
                    if !crate::runtime::signed_writes_kind::is_signed(&store, &query.name) {
                        return Err(RedDBError::Query(format!(
                            "ALTER COLLECTION REVOKE SIGNER: '{}' has no signer registry",
                            query.name
                        )));
                    }
                    let actor = crate::runtime::impl_core::current_user_projected()
                        .unwrap_or_else(|| "@system/alter".to_string());
                    let changed = crate::runtime::signed_writes_kind::revoke_signer(
                        &store,
                        &query.name,
                        pubkey,
                        &actor,
                    );
                    messages.push(format!(
                        "signer {} on '{}'",
                        if changed {
                            "revoked"
                        } else {
                            "already revoked"
                        },
                        query.name
                    ));
                }
                AlterOperation::SetRetention { duration_ms } => {
                    // Issue #580 — validate that the collection has a
                    // timestamp column the lazy-on-scan filter can key
                    // off. Without one there is no anchor for "older
                    // than now - duration"; reject at ALTER time so the
                    // policy can never silently hide all rows.
                    let existing = self.inner.db.collection_contract(&query.name);
                    let has_ts_column = existing
                        .as_ref()
                        .map(retention_timestamp_column_exists)
                        .unwrap_or(false);
                    if !has_ts_column {
                        return Err(RedDBError::Query(format!(
                            "ALTER COLLECTION SET RETENTION: '{}' has no timestamp \
                             column — declare a TIMESTAMP/TIMESTAMPMS/DATETIME column \
                             or enable WITH timestamps = true before setting a \
                             retention policy",
                            query.name
                        )));
                    }
                    messages.push(format!(
                        "retention set to {duration_ms} ms on '{}'",
                        query.name
                    ));
                }
                AlterOperation::UnsetRetention => {
                    messages.push(format!("retention cleared on '{}'", query.name));
                }
                AlterOperation::AddAnalytics(views) => {
                    // Issue #801 — analytics lifecycle is graph-only. Reject the
                    // op on a non-graph collection so a misrouted ALTER fails
                    // loudly instead of silently writing analytics_config onto a
                    // model whose reader never resolves `<name>.<output>`.
                    self.require_graph_for_analytics(&query.name)?;
                    let existing = self.inner.db.collection_contract(&query.name);
                    let enabled: std::collections::BTreeSet<crate::catalog::AnalyticsOutput> =
                        existing
                            .as_ref()
                            .map(|c| c.analytics_config.iter().map(|v| v.output).collect())
                            .unwrap_or_default();
                    for view in views {
                        if enabled.contains(&view.output) {
                            // Idempotent: adding an already-enabled output is a
                            // no-op — no error, no duplicate state.
                            messages.push(format!(
                                "analytics '{}' already enabled on '{}'",
                                view.output.as_str(),
                                query.name
                            ));
                        } else {
                            messages.push(format!(
                                "analytics '{}' enabled on '{}'",
                                view.output.as_str(),
                                query.name
                            ));
                        }
                    }
                }
                AlterOperation::DropAnalytics(output) => {
                    self.require_graph_for_analytics(&query.name)?;
                    let enabled = self
                        .inner
                        .db
                        .collection_contract(&query.name)
                        .map(|c| c.analytics_config.iter().any(|v| v.output == *output))
                        .unwrap_or(false);
                    if !enabled {
                        // Dropping an output that was never enabled is a clean,
                        // explicit error (AC4) rather than a silent no-op.
                        return Err(RedDBError::Query(format!(
                            "ALTER GRAPH DROP ANALYTICS: analytics output '{}' is not enabled on graph '{}'",
                            output.as_str(),
                            query.name
                        )));
                    }
                    messages.push(format!(
                        "analytics '{}' disabled on '{}'",
                        output.as_str(),
                        query.name
                    ));
                }
            }
        }

        let mut contract = self
            .inner
            .db
            .collection_contract(&query.name)
            .unwrap_or_else(|| default_collection_contract_for_existing_table(&query.name));
        apply_alter_operations_to_contract(&mut contract, &query.operations);
        contract.version = contract.version.saturating_add(1);
        contract.updated_at_unix_ms = current_unix_ms();
        self.inner
            .db
            .save_collection_contract(contract)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        // Issue #301 — emit OperatorEvent when column schema changes on a
        // collection that has active event subscriptions, so operators know
        // downstream consumers may see a different payload shape.
        if !fields_added.is_empty() || !fields_removed.is_empty() {
            let sub_names: Vec<String> = self
                .inner
                .db
                .collection_contract(&query.name)
                .map(|c| {
                    c.subscriptions
                        .iter()
                        .filter(|s| s.enabled)
                        .map(|s| s.name.clone())
                        .collect()
                })
                .unwrap_or_default();
            if !sub_names.is_empty() {
                crate::telemetry::operator_event::OperatorEvent::SubscriptionSchemaChange {
                    collection: query.name.clone(),
                    subscription_names: sub_names.join(", "),
                    fields_added: fields_added.join(", "),
                    fields_removed: fields_removed.join(", "),
                    lsn: self.cdc_current_lsn(),
                }
                .emit_global();
            }
        }

        self.clear_table_planner_stats(&query.name);
        self.invalidate_result_cache();
        // Issue #120 — refresh the schema-vocabulary entries from the
        // post-ALTER contract. Drop+recreate inside the index keeps
        // the invalidation guarantee complete (no stale columns from
        // before an ALTER ... DROP COLUMN).
        let post_alter_columns: Vec<String> = self
            .inner
            .db
            .collection_contract(&query.name)
            .map(|contract| {
                contract
                    .declared_columns
                    .iter()
                    .map(|col| col.name.clone())
                    .collect()
            })
            .unwrap_or_default();
        self.schema_vocabulary_apply(
            crate::runtime::schema_vocabulary::DdlEvent::AlterCollection {
                collection: query.name.clone(),
                columns: post_alter_columns,
                type_tags: Vec::new(),
                description: None,
            },
        );

        let message = if messages.is_empty() {
            format!("table '{}' altered (no operations)", query.name)
        } else {
            format!("table '{}' altered: {}", query.name, messages.join(", "))
        };

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &message,
            "alter",
        ))
    }

    pub fn execute_create_vcs_ref(
        &self,
        raw_query: &str,
        query: &CreateVcsRefQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        let connection_id = crate::runtime::impl_core::current_connection_id();
        match query.kind {
            VcsRefKind::Branch => {
                self.vcs_branch_create(crate::application::vcs::CreateBranchInput {
                    name: query.name.clone(),
                    from: query.target.clone(),
                    connection_id,
                })?;
            }
            VcsRefKind::Tag => {
                let target = match &query.target {
                    Some(target) => target.clone(),
                    None => self
                        .vcs_status(crate::application::vcs::StatusInput { connection_id })?
                        .head_commit
                        .filter(|head| !head.is_empty())
                        .ok_or_else(|| {
                            RedDBError::InvalidConfig(
                                "cannot create tag: HEAD has no commits".to_string(),
                            )
                        })?,
                };
                self.vcs_tag_create(crate::application::vcs::CreateTagInput {
                    name: query.name.clone(),
                    target,
                    annotation: None,
                })?;
            }
        }
        let kind = match query.kind {
            VcsRefKind::Branch => "branch",
            VcsRefKind::Tag => "tag",
        };
        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!("{kind} '{}' created", query.name),
            "create",
        ))
    }

    pub fn execute_drop_vcs_ref(
        &self,
        raw_query: &str,
        query: &DropVcsRefQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        match query.kind {
            VcsRefKind::Branch => self.vcs_branch_delete(&query.name)?,
            VcsRefKind::Tag => self.vcs_tag_delete(&query.name)?,
        }
        let kind = match query.kind {
            VcsRefKind::Branch => "branch",
            VcsRefKind::Tag => "tag",
        };
        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!("{kind} '{}' dropped", query.name),
            "drop",
        ))
    }

    /// Execute EXPLAIN ALTER FOR CREATE TABLE
    ///
    /// Pure read: computes the schema diff between the target table's
    /// current `CollectionContract` and the embedded `CREATE TABLE` body,
    /// and returns it as SQL `ALTER TABLE` text (default) or structured
    /// JSON. Never mutates storage.
    pub fn execute_explain_alter(
        &self,
        raw_query: &str,
        query: &ExplainAlterQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        // Validate the target CREATE TABLE body so syntactically valid
        // but semantically broken targets (bad SQL types, duplicate
        // columns) are caught here rather than inside the diff engine.
        analyze_create_table(&query.target).map_err(|err| RedDBError::Query(err.to_string()))?;

        let current_contract = self.inner.db.collection_contract(&query.target.name);

        let current_columns: Vec<crate::physical::DeclaredColumnContract> = current_contract
            .as_ref()
            .map(|c| c.declared_columns.clone())
            .unwrap_or_default();

        let diff = super::schema_diff::compute_column_diff(
            &query.target.name,
            &current_columns,
            &query.target.columns,
        );

        let rendered = match query.format {
            ExplainFormat::Sql => super::schema_diff::format_as_sql(&diff),
            ExplainFormat::Json => super::schema_diff::format_as_json(&diff),
        };

        let format_label = match query.format {
            ExplainFormat::Sql => "sql",
            ExplainFormat::Json => "json",
        };

        let columns = vec![
            "table".to_string(),
            "format".to_string(),
            "diff".to_string(),
        ];
        let row = vec![
            ("table".to_string(), Value::text(query.target.name.clone())),
            ("format".to_string(), Value::text(format_label.to_string())),
            ("diff".to_string(), Value::text(rendered)),
        ];

        Ok(RuntimeQueryResult::ok_records(
            raw_query.to_string(),
            columns,
            vec![row],
            "explain",
        ))
    }

    /// Execute CREATE INDEX
    ///
    /// Registers a new index on a collection, builds it from existing data,
    /// and makes it available to the query executor for O(1) lookups.
    pub fn execute_create_index(
        &self,
        raw_query: &str,
        query: &CreateIndexQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        let store = self.inner.db.store();

        // Verify the table exists
        let manager = store
            .get_collection(&query.table)
            .ok_or_else(|| RedDBError::NotFound(format!("table '{}' not found", query.table)))?;

        let method_kind = match query.method {
            IndexMethod::Hash => super::index_store::IndexMethodKind::Hash,
            IndexMethod::BTree => super::index_store::IndexMethodKind::BTree,
            IndexMethod::Bitmap => super::index_store::IndexMethodKind::Bitmap,
            // Explicit opt-in to the in-RAM, memory-capped rstar R-tree.
            IndexMethod::RTree => super::index_store::IndexMethodKind::Spatial,
            // Generic spatial request → engine default spatial backend
            // (disk-resident H3 as of PRD #1574 slice 4, #1578).
            IndexMethod::Spatial => super::index_store::IndexMethodKind::default_spatial(),
            IndexMethod::H3 { resolution } => {
                super::index_store::IndexMethodKind::H3 { resolution }
            }
        };

        // Extract fields from existing entities for indexing. Row
        // entities may arrive in either the "named" HashMap layout
        // (gRPC `BulkInsertBinary` path) OR the columnar layout
        // (HTTP `POST /collections/X/bulk/rows` fast path, which uses
        // `schema: Some(Arc<Vec<String>>)` + `columns: Vec<Value>` and
        // leaves `named == None`). Prior to this commit the columnar
        // branch returned an empty field list, so `CREATE INDEX` built
        // a zero-entity index over HTTP-inserted data even though the
        // data was queryable via `SELECT`.
        let entities = manager.query_all(|_| true);
        let entity_fields: Vec<(crate::storage::unified::EntityId, Vec<(String, Value)>)> =
            entities
                .iter()
                .map(|e| {
                    let fields = match &e.data {
                        crate::storage::EntityData::Row(row) => {
                            if let Some(ref named) = row.named {
                                named.iter().map(|(k, v)| (k.clone(), v.clone())).collect()
                            } else if let Some(ref schema) = row.schema {
                                // Columnar layout — pair each column
                                // with its positional name from the
                                // shared schema Arc.
                                schema
                                    .iter()
                                    .zip(row.columns.iter())
                                    .map(|(k, v)| (k.clone(), v.clone()))
                                    .collect()
                            } else {
                                Vec::new()
                            }
                        }
                        crate::storage::EntityData::Node(node) => node
                            .properties
                            .iter()
                            .map(|(k, v)| (k.clone(), v.clone()))
                            .collect(),
                        _ => Vec::new(),
                    };
                    (e.id, fields)
                })
                .collect();

        // Build the index
        let indexed_count = self
            .inner
            .index_store
            .create_index(
                &query.name,
                &query.table,
                &query.columns,
                method_kind,
                query.unique,
                &entity_fields,
            )
            .map_err(RedDBError::Internal)?;

        let analyzed = crate::storage::query::planner::stats_catalog::analyze_entity_fields(
            &query.table,
            &entity_fields,
        );
        crate::storage::query::planner::stats_catalog::persist_table_stats(&store, &analyzed);
        self.invalidate_plan_cache();

        // Register metadata
        self.inner
            .index_store
            .register(super::index_store::RegisteredIndex {
                name: query.name.clone(),
                collection: query.table.clone(),
                columns: query.columns.clone(),
                method: method_kind,
                unique: query.unique,
            });
        self.persist_runtime_index_descriptor(super::index_store::RegisteredIndex {
            name: query.name.clone(),
            collection: query.table.clone(),
            columns: query.columns.clone(),
            method: method_kind,
            unique: query.unique,
        })?;
        // Issue #120 — surface the index name + indexed columns in
        // the schema-vocabulary so AskPipeline (#121) can resolve
        // "the email index" back to its collection.
        self.schema_vocabulary_apply(crate::runtime::schema_vocabulary::DdlEvent::CreateIndex {
            collection: query.table.clone(),
            index: query.name.clone(),
            columns: query.columns.clone(),
        });

        let method_str = format!("{}", query.method);
        let unique_str = if query.unique { "unique " } else { "" };
        let cols = query.columns.join(", ");

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!(
                "{}index '{}' created on '{}' ({}) using {} ({} entities indexed)",
                unique_str, query.name, query.table, cols, method_str, indexed_count
            ),
            "create",
        ))
    }

    /// Execute DROP INDEX
    ///
    /// Removes an index from a collection.
    pub fn execute_drop_index(
        &self,
        raw_query: &str,
        query: &DropIndexQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        let store = self.inner.db.store();

        // Verify the table exists
        if store.get_collection(&query.table).is_none() {
            if query.if_exists {
                return Ok(RuntimeQueryResult::ok_message(
                    raw_query.to_string(),
                    &format!("table '{}' does not exist", query.table),
                    "drop",
                ));
            }
            return Err(RedDBError::NotFound(format!(
                "table '{}' not found",
                query.table
            )));
        }

        // Remove from IndexStore
        self.inner.index_store.drop_index(&query.name, &query.table);
        self.persist_runtime_index_drop(&query.table, &query.name)?;
        self.invalidate_plan_cache();
        // Issue #120 — keep the schema-vocabulary index entry in sync.
        self.schema_vocabulary_apply(crate::runtime::schema_vocabulary::DdlEvent::DropIndex {
            collection: query.table.clone(),
            index: query.name.clone(),
        });

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!("index '{}' dropped from '{}'", query.name, query.table),
            "drop",
        ))
    }

    fn execute_drop_typed_collection(
        &self,
        raw_query: &str,
        name: &str,
        if_exists: bool,
        expected_model: CollectionModel,
        label: &str,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        if is_system_schema_name(name) {
            return Err(RedDBError::Query("system schema is read-only".to_string()));
        }
        let store = self.inner.db.store();
        if store.get_collection(name).is_none() {
            if if_exists {
                return Ok(RuntimeQueryResult::ok_message(
                    raw_query.to_string(),
                    &format!("{label} '{name}' does not exist"),
                    "drop",
                ));
            }
            return Err(RedDBError::NotFound(format!("{label} '{name}' not found")));
        }

        let actual = self
            .inner
            .db
            .collection_contract(name)
            .map(|contract| contract.declared_model)
            .map(Ok)
            .unwrap_or_else(|| {
                polymorphic_resolver::resolve(name, &self.inner.db.catalog_model_snapshot())
            })?;
        polymorphic_resolver::ensure_model_match(expected_model, actual)?;
        self.drop_collection_storage(raw_query, name, label)
    }

    pub fn execute_truncate(
        &self,
        raw_query: &str,
        query: &TruncateQuery,
    ) -> RedDBResult<RuntimeQueryResult> {
        self.check_write(crate::runtime::write_gate::WriteKind::Ddl)?;
        if is_system_schema_name(&query.name) {
            return Err(RedDBError::Query("system schema is read-only".to_string()));
        }

        let label = query
            .model
            .map(polymorphic_resolver::model_name)
            .unwrap_or("collection");
        let store = self.inner.db.store();
        if store.get_collection(&query.name).is_none() {
            if query.if_exists {
                return Ok(RuntimeQueryResult::ok_message(
                    raw_query.to_string(),
                    &format!("{label} '{}' does not exist", query.name),
                    "truncate",
                ));
            }
            return Err(RedDBError::NotFound(format!(
                "{label} '{}' not found",
                query.name
            )));
        }

        let actual =
            polymorphic_resolver::resolve(&query.name, &self.inner.db.catalog_model_snapshot())?;
        if let Some(expected) = query.model {
            polymorphic_resolver::ensure_model_match(expected, actual)?;
        }

        if actual == CollectionModel::Queue {
            return self.execute_queue_command(
                raw_query,
                &QueueCommand::Purge {
                    queue: query.name.clone(),
                },
            );
        }

        // Count before wiping so we can emit the aggregated truncate event.
        let affected = self.truncate_collection_entities(&query.name)?;
        // Emit 1 truncate event (not N delete events) for event-enabled collections.
        crate::runtime::mutation::emit_truncate_event_for_collection(self, &query.name, affected)?;
        self.inner.db.invalidate_vector_index(&query.name);
        self.clear_table_planner_stats(&query.name);
        self.invalidate_result_cache();

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!(
                "{affected} entities truncated from {label} '{}'",
                query.name
            ),
            "truncate",
        ))
    }

    fn truncate_collection_entities(&self, name: &str) -> RedDBResult<u64> {
        let store = self.inner.db.store();
        let Some(manager) = store.get_collection(name) else {
            return Ok(0);
        };
        let entities = manager.query_all(|_| true);
        if entities.is_empty() {
            return Ok(0);
        }

        for entity in &entities {
            let fields = entity_index_fields(&entity.data);
            self.inner
                .index_store
                .index_entity_delete(name, entity.id, &fields)
                .map_err(RedDBError::Internal)?;
        }

        let ids = entities.iter().map(|entity| entity.id).collect::<Vec<_>>();
        let deleted_ids = store
            .delete_batch(name, &ids)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        for id in &deleted_ids {
            store.context_index().remove_entity(*id);
        }
        Ok(deleted_ids.len() as u64)
    }

    fn drop_collection_storage(
        &self,
        raw_query: &str,
        name: &str,
        label: &str,
    ) -> RedDBResult<RuntimeQueryResult> {
        let store = self.inner.db.store();

        // Emit 1 collection_dropped event before storage is wiped.
        // Queue is preserved; subscription is removed with the contract below.
        let final_count = store
            .get_collection(name)
            .map(|manager| manager.query_all(|_| true).len() as u64)
            .unwrap_or(0);
        crate::runtime::mutation::emit_collection_dropped_event_for_collection(
            self,
            name,
            final_count,
        )?;

        let orphaned_indices: Vec<String> = self
            .inner
            .index_store
            .list_indices(name)
            .into_iter()
            .map(|index| index.name)
            .collect();
        for index_name in &orphaned_indices {
            self.inner.index_store.drop_index(index_name, name);
        }

        store
            .drop_collection(name)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.inner.db.invalidate_vector_index(name);
        self.inner.db.clear_collection_default_ttl_ms(name);
        self.inner
            .db
            .remove_collection_contract(name)
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.clear_table_planner_stats(name);
        self.invalidate_result_cache();
        if let Some(store) = self.inner.auth_store.read().clone() {
            store.invalidate_visible_collections_cache();
        }
        self.inner
            .db
            .persist_metadata()
            .map_err(|err| RedDBError::Internal(err.to_string()))?;
        self.schema_vocabulary_apply(
            crate::runtime::schema_vocabulary::DdlEvent::DropCollection {
                collection: name.to_string(),
            },
        );

        Ok(RuntimeQueryResult::ok_message(
            raw_query.to_string(),
            &format!("{label} '{name}' dropped"),
            "drop",
        ))
    }
}

pub(crate) fn is_system_schema_name(name: &str) -> bool {
    name == "red" || name.starts_with("red.") || name.starts_with("__red_schema_")
}

fn entity_index_fields(data: &EntityData) -> Vec<(String, Value)> {
    match data {
        EntityData::Row(row) => {
            if let Some(ref named) = row.named {
                named
                    .iter()
                    .map(|(key, value)| (key.clone(), value.clone()))
                    .collect()
            } else if let Some(ref schema) = row.schema {
                schema
                    .iter()
                    .zip(row.columns.iter())
                    .map(|(key, value)| (key.clone(), value.clone()))
                    .collect()
            } else {
                Vec::new()
            }
        }
        EntityData::Node(node) => node
            .properties
            .iter()
            .map(|(key, value)| (key.clone(), value.clone()))
            .collect(),
        _ => Vec::new(),
    }
}

/// DDL-time gate for a declared AI policy (issue #1271). Each declared
/// modality block is checked against the provider capability matrix
/// (#1269): a provider/model that cannot serve the requested modality is
/// rejected before the collection is created. Uses the built-in registry
/// (no per-deployment overrides at DDL time).
fn validate_ai_policy_modalities(policy: &crate::catalog::AiPolicy) -> RedDBResult<()> {
    use crate::runtime::ai::provider_capabilities::{Modality, Registry};
    let registry = Registry::new();
    let check = |provider: &str, model: &str, modality: Modality| -> RedDBResult<()> {
        registry
            .validate_policy_modality(provider, model, modality)
            .map_err(|err| RedDBError::Query(err.to_string()))
    };
    if let Some(embed) = &policy.embed {
        check(&embed.provider, &embed.model, Modality::Embed)?;
    }
    if let Some(moderate) = &policy.moderate {
        check(&moderate.provider, &moderate.model, Modality::Moderate)?;
    }
    if let Some(vision) = &policy.vision {
        check(&vision.provider, &vision.model, Modality::Vision)?;
    }
    Ok(())
}

fn collection_contract_from_create_table(
    query: &CreateTableQuery,
) -> RedDBResult<crate::physical::CollectionContract> {
    let now = current_unix_ms();
    let mut declared_columns: Vec<crate::physical::DeclaredColumnContract> = query
        .columns
        .iter()
        .map(declared_column_contract_from_ddl)
        .collect();
    if query.timestamps {
        // Opt-in `WITH timestamps = true` auto-adds two user-visible
        // columns that the write path populates from
        // UnifiedEntity::created_at/updated_at. BIGINT unix-ms, NOT NULL.
        declared_columns.push(crate::physical::DeclaredColumnContract {
            name: "created_at".to_string(),
            data_type: "BIGINT".to_string(),
            sql_type: Some(crate::storage::schema::SqlTypeName::simple("BIGINT")),
            not_null: true,
            default: None,
            compress: None,
            unique: false,
            primary_key: false,
            enum_variants: Vec::new(),
            array_element: None,
            decimal_precision: None,
        });
        declared_columns.push(crate::physical::DeclaredColumnContract {
            name: "updated_at".to_string(),
            data_type: "BIGINT".to_string(),
            sql_type: Some(crate::storage::schema::SqlTypeName::simple("BIGINT")),
            not_null: true,
            default: None,
            compress: None,
            unique: false,
            primary_key: false,
            enum_variants: Vec::new(),
            array_element: None,
            decimal_precision: None,
        });
    }
    Ok(crate::physical::CollectionContract {
        name: query.name.clone(),
        declared_model: crate::catalog::CollectionModel::Table,
        schema_mode: crate::catalog::SchemaMode::SemiStructured,
        origin: crate::physical::ContractOrigin::Explicit,
        version: 1,
        created_at_unix_ms: now,
        updated_at_unix_ms: now,
        default_ttl_ms: query.default_ttl_ms,
        vector_dimension: None,
        vector_metric: None,
        context_index_fields: query.context_index_fields.clone(),
        declared_columns,
        table_def: Some(build_table_def_from_create_table(query)?),
        timestamps_enabled: query.timestamps,
        context_index_enabled: query.context_index_enabled
            || !query.context_index_fields.is_empty(),
        metrics_raw_retention_ms: None,
        metrics_rollup_policies: Vec::new(),
        metrics_tenant_identity: None,
        metrics_namespace: None,
        append_only: query.append_only,
        subscriptions: query.subscriptions.clone(),
        analytics_config: Vec::new(),
        session_key: None,
        session_gap_ms: None,
        retention_duration_ms: None,
        analytical_storage: None,
        ai_policy: query.ai_policy.clone(),
    })
}

fn default_collection_contract_for_existing_table(
    name: &str,
) -> crate::physical::CollectionContract {
    let now = current_unix_ms();
    crate::physical::CollectionContract {
        name: name.to_string(),
        declared_model: crate::catalog::CollectionModel::Table,
        schema_mode: crate::catalog::SchemaMode::SemiStructured,
        origin: crate::physical::ContractOrigin::Explicit,
        version: 0,
        created_at_unix_ms: now,
        updated_at_unix_ms: now,
        default_ttl_ms: None,
        vector_dimension: None,
        vector_metric: None,
        context_index_fields: Vec::new(),
        declared_columns: Vec::new(),
        table_def: Some(crate::storage::schema::TableDef::new(name.to_string())),
        timestamps_enabled: false,
        context_index_enabled: false,
        metrics_raw_retention_ms: None,
        metrics_rollup_policies: Vec::new(),
        metrics_tenant_identity: None,
        metrics_namespace: None,
        append_only: false,
        subscriptions: Vec::new(),
        analytics_config: Vec::new(),
        session_key: None,
        session_gap_ms: None,
        retention_duration_ms: None,
        analytical_storage: None,

        ai_policy: None,
    }
}

fn keyed_collection_contract(
    name: &str,
    model: crate::catalog::CollectionModel,
    analytics_config: Vec<crate::catalog::AnalyticsViewDescriptor>,
) -> crate::physical::CollectionContract {
    let now = current_unix_ms();
    crate::physical::CollectionContract {
        name: name.to_string(),
        declared_model: model,
        schema_mode: crate::catalog::SchemaMode::Dynamic,
        origin: crate::physical::ContractOrigin::Explicit,
        version: 1,
        created_at_unix_ms: now,
        updated_at_unix_ms: now,
        default_ttl_ms: None,
        vector_dimension: None,
        vector_metric: None,
        context_index_fields: Vec::new(),
        declared_columns: Vec::new(),
        table_def: None,
        timestamps_enabled: false,
        context_index_enabled: false,
        metrics_raw_retention_ms: None,
        metrics_rollup_policies: Vec::new(),
        metrics_tenant_identity: None,
        metrics_namespace: None,
        append_only: false,
        subscriptions: Vec::new(),
        analytics_config,
        session_key: None,
        session_gap_ms: None,
        retention_duration_ms: None,
        analytical_storage: None,

        ai_policy: None,
    }
}

fn metrics_collection_contract(query: &CreateTableQuery) -> crate::physical::CollectionContract {
    let now = current_unix_ms();
    crate::physical::CollectionContract {
        name: query.name.clone(),
        declared_model: crate::catalog::CollectionModel::Metrics,
        schema_mode: crate::catalog::SchemaMode::SemiStructured,
        origin: crate::physical::ContractOrigin::Explicit,
        version: 1,
        created_at_unix_ms: now,
        updated_at_unix_ms: now,
        default_ttl_ms: query.default_ttl_ms,
        vector_dimension: None,
        vector_metric: None,
        context_index_fields: Vec::new(),
        declared_columns: Vec::new(),
        table_def: None,
        timestamps_enabled: false,
        context_index_enabled: false,
        metrics_raw_retention_ms: query.default_ttl_ms,
        metrics_rollup_policies: query.metrics_rollup_policies.clone(),
        metrics_tenant_identity: Some(
            query
                .tenant_by
                .clone()
                .unwrap_or_else(|| "current_tenant".to_string()),
        ),
        metrics_namespace: Some("default".to_string()),
        append_only: true,
        subscriptions: Vec::new(),
        analytics_config: Vec::new(),
        session_key: None,
        session_gap_ms: None,
        retention_duration_ms: None,
        analytical_storage: None,

        ai_policy: None,
    }
}

fn vector_collection_contract(query: &CreateVectorQuery) -> crate::physical::CollectionContract {
    let now = current_unix_ms();
    crate::physical::CollectionContract {
        name: query.name.clone(),
        declared_model: crate::catalog::CollectionModel::Vector,
        schema_mode: crate::catalog::SchemaMode::Dynamic,
        origin: crate::physical::ContractOrigin::Explicit,
        version: 1,
        created_at_unix_ms: now,
        updated_at_unix_ms: now,
        default_ttl_ms: None,
        vector_dimension: Some(query.dimension),
        vector_metric: Some(query.metric),
        context_index_fields: Vec::new(),
        declared_columns: Vec::new(),
        table_def: None,
        timestamps_enabled: false,
        context_index_enabled: false,
        metrics_raw_retention_ms: None,
        metrics_rollup_policies: Vec::new(),
        metrics_tenant_identity: None,
        metrics_namespace: None,
        append_only: false,
        subscriptions: Vec::new(),
        analytics_config: Vec::new(),
        session_key: None,
        session_gap_ms: None,
        retention_duration_ms: None,
        analytical_storage: None,

        ai_policy: None,
    }
}

fn declared_column_contract_from_ddl(
    column: &CreateColumnDef,
) -> crate::physical::DeclaredColumnContract {
    crate::physical::DeclaredColumnContract {
        name: column.name.clone(),
        data_type: column.data_type.clone(),
        sql_type: Some(column.sql_type.clone()),
        not_null: column.not_null,
        default: column.default.clone(),
        compress: column.compress,
        unique: column.unique,
        primary_key: column.primary_key,
        enum_variants: column.enum_variants.clone(),
        array_element: column.array_element.clone(),
        decimal_precision: column.decimal_precision,
    }
}

fn apply_alter_operations_to_contract(
    contract: &mut crate::physical::CollectionContract,
    operations: &[AlterOperation],
) {
    if contract.table_def.is_none() {
        contract.table_def = Some(crate::storage::schema::TableDef::new(contract.name.clone()));
    }
    for operation in operations {
        match operation {
            AlterOperation::AddColumn(column) => {
                if !contract
                    .declared_columns
                    .iter()
                    .any(|existing| existing.name == column.name)
                {
                    contract
                        .declared_columns
                        .push(declared_column_contract_from_ddl(column));
                }
                if let Some(table_def) = contract.table_def.as_mut() {
                    if table_def.get_column(&column.name).is_none() {
                        if let Ok(column_def) = column_def_from_ddl(column) {
                            if column.primary_key {
                                table_def.primary_key.push(column.name.clone());
                                table_def.constraints.push(
                                    crate::storage::schema::Constraint::new(
                                        format!("pk_{}", column.name),
                                        crate::storage::schema::ConstraintType::PrimaryKey,
                                    )
                                    .on_columns(vec![column.name.clone()]),
                                );
                            }
                            if column.unique {
                                table_def.constraints.push(
                                    crate::storage::schema::Constraint::new(
                                        format!("uniq_{}", column.name),
                                        crate::storage::schema::ConstraintType::Unique,
                                    )
                                    .on_columns(vec![column.name.clone()]),
                                );
                            }
                            if column.not_null {
                                table_def.constraints.push(
                                    crate::storage::schema::Constraint::new(
                                        format!("not_null_{}", column.name),
                                        crate::storage::schema::ConstraintType::NotNull,
                                    )
                                    .on_columns(vec![column.name.clone()]),
                                );
                            }
                            table_def.columns.push(column_def);
                        }
                    }
                }
            }
            AlterOperation::DropColumn(name) => {
                contract
                    .declared_columns
                    .retain(|column| column.name != *name);
                if let Some(table_def) = contract.table_def.as_mut() {
                    if let Some(index) = table_def.column_index(name) {
                        table_def.columns.remove(index);
                    }
                    table_def.primary_key.retain(|column| column != name);
                    table_def.constraints.retain(|constraint| {
                        !constraint.columns.iter().any(|column| column == name)
                    });
                    table_def
                        .indexes
                        .retain(|index| !index.columns.iter().any(|column| column == name));
                }
            }
            AlterOperation::RenameColumn { from, to } => {
                if contract
                    .declared_columns
                    .iter()
                    .any(|column| column.name == *to)
                {
                    continue;
                }
                if let Some(column) = contract
                    .declared_columns
                    .iter_mut()
                    .find(|column| column.name == *from)
                {
                    column.name = to.clone();
                }
                if let Some(table_def) = contract.table_def.as_mut() {
                    if let Some(column) = table_def
                        .columns
                        .iter_mut()
                        .find(|column| column.name == *from)
                    {
                        column.name = to.clone();
                    }
                    for primary_key in &mut table_def.primary_key {
                        if *primary_key == *from {
                            *primary_key = to.clone();
                        }
                    }
                    for constraint in &mut table_def.constraints {
                        for column in &mut constraint.columns {
                            if *column == *from {
                                *column = to.clone();
                            }
                        }
                        if let Some(ref_columns) = constraint.ref_columns.as_mut() {
                            for column in ref_columns {
                                if *column == *from {
                                    *column = to.clone();
                                }
                            }
                        }
                    }
                    for index in &mut table_def.indexes {
                        for column in &mut index.columns {
                            if *column == *from {
                                *column = to.clone();
                            }
                        }
                    }
                }
            }
            // Partition ops don't touch the column contract — metadata is
            // persisted separately via `red_config.partition.*`.
            AlterOperation::AttachPartition { .. } | AlterOperation::DetachPartition { .. } => {}
            // RLS toggles don't touch the column contract — flag is persisted
            // separately via `red_config.rls.enabled.{table}` and enforced
            // through the in-memory `rls_enabled_tables` set.
            AlterOperation::EnableRowLevelSecurity | AlterOperation::DisableRowLevelSecurity => {}
            // Phase 2.5.4: tenancy toggles persist via `red_config.tenant_tables.*`
            // and are enforced through `tenant_tables` + RLS auto-policy.
            AlterOperation::EnableTenancy { .. } | AlterOperation::DisableTenancy => {}
            AlterOperation::SetAppendOnly(on) => {
                contract.append_only = *on;
            }
            // VCS opt-in is persisted to red_vcs_settings by the
            // executor, not the contract — nothing to do here.
            AlterOperation::SetVersioned(_) => {}
            AlterOperation::EnableEvents(subscription) => {
                let mut subscription = subscription.clone();
                subscription.source = contract.name.clone();
                subscription.enabled = true;
                if let Some(existing) = contract
                    .subscriptions
                    .iter_mut()
                    .find(|existing| existing.target_queue == subscription.target_queue)
                {
                    *existing = subscription;
                } else {
                    contract.subscriptions.push(subscription);
                }
            }
            AlterOperation::DisableEvents => {
                for subscription in &mut contract.subscriptions {
                    subscription.enabled = false;
                }
            }
            AlterOperation::AddSubscription { name, descriptor } => {
                let mut sub = descriptor.clone();
                sub.name = name.clone();
                sub.source = contract.name.clone();
                sub.enabled = true;
                if let Some(existing) = contract.subscriptions.iter_mut().find(|s| s.name == *name)
                {
                    *existing = sub;
                } else {
                    contract.subscriptions.push(sub);
                }
            }
            AlterOperation::DropSubscription { name } => {
                contract.subscriptions.retain(|s| s.name != *name);
            }
            // Signer registry mutations live in `red_config` outside the
            // contract surface — the executor applied them directly via
            // `signed_writes_kind::{add,revoke}_signer`. Nothing to fold
            // into the column-shaped contract.
            AlterOperation::AddSigner { .. } | AlterOperation::RevokeSigner { .. } => {}
            AlterOperation::SetRetention { duration_ms } => {
                contract.retention_duration_ms = Some(*duration_ms);
            }
            AlterOperation::UnsetRetention => {
                contract.retention_duration_ms = None;
            }
            // Issue #801 — fold analytics lifecycle into the WAL-backed
            // `analytics_config` so the change is durable and the
            // `<graph>.<output>` resolver picks it up on the next read.
            AlterOperation::AddAnalytics(views) => {
                for view in views {
                    // Idempotent: skip outputs already enabled so a repeated
                    // ADD never duplicates state. The first declaration wins —
                    // re-declaring options requires DROP then ADD.
                    if !contract
                        .analytics_config
                        .iter()
                        .any(|existing| existing.output == view.output)
                    {
                        contract.analytics_config.push(view.clone());
                    }
                }
            }
            AlterOperation::DropAnalytics(output) => {
                contract
                    .analytics_config
                    .retain(|view| view.output != *output);
            }
        }
    }
}

/// Issue #580 — returns true if the contract carries at least one
/// column the retention filter can use as a timestamp anchor:
/// either `WITH timestamps = true` (auto `created_at` / `updated_at`)
/// or a user-declared column with a temporal data_type.
pub(crate) fn retention_timestamp_column_exists(
    contract: &crate::physical::CollectionContract,
) -> bool {
    if contract.timestamps_enabled {
        return true;
    }
    if matches!(
        contract.declared_model,
        crate::catalog::CollectionModel::TimeSeries | crate::catalog::CollectionModel::Metrics
    ) {
        // Time-series and metrics collections carry an intrinsic
        // timestamp axis on every row even without a declared column;
        // retention has a natural anchor.
        return true;
    }
    contract
        .declared_columns
        .iter()
        .any(|column| is_temporal_data_type(&column.data_type))
}

fn is_temporal_data_type(data_type: &str) -> bool {
    let upper = data_type.to_ascii_uppercase();
    matches!(
        upper.as_str(),
        "TIMESTAMP" | "TIMESTAMPMS" | "TIMESTAMP_MS" | "DATETIME" | "DATE"
    )
}

fn validate_event_subscriptions(
    runtime: &RedDBRuntime,
    source: &str,
    subscriptions: &[crate::catalog::SubscriptionDescriptor],
) -> RedDBResult<()> {
    for subscription in subscriptions
        .iter()
        .filter(|subscription| subscription.enabled)
    {
        if subscription.all_tenants && crate::runtime::impl_core::current_tenant().is_some() {
            return Err(RedDBError::Query(
                "cross-tenant subscription requires cluster-admin capability (events:cluster_subscribe)".to_string(),
            ));
        }
        validate_subscription_auth(runtime, source, subscription)?;
        if subscription.target_queue == source
            || subscription_would_create_cycle(
                &runtime.inner.db,
                source,
                &subscription.target_queue,
            )
        {
            return Err(RedDBError::Query(
                "subscription would create cycle".to_string(),
            ));
        }
        audit_subscription_redact_gap(runtime, source, subscription);
    }
    Ok(())
}

fn validate_subscription_auth(
    runtime: &RedDBRuntime,
    source: &str,
    subscription: &crate::catalog::SubscriptionDescriptor,
) -> RedDBResult<()> {
    let auth_store = match runtime.inner.auth_store.read().clone() {
        Some(store) => store,
        None => return Ok(()),
    };
    let (username, role) = match crate::runtime::impl_core::current_auth_identity() {
        Some(identity) => identity,
        None => return Ok(()),
    };
    let tenant = crate::runtime::impl_core::current_tenant();
    let principal = crate::auth::UserId::from_parts(tenant.as_deref(), &username);

    if auth_store.iam_authorization_enabled() {
        let ctx = crate::auth::policies::EvalContext {
            principal_tenant: tenant.clone(),
            current_tenant: tenant.clone(),
            peer_ip: None,
            mfa_present: false,
            now_ms: crate::auth::now_ms(),
            principal_is_admin_role: role == crate::auth::Role::Admin,
            principal_is_platform_scoped: principal.tenant.is_none(),
        };
        let mut source_resource = crate::auth::policies::ResourceRef::new("table", source);
        if let Some(t) = tenant.as_deref() {
            source_resource = source_resource.with_tenant(t.to_string());
        }
        if !auth_store.check_policy_authz_with_role(
            &principal,
            "select",
            &source_resource,
            &ctx,
            role,
        ) {
            return Err(RedDBError::Query(format!(
                "permission denied: principal=`{}` action=`select` resource=`{}:{}` denied by IAM policy",
                principal, source_resource.kind, source_resource.name
            )));
        }

        let mut target_resource =
            crate::auth::policies::ResourceRef::new("queue", subscription.target_queue.clone());
        if let Some(t) = tenant.as_deref() {
            target_resource = target_resource.with_tenant(t.to_string());
        }
        if !auth_store.check_policy_authz_with_role(
            &principal,
            "write",
            &target_resource,
            &ctx,
            role,
        ) {
            return Err(RedDBError::Query(format!(
                "permission denied: principal=`{}` action=`write` resource=`{}:{}` denied by IAM policy",
                principal, target_resource.kind, target_resource.name
            )));
        }
        return Ok(());
    }

    let ctx = crate::auth::privileges::AuthzContext {
        principal: &username,
        effective_role: role,
        tenant: tenant.as_deref(),
    };
    auth_store
        .check_grant(
            &ctx,
            crate::auth::privileges::Action::Select,
            &crate::auth::privileges::Resource::table_from_name(source),
        )
        .map_err(|err| RedDBError::Query(format!("permission denied: {err}")))?;
    auth_store
        .check_grant(
            &ctx,
            crate::auth::privileges::Action::Insert,
            &crate::auth::privileges::Resource::table_from_name(&subscription.target_queue),
        )
        .map_err(|err| RedDBError::Query(format!("permission denied: {err}")))?;
    Ok(())
}

fn audit_subscription_redact_gap(
    runtime: &RedDBRuntime,
    source: &str,
    subscription: &crate::catalog::SubscriptionDescriptor,
) {
    let auth_store = match runtime.inner.auth_store.read().clone() {
        Some(store) if store.iam_authorization_enabled() => store,
        _ => return,
    };
    let (username, role) = match crate::runtime::impl_core::current_auth_identity() {
        Some(identity) => identity,
        None => return,
    };
    let tenant = crate::runtime::impl_core::current_tenant();
    let principal = crate::auth::UserId::from_parts(tenant.as_deref(), &username);
    let missing = subscription_redact_gap_columns(&auth_store, &principal, source, subscription);
    if missing.is_empty() {
        return;
    }

    let columns = missing.into_iter().collect::<Vec<_>>().join(", ");
    tracing::warn!(
        target: "reddb::operator",
        "subscription_redact_gap: source={} target_queue={} columns=[{}]",
        source,
        subscription.target_queue,
        columns
    );
    let mut event = AuditEvent::builder("subscription_redact_gap")
        .principal(username)
        .source(AuditAuthSource::System)
        .resource(format!(
            "subscription:{}->{}",
            source, subscription.target_queue
        ))
        .outcome(Outcome::Success)
        .field(AuditFieldEscaper::field("source", source))
        .field(AuditFieldEscaper::field(
            "target_queue",
            subscription.target_queue.clone(),
        ))
        .field(AuditFieldEscaper::field(
            "subscription",
            subscription.name.clone(),
        ))
        .field(AuditFieldEscaper::field("columns", columns))
        .field(AuditFieldEscaper::field("role", role.as_str()));
    if let Some(t) = tenant {
        event = event.tenant(t);
    }
    runtime.inner.audit_log.record_event(event.build());
}

fn subscription_redact_gap_columns(
    auth_store: &crate::auth::store::AuthStore,
    principal: &crate::auth::UserId,
    source: &str,
    subscription: &crate::catalog::SubscriptionDescriptor,
) -> BTreeSet<String> {
    let redacted: HashSet<String> = subscription
        .redact_fields
        .iter()
        .map(|field| field.to_ascii_lowercase())
        .collect();
    auth_store
        .effective_policies(principal)
        .iter()
        .flat_map(|policy| policy.statements.iter())
        .filter(|statement| statement.effect == crate::auth::policies::Effect::Deny)
        .filter(|statement| statement.actions.iter().any(action_pattern_matches_select))
        .flat_map(|statement| statement.resources.iter())
        .filter_map(|resource| denied_column_for_source(resource, source))
        .filter(|column| !redact_covers_column(&redacted, source, column))
        .collect()
}

fn action_pattern_matches_select(pattern: &crate::auth::policies::ActionPattern) -> bool {
    match pattern {
        crate::auth::policies::ActionPattern::Wildcard => true,
        crate::auth::policies::ActionPattern::Exact(action) => action == "select",
        crate::auth::policies::ActionPattern::Prefix(prefix) => {
            "select".len() > prefix.len() + 1
                && "select".starts_with(prefix)
                && "select".as_bytes()[prefix.len()] == b':'
        }
    }
}

fn denied_column_for_source(
    resource: &crate::auth::policies::ResourcePattern,
    source: &str,
) -> Option<String> {
    let crate::auth::policies::ResourcePattern::Exact { kind, name } = resource else {
        return None;
    };
    if kind != "column" {
        return None;
    }
    let column = crate::auth::ColumnRef::parse_resource_name(name).ok()?;
    (column.table_resource_name() == source).then_some(column.column)
}

fn redact_covers_column(redacted: &HashSet<String>, source: &str, column: &str) -> bool {
    let column = column.to_ascii_lowercase();
    let qualified = format!("{}.{}", source.to_ascii_lowercase(), column);
    redacted.contains("*") || redacted.contains(&column) || redacted.contains(&qualified)
}

fn subscription_would_create_cycle(
    db: &crate::storage::unified::devx::RedDB,
    source: &str,
    target: &str,
) -> bool {
    let mut graph: HashMap<String, Vec<String>> = HashMap::new();
    for contract in db.collection_contracts() {
        for subscription in contract
            .subscriptions
            .into_iter()
            .filter(|subscription| subscription.enabled)
        {
            graph
                .entry(subscription.source)
                .or_default()
                .push(subscription.target_queue);
        }
    }
    graph
        .entry(source.to_string())
        .or_default()
        .push(target.to_string());

    let mut stack = vec![target.to_string()];
    let mut seen = HashSet::new();
    while let Some(node) = stack.pop() {
        if node == source {
            return true;
        }
        if !seen.insert(node.clone()) {
            continue;
        }
        if let Some(next) = graph.get(&node) {
            stack.extend(next.iter().cloned());
        }
    }
    false
}

pub(crate) fn ensure_event_target_queue_pub(
    runtime: &RedDBRuntime,
    queue: &str,
) -> RedDBResult<()> {
    ensure_event_target_queue(runtime, queue)
}

fn ensure_event_target_queue(runtime: &RedDBRuntime, queue: &str) -> RedDBResult<()> {
    let store = runtime.inner.db.store();
    if store.get_collection(queue).is_some() {
        return Ok(());
    }
    store
        .create_collection(queue)
        .map_err(|err| RedDBError::Internal(err.to_string()))?;
    runtime
        .inner
        .db
        .save_collection_contract(event_queue_collection_contract(queue))
        .map_err(|err| RedDBError::Internal(err.to_string()))?;
    store.set_config_tree(
        &format!("queue.{queue}.mode"),
        &crate::serde_json::Value::String("fanout".to_string()),
    );
    Ok(())
}

fn event_queue_collection_contract(queue: &str) -> crate::physical::CollectionContract {
    let now = current_unix_ms();
    crate::physical::CollectionContract {
        name: queue.to_string(),
        declared_model: crate::catalog::CollectionModel::Queue,
        schema_mode: crate::catalog::SchemaMode::Dynamic,
        origin: crate::physical::ContractOrigin::Implicit,
        version: 1,
        created_at_unix_ms: now,
        updated_at_unix_ms: now,
        default_ttl_ms: None,
        vector_dimension: None,
        vector_metric: None,
        context_index_fields: Vec::new(),
        declared_columns: Vec::new(),
        table_def: None,
        timestamps_enabled: false,
        context_index_enabled: false,
        metrics_raw_retention_ms: None,
        metrics_rollup_policies: Vec::new(),
        metrics_tenant_identity: None,
        metrics_namespace: None,
        append_only: true,
        subscriptions: Vec::new(),
        analytics_config: Vec::new(),
        session_key: None,
        session_gap_ms: None,
        retention_duration_ms: None,
        analytical_storage: None,

        ai_policy: None,
    }
}

fn build_table_def_from_create_table(
    query: &CreateTableQuery,
) -> RedDBResult<crate::storage::schema::TableDef> {
    let mut table = crate::storage::schema::TableDef::new(query.name.clone());
    for column in &query.columns {
        if column.primary_key {
            table.primary_key.push(column.name.clone());
            table.constraints.push(
                crate::storage::schema::Constraint::new(
                    format!("pk_{}", column.name),
                    crate::storage::schema::ConstraintType::PrimaryKey,
                )
                .on_columns(vec![column.name.clone()]),
            );
        }
        if column.unique {
            table.constraints.push(
                crate::storage::schema::Constraint::new(
                    format!("uniq_{}", column.name),
                    crate::storage::schema::ConstraintType::Unique,
                )
                .on_columns(vec![column.name.clone()]),
            );
        }
        if column.not_null {
            table.constraints.push(
                crate::storage::schema::Constraint::new(
                    format!("not_null_{}", column.name),
                    crate::storage::schema::ConstraintType::NotNull,
                )
                .on_columns(vec![column.name.clone()]),
            );
        }
        table.columns.push(column_def_from_ddl(column)?);
    }
    // WITH timestamps = true: append the two runtime-managed columns
    // to the schema so resolved_contract_columns exposes them to the
    // normalize/validate path. Declared as UnsignedInteger (unix-ms),
    // not-nullable; the write path auto-fills them.
    if query.timestamps {
        table.columns.push(
            crate::storage::schema::ColumnDef::new(
                "created_at".to_string(),
                crate::storage::schema::DataType::UnsignedInteger,
            )
            .not_null(),
        );
        table.columns.push(
            crate::storage::schema::ColumnDef::new(
                "updated_at".to_string(),
                crate::storage::schema::DataType::UnsignedInteger,
            )
            .not_null(),
        );
        table.constraints.push(
            crate::storage::schema::Constraint::new(
                "not_null_created_at".to_string(),
                crate::storage::schema::ConstraintType::NotNull,
            )
            .on_columns(vec!["created_at".to_string()]),
        );
        table.constraints.push(
            crate::storage::schema::Constraint::new(
                "not_null_updated_at".to_string(),
                crate::storage::schema::ConstraintType::NotNull,
            )
            .on_columns(vec!["updated_at".to_string()]),
        );
    }
    table
        .validate()
        .map_err(|err| RedDBError::Query(format!("invalid table definition: {err}")))?;
    Ok(table)
}

fn column_def_from_ddl(column: &CreateColumnDef) -> RedDBResult<crate::storage::schema::ColumnDef> {
    let data_type = resolve_declared_data_type(&column.data_type)
        .map_err(|err| RedDBError::Query(err.to_string()))?;
    let mut column_def = crate::storage::schema::ColumnDef::new(column.name.clone(), data_type);
    if column.not_null {
        column_def = column_def.not_null();
    }
    if let Some(default) = &column.default {
        column_def = column_def.with_default(default.as_bytes().to_vec());
    }
    if column.compress.unwrap_or(0) > 0 {
        column_def = column_def.compressed();
    }
    if !column.enum_variants.is_empty() {
        column_def = column_def.with_variants(column.enum_variants.clone());
    }
    if let Some(precision) = column.decimal_precision {
        column_def = column_def.with_precision(precision);
    }
    if let Some(element_type) = &column.array_element {
        column_def = column_def.with_element_type(
            resolve_declared_data_type(element_type)
                .map_err(|err| RedDBError::Query(err.to_string()))?,
        );
    }
    column_def = column_def.with_metadata("ddl_data_type", column.data_type.clone());
    if column.unique {
        column_def = column_def.with_metadata("unique", "true");
    }
    if column.primary_key {
        column_def = column_def.with_metadata("primary_key", "true");
    }
    Ok(column_def)
}

fn current_unix_ms() -> u128 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default()
        .as_millis()
}

#[cfg(test)]
mod tests {
    use crate::auth::policies::{ActionPattern, Effect, Policy, ResourcePattern, Statement};
    use crate::auth::store::{AuthStore, PrincipalRef};
    use crate::auth::UserId;
    use crate::auth::{AuthConfig, Role};
    use crate::runtime::impl_core::{clear_current_auth_identity, set_current_auth_identity};
    use crate::storage::schema::Value;
    use crate::{RedDBOptions, RedDBRuntime};
    use std::sync::Arc;

    fn make_allow_policy(id: &str, action: &str, collection: &str) -> Policy {
        Policy {
            id: id.to_string(),
            version: 1,
            tenant: None,
            created_at: 0,
            updated_at: 0,
            statements: vec![Statement {
                sid: None,
                effect: Effect::Allow,
                actions: vec![ActionPattern::Exact(action.to_string())],
                resources: vec![ResourcePattern::Exact {
                    kind: "collection".to_string(),
                    name: collection.to_string(),
                }],
                condition: None,
            }],
        }
    }

    fn wire_auth_store(rt: &RedDBRuntime) -> Arc<AuthStore> {
        let store = Arc::new(AuthStore::new(AuthConfig::default()));
        *rt.inner.auth_store.write() = Some(store.clone());
        store
    }

    #[test]
    fn drop_denied_without_iam_policy() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE foo (id INT)").unwrap();
        let store = wire_auth_store(&rt);
        // Put a select-only policy so IAM mode activates, but give alice no drop policy.
        let select_only = Policy {
            id: "select-only".to_string(),
            version: 1,
            tenant: None,
            created_at: 0,
            updated_at: 0,
            statements: vec![Statement {
                sid: None,
                effect: Effect::Allow,
                actions: vec![ActionPattern::Exact("select".to_string())],
                resources: vec![ResourcePattern::Wildcard],
                condition: None,
            }],
        };
        store.put_policy_internal(select_only).unwrap();
        let alice = UserId::from_parts(None, "alice");
        store
            .attach_policy(PrincipalRef::User(alice), "select-only")
            .unwrap();
        set_current_auth_identity("alice".to_string(), Role::Write);
        let err = rt.execute_query("DROP TABLE foo").unwrap_err();
        clear_current_auth_identity();
        assert!(
            format!("{err}").contains("denied by IAM policy"),
            "got: {err}"
        );
    }

    #[test]
    fn drop_allowed_with_explicit_iam_policy() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE bar (id INT)").unwrap();
        let store = wire_auth_store(&rt);
        let policy = make_allow_policy("allow-drop-bar", "drop", "bar");
        store.put_policy_internal(policy).unwrap();
        let bob = UserId::from_parts(None, "bob");
        store
            .attach_policy(PrincipalRef::User(bob), "allow-drop-bar")
            .unwrap();
        set_current_auth_identity("bob".to_string(), Role::Write);
        rt.execute_query("DROP TABLE bar").unwrap();
        clear_current_auth_identity();
    }

    #[test]
    fn drop_allowed_with_wildcard_iam_policy() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE baz (id INT)").unwrap();
        let store = wire_auth_store(&rt);
        let policy = Policy {
            id: "allow-drop-all".to_string(),
            version: 1,
            tenant: None,
            created_at: 0,
            updated_at: 0,
            statements: vec![Statement {
                sid: None,
                effect: Effect::Allow,
                actions: vec![ActionPattern::Exact("drop".to_string())],
                resources: vec![ResourcePattern::Wildcard],
                condition: None,
            }],
        };
        store.put_policy_internal(policy).unwrap();
        let carl = UserId::from_parts(None, "carl");
        store
            .attach_policy(PrincipalRef::User(carl), "allow-drop-all")
            .unwrap();
        set_current_auth_identity("carl".to_string(), Role::Write);
        rt.execute_query("DROP TABLE baz").unwrap();
        clear_current_auth_identity();
    }

    #[test]
    fn truncate_denied_without_iam_policy() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE qux (id INT)").unwrap();
        let store = wire_auth_store(&rt);
        // Acceptance #2 (#712 / S5A): in `policy_only` mode a
        // principal with no matching policy is denied even if their
        // role would have permitted the action. The pre-#712 default
        // of "no policy → deny" only holds under `policy_only`, so
        // pin the mode explicitly here so the assertion holds
        // regardless of the construction-time default.
        store
            .set_enforcement_mode(crate::auth::enforcement_mode::PolicyEnforcementMode::PolicyOnly);
        // A policy exists (IAM active) but gives no truncate right.
        let select_only = Policy {
            id: "select-only-2".to_string(),
            version: 1,
            tenant: None,
            created_at: 0,
            updated_at: 0,
            statements: vec![Statement {
                sid: None,
                effect: Effect::Allow,
                actions: vec![ActionPattern::Exact("select".to_string())],
                resources: vec![ResourcePattern::Wildcard],
                condition: None,
            }],
        };
        store.put_policy_internal(select_only).unwrap();
        let dana = UserId::from_parts(None, "dana");
        store
            .attach_policy(PrincipalRef::User(dana), "select-only-2")
            .unwrap();
        set_current_auth_identity("dana".to_string(), Role::Write);
        let err = rt.execute_query("TRUNCATE TABLE qux").unwrap_err();
        clear_current_auth_identity();
        assert!(
            format!("{err}").contains("denied by IAM policy"),
            "got: {err}"
        );
    }

    #[test]
    fn truncate_table_clears_rows_and_preserves_schema_and_indexes() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE users (id INT, name TEXT)")
            .unwrap();
        rt.execute_query("INSERT INTO users (id, name) VALUES (1, 'ana'), (2, 'bob')")
            .unwrap();
        rt.execute_query("CREATE INDEX idx_users_id ON users (id) USING HASH")
            .unwrap();

        let truncated = rt.execute_query("TRUNCATE TABLE users").unwrap();
        assert_eq!(truncated.statement_type, "truncate");
        assert_eq!(truncated.affected_rows, 0);

        let empty = rt.execute_query("SELECT id FROM users").unwrap();
        assert!(empty.result.records.is_empty());

        rt.execute_query("INSERT INTO users (id, name) VALUES (3, 'cy')")
            .unwrap();
        let selected = rt
            .execute_query("SELECT name FROM users WHERE id = 3")
            .unwrap();
        let name = selected.result.records[0].get("name").unwrap();
        assert_eq!(name, &Value::text("cy"));
        assert!(rt.db().collection_contract("users").is_some());
        assert!(rt
            .inner
            .index_store
            .list_indices("users")
            .iter()
            .any(|index| index.name == "idx_users_id"));
    }

    #[test]
    fn truncate_collection_is_polymorphic_and_typed_mismatch_fails() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE QUEUE tasks").unwrap();
        rt.execute_query("QUEUE PUSH tasks {'job':'a'}").unwrap();

        let err = rt.execute_query("TRUNCATE TABLE tasks").unwrap_err();
        assert!(format!("{err}").contains("model mismatch: expected table, got queue"));

        rt.execute_query("TRUNCATE COLLECTION tasks").unwrap();
        let len = rt.execute_query("QUEUE LEN tasks").unwrap();
        assert_eq!(
            len.result.records[0].get("len"),
            Some(&Value::UnsignedInteger(0))
        );
    }

    #[test]
    fn truncate_system_schema_is_read_only() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        let err = rt
            .execute_query("TRUNCATE COLLECTION red.collections")
            .unwrap_err();
        assert!(format!("{err}").contains("system schema is read-only"));
    }

    // ── #302 / #310: TRUNCATE / DROP single-event semantics ────────────────

    fn queue_payloads(rt: &RedDBRuntime, queue: &str) -> Vec<crate::json::Value> {
        let result = rt
            .execute_query(&format!("QUEUE PEEK {queue} 100"))
            .expect("peek queue");
        result
            .result
            .records
            .iter()
            .map(
                |record| match record.get("payload").expect("payload column") {
                    Value::Json(bytes) => crate::json::from_slice(bytes).expect("json payload"),
                    other => panic!("expected JSON queue payload, got {other:?}"),
                },
            )
            .collect()
    }

    /// `TRUNCATE users` on an event-enabled collection emits exactly 1
    /// `truncate` event, not one delete event per row.
    #[test]
    fn truncate_event_enabled_table_emits_single_truncate_event() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE users (id INT, name TEXT) WITH EVENTS TO users_events")
            .unwrap();
        rt.execute_query(
            "INSERT INTO users (id, name) VALUES (1, 'alice'), (2, 'bob'), (3, 'carol')",
        )
        .unwrap();

        // Drain the 3 insert events so we start clean.
        rt.execute_query("QUEUE POP users_events COUNT 10").unwrap();

        rt.execute_query("TRUNCATE TABLE users").unwrap();

        let events = queue_payloads(&rt, "users_events");
        // Must be exactly 1 truncate event, not 3 delete events.
        assert_eq!(
            events.len(),
            1,
            "expected 1 truncate event, got {}",
            events.len()
        );
        let ev = events[0].as_object().expect("event is object");
        assert_eq!(
            ev.get("op").and_then(crate::json::Value::as_str),
            Some("truncate")
        );
        assert_eq!(
            ev.get("collection").and_then(crate::json::Value::as_str),
            Some("users")
        );
        assert_eq!(
            ev.get("entities_count")
                .and_then(crate::json::Value::as_u64),
            Some(3)
        );
        assert!(ev.get("ts").and_then(crate::json::Value::as_u64).is_some());
        assert!(ev.get("lsn").and_then(crate::json::Value::as_u64).is_some());
        assert!(ev
            .get("event_id")
            .and_then(crate::json::Value::as_str)
            .is_some_and(|s| !s.is_empty()));
    }

    /// `TRUNCATE users` on a collection without event subscription emits no events.
    #[test]
    fn truncate_no_events_collection_emits_nothing() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE plain (id INT, val TEXT)")
            .unwrap();
        rt.execute_query("INSERT INTO plain (id, val) VALUES (1, 'a'), (2, 'b')")
            .unwrap();
        // No EVENTS subscription — truncate must work without touching any queue.
        rt.execute_query("TRUNCATE TABLE plain").unwrap();
        // No crash, no queue to check. Just verify truncation happened.
        let rows = rt.execute_query("SELECT id FROM plain").unwrap();
        assert!(rows.result.records.is_empty());
    }

    /// `DROP TABLE users` on an event-enabled collection emits exactly 1
    /// `collection_dropped` event. The subscription is removed from the
    /// source contract but the target queue is preserved for consumer drain.
    #[test]
    fn drop_event_enabled_table_emits_single_collection_dropped_event() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE users (id INT, name TEXT) WITH EVENTS TO users_events")
            .unwrap();
        rt.execute_query("INSERT INTO users (id, name) VALUES (1, 'alice'), (2, 'bob')")
            .unwrap();

        // Drain insert events so we start clean.
        rt.execute_query("QUEUE POP users_events COUNT 10").unwrap();

        rt.execute_query("DROP TABLE users").unwrap();

        // Queue must still exist with 1 collection_dropped event.
        let events = queue_payloads(&rt, "users_events");
        assert_eq!(
            events.len(),
            1,
            "expected 1 collection_dropped event, got {}",
            events.len()
        );
        let ev = events[0].as_object().expect("event is object");
        assert_eq!(
            ev.get("op").and_then(crate::json::Value::as_str),
            Some("collection_dropped")
        );
        assert_eq!(
            ev.get("collection").and_then(crate::json::Value::as_str),
            Some("users")
        );
        assert_eq!(
            ev.get("final_entities_count")
                .and_then(crate::json::Value::as_u64),
            Some(2)
        );
        assert!(ev.get("ts").and_then(crate::json::Value::as_u64).is_some());
        assert!(ev.get("lsn").and_then(crate::json::Value::as_u64).is_some());
        assert!(ev
            .get("event_id")
            .and_then(crate::json::Value::as_str)
            .is_some_and(|s| !s.is_empty()));

        // Source collection is gone.
        let err = rt.execute_query("SELECT id FROM users").unwrap_err();
        assert!(
            format!("{err}").contains("users"),
            "expected not-found error"
        );
    }

    /// `DROP TABLE users` on a collection without event subscription works
    /// normally with no event emitted.
    #[test]
    fn drop_no_events_collection_emits_nothing() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE plain (id INT, val TEXT)")
            .unwrap();
        rt.execute_query("INSERT INTO plain (id, val) VALUES (1, 'a')")
            .unwrap();
        rt.execute_query("DROP TABLE plain").unwrap();
        // No crash and collection is gone.
        let err = rt.execute_query("SELECT id FROM plain").unwrap_err();
        assert!(format!("{err}").contains("plain"));
    }

    // ── #297: ops_filter + WHERE filter ────────────────────────────────────

    /// `WITH EVENTS (INSERT)` — UPDATE and DELETE events must NOT be emitted.
    #[test]
    fn ops_filter_insert_only_ignores_update_and_delete() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query(
            "CREATE TABLE items (id INT, val TEXT) WITH EVENTS (INSERT) TO items_events",
        )
        .unwrap();
        rt.execute_query("INSERT INTO items (id, val) VALUES (1, 'a')")
            .unwrap();
        rt.execute_query("UPDATE items SET val = 'b' WHERE id = 1")
            .unwrap();
        rt.execute_query("DELETE FROM items WHERE id = 1").unwrap();

        let events = queue_payloads(&rt, "items_events");
        // Only the INSERT should have fired.
        assert_eq!(
            events.len(),
            1,
            "expected 1 insert event, got {}",
            events.len()
        );
        assert_eq!(
            events[0]
                .as_object()
                .unwrap()
                .get("op")
                .and_then(crate::json::Value::as_str),
            Some("insert")
        );
    }

    /// `WITH EVENTS WHERE status = 'active'` — only rows matching the predicate generate events.
    #[test]
    fn where_filter_skips_rows_that_do_not_match() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query(
            "CREATE TABLE users (id INT, status TEXT) WITH EVENTS WHERE status = 'active' TO users_events",
        )
        .unwrap();

        // This row should generate an event.
        rt.execute_query("INSERT INTO users (id, status) VALUES (1, 'active')")
            .unwrap();
        // This row should NOT generate an event.
        rt.execute_query("INSERT INTO users (id, status) VALUES (2, 'inactive')")
            .unwrap();

        let events = queue_payloads(&rt, "users_events");
        assert_eq!(
            events.len(),
            1,
            "expected 1 event (only active), got {}",
            events.len()
        );
        let ev = events[0].as_object().unwrap();
        assert_eq!(
            ev.get("op").and_then(crate::json::Value::as_str),
            Some("insert")
        );
        let after = ev.get("after").unwrap().as_object().unwrap();
        assert_eq!(
            after.get("status").and_then(crate::json::Value::as_str),
            Some("active")
        );
    }

    /// `WITH EVENTS (INSERT, UPDATE) WHERE status = 'active'` — combination functional.
    #[test]
    fn ops_filter_and_where_filter_combined() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query(
            "CREATE TABLE items (id INT, status TEXT) WITH EVENTS (INSERT, UPDATE) WHERE status = 'active' TO items_events",
        )
        .unwrap();

        // INSERT active → event
        rt.execute_query("INSERT INTO items (id, status) VALUES (1, 'active')")
            .unwrap();
        // INSERT inactive → no event
        rt.execute_query("INSERT INTO items (id, status) VALUES (2, 'inactive')")
            .unwrap();
        // UPDATE row 1 to inactive → after = inactive, no event
        rt.execute_query("UPDATE items SET status = 'inactive' WHERE id = 1")
            .unwrap();
        // DELETE → ops_filter excludes it
        rt.execute_query("DELETE FROM items WHERE id = 2").unwrap();

        let events = queue_payloads(&rt, "items_events");
        // Only the first INSERT (active) fires; UPDATE result is inactive so skipped; DELETE excluded by ops_filter.
        assert_eq!(
            events.len(),
            1,
            "expected 1 event, got {}: {events:?}",
            events.len()
        );
        assert_eq!(
            events[0]
                .as_object()
                .unwrap()
                .get("op")
                .and_then(crate::json::Value::as_str),
            Some("insert")
        );
    }

    /// WHERE filter on DELETE events — the before-state (pre-image) is evaluated.
    #[test]
    fn where_filter_on_delete_checks_before_state() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query(
            "CREATE TABLE users (id INT, status TEXT) WITH EVENTS (DELETE) WHERE status = 'active' TO users_events",
        )
        .unwrap();

        rt.execute_query("INSERT INTO users (id, status) VALUES (1, 'active'), (2, 'inactive')")
            .unwrap();

        // Delete active row → event (before-state was active)
        rt.execute_query("DELETE FROM users WHERE id = 1").unwrap();
        // Delete inactive row → no event (before-state was inactive)
        rt.execute_query("DELETE FROM users WHERE id = 2").unwrap();

        let events = queue_payloads(&rt, "users_events");
        assert_eq!(
            events.len(),
            1,
            "expected 1 delete event, got {}",
            events.len()
        );
        let ev = events[0].as_object().unwrap();
        assert_eq!(
            ev.get("op").and_then(crate::json::Value::as_str),
            Some("delete")
        );
    }

    // ── #301: schema evolution OperatorEvent on ALTER ───────────────────────

    /// ADD COLUMN on event-enabled table must succeed (OperatorEvent is best-effort).
    #[test]
    fn alter_add_column_on_event_enabled_table_succeeds() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE users (id INT, name TEXT) WITH EVENTS TO users_events")
            .unwrap();
        // Must not error — OperatorEvent emission is best-effort (no global sink in tests).
        rt.execute_query("ALTER TABLE users ADD COLUMN phone TEXT")
            .unwrap();
        // The column is now in the contract.
        let contract = rt.db().collection_contract("users").unwrap();
        assert!(
            contract.declared_columns.iter().any(|c| c.name == "phone"),
            "phone column should be in contract"
        );
        // Subscription still enabled after the alter.
        assert!(
            contract.subscriptions.iter().any(|s| s.enabled),
            "subscription should remain enabled"
        );
    }

    /// DROP COLUMN on event-enabled table must succeed; non-column ALTERs
    /// (like ENABLE ROW LEVEL SECURITY) must also succeed without emitting.
    #[test]
    fn alter_drop_column_and_rls_on_event_enabled_table_succeeds() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query(
            "CREATE TABLE items (id INT, secret TEXT, status TEXT) WITH EVENTS TO items_events",
        )
        .unwrap();
        // DROP COLUMN — schema change event path exercises, must not error.
        rt.execute_query("ALTER TABLE items DROP COLUMN secret")
            .unwrap();
        let contract = rt.db().collection_contract("items").unwrap();
        assert!(
            !contract.declared_columns.iter().any(|c| c.name == "secret"),
            "secret column should be removed"
        );
        // ENABLE RLS — non-column op, no schema-change event (coverage).
        rt.execute_query("ALTER TABLE items ENABLE ROW LEVEL SECURITY")
            .unwrap();
        // Collection and subscription still intact.
        assert!(
            contract.subscriptions.iter().any(|s| s.enabled),
            "subscription should remain enabled"
        );
    }

    /// Slice G (#675) — every newly-created `CollectionModel::Vector`
    /// collection is marked `vector.turbo` and gains a materialised
    /// `TurboCollectionState`. The marker is what the SEARCH/INSERT
    /// hot paths read to branch between TurboQuant and the legacy
    /// brute-force fallback.
    #[test]
    fn create_vector_marks_collection_as_turbo_baseline() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE VECTOR embeddings DIM 4").unwrap();
        let store = rt.db().store();
        assert!(
            crate::runtime::vector_turbo_kind::is_turbo(&store, "embeddings"),
            "new vector collections must be turbo-marked baseline"
        );
        assert!(
            rt.db().turbo_state("embeddings").is_some(),
            "turbo_state must materialise after CREATE VECTOR"
        );
    }

    /// Non-vector collections must NOT be turbo-marked. Guards against
    /// the always-baseline change accidentally leaking the marker onto
    /// CREATE TABLE / CREATE DOCUMENT / etc.
    #[test]
    fn create_table_does_not_mark_turbo() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE TABLE plain (id INT)").unwrap();
        let store = rt.db().store();
        assert!(
            !crate::runtime::vector_turbo_kind::is_turbo(&store, "plain"),
            "non-vector collections must not gain the turbo marker"
        );
        assert!(rt.db().turbo_state("plain").is_none());
    }

    /// `CREATE COLLECTION KIND vector.turbo` continues to mark the
    /// collection (idempotent with the new always-baseline path).
    #[test]
    fn create_collection_kind_vector_turbo_still_marked() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query("CREATE COLLECTION turbo_v KIND vector.turbo DIM 4")
            .unwrap();
        let store = rt.db().store();
        assert!(crate::runtime::vector_turbo_kind::is_turbo(
            &store, "turbo_v"
        ));
        assert!(rt.db().turbo_state("turbo_v").is_some());
    }

    /// Issue #1271: a declared AI policy is persisted in the catalog and
    /// reads back identical via the collection contract (introspection).
    #[test]
    fn create_table_persists_and_introspects_ai_policy() {
        use crate::catalog::{ModerateDegradedMode, ModerateRejectAction};
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        rt.execute_query(
            "CREATE TABLE posts (id INT, title TEXT, body TEXT, photo TEXT) WITH ( \
               EMBED (fields = ('title', 'body'), provider = 'openai', model = 'text-embedding-3-small'), \
               MODERATE (fields = ('body'), provider = 'openai', model = 'omni-moderation-latest', sync = true, degraded = closed, on_reject = flag), \
               VISION (image_field = 'photo', outputs = ('caption'), provider = 'openai', model = 'gpt-4o') \
             )",
        )
        .expect("create table with ai policy");

        let contracts = rt.db().collection_contracts();
        let contract = contracts
            .iter()
            .find(|c| c.name == "posts")
            .expect("contract persisted");
        let policy = contract.ai_policy.as_ref().expect("ai policy persisted");

        let embed = policy.embed.as_ref().expect("embed");
        assert_eq!(embed.fields, vec!["title".to_string(), "body".to_string()]);
        assert_eq!(embed.model, "text-embedding-3-small");

        let moderate = policy.moderate.as_ref().expect("moderate");
        assert!(moderate.sync_gate);
        assert_eq!(moderate.degraded_mode, ModerateDegradedMode::Closed);
        assert_eq!(moderate.reject_action, ModerateRejectAction::Flag);

        let vision = policy.vision.as_ref().expect("vision");
        assert_eq!(vision.image_field, "photo");
        assert_eq!(vision.model, "gpt-4o");
    }

    /// Issue #1271 / #1269: a policy wiring a provider to a modality it
    /// cannot serve is rejected at DDL time, and the collection is not
    /// created. Anthropic has no embeddings product in the matrix.
    #[test]
    fn create_table_rejects_ai_policy_incapable_provider() {
        let rt = RedDBRuntime::with_options(RedDBOptions::in_memory()).unwrap();
        let err = rt
            .execute_query(
                "CREATE TABLE bad (id INT, body TEXT) WITH ( \
                   EMBED (fields = ('body'), provider = 'anthropic', model = 'claude-3-5-sonnet') \
                 )",
            )
            .unwrap_err();
        assert!(
            err.to_string()
                .contains("cannot serve the 'embed' modality"),
            "{err}"
        );
        assert!(
            rt.db().store().get_collection("bad").is_none(),
            "rejected DDL must not create the collection"
        );
    }
}