cljrs_runtime/env/

env.rs

//! Lexical environment: local frames, global namespace table, and current Env.

use std::collections::{HashMap, HashSet};
use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
use std::sync::{Arc, Condvar, Mutex, RwLock};

use crate::env::async_hook::AsyncRuntime;

use crate::env::error::EvalResult;
use crate::mode::{ExecutionMode, TierState};
use cljrs_gc::{GcConfig, GcPtr};
use cljrs_reader::Form;
use cljrs_value::{CljxFn, Namespace, ReferClojureFilter, Value, Var};
// ── RequireSpec / RequireRefer ─────────────────────────────────────────────────

/// How symbols should be referred into the requiring namespace.
#[derive(Debug, Clone)]
pub enum RequireRefer {
    None,
    All,
    Named(Vec<Arc<str>>),
}

/// A parsed `require` specification.
#[derive(Debug, Clone)]
pub struct RequireSpec {
    pub ns: Arc<str>,
    /// Present when the namespace symbol carried a `@<hash>` version suffix.
    pub version: Option<Arc<str>>,
    pub alias: Option<Arc<str>>,
    pub refer: RequireRefer,
}

// ── Frame ─────────────────────────────────────────────────────────────────────

/// One stack frame of local bindings (a single `let*`, `fn`, or `loop*` scope).
pub struct Frame {
    pub bindings: Vec<(Arc<str>, Value)>,
}

impl Default for Frame {
    fn default() -> Self {
        Self::new()
    }
}

impl Frame {
    pub fn new() -> Self {
        Self {
            bindings: Vec::new(),
        }
    }

    pub fn bind(&mut self, name: Arc<str>, val: Value) {
        // Shadow: push new binding; lookup searches from the end.
        self.bindings.push((name, val));
    }

    pub fn lookup(&self, name: &str) -> Option<&Value> {
        // Search in reverse order so later bindings shadow earlier ones.
        tracing::trace!(target: "env", "lookup {}", name);
        for (n, v) in self.bindings.iter().rev() {
            if n.as_ref() == name {
                return Some(v);
            }
        }
        None
    }
}

// ── GlobalEnv ─────────────────────────────────────────────────────────────────

/// The global mutable store of all namespaces.
pub struct GlobalEnv {
    /// Process-unique identity of this runtime instance.
    ///
    /// Allocated from a counter, not derived from the `Arc`'s address: an
    /// address is only unique while the allocation is live, so a dropped
    /// runtime could hand its key to the next one and let it inherit stale
    /// cross-defn IR.  Used to scope per-instance registries.
    id: u64,
    pub namespaces: RwLock<HashMap<Arc<str>, GcPtr<Namespace>>>,
    /// Directories to search when resolving namespace names to files.
    pub source_paths: RwLock<Vec<std::path::PathBuf>>,
    /// Namespaces that have been fully loaded from a file (idempotent guard).
    pub loaded: Mutex<std::collections::HashSet<Arc<str>>>,
    /// Namespaces currently being loaded, mapped to the thread loading them.
    /// Used to detect true circular requires (same thread) vs concurrent loads
    /// (different thread — those wait on `loading_done` instead of erroring).
    pub loading: Mutex<HashMap<Arc<str>, std::thread::ThreadId>>,
    /// Signalled whenever a namespace finishes loading (or fails).
    pub loading_done: Condvar,
    /// Built-in namespace sources embedded in the binary.
    /// Checked by `load_ns` before falling back to source-path search.
    pub builtin_sources: RwLock<HashMap<Arc<str>, &'static str>>,
    /// GC configuration for automatic collection based on memory pressure.
    pub gc_config: RwLock<Option<Arc<GcConfig>>>,
    /// How this runtime executes function calls.  Fixed when the runtime is
    /// built; see [`crate::RuntimeBuilder::execution_mode`].
    execution_mode: ExecutionMode,
    /// Which tiers are live right now (see [`TierState`]).  Starts at
    /// [`TierState::TreeWalk`] — nothing can be lowered until `clojure.core`
    /// exists — and is raised once to `execution_mode.target_tier()` when the
    /// builder finishes bootstrapping.
    tier_state: AtomicU8,
    /// This runtime's Tier-1 and Tier-2 state: the lowered-IR cache, the JIT
    /// counters and native-code tables, and the JIT backend attached to this
    /// runtime.  Instance state: two runtimes in one process never read,
    /// evict, or invalidate each other's entries, and everything dies with
    /// the runtime.
    tiers: Arc<crate::tiered::tiers::Tiers>,
    /// Optional async runtime registered by `cljrs-async`.
    /// `None` when the library is not linked; `Some` after `cljrs_async::init`.
    pub async_rt: RwLock<Option<Arc<dyn AsyncRuntime>>>,
    /// Cache of values resolved at a specific commit.
    /// Key format: `"<ns>/<name>@<commit>"` for individual vars,
    /// or `"<ns>@<commit>"` for whole versioned namespaces.
    pub version_cache: Mutex<HashMap<Arc<str>, Value>>,
    /// Parsed `cljrs.edn` config, loaded once at startup.
    pub deps_config: RwLock<Option<Arc<cljrs_project::config::DepsConfig>>>,
    /// When true, every versioned-symbol or versioned-namespace resolution must
    /// carry a valid commit signature (verified natively against `trusted_keys`)
    /// before the historical code is executed.  Off by default; enabled via
    /// `--verify-commit-signatures` CLI flag or `:verify-commit-signatures true`
    /// in `cljrs.edn`.
    pub verify_commit_signatures: AtomicBool,
    /// The git backend used by versioned resolution and signature checking, or
    /// `None` in builds that carry no VCS implementation (wasm, or
    /// `cljrs-runtime` without its default `deps` feature).  With no provider,
    /// source files are treated as living outside any repository and versioned
    /// resolution can only use embedded (AOT) sources.  See [`crate::env::vcs`].
    vcs: RwLock<Option<Arc<dyn crate::env::vcs::VcsProvider>>>,
    /// Session-scoped cache of commits that have already passed signature
    /// verification this run, keyed by `(repo_root, commit_hash)`.
    pub sig_verify_cache: Mutex<HashSet<(Arc<str>, Arc<str>)>>,
    /// Pinned source texts fetched from git this session, keyed by
    /// `"<ns>@<commit>"`.  The AOT compiler embeds these in the produced
    /// binary so versioned namespaces resolve without git at runtime.
    pub versioned_sources: RwLock<HashMap<Arc<str>, Arc<str>>>,
    /// When true (set by AOT harness main), versioned namespaces resolve
    /// only from embedded builtin sources — never from git.  A versioned
    /// namespace that was not embedded at compile time fails with a clear
    /// error instead of attempting a fetch.
    pub versioned_offline: AtomicBool,
    /// Provenance of native (Rust-backed) packages recorded at registration:
    /// namespace → the git commit the package was built from.  Consulted by
    /// the versioned resolver's native HEAD fallback to detect pinned-commit
    /// mismatches.
    pub native_provenance: RwLock<HashMap<Arc<str>, Arc<str>>>,
    /// When true, a pinned lookup of a native function whose recorded
    /// provenance does not match the requested commit is an error instead of
    /// a once-per-pin warning.  CLI: `--enforce-native-versions`; cljrs.edn:
    /// `:enforce-native-versions true`.
    pub enforce_native_versions: AtomicBool,
    /// Pinned-native mismatches already warned about this session
    /// (key: `"<ns>@<commit>"`), so each pin warns at most once.
    pub provenance_warned: Mutex<HashSet<Arc<str>>>,
    /// Optional loader for **pinned native packages** (`:rust/load :dylib`),
    /// installed by the CLI.  Called by the versioned resolver with
    /// `(globals, base_ns, commit)` before falling back to the HEAD native
    /// binding; returns `Ok(true)` when it registered the package's pinned
    /// implementations into the `"<base_ns>@<commit>"` namespace.
    #[allow(clippy::type_complexity)]
    pub pinned_native_loader: RwLock<Option<PinnedNativeLoader>>,
    /// Optional loader for **native dependencies on the plain `require` path**
    /// (`:rust/load :dylib`), installed by the CLI.  Called by the
    /// unversioned namespace loader with `(globals, ns)` when a `require`d
    /// namespace has no Clojure source on the source path; returns `Ok(true)`
    /// when it built the dep's crate at the pinned `:git/sha` and registered
    /// the package's exports into the **unversioned** namespace, so a plain
    /// `(require '[my.native.lib :as lib])` brings the native code in.
    #[allow(clippy::type_complexity)]
    pub native_require_loader: RwLock<Option<NativeRequireLoader>>,
    /// Loaders for **AOT-compiled namespaces**, installed by the binary
    /// produced by `cljrs compile`.  Keyed by namespace name.  When a plain
    /// `require` resolves a namespace that has a registered loader, `load_ns`
    /// invokes the loader instead of interpreting Clojure source: the loader
    /// evaluates the namespace's small interpreted preamble (its `ns`/`require`
    /// and macro definitions) and then calls the namespace's natively compiled
    /// initializer, so the bulk of the namespace runs as machine code rather
    /// than being tree-walked at startup.
    #[allow(clippy::type_complexity)]
    pub compiled_ns_loaders: RwLock<HashMap<Arc<str>, CompiledNsLoader>>,
}

/// Loader callback for an AOT-compiled namespace (see
/// `GlobalEnv::compiled_ns_loaders`).  Given the global env, it loads the
/// namespace by running its interpreted preamble and its compiled initializer.
pub type CompiledNsLoader = Arc<dyn Fn(&Arc<GlobalEnv>) -> EvalResult<()> + Send + Sync>;

/// Loader callback for pinned native packages (see
/// `GlobalEnv::pinned_native_loader`).
pub type PinnedNativeLoader =
    Arc<dyn Fn(&Arc<GlobalEnv>, &str, &str) -> EvalResult<bool> + Send + Sync>;

/// Loader callback for native dependencies reached through a plain `require`
/// (see `GlobalEnv::native_require_loader`).
pub type NativeRequireLoader = Arc<dyn Fn(&Arc<GlobalEnv>, &str) -> EvalResult<bool> + Send + Sync>;

/// Source of [`GlobalEnv::id`] values.
static NEXT_GLOBAL_ENV_ID: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);

impl std::fmt::Debug for GlobalEnv {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "GlobalEnv {{ ... }}")
    }
}

impl GlobalEnv {
    /// Create an empty global environment for the given execution mode.
    ///
    /// This is the *raw* constructor: no builtins, no bootstrap, no source
    /// paths.  Use [`crate::Runtime::builder`] unless you are the builder.
    pub fn new(execution_mode: ExecutionMode) -> Arc<Self> {
        let id = NEXT_GLOBAL_ENV_ID.fetch_add(1, Ordering::Relaxed);
        Arc::new(Self {
            id,
            namespaces: RwLock::new(HashMap::new()),
            source_paths: RwLock::new(Vec::new()),
            loaded: Mutex::new(std::collections::HashSet::new()),
            loading: Mutex::new(HashMap::new()),
            loading_done: Condvar::new(),
            builtin_sources: RwLock::new(HashMap::new()),
            gc_config: RwLock::new(None),
            execution_mode,
            tier_state: AtomicU8::new(TierState::TreeWalk as u8),
            tiers: crate::tiered::tiers::Tiers::new(id),
            async_rt: RwLock::new(None),
            version_cache: Mutex::new(HashMap::new()),
            deps_config: RwLock::new(None),
            verify_commit_signatures: AtomicBool::new(false),
            vcs: RwLock::new(crate::env::vcs::default_provider()),
            sig_verify_cache: Mutex::new(HashSet::new()),
            versioned_sources: RwLock::new(HashMap::new()),
            versioned_offline: AtomicBool::new(false),
            native_provenance: RwLock::new(HashMap::new()),
            enforce_native_versions: AtomicBool::new(false),
            provenance_warned: Mutex::new(HashSet::new()),
            pinned_native_loader: RwLock::new(None),
            native_require_loader: RwLock::new(None),
            compiled_ns_loaders: RwLock::new(HashMap::new()),
        })
    }

    /// Replace the source path list.
    pub fn set_source_paths(&self, paths: Vec<std::path::PathBuf>) {
        *self.source_paths.write().unwrap() = paths;
    }

    /// Register an embedded namespace source (called by cljrs-stdlib at startup).
    pub fn register_builtin_source(&self, ns: &str, src: &'static str) {
        self.builtin_sources
            .write()
            .unwrap()
            .insert(Arc::from(ns), src);
    }

    /// Look up an embedded source for a namespace, if one has been registered.
    pub fn builtin_source(&self, ns: &str) -> Option<&'static str> {
        self.builtin_sources.read().unwrap().get(ns).copied()
    }

    /// Register a loader for an AOT-compiled namespace (called by the harness
    /// `main` of a binary produced by `cljrs compile`).
    pub fn register_compiled_ns_loader(&self, ns: &str, loader: CompiledNsLoader) {
        self.compiled_ns_loaders
            .write()
            .unwrap()
            .insert(Arc::from(ns), loader);
    }

    /// Look up the loader for an AOT-compiled namespace, if one is registered.
    pub fn compiled_ns_loader(&self, ns: &str) -> Option<CompiledNsLoader> {
        self.compiled_ns_loaders.read().unwrap().get(ns).cloned()
    }

    /// Mark a namespace as fully loaded from a file.
    pub fn mark_loaded(&self, ns: &str) {
        self.loaded.lock().unwrap().insert(Arc::from(ns));
    }

    /// True if the namespace has already been loaded from a file.
    pub fn is_loaded(&self, ns: &str) -> bool {
        self.loaded.lock().unwrap().contains(ns)
    }

    /// Set the GC configuration for automatic memory pressure management.
    pub fn set_gc_config(&self, config: Arc<GcConfig>) {
        *self.gc_config.write().unwrap() = Some(config);
    }

    /// Get the GC configuration, if one has been set.
    pub fn gc_config(&self) -> Option<Arc<GcConfig>> {
        self.gc_config.read().unwrap().clone()
    }

    /// Resolve a short alias to a full namespace name in `current_ns`.
    pub fn resolve_alias(&self, current_ns: &str, alias: &str) -> Option<Arc<str>> {
        let map = self.namespaces.read().unwrap();
        let ns = map.get(current_ns)?;
        let aliases = ns.get().aliases.lock().unwrap();
        aliases.get(alias).cloned()
    }

    /// Resolve an auto-resolved keyword name (the text after `::`) to its
    /// fully-qualified `ns/name` form.
    ///
    /// `::kw` qualifies with `current_ns` directly; `::alias/kw` looks
    /// `alias` up in `current_ns`'s alias table (populated by `(require
    /// '[... :as alias])`) and qualifies with the resolved namespace.
    pub fn resolve_auto_keyword(&self, current_ns: &str, name: &str) -> Result<String, String> {
        match name.split_once('/') {
            Some((alias, kw_name)) => match self.resolve_alias(current_ns, alias) {
                Some(ns) => Ok(format!("{ns}/{kw_name}")),
                None => Err(format!(
                    "invalid token: ::{name} (no such namespace alias: {alias})"
                )),
            },
            None => Ok(format!("{current_ns}/{name}")),
        }
    }

    /// Return the namespace with this name, creating it if it doesn't exist.
    pub fn get_or_create_ns(&self, name: &str) -> GcPtr<Namespace> {
        // Fast path: already exists.
        {
            let map = self.namespaces.read().unwrap();
            if let Some(ns) = map.get(name) {
                return ns.clone();
            }
        }
        // Slow path: insert.
        let mut map = self.namespaces.write().unwrap();
        // Re-check after acquiring write lock.
        if let Some(ns) = map.get(name) {
            return ns.clone();
        }
        let ns = GcPtr::new(Namespace::new(name));
        map.insert(Arc::from(name), ns.clone());
        ns
    }

    /// Intern `name` with `val` in the given namespace, returning the Var.
    pub fn intern(&self, ns_name: &str, name: Arc<str>, val: Value) -> GcPtr<Var> {
        let ns = self.get_or_create_ns(ns_name);
        let mut interns = ns.get().interns.lock().unwrap();
        if let Some(var) = interns.get(&name) {
            // Update existing var.
            var.get().bind(val);
            return var.clone();
        }
        let var = GcPtr::new(Var::new(ns_name, name.as_ref()));
        var.get().bind(val);
        interns.insert(name, var.clone());
        var
    }

    /// Look up a Var in the named namespace (interns only).
    pub fn lookup_var(&self, ns_name: &str, sym_name: &str) -> Option<GcPtr<Var>> {
        let map = self.namespaces.read().unwrap();
        let ns = map.get(ns_name)?;
        let interns = ns.get().interns.lock().unwrap();
        interns.get(sym_name).cloned()
    }

    /// Look up a value in `ns_name`: checks interns then refers.
    /// Routes through the dynamic binding stack so `binding` overrides work.
    pub fn lookup_in_ns(&self, ns_name: &str, sym_name: &str) -> Option<Value> {
        let map = self.namespaces.read().unwrap();
        let ns = map.get(ns_name)?;
        let ns_ref = ns.get();
        // Check interns first.
        {
            let interns = ns_ref.interns.lock().unwrap();
            if let Some(var) = interns.get(sym_name) {
                return crate::env::dynamics::deref_var(var);
            }
        }
        // Then refers.
        {
            let refers = ns_ref.refers.lock().unwrap();
            if let Some(var) = refers.get(sym_name) {
                return crate::env::dynamics::deref_var(var);
            }
        }
        None
    }

    /// Look up the raw Var (not its value) in `ns_name`: interns then refers.
    pub fn lookup_var_in_ns(&self, ns_name: &str, sym_name: &str) -> Option<GcPtr<Var>> {
        let map = self.namespaces.read().unwrap();
        let ns = map.get(ns_name)?;
        let ns_ref = ns.get();
        {
            let interns = ns_ref.interns.lock().unwrap();
            if let Some(var) = interns.get(sym_name) {
                return Some(var.clone());
            }
        }
        {
            let refers = ns_ref.refers.lock().unwrap();
            if let Some(var) = refers.get(sym_name) {
                return Some(var.clone());
            }
        }
        None
    }

    /// Copy all interns from `src_ns` into `dst_ns` as refers.
    ///
    /// This is the *explicit* refer — `(:require [x :refer :all])` — so it is
    /// never narrowed by `dst_ns`'s `(:refer-clojure ...)` filter, matching
    /// `clojure.core/refer`: naming a namespace explicitly re-maps even names
    /// an earlier `refer-clojure` left out.  The automatic core refer every
    /// namespace starts with goes through [`GlobalEnv::refer_core`] instead.
    pub fn refer_all(&self, dst_ns: &str, src_ns: &str) {
        let map = self.namespaces.read().unwrap();
        let src = match map.get(src_ns) {
            Some(ns) => ns.clone(),
            None => return,
        };
        let dst = match map.get(dst_ns) {
            Some(ns) => ns.clone(),
            None => return,
        };
        let src_interns = src.get().interns.lock().unwrap();
        let mut dst_refers = dst.get().refers.lock().unwrap();
        for (name, var) in src_interns.iter() {
            dst_refers.insert(name.clone(), var.clone());
        }
    }

    /// Apply the automatic `clojure.core` refer that every namespace starts
    /// with, narrowed by `dst_ns`'s `(:refer-clojure ...)` filter.
    pub fn refer_core(&self, dst_ns: &str) {
        self.refer_core_impl(dst_ns, false);
    }

    /// `replace`: drop the refers `dst_ns` already inherited from
    /// `clojure.core` before re-referring, under the same lock — so installing
    /// a filter after the namespace was pre-referred neither leaves stale
    /// names behind nor exposes a window where core is only half-referred.
    fn refer_core_impl(&self, dst_ns: &str, replace: bool) {
        let map = self.namespaces.read().unwrap();
        let src = match map.get("clojure.core") {
            Some(ns) => ns.clone(),
            None => return,
        };
        let dst = match map.get(dst_ns) {
            Some(ns) => ns.clone(),
            None => return,
        };
        // Lock order is filter → src interns → dst refers throughout.
        let filter = dst.get().refer_clojure_filter.lock().unwrap();
        let src_interns = src.get().interns.lock().unwrap();
        let mut dst_refers = dst.get().refers.lock().unwrap();
        if replace {
            dst_refers.retain(|_, var| var.get().namespace.as_ref() != "clojure.core");
        }
        match filter.as_ref() {
            Some(f) => {
                for (name, var) in src_interns.iter() {
                    if let Some(local) = f.local_name(name) {
                        dst_refers.insert(local, var.clone());
                    }
                }
            }
            None => {
                for (name, var) in src_interns.iter() {
                    dst_refers.insert(name.clone(), var.clone());
                }
            }
        }
    }

    /// Install `dst_ns`'s `(:refer-clojure ...)` filter (`None` removes any
    /// previous one) and re-apply the automatic `clojure.core` refer under it.
    ///
    /// Refers already inherited from `clojure.core` are dropped first, so a
    /// filter set after the namespace was pre-referred — the loader refers core
    /// before it reads the file, and `ns` itself refers core before it reaches
    /// the clause — still takes effect.
    pub fn set_refer_clojure_filter(
        &self,
        dst_ns: &str,
        filter: Option<ReferClojureFilter>,
    ) -> Result<(), String> {
        if let Some(f) = &filter {
            self.validate_refer_clojure_filter(f)?;
        }
        let dst = self.get_or_create_ns(dst_ns);
        {
            let mut slot = dst.get().refer_clojure_filter.lock().unwrap();
            // Nothing to install and nothing to undo: leave the refers alone.
            if slot.is_none() && filter.is_none() {
                return Ok(());
            }
            *slot = filter;
        }
        self.refer_core_impl(dst_ns, true);
        Ok(())
    }

    /// Check a `(:refer-clojure ...)` filter against the names `clojure.core`
    /// actually publishes, so a typo fails at the `ns` form rather than as an
    /// unbound symbol somewhere further down the file.
    ///
    /// `:only` and `:rename` name specific vars and must resolve; `:exclude` is
    /// subtractive and stays permissive (excluding a name core does not have is
    /// harmless, and lets a file stay portable across core versions).  Clojure
    /// validates `:only` the same way but ignores an unresolvable `:rename`
    /// key, since it only consults the rename map for names already in its
    /// to-do list.
    ///
    /// Two names landing on the same local name is an error rather than a coin
    /// flip: with `:rename {inc str}` both `inc` and core's own `str` want the
    /// name `str`.  Clojure warns and lets whichever one its intern table
    /// yields last win; picking a winner by hash order here would make the
    /// choice unstable from run to run.
    fn validate_refer_clojure_filter(&self, filter: &ReferClojureFilter) -> Result<(), String> {
        let map = self.namespaces.read().unwrap();
        let Some(core) = map.get("clojure.core").cloned() else {
            return Ok(());
        };
        drop(map);
        let interns = core.get().interns.lock().unwrap();
        // A runtime built without the core bootstrap has nothing to check
        // against; do not fail every name.
        if interns.is_empty() {
            return Ok(());
        }

        for (opt, names) in [
            ("only", filter.only.iter().flatten().collect::<Vec<_>>()),
            ("rename", filter.rename.keys().collect::<Vec<_>>()),
        ] {
            let mut unknown: Vec<&str> = names
                .into_iter()
                .filter(|n| !interns.contains_key(*n))
                .map(|n| n.as_ref())
                .collect();
            if !unknown.is_empty() {
                unknown.sort_unstable();
                return Err(format!(
                    ":refer-clojure :{opt} names {}, which clojure.core does not define",
                    unknown.join(", ")
                ));
            }
        }

        // local name → the core name referred under it.
        let mut taken: HashMap<Arc<str>, Arc<str>> = HashMap::new();
        let mut conflicts: Vec<(Arc<str>, Arc<str>, Arc<str>)> = Vec::new();
        for name in interns.keys() {
            let Some(local) = filter.local_name(name) else {
                continue;
            };
            if let Some(prev) = taken.insert(local.clone(), name.clone()) {
                let (a, b) = if prev.as_ref() <= name.as_ref() {
                    (prev, name.clone())
                } else {
                    (name.clone(), prev)
                };
                conflicts.push((local, a, b));
            }
        }
        if !conflicts.is_empty() {
            conflicts.sort_unstable();
            let (local, a, b) = &conflicts[0];
            return Err(format!(
                ":refer-clojure would refer both {a} and {b} as {local}; \
                 rename or exclude one of them"
            ));
        }
        Ok(())
    }

    /// Names `ns_name` resolves to something other than `clojure.core`'s var
    /// of the same name — what the IR lowerer must not inline as a builtin.
    ///
    /// Three things put a name in here: a `def` in `ns_name` itself, a refer
    /// of that name from another namespace (or of a *different* core name
    /// under it, via `:rename`), and a `(:refer-clojure ...)` filter that
    /// leaves the name out of the automatic core refer.  In each case an
    /// unqualified call resolves to something that is not `clojure.core/name`
    /// — or to nothing at all — and the tree-walking interpreter calls that,
    /// so the lowered call site has to as well (issue #337).
    ///
    /// A name absent from the namespace's tables is *not* reported: with no
    /// evidence to the contrary the lowerer keeps assuming core, which is what
    /// the automatic core refer makes true for the overwhelming majority of
    /// call sites (and keeps the lowerer's synthetic names, e.g. `case=`,
    /// working in namespaces whose refers are not populated yet).
    pub fn core_shadowed_names(&self, ns_name: &str) -> HashSet<Arc<str>> {
        let mut out: HashSet<Arc<str>> = HashSet::new();
        let (ns, core) = {
            let map = self.namespaces.read().unwrap();
            match map.get(ns_name) {
                Some(ns) => (ns.clone(), map.get("clojure.core").cloned()),
                None => return out,
            }
        };
        let ns_ref = ns.get();

        // A var bound here is core's only if it *is* core's var under its own
        // name; core's own namespace passes this trivially for its interns.
        let shadows = |name: &Arc<str>, var: &GcPtr<Var>| {
            let v = var.get();
            v.namespace.as_ref() != "clojure.core" || v.name != *name
        };
        for table in [&ns_ref.interns, &ns_ref.refers] {
            let entries = table.lock().unwrap();
            for (name, var) in entries.iter() {
                if shadows(name, var) {
                    out.insert(name.clone());
                }
            }
        }

        // Names the `(:refer-clojure ...)` filter kept out of the automatic
        // refer: nothing binds them here, so they are not core's either.
        // Lock order is filter → core interns, as in `refer_core_impl`.
        let filter = ns_ref.refer_clojure_filter.lock().unwrap();
        if let (Some(filter), Some(core)) = (filter.as_ref(), core) {
            let interns = core.get().interns.lock().unwrap();
            for name in interns.keys() {
                if filter.local_name(name).as_ref() != Some(name) {
                    out.insert(name.clone());
                }
            }
        }
        out
    }

    /// Copy selected interns from `src_ns` into `dst_ns` as refers.
    pub fn refer_named(&self, dst_ns: &str, src_ns: &str, names: &[Arc<str>]) {
        let map = self.namespaces.read().unwrap();
        let src = match map.get(src_ns) {
            Some(ns) => ns.clone(),
            None => return,
        };
        let dst = match map.get(dst_ns) {
            Some(ns) => ns.clone(),
            None => return,
        };
        let src_interns = src.get().interns.lock().unwrap();
        let mut dst_refers = dst.get().refers.lock().unwrap();
        for name in names {
            if let Some(var) = src_interns.get(name) {
                // Use insert (not or_insert_with) so that an explicit
                // `require :refer [name]` always overrides a previous refer
                // (e.g. one inherited from clojure.core via refer-all).
                // clojure.core.async's `into` intentionally shadows clojure.core/into;
                // or_insert_with would silently drop the override.
                dst_refers.insert(name.clone(), var.clone());
            }
        }
    }

    /// Register `alias` → `full_ns` in `current_ns`'s alias table.
    pub fn add_alias(&self, current_ns: &str, alias: &str, full_ns: &str) {
        let ns_ptr = self.get_or_create_ns(current_ns);
        let mut aliases = ns_ptr.get().aliases.lock().unwrap();
        aliases.insert(Arc::from(alias), Arc::from(full_ns));
    }

    /// Process-unique identity of this runtime instance.
    #[inline(always)]
    pub fn id(&self) -> u64 {
        self.id
    }

    /// This runtime's Tier-1/Tier-2 state.
    #[inline(always)]
    pub fn tiers(&self) -> &Arc<crate::tiered::tiers::Tiers> {
        &self.tiers
    }

    /// This runtime's cache of lowered IR.
    #[inline(always)]
    pub fn ir_cache(&self) -> &crate::tiered::ir_cache::IrCache {
        self.tiers.ir_cache()
    }

    /// This runtime's JIT counters, profiles, and native-code tables.
    #[inline(always)]
    pub fn jit(&self) -> &crate::tiered::jit_state::JitState {
        self.tiers.jit()
    }

    /// The JIT compiler attached to this runtime, if any.
    ///
    /// `None` when no JIT is linked or installed; callers then keep to the
    /// interpreter tiers.  Installed by `cljrs_compiler::jit::install`.
    #[inline(always)]
    pub fn jit_backend(&self) -> Option<Arc<dyn crate::tiered::backend::JitBackend>> {
        self.tiers.jit().backend().cloned()
    }

    // ── Execution mode and tier state ────────────────────────────────────

    /// How this runtime executes function calls.
    #[inline(always)]
    pub fn execution_mode(&self) -> ExecutionMode {
        self.execution_mode
    }

    /// Which tiers are live right now.
    #[inline(always)]
    pub fn tier_state(&self) -> TierState {
        TierState::from_u8(self.tier_state.load(Ordering::Acquire))
    }

    /// Raise the live tier state.  Called once by the runtime builder after
    /// the bootstrap completes; lowering the tier is not supported, so a
    /// request below the current state is ignored.
    pub fn set_tier_state(&self, tier: TierState) {
        let _ = self.tier_state.fetch_max(tier as u8, Ordering::AcqRel);
    }

    /// True when IR may be lowered, cached, and interpreted.  This is the
    /// gate the old `compiler_ready` flag served.
    #[inline(always)]
    pub fn ir_enabled(&self) -> bool {
        self.tier_state().ir_enabled()
    }

    // ── Evaluation entry points ──────────────────────────────────────────

    /// Evaluate `form` in `env`.
    #[inline(always)]
    pub fn eval(&self, form: &Form, env: &mut Env) -> EvalResult {
        crate::interp::eval::eval(form, env)
    }

    /// Call a Clojure function, taking the path this runtime's
    /// [`ExecutionMode`] selects.
    ///
    /// This is the single function-call dispatch point: tree walk, tier-1 IR,
    /// and JIT-native execution are all reached from here.
    #[inline(always)]
    pub fn call_cljrs_fn(&self, func: &CljxFn, args: &[Value], env: &mut Env) -> EvalResult {
        match self.execution_mode {
            ExecutionMode::TreeWalk => crate::interp::apply::call_cljrs_fn(func, args, env),
            ExecutionMode::Tiered | ExecutionMode::TieredNoJit => {
                crate::tiered::apply::call_cljrs_fn(func, args, env)
            }
            ExecutionMode::NoGcTransaction => crate::env::depth::call_cljrs_fn(func, args, env),
        }
    }

    /// Notify the active tier that a new `fn*` was defined.
    ///
    /// In a tiered runtime with IR enabled this eagerly lowers the function
    /// (when eager lowering is on); in every other mode it does nothing.
    #[inline(always)]
    pub fn on_fn_defined(&self, f: &CljxFn, env: &mut Env) {
        if self.execution_mode.is_tiered() && self.ir_enabled() {
            crate::tiered::ir_interp::eager_lower_fn(f, env);
        }
    }

    /// Install an async runtime. Called once by `cljrs_async::init`.
    /// Subsequent calls are silently ignored (first writer wins).
    pub fn set_async_runtime(&self, rt: Arc<dyn AsyncRuntime>) {
        let mut guard = self.async_rt.write().unwrap();
        if guard.is_none() {
            *guard = Some(rt);
        }
    }

    /// Return the async runtime, if one has been registered.
    pub fn async_runtime(&self) -> Option<Arc<dyn AsyncRuntime>> {
        self.async_rt.read().unwrap().clone()
    }

    /// Return `(source_file, git_repo_root)` for the named namespace, if
    /// both have been populated by the loader.
    pub fn get_ns_git_context(&self, ns_name: &str) -> Option<(Arc<str>, Arc<str>)> {
        let map = self.namespaces.read().unwrap();
        let ns = map.get(ns_name)?;
        let ns_ref = ns.get();
        let file = ns_ref.source_file.lock().unwrap().clone()?;
        let repo = ns_ref.git_repo_root.lock().unwrap().clone()?;
        Some((file, repo))
    }

    /// Store a resolved versioned value in the cache.
    /// Key: `"<ns>/<name>@<commit>"`.
    pub fn cache_versioned(&self, ns: &str, name: &str, commit: &str, val: Value) {
        let key: Arc<str> = Arc::from(format!("{ns}/{name}@{commit}"));
        self.version_cache.lock().unwrap().insert(key, val);
    }

    /// Retrieve a previously resolved versioned value, if cached.
    pub fn get_cached_versioned(&self, ns: &str, name: &str, commit: &str) -> Option<Value> {
        let key = format!("{ns}/{name}@{commit}");
        self.version_cache
            .lock()
            .unwrap()
            .get(key.as_str())
            .cloned()
    }

    /// Mark namespace `name@commit` as loaded in the standard loaded set.
    pub fn cache_versioned_ns(&self, ns: &str, commit: &str) {
        let key: Arc<str> = Arc::from(format!("{ns}@{commit}"));
        self.version_cache.lock().unwrap().insert(key, Value::Nil);
    }

    /// Record the source text of a versioned namespace fetched from git.
    /// Key: `"<ns>@<commit>"`.  Consumed by the AOT compiler for embedding.
    pub fn record_versioned_source(&self, versioned_ns: &str, src: &str) {
        self.versioned_sources
            .write()
            .unwrap()
            .insert(Arc::from(versioned_ns), Arc::from(src));
    }

    /// Snapshot of all versioned sources fetched this session, sorted by key.
    pub fn versioned_sources_snapshot(&self) -> Vec<(Arc<str>, Arc<str>)> {
        let map = self.versioned_sources.read().unwrap();
        let mut entries: Vec<_> = map.iter().map(|(k, v)| (k.clone(), v.clone())).collect();
        entries.sort_by(|a, b| a.0.cmp(&b.0));
        entries
    }

    /// Restrict versioned-namespace resolution to embedded builtin sources
    /// (no git).  Called by AOT harness binaries, which embed every pinned
    /// source discovered at compile time.
    pub fn set_versioned_offline(&self, offline: bool) {
        self.versioned_offline.store(offline, Ordering::Relaxed);
    }

    /// True when versioned namespaces may only come from embedded sources.
    pub fn versioned_offline(&self) -> bool {
        self.versioned_offline.load(Ordering::Relaxed)
    }

    /// Record the git commit a native (Rust-backed) package was built from.
    /// Called at registration time (`Registry::set_provenance` or the
    /// `register_provenance!` inventory entry in cljrs-interop).
    pub fn set_native_provenance(&self, ns: &str, commit: &str) {
        self.native_provenance
            .write()
            .unwrap()
            .insert(Arc::from(ns), Arc::from(commit));
    }

    /// The recorded provenance commit for a native package's namespace.
    pub fn native_provenance_for(&self, ns: &str) -> Option<Arc<str>> {
        self.native_provenance.read().unwrap().get(ns).cloned()
    }

    /// Make pinned-native provenance mismatches hard errors.
    pub fn set_enforce_native_versions(&self, enforce: bool) {
        self.enforce_native_versions
            .store(enforce, Ordering::Relaxed);
    }

    /// True when pinned-native provenance mismatches are errors.
    pub fn enforce_native_versions(&self) -> bool {
        self.enforce_native_versions.load(Ordering::Relaxed)
    }

    /// Install the pinned-native package loader (called once by
    /// `cljrs::native::pinned::install`; first writer wins).
    pub fn set_pinned_native_loader(&self, loader: PinnedNativeLoader) {
        let mut guard = self.pinned_native_loader.write().unwrap();
        if guard.is_none() {
            *guard = Some(loader);
        }
    }

    /// Install the native-dependency `require` loader (called once by
    /// `cljrs::native::pinned::install`; first writer wins).
    pub fn set_native_require_loader(&self, loader: NativeRequireLoader) {
        let mut guard = self.native_require_loader.write().unwrap();
        if guard.is_none() {
            *guard = Some(loader);
        }
    }

    /// The installed VCS backend, or `None` when this build has none (see
    /// [`crate::env::vcs`]).  Callers must degrade gracefully: "no provider"
    /// means "this source file is not in a git repository".
    pub fn vcs(&self) -> Option<Arc<dyn crate::env::vcs::VcsProvider>> {
        self.vcs.read().unwrap().clone()
    }

    /// Replace the VCS backend.  Lets an embedder that built without the
    /// `deps` feature supply its own git implementation, or a sandboxed host
    /// remove the default one (`None`) so no versioned resolution can reach
    /// the filesystem's git history.
    ///
    /// Drops every cached signature verdict: those were reached by the
    /// outgoing provider, against its trust set and its view of the
    /// repository, and say nothing about what the incoming one would decide
    /// for the same `(repo, commit)`.  Keeping them would let a permissive
    /// provider launder an approval for source a later provider serves.
    pub fn set_vcs_provider(&self, provider: Option<Arc<dyn crate::env::vcs::VcsProvider>>) {
        // Neither this nor `check_commit_signature` ever holds the `vcs` and
        // `sig_verify_cache` locks at the same time, and the two reach for
        // them in opposite orders — keep it that way, or the pair becomes a
        // lock-order inversion.
        *self.vcs.write().unwrap() = provider;
        self.invalidate_signature_cache();
    }

    /// Forget every cached signature verdict, so the next
    /// [`check_commit_signature`](Self::check_commit_signature) re-asks the
    /// current provider.  Called whenever the thing that produced those
    /// verdicts changes: the provider itself, or its trusted-key set.
    pub fn invalidate_signature_cache(&self) {
        self.sig_verify_cache.lock().unwrap().clear();
    }

    /// If `:verify-commit-signatures` is enabled, verify that `commit` inside
    /// `repo_root` carries a valid GPG or SSH signature.
    ///
    /// Returns `Ok(())` immediately when the feature is off.  On the happy
    /// path the result is cached per `(repo_root, commit)` so each commit is
    /// only verified once per session.  On failure returns
    /// `EvalError::CommitSignatureVerificationFailed`.
    ///
    /// If verification is demanded but this build has no VCS provider, the
    /// check fails: silently accepting an unverifiable commit would defeat the
    /// flag the user explicitly turned on.
    pub fn check_commit_signature(&self, repo_root: &str, commit: &str) -> EvalResult<()> {
        if !self.verify_commit_signatures.load(Ordering::Relaxed) {
            return Ok(());
        }
        let key = (Arc::<str>::from(repo_root), Arc::<str>::from(commit));
        if self.sig_verify_cache.lock().unwrap().contains(&key) {
            return Ok(());
        }
        let Some(vcs) = self.vcs() else {
            return Err(crate::env::error::EvalError::Runtime(format!(
                "commit-signature verification is enabled, but this build has no VCS \
                 provider to verify commit {commit} with (cljrs-runtime built without \
                 the `deps` feature)"
            )));
        };
        vcs.verify_commit_signature(std::path::Path::new(repo_root), commit)
            .map_err(|e| match e {
                crate::env::vcs::SignatureFailure::Untrusted { commit, reason } => {
                    crate::env::error::EvalError::CommitSignatureVerificationFailed {
                        commit,
                        reason,
                    }
                }
                crate::env::vcs::SignatureFailure::Error(msg) => {
                    crate::env::error::EvalError::Runtime(msg)
                }
            })?;
        self.sig_verify_cache.lock().unwrap().insert(key);
        Ok(())
    }

    /// Build the trusted-signer key set from a parsed `cljrs.edn` config and
    /// install it, so subsequent `check_commit_signature` calls verify against
    /// it.  Inline keys are parsed directly; `File` entries are read from disk.
    /// Returns the number of keys loaded; warns (to stderr) on any key that
    /// fails to load rather than aborting.  Returns 0 when this build has no
    /// VCS provider, since there is nothing that could consume the keys.
    ///
    /// Replacing the trust set invalidates the signature cache for the same
    /// reason replacing the provider does: a verdict reached under the old
    /// keys is not a verdict under the new ones.  (In the normal flow this
    /// runs at session start, before anything has been verified.)
    pub fn load_trusted_signers(&self, config: &cljrs_project::config::DepsConfig) -> usize {
        let Some(vcs) = self.vcs() else {
            return 0;
        };
        let loaded = vcs.load_trusted_signers(&config.trusted_signers);
        self.invalidate_signature_cache();
        loaded
    }
}

// ── Env ───────────────────────────────────────────────────────────────────────

/// The full execution environment: a stack of local frames plus the global env.
pub struct Env {
    pub frames: Vec<Frame>,
    pub current_ns: Arc<str>,
    pub globals: Arc<GlobalEnv>,
    /// When set, unversioned same-namespace symbol lookups implicitly resolve
    /// at this commit hash instead of HEAD.  Set by the versioned resolver when
    /// evaluating a function body fetched from git history.
    pub versioned_eval_commit: Option<Arc<str>>,
    /// True when evaluating the body of an `^:async` function.
    /// Set by `cljrs-async`; allows the `await` special form to know whether
    /// to yield (async context) or block the OS thread (sync context).
    pub is_async: bool,
}

impl Env {
    pub fn new(globals: Arc<GlobalEnv>, ns: &str) -> Self {
        Self {
            frames: Vec::new(),
            current_ns: Arc::from(ns),
            globals,
            versioned_eval_commit: None,
            is_async: false,
        }
    }

    /// Create an Env for evaluating source at a specific commit.
    pub fn new_versioned(globals: Arc<GlobalEnv>, ns: &str, commit: &str) -> Self {
        Self {
            versioned_eval_commit: Some(Arc::from(commit)),
            ..Self::new(globals, ns)
        }
    }

    /// Create an Env pre-loaded with a function's closed-over bindings.
    pub fn with_closure(globals: Arc<GlobalEnv>, ns: &str, f: &CljxFn) -> Self {
        let mut env = Self::new(globals, ns);
        if !f.closed_over_names.is_empty() {
            env.push_frame();
            for (name, val) in f.closed_over_names.iter().zip(f.closed_over_vals.iter()) {
                env.bind(name.clone(), val.clone());
            }
        }
        env
    }

    pub fn push_frame(&mut self) {
        self.frames.push(Frame::new());
    }

    pub fn pop_frame(&mut self) {
        self.frames.pop();
    }

    /// Bind `name` to `val` in the top frame.
    pub fn bind(&mut self, name: Arc<str>, val: Value) {
        if let Some(frame) = self.frames.last_mut() {
            frame.bind(name, val);
        }
        // If there are no frames, the binding is silently dropped.
        // Callers must push a frame first.
    }

    /// Look up `name`: local frames (innermost first), then the current namespace.
    pub fn lookup(&self, name: &str) -> Option<Value> {
        tracing::trace!(target: "env", "lookup {} in {} frames", name, self.frames.len());
        for frame in self.frames.iter().rev() {
            if let Some(v) = frame.lookup(name) {
                return Some(v.clone());
            }
        }
        self.globals.lookup_in_ns(&self.current_ns, name)
    }

    /// Look up `name` in local frames only — does **not** fall back to the
    /// global namespace.  Used by the versioned resolver to check for local
    /// bindings before applying commit inheritance.
    pub fn lookup_local_frames(&self, name: &str) -> Option<Value> {
        for frame in self.frames.iter().rev() {
            if let Some(v) = frame.lookup(name) {
                return Some(v.clone());
            }
        }
        None
    }

    /// Look up the Var object for `name` in the current namespace.
    pub fn lookup_var(&self, name: &str) -> Option<GcPtr<Var>> {
        self.globals.lookup_var_in_ns(&self.current_ns, name)
    }

    /// Collect all current local bindings (all frames, innermost last).
    /// Used for closure capture.
    pub fn all_local_bindings(&self) -> (Vec<Arc<str>>, Vec<Value>) {
        let mut names = Vec::new();
        let mut vals = Vec::new();
        // Outermost first so inner frames override on lookup.
        for frame in &self.frames {
            for (n, v) in &frame.bindings {
                names.push(n.clone());
                vals.push(v.clone());
            }
        }
        (names, vals)
    }

    /// Create a child Env for closure capture (same globals, same ns, captures locals).
    pub fn child(&self) -> Self {
        let (names, vals) = self.all_local_bindings();
        let mut child = Self::new(self.globals.clone(), &self.current_ns);
        child.is_async = self.is_async;
        if !names.is_empty() {
            child.push_frame();
            for (n, v) in names.into_iter().zip(vals) {
                child.bind(n, v);
            }
        }
        child
    }

    #[inline(always)]
    pub fn eval(&mut self, form: &Form) -> EvalResult {
        let globals = self.globals.clone();
        globals.eval(form, self)
    }

    #[inline(always)]
    pub fn call_cljrs_fn(&mut self, func: &CljxFn, args: &[Value]) -> EvalResult {
        let globals = self.globals.clone();
        globals.call_cljrs_fn(func, args, self)
    }

    #[inline(always)]
    pub fn on_fn_defined(&mut self, func: &CljxFn) {
        let globals = self.globals.clone();
        globals.on_fn_defined(func, self);
    }
}