reddb_server/runtime/

execution_context.rs

//! Per-thread runtime execution context.
//!
//! This module owns connection identity, auth/tenant scope, statement-local
//! config/secret resolvers, and MVCC snapshot visibility helpers.

use std::collections::{HashMap, HashSet};
use std::sync::Arc;

use crate::api::{RedDBError, RedDBResult};
use crate::storage::RedDB;
use reddb_types::Value;

thread_local! {
    /// Current connection id for the executing statement. Set by the
    /// per-connection wrapper (stdio/gRPC handlers) before dispatching
    /// into `execute_query`; falls back to `0` for embedded callers.
    static CURRENT_CONN_ID: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };

    /// Authenticated user + role for the executing statement (Phase 2.5.2
    /// RLS enforcement). Set by the transport middleware after validating
    /// credentials (password / cert / oauth); unset means "anonymous" /
    /// "embedded" — RLS policies degrade to the role-agnostic subset.
    ///
    /// `None` skips RLS injection entirely; `Some((username, role))`
    /// passes `role` to `matching_rls_policies(table, Some(role), action)`.
    static CURRENT_AUTH_IDENTITY: std::cell::RefCell<Option<(String, crate::auth::Role)>> =
        const { std::cell::RefCell::new(None) };

    /// Immutable principal produced by credential validation. Unlike
    /// `CURRENT_TENANT_ID`, this value is never changed by routing/scope SQL.
    static CURRENT_AUTH_PRINCIPAL: std::cell::RefCell<Option<crate::auth::UserId>> =
        const { std::cell::RefCell::new(None) };

    /// MVCC snapshot scoped to the currently-executing statement (Phase
    /// 2.3.2d PG parity). `execute_query` captures it on entry and drops
    /// it on exit; every scan consults it via
    /// `entity_visible_under_current_snapshot` to hide tuples whose xmin
    /// hasn't committed or whose xmax already has.
    ///
    /// `None` means "pre-MVCC semantics" — the read path returns every
    /// tuple regardless of xmin/xmax. All embedded callers that bypass
    /// `execute_query` see this default.
    static CURRENT_SNAPSHOT: std::cell::RefCell<Option<SnapshotContext>> =
        const { std::cell::RefCell::new(None) };

    /// Cheap presence flag for `CURRENT_SNAPSHOT`. Scan hot paths
    /// poll this instead of `borrow()`-ing the RefCell on every
    /// row — the common case (autocommit / no MVCC session) reads
    /// one atomic `Cell<bool>` and short-circuits, saving ~10ns × N
    /// rows on aggregate_group / select_range scans.
    static HAS_SNAPSHOT: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };

    /// Session-scoped tenant id for the current connection (Phase 2.5.3
    /// multi-tenancy). Populated by `SET TENANT 'id'` or by transport
    /// middleware after resolving tenant from auth claims. Read by the
    /// `CURRENT_TENANT()` scalar function — RLS policies typically
    /// combine it as `USING (tenant_id = CURRENT_TENANT())` to scope
    /// every query to one tenant.
    ///
    /// `None` means "no tenant bound" — `CURRENT_TENANT()` returns
    /// NULL, and RLS policies that gate on it hide every row.
    static CURRENT_TENANT_ID: std::cell::RefCell<Option<String>> =
        const { std::cell::RefCell::new(None) };

    /// Statement-local config resolver. SQL expressions materialize the
    /// `red.config` snapshot lazily on the first `$config.*`/`CONFIG()`
    /// access, keeping ordinary statements on the zero-scan path.
    static CURRENT_CONFIG_RESOLVER: std::cell::RefCell<Option<ConfigResolver>> =
        const { std::cell::RefCell::new(None) };

    /// Statement-local secret resolver. SQL expressions materialize the
    /// vault KV snapshot lazily on first `$secret.*` access, then use
    /// lock-free map reads for the rest of the statement.
    static CURRENT_SECRET_RESOLVER: std::cell::RefCell<Option<SecretResolver>> =
        const { std::cell::RefCell::new(None) };

    /// Statement-local plain-KV resolver (#1602). Mirrors the secret
    /// resolver but reads the non-encrypted `plain_kv` store and gates on
    /// `kv:read`. Materialized lazily on the first `$kv.*` access.
    static CURRENT_KV_RESOLVER: std::cell::RefCell<Option<KvResolver>> =
        const { std::cell::RefCell::new(None) };
}

pub use reddb_engine::transaction::read::SnapshotContext;
use reddb_engine::transaction::read::{record_serializable_read, visibility_check};

/// Install a connection id on the current thread for the duration of a
/// statement. The Transaction State module is keyed
/// by this id so different connections can hold independent BEGINs.
///
/// Pub so transports (PG wire, gRPC, HTTP per-request spawners) and
/// tests can emulate per-connection isolation. Call it once when
/// binding the connection's worker thread; pair with
/// `clear_current_connection_id` on teardown.
pub fn set_current_connection_id(id: u64) {
    CURRENT_CONN_ID.with(|c| c.set(id));
}

/// Reset the thread's connection id back to `0` (autocommit).
pub fn clear_current_connection_id() {
    CURRENT_CONN_ID.with(|c| c.set(0));
}

/// Read the connection id set by `set_current_connection_id`. Returns
/// `0` when no wrapper installed one — auto-commit path.
pub fn current_connection_id() -> u64 {
    CURRENT_CONN_ID.with(|c| c.get())
}

/// Install the authenticated identity for the current thread (Phase 2.5.2
/// RLS enforcement). Transport layers call this right after resolving
/// auth so the query dispatch can fold RLS policies into the filter.
pub fn set_current_auth_identity(username: String, role: crate::auth::Role) {
    set_current_auth_principal(crate::auth::UserId::platform(username), role);
}

/// Install the structured principal returned by credential validation.
pub fn set_current_auth_principal(principal: crate::auth::UserId, role: crate::auth::Role) {
    CURRENT_AUTH_IDENTITY.with(|cell| {
        *cell.borrow_mut() = Some((principal.username.clone(), role));
    });
    CURRENT_AUTH_PRINCIPAL.with(|cell| *cell.borrow_mut() = Some(principal));
}

/// Replace only the SQL/RLS projection while preserving the immutable
/// credential principal used by authorization.
pub(crate) fn set_current_auth_projection(username: String, role: crate::auth::Role) {
    CURRENT_AUTH_IDENTITY.with(|cell| *cell.borrow_mut() = Some((username, role)));
}

/// Clear the thread-local auth identity. Transports call this after the
/// statement completes so pooled threads don't leak identities across
/// requests.
pub fn clear_current_auth_identity() {
    CURRENT_AUTH_IDENTITY.with(|cell| *cell.borrow_mut() = None);
    CURRENT_AUTH_PRINCIPAL.with(|cell| *cell.borrow_mut() = None);
}

/// Read the current-thread auth identity. `None` when no transport
/// installed one (embedded mode / anonymous access).
pub(crate) fn current_auth_identity() -> Option<(String, crate::auth::Role)> {
    CURRENT_AUTH_IDENTITY.with(|cell| cell.borrow().clone())
}

/// Read the immutable credential principal, independently of mutable scope.
pub(crate) fn current_auth_principal() -> Option<crate::auth::UserId> {
    CURRENT_AUTH_PRINCIPAL.with(|cell| cell.borrow().clone())
}

/// Public probe of the thread-local auth identity for callers outside
/// the `runtime` module (e.g. the AI credential resolver, which audits
/// who triggered a secret read on behalf of a query).
pub fn current_auth_identity_for_audit() -> Option<(String, crate::auth::Role)> {
    current_auth_identity()
}

/// Install the session tenant id for the current thread (Phase 2.5.3
/// multi-tenancy). Called by `SET TENANT 'id'` dispatch and by
/// transport middleware that resolves tenant from auth claims (e.g.
/// JWT `tenant` claim, HTTP header, subdomain).
pub fn set_current_tenant(tenant_id: String) {
    CURRENT_TENANT_ID.with(|cell| *cell.borrow_mut() = Some(tenant_id));
}

/// Clear the current-thread tenant — `CURRENT_TENANT()` will then
/// return NULL and any RLS policy gated on it will hide every row.
pub fn clear_current_tenant() {
    CURRENT_TENANT_ID.with(|cell| *cell.borrow_mut() = None);
}

/// Read the current-thread tenant id, applying overrides in priority order:
///   1. `WITHIN TENANT '<id>' …` per-statement override (highest)
///   2. `SET LOCAL TENANT '<id>'` transaction-local override (consulted
///      only when the current connection has an open transaction)
///   3. `SET TENANT '<id>'` session-level thread-local
///   4. `None` (deny-default for RLS).
///
/// The transaction-local layer is read through the runtime; an embedded
/// helper crate that has no `RedDBRuntime` access still gets correct
/// behaviour for layers 1, 3, and 4.
pub fn current_tenant() -> Option<String> {
    let inherited = CURRENT_TENANT_ID.with(|cell| cell.borrow().clone());
    if let Some(over) = current_scope_override() {
        if over.tenant.is_active() {
            return over.tenant.resolve(inherited);
        }
    }
    if let Some(tx_local) = current_tx_local_tenant() {
        return tx_local;
    }
    inherited
}

thread_local! {
    /// Snapshot of the active connection's transaction-local tenant for
    /// the current `execute_query` call. Outer `Some(_)` means "a
    /// transaction-local tenant override is active for this call";
    /// inner is the override's value (`Some(s)` overrides to `s`,
    /// `None` overrides to NULL/cleared). Refreshed at the top of every
    /// `execute_query` invocation and cleared by the RAII guard on
    /// return so pooled connections cannot leak the override past the
    /// statement that owns it.
    static TX_LOCAL_TENANT: std::cell::RefCell<Option<Option<String>>> =
        const { std::cell::RefCell::new(None) };
}

fn current_tx_local_tenant() -> Option<Option<String>> {
    TX_LOCAL_TENANT.with(|cell| cell.borrow().clone())
}

/// Recognise `SET LOCAL TENANT '<id>'` / `SET LOCAL TENANT NULL` —
/// returns `Ok(Some(Some(id)))` for an explicit value, `Ok(Some(None))`
/// for an explicit NULL clear, `Ok(None)` when the input is not a
/// `SET LOCAL TENANT` statement at all, and `Err` when the prefix
/// matches but the value is malformed.
pub(crate) fn parse_set_local_tenant(query: &str) -> RedDBResult<Option<Option<String>>> {
    let mut tokens = query.split_ascii_whitespace();
    let Some(w1) = tokens.next() else {
        return Ok(None);
    };
    if !w1.eq_ignore_ascii_case("SET") {
        return Ok(None);
    }
    let Some(w2) = tokens.next() else {
        return Ok(None);
    };
    if !w2.eq_ignore_ascii_case("LOCAL") {
        return Ok(None);
    }
    let Some(w3) = tokens.next() else {
        return Ok(None);
    };
    if !w3.eq_ignore_ascii_case("TENANT") {
        return Ok(None);
    }
    let rest: String = tokens.collect::<Vec<_>>().join(" ");
    let rest = rest.trim().trim_end_matches(';').trim();
    let value_str = rest.strip_prefix('=').map(|s| s.trim()).unwrap_or(rest);
    if value_str.is_empty() {
        return Err(RedDBError::Query(
            "SET LOCAL TENANT expects a string literal or NULL".to_string(),
        ));
    }
    if value_str.eq_ignore_ascii_case("NULL") {
        return Ok(Some(None));
    }
    if value_str.starts_with('\'') && value_str.ends_with('\'') && value_str.len() >= 2 {
        let inner = &value_str[1..value_str.len() - 1];
        return Ok(Some(Some(inner.to_string())));
    }
    Err(RedDBError::Query(format!(
        "SET LOCAL TENANT expects a string literal or NULL, got `{value_str}`"
    )))
}

pub(crate) struct TxLocalTenantGuard;

impl TxLocalTenantGuard {
    pub fn install(value: Option<Option<String>>) -> Self {
        TX_LOCAL_TENANT.with(|cell| *cell.borrow_mut() = value);
        Self
    }
}

impl Drop for TxLocalTenantGuard {
    fn drop(&mut self) {
        TX_LOCAL_TENANT.with(|cell| *cell.borrow_mut() = None);
    }
}

thread_local! {
    /// Stack of `WITHIN ... <stmt>` overrides active on the current
    /// thread. Every entry corresponds to one in-flight `execute_query`
    /// call that started with a `WITHIN` prefix; the entry is pushed
    /// before dispatch and popped before the call returns. The stack
    /// shape supports nested invocations (e.g. a view body that itself
    /// re-enters execute_query).
    static SCOPE_OVERRIDES: std::cell::RefCell<Vec<crate::runtime::within_clause::ScopeOverride>> =
        const { std::cell::RefCell::new(Vec::new()) };
}

pub(crate) fn push_scope_override(over: crate::runtime::within_clause::ScopeOverride) {
    SCOPE_OVERRIDES.with(|cell| cell.borrow_mut().push(over));
}

pub(crate) fn pop_scope_override() {
    SCOPE_OVERRIDES.with(|cell| {
        cell.borrow_mut().pop();
    });
}

pub(crate) fn current_scope_override() -> Option<crate::runtime::within_clause::ScopeOverride> {
    SCOPE_OVERRIDES.with(|cell| cell.borrow().last().cloned())
}

/// Cheap probe: is any `WITHIN …` scope override active on this
/// thread? The fast-path needs to know without paying for the full
/// `.last().cloned()` allocation — just peek at stack length.
pub(crate) fn has_scope_override_active() -> bool {
    SCOPE_OVERRIDES.with(|cell| !cell.borrow().is_empty())
}

/// RAII guard pairing `push_scope_override` with the matching pop, so
/// the stack stays balanced even when the inner `execute_query` returns
/// early via `?`.
pub(crate) struct ScopeOverrideGuard;

impl ScopeOverrideGuard {
    pub fn install(over: crate::runtime::within_clause::ScopeOverride) -> Self {
        push_scope_override(over);
        Self
    }
}

impl Drop for ScopeOverrideGuard {
    fn drop(&mut self) {
        pop_scope_override();
    }
}

/// Read the current-thread auth identity, honouring per-statement
/// `WITHIN ... USER '<u>' AS ROLE '<r>'` overrides. The override only
/// supplies projected strings — it never grants additional privilege —
/// so callers that need to make authorisation decisions must read from
/// the underlying `current_auth_identity()` directly.
pub(crate) fn current_user_projected() -> Option<String> {
    let inherited = current_auth_identity().map(|(u, _)| u);
    if let Some(over) = current_scope_override() {
        if over.user.is_active() {
            return over.user.resolve(inherited);
        }
    }
    inherited
}

pub(crate) fn current_role_projected() -> Option<String> {
    let inherited = current_auth_identity().map(|(_, r)| format!("{r:?}").to_lowercase());
    if let Some(over) = current_scope_override() {
        if over.role.is_active() {
            return over.role.resolve(inherited);
        }
    }
    inherited
}

pub(crate) fn current_secret_value(path: &str) -> Option<Value> {
    try_current_secret_value(path).ok().flatten()
}

pub(crate) fn try_current_secret_value(path: &str) -> RedDBResult<Option<Value>> {
    let key = path.to_ascii_lowercase();
    CURRENT_SECRET_RESOLVER.with(|cell| {
        let mut resolver = cell.borrow_mut();
        let Some(resolver) = resolver.as_mut() else {
            return Ok(None);
        };
        if let Some(value) = resolver.values.get(&key) {
            return Ok(value.clone());
        }
        let value = resolver.runtime.query_secret_value(&key)?;
        resolver.values.insert(key, value.clone());
        Ok(value)
    })
}

/// Decrypt only while evaluating a query. Stored and projected values retain
/// their Secret representation, so formatters cannot expose plaintext.
pub(crate) fn secret_query_input(value: Value) -> Option<Value> {
    if !matches!(value, Value::Secret(_)) {
        return Some(value);
    }
    CURRENT_SECRET_RESOLVER.with(|cell| {
        let resolver = cell.borrow();
        resolver.as_ref()?.runtime.secret_query_input(value)
    })
}

pub(crate) fn try_secret_query_input(
    value: Value,
) -> Result<Option<Value>, super::impl_dml_crypto::SecretInputReadLimit> {
    if !matches!(value, Value::Secret(_)) {
        return Ok(Some(value));
    }
    CURRENT_SECRET_RESOLVER.with(|cell| {
        let resolver = cell.borrow();
        match resolver.as_ref() {
            Some(resolver) => resolver.runtime.try_secret_query_input(value),
            None => Ok(None),
        }
    })
}

pub(crate) fn secret_query_output(value: Value) -> crate::RedDBResult<Value> {
    if value.is_null() || matches!(value, Value::Secret(_)) {
        return Ok(value);
    }
    CURRENT_SECRET_RESOLVER.with(|cell| {
        let resolver = cell.borrow();
        let resolver = resolver.as_ref().ok_or_else(|| {
            RedDBError::Query("secret expression requires an active statement".into())
        })?;
        resolver.runtime.secret_query_output(value)
    })
}

#[cfg(test)]
fn secret_value_from_snapshot(values: &HashMap<String, String>, key: &str) -> Option<String> {
    if key.starts_with("red.secret.") {
        return None;
    }
    values.get(key).cloned()
}

struct SecretResolver {
    runtime: super::RedDBRuntime,
    values: HashMap<String, Option<Value>>,
}

pub(crate) struct SecretStoreGuard {
    previous: Option<SecretResolver>,
}

impl SecretStoreGuard {
    pub(super) fn install(runtime: &super::RedDBRuntime) -> Self {
        let previous = CURRENT_SECRET_RESOLVER.with(|cell| {
            cell.replace(Some(SecretResolver {
                runtime: runtime.clone(),
                values: HashMap::new(),
            }))
        });
        Self { previous }
    }
}

impl Drop for SecretStoreGuard {
    fn drop(&mut self) {
        let previous = self.previous.take();
        CURRENT_SECRET_RESOLVER.with(|cell| {
            cell.replace(previous);
        });
    }
}

/// Resolve `$kv.<path>` from the plain (non-encrypted) KV store (#1602).
///
/// The parser desugars `$kv.<path>` to `__KV_REF("red.kv/<path>")`; this
/// strips the `red.kv/` prefix and looks up the bare key in the
/// statement-local snapshot, gating each hit on `kv:read`. Returns `None`
/// (→ SQL NULL) when the key is absent or the principal is denied — never
/// an error, mirroring the secret resolver's deny-to-NULL behaviour.
pub(crate) fn current_kv_value(path: &str) -> Option<String> {
    let key = path.to_ascii_lowercase();
    CURRENT_KV_RESOLVER.with(|cell| {
        let mut resolver = cell.borrow_mut();
        let resolver = resolver.as_mut()?;
        if resolver.values.is_none() {
            resolver.values = resolver
                .store
                .as_ref()
                .map(|store| store.plain_kv_snapshot());
        }
        let values = resolver.values.as_ref()?;
        // Accept both the namespaced `red.kv/<key>` form (from the
        // `$kv.*` desugar) and the bare key (from `update_current_kv_value`
        // after a `SET KV`).
        let found = values
            .get(&key)
            .map(|value| (key.as_str(), value))
            .or_else(|| {
                key.strip_prefix("red.kv/")
                    .and_then(|rest| values.get(rest).map(|value| (rest, value)))
            })?;
        if !resolver.can_read(found.0) {
            return None;
        }
        Some(found.1.clone())
    })
}

struct KvResolver {
    store: Option<Arc<crate::auth::store::AuthStore>>,
    values: Option<HashMap<String, String>>,
    identity: Option<(String, crate::auth::Role, Option<String>)>,
}

impl KvResolver {
    fn can_read(&self, key: &str) -> bool {
        let Some(store) = &self.store else {
            return true;
        };
        let Some((username, role, tenant)) = &self.identity else {
            return true;
        };
        let principal = crate::auth::UserId::from_parts(tenant.as_deref(), username);
        let mut resource =
            crate::auth::policies::ResourceRef::new("kv".to_string(), key.to_string());
        if let Some(tenant) = tenant {
            resource = resource.with_tenant(tenant.clone());
        }
        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: tenant.is_none(),
        };
        store.check_policy_authz_with_role(&principal, "kv:read", &resource, &ctx, *role)
    }
}

pub(crate) struct KvStoreGuard {
    // Boxed to keep the stack footprint of nested guards small. Each
    // StatementFrameGuards is live for the full recursive call depth of a
    // materialized-view refresh chain; unboxed KvResolver (≈120 B) would
    // push those deep paths past the 8 MB stack limit.
    previous: Option<Box<KvResolver>>,
}

impl KvStoreGuard {
    pub(super) fn install(store: Option<Arc<crate::auth::store::AuthStore>>) -> Self {
        let previous = CURRENT_KV_RESOLVER.with(|cell| {
            cell.replace(Some(KvResolver {
                store,
                values: None,
                identity: current_auth_identity().map(|(username, role)| {
                    let tenant = current_tenant();
                    (username, role, tenant)
                }),
            }))
        });
        Self {
            previous: previous.map(Box::new),
        }
    }
}

impl Drop for KvStoreGuard {
    fn drop(&mut self) {
        let previous = self.previous.take().map(|b| *b);
        CURRENT_KV_RESOLVER.with(|cell| {
            cell.replace(previous);
        });
    }
}

/// Update the statement-local KV snapshot after a `SET KV` / `DELETE KV`
/// so a subsequent `$kv.*` read in the same statement observes the write.
pub(crate) fn update_current_kv_value(path: &str, value: Option<String>) {
    let key = path.to_ascii_lowercase();
    CURRENT_KV_RESOLVER.with(|cell| {
        if let Some(resolver) = cell.borrow_mut().as_mut() {
            let Some(values) = resolver.values.as_mut() else {
                return;
            };
            match value {
                Some(value) => {
                    values.insert(key, value);
                }
                None => {
                    values.remove(&key);
                }
            }
        }
    });
}

pub(crate) fn current_config_value(path: &str) -> Option<Value> {
    try_current_config_value(path).ok().flatten()
}

pub(crate) fn try_current_config_value(path: &str) -> RedDBResult<Option<Value>> {
    let key = path.to_ascii_lowercase();
    CURRENT_CONFIG_RESOLVER.with(|cell| {
        let mut resolver = cell.borrow_mut();
        let Some(resolver) = resolver.as_mut() else {
            return Ok(None);
        };
        if !resolver.can_read(&key) {
            return Ok(None);
        }
        if resolver.values.is_none() {
            resolver.values = Some(latest_config_snapshot(&resolver.db)?);
        }
        // #1370 — `$config.<path>` desugars to `CONFIG("red.config/<path>")`,
        // but `SET CONFIG <path>` stores under the bare key. Mirror the secret
        // resolver: after the namespaced key, fall back to the stripped bare
        // key. Track the key
        // that matched so the `config:read` gate authorizes the real target.
        let found = {
            let values = resolver
                .values
                .as_ref()
                .expect("invariant: successful snapshot is installed");
            values
                .get(&key)
                .map(|value| (key.clone(), value.clone()))
                .or_else(|| {
                    key.strip_prefix("red.config/").and_then(|rest| {
                        values
                            .get(rest)
                            .map(|value| (rest.to_string(), value.clone()))
                    })
                })
        };
        let Some(found) = found else { return Ok(None) };
        // #1743 — hard-block the reserved `red.config.*` namespace and gate the
        // read on `config:read`, mirroring the `$secret` sibling. Denied reads
        // resolve to `None` (→ SQL NULL), never an error.
        if !resolver.can_read(&found.0) {
            return Ok(None);
        }
        Ok(Some(found.1))
    })
}

pub(crate) fn update_current_config_value(path: &str, value: Value) {
    let key = path.to_ascii_lowercase();
    CURRENT_CONFIG_RESOLVER.with(|cell| {
        if let Some(resolver) = cell.borrow_mut().as_mut() {
            if let Some(values) = resolver.values.as_mut() {
                values.insert(key, value);
            }
        }
    });
}

pub(crate) fn update_current_secret_value(_path: &str, _value: Option<String>) {
    CURRENT_SECRET_RESOLVER.with(|cell| {
        if let Some(resolver) = cell.borrow_mut().as_mut() {
            resolver.values.clear();
        }
    });
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Companion to `raw_iteration_confined_to_maintenance_allowlist`:
    /// the snapshot thread-local is an implementation detail of the
    /// statement frame (issue #2138). It must stay private to this module,
    /// so the only way any other module can observe ambient snapshot state
    /// is `capture_current_snapshot`, which hands back an owned `Option`
    /// the caller then passes explicitly into the scan API.
    #[test]
    fn snapshot_thread_local_stays_private_to_the_statement_frame() {
        let src = include_str!("execution_context.rs");

        for name in ["CURRENT_SNAPSHOT", "HAS_SNAPSHOT"] {
            assert!(
                !src.contains(&format!("pub static {name}"))
                    && !src.contains(&format!("pub(crate) static {name}")),
                "{name} must stay private to execution_context; expose an explicit \
                 Option<SnapshotContext> via capture_current_snapshot instead"
            );
        }

        assert!(
            src.contains("the only sanctioned ambient read"),
            "capture_current_snapshot must keep documenting that it is the single \
             sanctioned ambient read of the snapshot thread-local"
        );
    }

    #[test]
    fn secret_snapshot_hard_blocks_system_keys() {
        let values = HashMap::from([
            ("red.secret.aes_key".into(), "internal".into()),
            ("acme.key".into(), "user-value".into()),
        ]);
        assert_eq!(
            secret_value_from_snapshot(&values, "red.secret.aes_key"),
            None
        );
        assert_eq!(
            secret_value_from_snapshot(&values, "acme.key").as_deref(),
            Some("user-value")
        );
    }

    #[test]
    fn config_snapshot_does_not_copy_superseded_values() {
        use crate::storage::no_malloc_hot_paths::measure_allocations;

        // Drive the selection in a known order. Two traversals of the live
        // store need not have the same order (or see the same compaction), so
        // counting replacements in a separate traversal is not a stable bound.
        let observe = |payload_bytes| {
            let values: Vec<_> = (1..=64)
                .rev()
                .map(|id| (id, Value::Blob(vec![id as u8; payload_bytes])))
                .collect();
            let (latest, allocations) = measure_allocations(|| {
                let mut latest = HashMap::new();
                for (id, value) in &values {
                    let mut shared = None;
                    insert_latest_config_value(
                        &mut latest,
                        "fixture.copy".into(),
                        *id,
                        value,
                        &mut shared,
                    );
                    insert_latest_config_value(
                        &mut latest,
                        "red.config/fixture.copy".into(),
                        *id,
                        value,
                        &mut shared,
                    );
                }
                latest
            });
            assert_eq!(latest["fixture.copy"].0, 64);
            assert_eq!(
                *latest["fixture.copy"].1,
                Value::Blob(vec![64; payload_bytes])
            );
            assert!(Arc::ptr_eq(
                &latest["fixture.copy"].1,
                &latest["red.config/fixture.copy"].1
            ));
            allocations
        };
        let empty = observe(0);
        let large = observe(64 * 1024);
        assert!(
            large.allocated_bytes <= empty.allocated_bytes + 2 * 64 * 1024,
            "superseded config payload copies: {empty:?} -> {large:?}"
        );
    }

    #[test]
    fn config_snapshot_keeps_bare_and_namespaced_aliases_for_canonical_keys() {
        use crate::storage::{EntityData, EntityId, RowData, UnifiedEntity};
        let runtime = super::super::RedDBRuntime::in_memory().expect("runtime");
        let store = runtime.db().store();
        let manager = store.get_or_create_collection("red_config");
        assert!(Arc::ptr_eq(
            &manager,
            &store.get_collection("red.config").unwrap()
        ));
        for (id, key, value, tombstone) in [
            (1, "theme", "dark", false),
            (2, "theme", "light", false),
            (3, "other", "hidden", true),
        ] {
            let mut entity =
                UnifiedEntity::table_row(EntityId::new(2_000_000 + id), "red_config", id, vec![]);
            entity.data = EntityData::Row(RowData {
                columns: vec![],
                schema: None,
                named: Some(HashMap::from([
                    ("key".into(), Value::text(key)),
                    ("value".into(), Value::text(value)),
                    ("tombstone".into(), Value::Boolean(tombstone)),
                ])),
            });
            manager.insert(entity).expect("config row");
        }
        let values = latest_config_snapshot(runtime.db().as_ref()).expect("snapshot");
        assert_eq!(values.get("theme"), Some(&Value::text("light")));
        assert_eq!(values.get("red.config/theme"), Some(&Value::text("light")));
        assert!(!values.contains_key("red.config.theme"));
        assert_eq!(values.get("other"), Some(&Value::text("hidden")));
        assert!(!values.contains_key("red.config/other"));
    }

    fn with_kv_values<T>(values: HashMap<String, String>, f: impl FnOnce() -> T) -> T {
        CURRENT_KV_RESOLVER.with(|cell| {
            cell.replace(Some(KvResolver {
                store: None,
                values: Some(values),
                identity: None,
            }));
        });
        let result = f();
        CURRENT_KV_RESOLVER.with(|cell| {
            cell.replace(None);
        });
        result
    }

    #[test]
    fn current_kv_value_resolves_namespaced_and_bare_keys() {
        let values = HashMap::from([("acme.key".to_string(), "plain-value".to_string())]);

        with_kv_values(values, || {
            // `$kv.acme.key` desugars to `red.kv/acme.key`.
            assert_eq!(
                current_kv_value("red.kv/acme.key").as_deref(),
                Some("plain-value")
            );
            // Bare-key lookup (post-`SET KV` snapshot update) also resolves.
            assert_eq!(current_kv_value("acme.key").as_deref(), Some("plain-value"));
            // Unknown keys resolve to None (→ SQL NULL), never an error.
            assert_eq!(current_kv_value("red.kv/missing.key"), None);
        });
    }

    #[test]
    fn config_key_read_allowed_hard_blocks_reserved_namespace() {
        // The reserved `red.config.*` system namespace is denied role- and
        // store-independently, mirroring the `red.secret.*` block (#1743).
        assert!(!config_key_read_allowed(
            None,
            None,
            "red.config/red.config.aes_key"
        ));
        assert!(!config_key_read_allowed(None, None, "red.config.aes_key"));
        // Ordinary config keys pass when no store is installed (non-IAM path).
        assert!(config_key_read_allowed(
            None,
            None,
            "red.config/ai.openrouter.default.key"
        ));
        assert!(config_key_read_allowed(None, None, "acme.flags.beta"));
    }

    #[test]
    fn is_config_collection_matches_system_config_stores() {
        assert!(is_config_collection("red_config"));
        assert!(is_config_collection("RED_CONFIG"));
        assert!(is_config_collection("red.config"));
        assert!(!is_config_collection("users"));
        assert!(!is_config_collection("red_kv"));
    }

    #[test]
    fn update_current_kv_value_reflects_in_resolver() {
        with_kv_values(HashMap::new(), || {
            assert_eq!(current_kv_value("red.kv/feature.flag"), None);
            update_current_kv_value("feature.flag", Some("on".to_string()));
            assert_eq!(
                current_kv_value("red.kv/feature.flag").as_deref(),
                Some("on")
            );
            update_current_kv_value("feature.flag", None);
            assert_eq!(current_kv_value("red.kv/feature.flag"), None);
        });
    }
}

fn latest_config_snapshot(db: &RedDB) -> RedDBResult<HashMap<String, Value>> {
    let mut latest: HashMap<String, (u64, Arc<Value>)> = HashMap::new();

    // The store canonicalizes the legacy `red_config` collection name to `red.config`.
    // Scan it once, preserving both bare and namespaced resolver keys.
    if let Some(manager) = db.store().get_collection("red.config") {
        super::function_budget::try_scan(
            |visit| manager.try_for_each_entity(usize::MAX, visit),
            |entity| {
                let Some(row) = entity.data.as_row() else {
                    return true;
                };
                let Some(Value::Text(key)) = row.get_field("key") else {
                    return true;
                };
                let value = row.get_field("value").unwrap_or(&Value::Null);
                let id = entity.id.raw();
                let key = key.to_ascii_lowercase();
                // One value may be visible under several aliases. Clone the
                // payload at most once for each advancing entity version.
                let mut shared = None;
                insert_latest_config_value(&mut latest, key.clone(), id, value, &mut shared);
                if !matches!(row.get_field("tombstone"), Some(Value::Boolean(true))) {
                    insert_latest_config_value(
                        &mut latest,
                        format!("red.config/{key}"),
                        id,
                        value,
                        &mut shared,
                    );
                }
                true
            },
        )?;
    }

    Ok(latest
        .into_iter()
        .map(|(key, (_, value))| {
            (
                key,
                Arc::try_unwrap(value).unwrap_or_else(|shared| (*shared).clone()),
            )
        })
        .collect())
}

fn insert_latest_config_value(
    latest: &mut HashMap<String, (u64, Arc<Value>)>,
    key: String,
    id: u64,
    value: &Value,
    shared: &mut Option<Arc<Value>>,
) {
    match latest.get(&key) {
        Some((prev_id, _)) if *prev_id > id => {}
        _ => {
            let shared = shared.get_or_insert_with(|| Arc::new(value.clone()));
            latest.insert(key, (id, Arc::clone(shared)));
        }
    }
}

struct ConfigResolver {
    db: Arc<RedDB>,
    store: Option<Arc<crate::auth::store::AuthStore>>,
    identity: Option<(String, crate::auth::Role, Option<String>)>,
    values: Option<HashMap<String, Value>>,
}

impl ConfigResolver {
    fn can_read(&self, key: &str) -> bool {
        config_key_read_allowed(self.store.as_ref(), self.identity.as_ref(), key)
    }
}

/// The reserved `red.config.*` system-config namespace. Never expose it via
/// the inline `$config`/`CONFIG()`/`KV()` resolver regardless of IAM role,
/// mirroring the role-independent `red.secret.*` hard-block (#1743).
fn is_reserved_config_key(key: &str) -> bool {
    let key = key.strip_prefix("red.config/").unwrap_or(key);
    key.starts_with("red.config.")
        || key == "red.config"
        || key == super::function_catalog::REGISTRY_KEY
}

/// The canonical system config store reached by the inline resolver. Exact
/// collection aliases are normalized at this boundary, while other collections
/// remain unaffected (#1743).
fn is_config_collection(collection: &str) -> bool {
    let normalized = collection.to_ascii_lowercase();
    reddb_engine::storage::system_collection_names::canonical_or_self(&normalized) == "red.config"
}

fn config_resource_target(key: &str) -> String {
    let bare = key.strip_prefix("red.config/").unwrap_or(key);
    format!("red.config/{bare}")
}

/// Shared inline-config read gate: a role-independent hard-block on the
/// reserved `red.config.*` namespace, then a `config:read` capability check
/// mirroring `SHOW CONFIG` / the `$secret` sibling (#1743). Absent a store or
/// with IAM authorization disabled, only the hard-block applies so existing
/// non-IAM `$config` reads keep working.
fn config_key_read_allowed(
    store: Option<&Arc<crate::auth::store::AuthStore>>,
    identity: Option<&(String, crate::auth::Role, Option<String>)>,
    key: &str,
) -> bool {
    if is_reserved_config_key(key) {
        return false;
    }
    let Some(store) = store else {
        return true;
    };
    if !store.iam_authorization_enabled() {
        return true;
    }
    let Some((username, role, tenant)) = identity else {
        return true;
    };
    let principal = crate::auth::UserId::from_parts(tenant.as_deref(), username);
    let mut resource =
        crate::auth::policies::ResourceRef::new("config".to_string(), config_resource_target(key));
    if let Some(tenant) = tenant {
        resource = resource.with_tenant(tenant.clone());
    }
    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: tenant.is_none(),
    };
    store.check_policy_authz_with_role(&principal, "config:read", &resource, &ctx, *role)
}

/// Whether the current principal may read config `key` through the inline
/// `$config`/`CONFIG()`/`KV('red_config', …)` resolver. Used by the db-fallback
/// lookup paths that bypass [`current_config_value`] (#1743).
pub(crate) fn config_read_permitted(key: &str) -> bool {
    let key = key.to_ascii_lowercase();
    CURRENT_CONFIG_RESOLVER.with(|cell| match cell.borrow().as_ref() {
        Some(resolver) => resolver.can_read(&key),
        None => !is_reserved_config_key(&key),
    })
}

/// Gate a raw `KV(collection, key)` read: config system collections go through
/// the `$config` gate; every other collection is unaffected (#1743).
pub(crate) fn kv_read_permitted(collection: &str, key: &str) -> bool {
    if is_config_collection(collection) {
        config_read_permitted(key)
    } else {
        true
    }
}

pub(crate) struct ConfigSnapshotGuard {
    previous: Option<ConfigResolver>,
}

impl ConfigSnapshotGuard {
    pub(super) fn install(
        db: Arc<RedDB>,
        store: Option<Arc<crate::auth::store::AuthStore>>,
    ) -> Self {
        let identity = current_auth_identity().map(|(username, role)| {
            let tenant = current_tenant();
            (username, role, tenant)
        });
        let previous = CURRENT_CONFIG_RESOLVER.with(|cell| {
            cell.replace(Some(ConfigResolver {
                db,
                store,
                identity,
                values: None,
            }))
        });
        Self { previous }
    }
}

impl Drop for ConfigSnapshotGuard {
    fn drop(&mut self) {
        let previous = self.previous.take();
        CURRENT_CONFIG_RESOLVER.with(|cell| {
            cell.replace(previous);
        });
    }
}

/// Install the MVCC snapshot used by the current thread for the duration
/// of one statement. Paired with `clear_current_snapshot()` — callers
/// should prefer the `CurrentSnapshotGuard` RAII wrapper so early returns
/// still clean up.
pub fn set_current_snapshot(ctx: SnapshotContext) {
    CURRENT_SNAPSHOT.with(|cell| *cell.borrow_mut() = Some(ctx));
    HAS_SNAPSHOT.with(|c| c.set(true));
}

pub fn clear_current_snapshot() {
    CURRENT_SNAPSHOT.with(|cell| *cell.borrow_mut() = None);
    HAS_SNAPSHOT.with(|c| c.set(false));
}

/// Drop-guard that restores the previous snapshot on scope exit. Safe to
/// nest — each statement saves the caller's snapshot and puts it back
/// instead of blindly clearing, so a top-level `execute_query` called
/// from inside another statement dispatch (e.g. vector source subqueries)
/// doesn't strip visibility from the outer scan.
pub(crate) struct CurrentSnapshotGuard {
    previous: Option<SnapshotContext>,
}

impl CurrentSnapshotGuard {
    pub(crate) fn install(ctx: SnapshotContext) -> Self {
        let previous = CURRENT_SNAPSHOT.with(|cell| cell.borrow().clone());
        set_current_snapshot(ctx);
        Self { previous }
    }
}

impl Drop for CurrentSnapshotGuard {
    fn drop(&mut self) {
        let prev = self.previous.take();
        let has = prev.is_some();
        CURRENT_SNAPSHOT.with(|cell| *cell.borrow_mut() = prev);
        HAS_SNAPSHOT.with(|c| c.set(has));
    }
}

/// Is this entity visible under the current thread's MVCC snapshot?
///
/// Returns `true` (no filtering) when no snapshot is installed — that
/// path is used by embedded callers and by operations that intentionally
/// bypass MVCC (VACUUM, snapshot export, admin introspection).
///
/// When a snapshot is installed the result is
///   `snapshot.sees(xmin, xmax) && !mgr.is_aborted(xmin) && !xmax_half_abort`
/// where `xmax_half_abort` re-grants visibility for tuples whose
/// deleting transaction rolled back.
#[inline]
pub fn entity_visible_under_current_snapshot(
    entity: &crate::storage::unified::entity::UnifiedEntity,
) -> bool {
    // Moderation visibility gate (#1274, ADR 0057). A row carrying the
    // moderation status marker — quarantine-pending or rejected-tombstone
    // — is hidden from every normal read, on top of MVCC visibility. The
    // marker lives on the row itself, so the check is a single field probe
    // and rides the existing per-row visibility chokepoint rather than
    // adding a separate filter pass to each scan call-site.
    if crate::runtime::ai::moderation::entity_moderation_hidden(entity) {
        return false;
    }
    // Fast path — one `Cell<bool>` read, no RefCell borrow. Autocommit
    // reads (no active MVCC transaction) still hide superseded physical
    // versions while avoiding a full snapshot-context lookup.
    // This runs on every row of every scan; the slow path only fires
    // inside an explicit transaction.
    if !HAS_SNAPSHOT.with(|c| c.get()) {
        return entity.xmax == 0;
    }
    CURRENT_SNAPSHOT.with(|cell| {
        let guard = cell.borrow();
        let Some(ctx) = guard.as_ref() else {
            return true;
        };
        let visible = reddb_engine::transaction::read::entity_visibility_check(ctx, entity);
        if visible {
            record_serializable_read(ctx, entity);
        }
        visible
    })
}

/// Direct visibility check from raw `(xmin, xmax)` — bypasses the
/// entity borrow for callers that already decomposed the tuple (e.g.
/// pre-materialized scan caches). Same semantics as
/// `entity_visible_under_current_snapshot`.
#[inline]
pub(crate) fn xids_visible_under_current_snapshot(xmin: u64, xmax: u64) -> bool {
    if !HAS_SNAPSHOT.with(|c| c.get()) {
        return true;
    }
    CURRENT_SNAPSHOT.with(|cell| {
        let guard = cell.borrow();
        let Some(ctx) = guard.as_ref() else {
            return true;
        };
        visibility_check(ctx, xmin, xmax)
    })
}

/// Clone the current thread's snapshot context. Parallel scan paths
/// (`query_all_zoned` with `std::thread::scope`) call this on the main
/// thread *before* spawning workers so the captured `SnapshotContext`
/// can be moved into every worker closure. Worker threads do not
/// inherit thread-locals, so calling `entity_visible_under_current_snapshot`
/// from inside a spawned closure would silently skip the filter.
///
/// This is the only sanctioned ambient read of the snapshot thread-local
/// (issue #2138). `CURRENT_SNAPSHOT` and `HAS_SNAPSHOT` are private to this
/// module and stay that way: they exist for statement-frame entry and for
/// detecting a frameless read, nothing else. Everything downstream must
/// take the resulting `Option<SnapshotContext>` as an explicit argument —
/// that is what makes `SegmentManager::scan*` thread-independent.
///
/// Statement-frame build also reads it, so a nested sub-execution inside
/// one statement (CTE prelude, materialized-view refresh, inline graph
/// TVF) inherits the enclosing snapshot instead of minting a fresh one
/// (#2183).
///
/// The `Option` is load-bearing: `None` means no statement frame is
/// installed — the low-level callers that intentionally bypass MVCC
/// (VACUUM, snapshot export, admin introspection) — and the scan API
/// keeps a documented fallback for that case rather than assuming a frame
/// always exists.
pub fn capture_current_snapshot() -> Option<SnapshotContext> {
    CURRENT_SNAPSHOT.with(|cell| cell.borrow().clone())
}

/// Whether the active read snapshot may need historical tuple versions
/// that the current secondary indexes cannot prove. Index paths can still
/// recheck visible candidates, but only a heap scan can discover versions
/// whose indexed value was changed or deleted after this snapshot.
pub(crate) fn current_snapshot_requires_index_fallback() -> bool {
    if !HAS_SNAPSHOT.with(|c| c.get()) {
        return false;
    }
    CURRENT_SNAPSHOT.with(|cell| {
        cell.borrow()
            .as_ref()
            .is_some_and(|ctx| ctx.requires_index_fallback)
    })
}

/// Frozen MVCC + identity context for callers that need to reinstall
/// the same view across thread-local boundaries — long-lived cursors,
/// background batchers, anything that detaches from the dispatch path
/// and re-enters later.
///
/// The bundle bakes in the three thread-locals every read path
/// consults: `SnapshotContext` (MVCC visibility), the auth identity
/// (RLS policy gate), and the tenant id (RLS scope). A FETCH that
/// reinstalls the bundle sees exactly the same rows as the DECLARE
/// would have, regardless of writes that landed in between.
///
/// Cheap to clone — `SnapshotContext` is a clone of three
/// `Arc`-backed fields, identity is a `(String, Role)`, tenant is a
/// `String`. None of these contend with the read path.
#[derive(Clone, Default)]
pub struct SnapshotBundle {
    pub snapshot: Option<SnapshotContext>,
    pub auth: Option<(String, crate::auth::Role)>,
    pub auth_principal: Option<crate::auth::UserId>,
    pub tenant: Option<String>,
}

/// Capture the three read-path thread-locals into a `SnapshotBundle`.
/// Pairs with `with_snapshot_bundle` for re-entry.
pub fn snapshot_bundle() -> SnapshotBundle {
    SnapshotBundle {
        snapshot: capture_current_snapshot(),
        auth: current_auth_identity(),
        auth_principal: current_auth_principal(),
        tenant: CURRENT_TENANT_ID.with(|cell| cell.borrow().clone()),
    }
}

/// Reinstall a captured `SnapshotBundle` for the duration of `f`.
/// Restores the caller's previous thread-locals on exit (panic-safe via
/// the explicit guard struct so a panic in `f` cannot leak the
/// installed identity into the worker's next request).
pub fn with_snapshot_bundle<R>(bundle: &SnapshotBundle, f: impl FnOnce() -> R) -> R {
    struct Guard {
        prev_snapshot: Option<SnapshotContext>,
        prev_auth: Option<(String, crate::auth::Role)>,
        prev_auth_principal: Option<crate::auth::UserId>,
        prev_tenant: Option<String>,
    }
    impl Drop for Guard {
        fn drop(&mut self) {
            let snap = self.prev_snapshot.take();
            let has = snap.is_some();
            CURRENT_SNAPSHOT.with(|cell| *cell.borrow_mut() = snap);
            HAS_SNAPSHOT.with(|c| c.set(has));
            CURRENT_AUTH_IDENTITY.with(|cell| *cell.borrow_mut() = self.prev_auth.take());
            CURRENT_AUTH_PRINCIPAL
                .with(|cell| *cell.borrow_mut() = self.prev_auth_principal.take());
            CURRENT_TENANT_ID.with(|cell| *cell.borrow_mut() = self.prev_tenant.take());
        }
    }

    let _guard = {
        let prev_snapshot = CURRENT_SNAPSHOT.with(|cell| cell.borrow().clone());
        let prev_auth = CURRENT_AUTH_IDENTITY.with(|cell| cell.borrow().clone());
        let prev_auth_principal = CURRENT_AUTH_PRINCIPAL.with(|cell| cell.borrow().clone());
        let prev_tenant = CURRENT_TENANT_ID.with(|cell| cell.borrow().clone());

        match bundle.snapshot.clone() {
            Some(ctx) => set_current_snapshot(ctx),
            None => clear_current_snapshot(),
        }
        CURRENT_AUTH_IDENTITY.with(|cell| *cell.borrow_mut() = bundle.auth.clone());
        CURRENT_AUTH_PRINCIPAL.with(|cell| *cell.borrow_mut() = bundle.auth_principal.clone());
        CURRENT_TENANT_ID.with(|cell| *cell.borrow_mut() = bundle.tenant.clone());

        Guard {
            prev_snapshot,
            prev_auth,
            prev_auth_principal,
            prev_tenant,
        }
    };
    f()
}

/// Apply the same visibility rules used by the thread-local helpers
/// against a caller-provided context. Intended for parallel workers
/// that captured the snapshot with `capture_current_snapshot()`.
#[inline]
pub fn entity_visible_with_context(
    ctx: Option<&SnapshotContext>,
    entity: &crate::storage::unified::entity::UnifiedEntity,
) -> bool {
    reddb_engine::storage::visibility::entity_visible_with_context(ctx, entity)
}