pine_interpreter/

lib.rs

mod num;
mod signature;

pub use num::Num;
pub use signature::{BuiltinSignature, Param, ParamType};

use pine_core::{Color, DefaultPineOutput, PineOutput, MAX_LOOKBACK};

use pine_ast::{Argument, BinOp, Expr, Literal, MethodParam, Program, Stmt, TypeField, UnOp};
use std::cell::RefCell;
use std::collections::HashMap;
use std::rc::Rc;
use thiserror::Error;

pub use pine_core::LibraryLoader;

/// Record `value` as what `name` held on a completed bar, so `name[n]` can reach
/// it. Entries beyond [`MAX_LOOKBACK`] are dropped.
///
/// Takes the history map rather than `&mut self` so callers can hold a borrow of
/// another interpreter field while recording.
fn push_history<O: PineOutput>(
    history: &mut HashMap<String, Vec<Value<O>>>,
    name: &str,
    value: Value<O>,
) {
    let entries = history.entry(name.to_string()).or_default();
    entries.push(value);
    if entries.len() > MAX_LOOKBACK {
        entries.drain(..entries.len() - MAX_LOOKBACK);
    }
}

/// Apply a numeric binary operator under Pine's int/float rule (see [`Num`]).
/// An na operand, a non-numeric operand, or a `None` from `op` (a zero divisor)
/// all yield `na`.
fn numeric_op<O: PineOutput>(
    left: &Value<O>,
    right: &Value<O>,
    op: impl Fn(Num, Num) -> Option<Num>,
) -> Result<Value<O>, RuntimeError> {
    // Reject a genuinely non-numeric operand (a string), while letting na through.
    left.to_number()?;
    right.to_number()?;

    match (left.as_num(), right.as_num()) {
        (Some(a), Some(b)) => Ok(op(a, b).map_or(Value::Na, Value::from)),
        _ => Ok(Value::Na),
    }
}

#[derive(Error, Debug)]
pub enum RuntimeError {
    #[error("Variable '{0}' not found")]
    UndefinedVariable(String),

    #[error("Type error: {0}")]
    TypeError(String),

    #[error("Division by zero")]
    DivisionByZero,

    #[error("Index out of bounds: {0}")]
    IndexOutOfBounds(usize),

    #[error("Cannot iterate: from={0}, to={1}")]
    InvalidForLoop(f64, f64),

    #[error("Break statement outside of loop")]
    BreakOutsideLoop,

    #[error("Continue statement outside of loop")]
    ContinueOutsideLoop,

    #[error("Library error: {0}")]
    LibraryError(String),

    #[error("Cannot reassign const variable '{0}'")]
    ConstReassignment(String),
}

/// Control flow signals for loops
#[derive(Debug, Clone, PartialEq)]
enum LoopControl {
    None,
    Break,
    Continue,
}

/// Variable storage with const qualifier tracking
#[derive(Clone)]
struct Variable<O: PineOutput = DefaultPineOutput> {
    value: Value<O>,
    is_const: bool,
    /// true when declared with `var`/`varip` — this variable survives function call boundaries
    is_var_persistent: bool,
}

/// Represents a time series with an identifier and current value
#[derive(Clone, Debug)]
pub struct Series<O: PineOutput = DefaultPineOutput> {
    pub id: String,
    pub current: Box<Value<O>>,
}

/// Value types in the interpreter
#[derive(Clone)]
pub enum Value<O: PineOutput> {
    Int(i64),
    Number(f64),
    String(String),
    Bool(bool),
    Na,                                // PineScript's N/A value
    Array(Rc<RefCell<Vec<Value<O>>>>), // Mutable shared array reference
    Series(Series<O>),                 // Time series - ID and current value only
    Object {
        type_name: String, // The type name of this object (e.g., "InfoLabel")
        fields: Rc<RefCell<HashMap<String, Value<O>>>>, // Dictionary/Object with string keys
        call: Option<BuiltinFn<O>>,
    },
    Function {
        params: Vec<pine_ast::FunctionParam>,
        body: Vec<Stmt>,
    },
    BuiltinFunction(Builtin<O>), // Builtin callable plus the arguments it accepts
    /// An unevaluated expression, passed to a builtin that captured it (a lazy
    /// parameter) to run in another context — e.g. `request.security`.
    Expr(Rc<Expr>),
    Type {
        name: String,
        fields: Vec<TypeField>,
    }, // User-defined type
    Enum {
        enum_name: String,  // The enum type name (e.g., "Signal")
        field_name: String, // The specific field/member name (e.g., "buy")
        title: String,      // The title of this enum member
    }, // Enum member value
    Color(Color), // Color value
    Matrix {
        element_type: String, // Type of elements: "int", "float", "string", "bool"
        data: Rc<RefCell<Vec<Vec<Value<O>>>>>, // 2D matrix - mutable shared reference to rows of columns
    },
}

impl<O: PineOutput> From<Num> for Value<O> {
    /// A [`Num`] carries its own type, so it lands on the matching variant.
    fn from(n: Num) -> Self {
        match n {
            Num::Int(n) => Value::Int(n),
            Num::Float(n) => Value::Number(n),
        }
    }
}

impl<O: PineOutput> Value<O> {
    pub fn new_color(r: u8, g: u8, b: u8, t: u8) -> Value<O> {
        Value::Color(Color::new(r, g, b, t))
    }
}

// Manual Debug impl since function pointers don't implement Debug
impl<O: PineOutput> std::fmt::Debug for Value<O> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Value::Int(n) => write!(f, "Int({:?})", n),
            Value::Number(n) => write!(f, "Number({:?})", n),
            Value::String(s) => write!(f, "String({:?})", s),
            Value::Bool(b) => write!(f, "Bool({:?})", b),
            Value::Na => write!(f, "Na"),
            Value::Array(a) => write!(f, "Array({:?})", a),
            Value::Series(s) => write!(f, "Series({:?})", s),
            Value::Object {
                type_name, fields, ..
            } => write!(f, "Object({}:{:?})", type_name, fields),
            Value::Function { params, .. } => write!(f, "Function({} params)", params.len()),
            Value::BuiltinFunction(_) => write!(f, "BuiltinFunction"),
            Value::Expr(_) => write!(f, "Expr"),
            Value::Type { name, .. } => write!(f, "Type({})", name),
            Value::Enum {
                enum_name,
                field_name,
                ..
            } => write!(f, "Enum({}::{})", enum_name, field_name),
            Value::Color(color) => write!(
                f,
                "Color(rgba({}, {}, {}, {}))",
                color.r, color.g, color.b, color.t
            ),
            Value::Matrix { element_type, data } => {
                write!(f, "Matrix<{}>({:?})", element_type, data)
            }
        }
    }
}

impl<O: PineOutput> PartialEq for Value<O> {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (Value::Int(a), Value::Int(b)) => a == b,
            // int and float compare by value, so `1 == 1.0`.
            (Value::Int(a), Value::Number(b)) | (Value::Number(b), Value::Int(a)) => {
                (*a as f64 - b).abs() < f64::EPSILON
            }
            (Value::Number(a), Value::Number(b)) => (a - b).abs() < f64::EPSILON,
            (Value::String(a), Value::String(b)) => a == b,
            (Value::Bool(a), Value::Bool(b)) => a == b,
            (Value::Na, Value::Na) => true,
            // Arrays compare by reference (Rc pointer equality)
            (Value::Array(a), Value::Array(b)) => Rc::ptr_eq(a, b),
            // Series compare by ID and current value
            (Value::Series(a), Value::Series(b)) => a.id == b.id && *a.current == *b.current,
            (Value::Object { fields: a, .. }, Value::Object { fields: b, .. }) => Rc::ptr_eq(a, b),
            // Functions never equal (can't compare closures or function pointers)
            (Value::Function { .. }, Value::Function { .. }) => false,
            (Value::BuiltinFunction(_), Value::BuiltinFunction(_)) => false,
            // Types compare by name
            (Value::Type { name: a, .. }, Value::Type { name: b, .. }) => a == b,
            // Enums compare by enum name and field name (ensuring type safety)
            (
                Value::Enum {
                    enum_name: a_enum,
                    field_name: a_field,
                    ..
                },
                Value::Enum {
                    enum_name: b_enum,
                    field_name: b_field,
                    ..
                },
            ) => a_enum == b_enum && a_field == b_field,
            // Colors compare by all components
            (Value::Color(c1), Value::Color(c2)) => c1 == c2,
            // Matrices compare by reference (Rc pointer equality)
            (Value::Matrix { data: a, .. }, Value::Matrix { data: b, .. }) => Rc::ptr_eq(a, b),
            _ => false,
        }
    }
}

/// Evaluated function argument
#[derive(Debug, Clone)]
pub enum EvaluatedArg<O: PineOutput = DefaultPineOutput> {
    Positional(Value<O>),
    Named { name: String, value: Value<O> },
}

/// Container for function call arguments including type parameters
#[derive(Debug, Clone)]
pub struct FunctionCallArgs<O: PineOutput = DefaultPineOutput> {
    pub type_args: Vec<String>,
    pub args: Vec<EvaluatedArg<O>>,
    pub call_id: u32,
}

impl<O: PineOutput> FunctionCallArgs<O> {
    pub fn new(type_args: Vec<String>, args: Vec<EvaluatedArg<O>>) -> Self {
        Self {
            type_args,
            args,
            call_id: 0,
        }
    }

    pub fn without_types(args: Vec<EvaluatedArg<O>>) -> Self {
        Self {
            type_args: vec![],
            args,
            call_id: 0,
        }
    }

    pub fn with_call_id(mut self, call_id: u32) -> Self {
        self.call_id = call_id;
        self
    }
}

/// Type signature for builtin functions (can be function pointers or closures)
pub type BuiltinFn<O> =
    Rc<dyn Fn(&mut Interpreter<O>, FunctionCallArgs<O>) -> Result<Value<O>, RuntimeError>>;

/// A callable builtin together with the arguments it accepts, so semantic
/// analysis can reject a bad call without running it. Both come from the same
/// `#[derive(BuiltinFunction)]`, so they cannot drift apart.
#[derive(Clone)]
pub struct Builtin<O: PineOutput> {
    pub call: BuiltinFn<O>,
    pub signature: BuiltinSignature,
}

impl<O: PineOutput> Builtin<O> {
    /// A builtin whose arguments are not described, so nothing is checked.
    /// For the few callables written by hand rather than derived.
    pub fn untyped(call: BuiltinFn<O>) -> Self {
        Self {
            call,
            signature: BuiltinSignature::default(),
        }
    }
}

impl<O: PineOutput> Value<O> {
    /// Extract as f64. Na → NaN (propagates via IEEE 754). Type mismatch → Err.
    /// For external callers (builtins, adapters). Internal operator code uses `to_number`.
    pub fn as_number(&self) -> Result<f64, RuntimeError> {
        self.to_number().map(|opt| opt.unwrap_or(f64::NAN))
    }

    /// Extract as bool. Na → false (Pine v6: booleans are never na). Type mismatch → Err.
    /// For external callers. Internal conditional code uses `truthy_for_condition`.
    pub fn as_bool(&self) -> Result<bool, RuntimeError> {
        Ok(self.to_bool()?.unwrap_or(false))
    }

    /// This value as a [`Num`], preserving whether it is an int or a float, so
    /// callers can apply Pine's overload rule. `None` for `na` and for anything
    /// non-numeric.
    pub fn as_num(&self) -> Option<Num> {
        match self {
            Value::Int(n) => Some(Num::Int(*n)),
            Value::Number(n) => Some(Num::Float(*n)),
            Value::Bool(b) => Some(Num::Int(if *b { 1 } else { 0 })),
            Value::Series(series) => series.current.as_num(),
            _ => None,
        }
    }

    /// The integer this value carries, if it is int-typed.
    fn as_int(&self) -> Option<i64> {
        match self.as_num() {
            Some(Num::Int(n)) => Some(n),
            _ => None,
        }
    }

    /// Returns Ok(None) when self is Na so callers can propagate na correctly.
    /// Returns Err for genuine type mismatches (e.g. passing a string to arithmetic).
    pub fn to_number(&self) -> Result<Option<f64>, RuntimeError> {
        match self {
            Value::Int(n) => Ok(Some(*n as f64)),
            Value::Number(n) => Ok(Some(*n)),
            Value::Bool(b) => Ok(Some(if *b { 1.0 } else { 0.0 })),
            Value::Series(series) => series.current.to_number(),
            Value::Na => Ok(None),
            _ => Err(RuntimeError::TypeError(format!(
                "Expected number, got {:?}",
                self
            ))),
        }
    }

    /// Returns Ok(None) when self is Na. Returns Err for type mismatches.
    pub fn to_bool(&self) -> Result<Option<bool>, RuntimeError> {
        match self {
            Value::Bool(b) => Ok(Some(*b)),
            Value::Int(n) => Ok(Some(*n != 0)),
            // NaN must not become true: `n != 0.0` is true for NaN in IEEE 754.
            Value::Number(n) => Ok(Some(*n != 0.0 && !n.is_nan())),
            Value::Na => Ok(None),
            _ => Err(RuntimeError::TypeError(format!(
                "Expected bool, got {:?}",
                self
            ))),
        }
    }

    /// For conditional boundaries only (if, while, ternary).
    /// Pine v6: na in a condition takes the false/else branch.
    pub fn truthy_for_condition(&self) -> Result<bool, RuntimeError> {
        Ok(self.to_bool()?.unwrap_or(false))
    }

    pub fn as_string(&self) -> Result<String, RuntimeError> {
        match self {
            Value::String(s) => Ok(s.clone()),
            Value::Int(n) => Ok(n.to_string()),
            Value::Number(n) => Ok(n.to_string()),
            Value::Bool(b) => Ok(b.to_string()),
            Value::Na => Ok("na".to_string()),
            _ => Err(RuntimeError::TypeError(format!(
                "Cannot convert {:?} to string",
                self
            ))),
        }
    }

    pub fn as_array(&self) -> Result<&Rc<RefCell<Vec<Value<O>>>>, RuntimeError> {
        match self {
            Value::Array(arr) => Ok(arr),
            _ => Err(RuntimeError::TypeError(format!(
                "Expected array, got {:?}",
                self
            ))),
        }
    }

    pub fn as_color(&self) -> Result<Color, RuntimeError> {
        match self {
            Value::Color(color) => Ok(color.clone()),
            _ => Err(RuntimeError::TypeError(format!(
                "Expected color, got {:?}",
                self
            ))),
        }
    }
}

/// Method definition stored in the interpreter
#[derive(Clone)]
struct MethodDef {
    type_name: String, // The type this method belongs to (from first param's type annotation)
    params: Vec<pine_ast::MethodParam>,
    body: Vec<Stmt>,
}

/// The interpreter executes a program with a given bar
pub struct Interpreter<O: PineOutput> {
    /// Local variables in the current scope
    variables: HashMap<String, Variable<O>>,
    /// User-defined types, kept separate from `variables` so a UDT and a
    /// function/variable may share a name (Pine's type and value namespaces are
    /// distinct). `Type.new` / `Type.copy` resolve here.
    user_types: HashMap<String, Value<O>>,
    /// Method registry (method_name -> Vec<MethodDef>) - can have multiple methods with same name for different types
    methods: HashMap<String, Vec<MethodDef>>,
    /// Library loader for importing external libraries
    pub library_loader: Option<Box<dyn LibraryLoader>>,
    /// Exported items from this module (for library mode)
    exports: HashMap<String, Value<O>>,
    /// Output storage for plots, labels, logs, etc.
    pub output: O,
    /// Per-variable history for user-computed series (`var` declarations).
    /// history[len-1] = previous bar, history[len-2] = two bars ago, etc.
    /// Populated on each `Stmt::Assignment`; supports Pine's `name[n]` lookback.
    pub user_series_history: HashMap<String, Vec<Value<O>>>,
    /// Persistent local state for user-defined functions, keyed by the call
    /// site's stable lexical id (`Expr::Call::id`). Keying by call site — not
    /// by function name — means two calls to the same function keep independent
    /// state, mirroring TradingView (e.g. `o[1]` inside a function returns the
    /// previous bar's value of that call site's local `o`). A `call_id` of 0
    /// (a call with no stable identity) is not persisted.
    function_local_state: HashMap<u32, HashMap<String, Variable<O>>>,
    /// `var`/`varip` declarations whose initializer already ran, keyed by
    /// (call-site id, name). Pine `var` initializes only the FIRST time
    /// execution reaches the declaration (once ever, not per bar/iteration).
    /// The call-site id (0 at top level) scopes it per call site, so the same
    /// function-local `var` at two call sites initializes independently.
    /// Tracked separately from `variables` so a `var` declaration can shadow a
    /// pre-existing host-injected variable (e.g. `var close = 10`).
    ///
    /// The value is the bar it initialized on, so a reassignment can tell that
    /// there is no previous bar to read back yet.
    var_decls_initialized: HashMap<(u32, String), u64>,
    /// Lexical id of the call site currently executing (0 at top level). Scopes
    /// `var` init-once tracking to the active call site.
    current_call_id: u32,
    /// Counts bars executed. Stateful builtins compare against it to advance
    /// their state at most once per bar, however often their call site runs.
    bar_seq: u64,
    /// The simulated broker a `strategy` script trades against. `None` for an
    /// `indicator`. The `strategy.*` order builtins reach it through `ctx`.
    pub broker: Option<Box<dyn pine_broker::Broker>>,
    /// Builds [`broker`](Self::broker) the first bar a `strategy` runs.
    pub broker_factory: Option<Box<dyn pine_broker::BrokerFactory>>,
    /// The feed `request.security` draws other symbols/timeframes from.
    pub request_provider: Option<Rc<dyn pine_core::DataProvider>>,
    pub chart_period: Option<i64>,
}

/// Names a statement block ASSIGNS (declares or writes) directly — i.e. the true
/// locals of a function body. Reads (e.g. `open`) are ignored, and nested function
/// declarations are a separate scope so their bodies are not descended into. Used to
/// decide which variables a call site's persistent state should carry across bars.
fn collect_assigned_names(body: &[Stmt], out: &mut std::collections::HashSet<String>) {
    for s in body {
        match s {
            Stmt::VarDecl { name, .. } => {
                out.insert(name.clone());
            }
            Stmt::Assignment {
                target: Expr::Variable { name: n, .. },
                ..
            } => {
                out.insert(n.clone());
            }
            Stmt::TupleAssignment { names, .. } => {
                for n in names {
                    out.insert(n.clone());
                }
            }
            Stmt::If {
                then_branch,
                else_if_branches,
                else_branch,
                ..
            } => {
                collect_assigned_names(then_branch, out);
                for (_, b) in else_if_branches {
                    collect_assigned_names(b, out);
                }
                if let Some(b) = else_branch {
                    collect_assigned_names(b, out);
                }
            }
            Stmt::For { var_name, body, .. } => {
                out.insert(var_name.clone());
                collect_assigned_names(body, out);
            }
            Stmt::While { body, .. } | Stmt::ForIn { body, .. } => {
                collect_assigned_names(body, out)
            }
            _ => {}
        }
    }
}

/// The builtin namespace whose functions back a value's method syntax, e.g.
/// `arr.push(v)` dispatches to `array.push(arr, v)`.
fn builtin_namespace<O: PineOutput>(value: &Value<O>) -> Option<&'static str> {
    match value {
        Value::Array(_) => Some("array"),
        Value::Matrix { .. } => Some("matrix"),
        _ => None,
    }
}

/// Pine `na` is float NaN. NaN can also reach `==`/`!=` wrapped as a
/// `Value::Number(NaN)` (ta.* functions return `Number(NaN)` for all-NaN
/// windows) rather than `Value::Na` — both forms make the comparison yield na.
fn is_na_operand<O: PineOutput>(v: &Value<O>) -> bool {
    matches!(v, Value::Na) || matches!(v, Value::Number(n) if n.is_nan())
}

impl<O: PineOutput> Interpreter<O> {
    pub fn new() -> Self {
        Self {
            variables: HashMap::new(),
            user_types: HashMap::new(),
            methods: HashMap::new(),
            library_loader: None,
            exports: HashMap::new(),
            output: O::default(),
            user_series_history: HashMap::new(),
            function_local_state: HashMap::new(),
            var_decls_initialized: HashMap::new(),
            current_call_id: 0,
            bar_seq: 0,
            broker: None,
            broker_factory: Some(Box::new(pine_broker::DefaultBrokerFactory)),
            request_provider: None,
            chart_period: None,
        }
    }

    /// How many bars have been executed. A stateful builtin advances its state
    /// when this differs from the value it last saw.
    pub fn bar_seq(&self) -> u64 {
        self.bar_seq
    }

    /// Set the library loader
    pub fn set_library_loader(&mut self, library_loader: Box<dyn LibraryLoader>) {
        self.library_loader = Some(library_loader);
    }

    /// A copy of every defined variable's value, so a secondary interpreter
    /// (`request.security`) can start from the same namespaces and builtins
    /// without re-registering them.
    pub fn snapshot(&self) -> HashMap<String, Value<O>> {
        self.variables
            .iter()
            .map(|(name, var)| (name.clone(), var.value.clone()))
            .collect()
    }

    /// Get the exported items from this interpreter (for library mode)
    pub fn exports(&self) -> &HashMap<String, Value<O>> {
        &self.exports
    }

    /// Execute a program with a single bar
    pub fn execute(&mut self, program: &Program) -> Result<O, RuntimeError> {
        // Clear output from previous iteration
        self.output.clear();
        // A new bar: stateful builtins may advance their state again.
        self.bar_seq += 1;

        for stmt in &program.statements {
            self.execute_stmt(stmt)?;
        }

        // Return a clone of the output
        Ok(self.output.clone())
    }

    /// Get a variable value
    pub fn get_variable(&self, name: &str) -> Option<&Value<O>> {
        self.variables.get(name).map(|var| &var.value)
    }

    /// Whether `name` is a declared user-defined type.
    pub fn is_user_type(&self, name: &str) -> bool {
        self.user_types.contains_key(name)
    }

    /// The `member` field of a builtin namespace object (e.g. `array`'s `push`).
    fn namespace_member(&self, namespace: &str, member: &str) -> Option<Value<O>> {
        match self.variables.get(namespace).map(|var| &var.value) {
            Some(Value::Object { fields, .. }) => fields.borrow().get(member).cloned(),
            _ => None,
        }
    }

    /// Set a variable value (useful for loading objects and test setup)
    pub fn set_variable(&mut self, name: &str, value: Value<O>) {
        self.variables.insert(
            name.to_string(),
            Variable {
                value,
                is_const: false,
                is_var_persistent: false,
            },
        );
    }

    /// Set a built-in series to its value for a new bar, keeping the outgoing
    /// value reachable as `name[1]`.
    ///
    /// This is how the OHLCV series and their derivations get the same lookback
    /// as any user variable: history accumulates as bars execute, so `close[1]`
    /// is na until a second bar has run.
    pub fn advance_series(&mut self, name: &str, value: Value<O>) {
        if let Some(existing) = self.variables.get(name) {
            // Record the number the series held, not the series wrapper, so a
            // `name[1]` lookback reads as a plain value.
            let previous = match &existing.value {
                Value::Series(series) => (*series.current).clone(),
                other => other.clone(),
            };
            push_history(&mut self.user_series_history, name, previous);
        }
        self.set_variable(name, value);
    }

    /// Set a field on a namespace object (e.g. `strategy.position_size`),
    /// leaving the object's other fields untouched. A no-op if `object` is not
    /// a registered namespace object.
    pub fn set_object_field(&mut self, object: &str, field: &str, value: Value<O>) {
        if let Some(Variable {
            value: Value::Object { fields, .. },
            ..
        }) = self.variables.get(object)
        {
            fields.borrow_mut().insert(field.to_string(), value);
        }
    }

    /// Set a const variable (cannot be reassigned)
    pub fn set_const_variable(&mut self, name: &str, value: Value<O>) {
        self.variables.insert(
            name.to_string(),
            Variable {
                value,
                is_const: true,
                is_var_persistent: false,
            },
        );
    }

    /// Register every entry as a const variable — used to load the builtin
    /// namespaces and any host-supplied globals before a run.
    pub fn set_const_variables(&mut self, variables: HashMap<String, Value<O>>) {
        for (name, value) in variables {
            self.set_const_variable(&name, value);
        }
    }

    /// Helper to evaluate arguments and validate positional-before-named rule
    /// Evaluate a call's arguments. A parameter marked lazy in `signature`
    /// receives its argument unevaluated, as a captured [`Value::Expr`].
    fn evaluate_arguments(
        &mut self,
        args: &[Argument],
        signature: Option<&BuiltinSignature>,
    ) -> Result<Vec<EvaluatedArg<O>>, RuntimeError> {
        let mut evaluated_args = Vec::new();
        let mut seen_named = false;
        let mut positional_index = 0;

        for arg in args {
            match arg {
                Argument::Positional(expr) => {
                    if seen_named {
                        return Err(RuntimeError::TypeError(
                            "Positional arguments cannot follow named arguments".to_string(),
                        ));
                    }
                    let lazy = signature.is_some_and(|s| s.positional_is_lazy(positional_index));
                    let value = self.eval_or_capture(expr, lazy)?;
                    evaluated_args.push(EvaluatedArg::Positional(value));
                    positional_index += 1;
                }
                Argument::Named { name, value: expr } => {
                    seen_named = true;
                    let lazy = signature.is_some_and(|s| s.named_is_lazy(name));
                    let value = self.eval_or_capture(expr, lazy)?;
                    evaluated_args.push(EvaluatedArg::Named {
                        name: name.clone(),
                        value,
                    });
                }
            }
        }

        Ok(evaluated_args)
    }

    /// Evaluate `expr`, or capture it unevaluated as a [`Value::Expr`] when the
    /// parameter it binds to is lazy.
    fn eval_or_capture(&mut self, expr: &Expr, lazy: bool) -> Result<Value<O>, RuntimeError> {
        if lazy {
            Ok(Value::Expr(Rc::new(expr.clone())))
        } else {
            self.eval_expr(expr)
        }
    }

    fn execute_stmt(&mut self, stmt: &Stmt) -> Result<Option<Value<O>>, RuntimeError> {
        match stmt {
            Stmt::VarDecl {
                name,
                type_qualifier,
                type_annotation: _,
                initializer,
                // varip's intrabar-update behavior is not yet implemented; it
                // persists across bars exactly like var (is_persistent()).
                var_kind,
                ..
            } => {
                let is_var_persistent = var_kind.is_persistent();
                // Pine `var`/`varip` semantics: the initializer runs only the
                // FIRST time execution reaches this declaration (once ever).
                // Scoped by the current call site (0 at top level) so the same
                // function-local `var` at two call sites initializes
                // independently. Tracked separately from `variables` so a `var`
                // declaration can shadow a pre-existing host-injected builtin.
                if is_var_persistent {
                    let init_key = (self.current_call_id, name.clone());
                    if self.var_decls_initialized.contains_key(&init_key) {
                        return Ok(None);
                    }
                    self.var_decls_initialized.insert(init_key, self.bar_seq);
                }
                // Non-`var` declarations (e.g. `ha_bull_4h = expr`) re-execute on every bar.
                // Push the previous value to history so `name[1]` lookbacks work, exactly as
                // the Assignment handler does for `:=` reassignments.
                if !is_var_persistent {
                    if let Some(existing) = self.variables.get(name) {
                        push_history(&mut self.user_series_history, name, existing.value.clone());
                    }
                }
                let value = if let Some(init_expr) = initializer {
                    self.eval_expr(init_expr)?
                } else {
                    Value::Na
                };
                let is_const = matches!(type_qualifier, Some(pine_ast::TypeQualifier::Const));
                self.variables.insert(
                    name.clone(),
                    Variable {
                        value,
                        is_const,
                        is_var_persistent,
                    },
                );
                Ok(None)
            }

            Stmt::Assignment { target, value } => {
                // Pine `var`-persistent variables: push their current (previous-bar) value to
                // history BEFORE evaluating the RHS so that [1] lookback in the expression
                // sees the correct previous-bar value.  Non-var variables push after eval
                // (their old value was already pushed by VarDecl, or there is no VarDecl).
                //
                // Nothing is pushed on the bar the `var` initialized: there is no
                // previous bar yet, and inventing one would make `acc[1]` read the
                // initializer instead of na.
                if let Expr::Variable { name, .. } = target {
                    if let Some(var) = self.variables.get(name) {
                        let born_this_bar = self
                            .var_decls_initialized
                            .get(&(self.current_call_id, name.clone()))
                            == Some(&self.bar_seq);
                        if var.is_var_persistent && !born_this_bar {
                            push_history(&mut self.user_series_history, name, var.value.clone());
                        }
                    }
                }

                let val = self.eval_expr(value)?;
                match target {
                    Expr::Variable { name, .. } => {
                        // Preserve the existing variable's flags (const, persistent).
                        let (is_const, is_var_persistent) =
                            if let Some(var) = self.variables.get(name) {
                                if var.is_const {
                                    return Err(RuntimeError::ConstReassignment(name.clone()));
                                }
                                if !var.is_var_persistent {
                                    // Non-var: push current value to history after eval (Pine [n] lookback).
                                    push_history(
                                        &mut self.user_series_history,
                                        name,
                                        var.value.clone(),
                                    );
                                }
                                // var-persistent: already pushed before eval above.
                                (false, var.is_var_persistent)
                            } else {
                                (false, false)
                            };

                        self.variables.insert(
                            name.clone(),
                            Variable {
                                value: val,
                                is_const,
                                is_var_persistent,
                            },
                        );
                        Ok(None)
                    }
                    Expr::MemberAccess { object, member, .. } => {
                        // Check if we're trying to modify a member of a const variable
                        if let Expr::Variable { name: var_name, .. } = object.as_ref() {
                            if let Some(var) = self.variables.get(var_name) {
                                if var.is_const {
                                    return Err(RuntimeError::ConstReassignment(format!(
                                        "{}.{}",
                                        var_name, member
                                    )));
                                }
                            }
                        }

                        // Get the object
                        let obj_value = self.eval_expr(object)?;

                        if let Value::Object { fields, .. } = obj_value {
                            let mut obj = fields.borrow_mut();
                            obj.insert(member.clone(), val);
                            Ok(None)
                        } else {
                            Err(RuntimeError::TypeError(
                                "Cannot assign to member of non-object value".to_string(),
                            ))
                        }
                    }
                    _ => Err(RuntimeError::TypeError(
                        "Invalid assignment target".to_string(),
                    )),
                }
            }

            Stmt::TupleAssignment { names, value, .. } => {
                let val = self.eval_expr(value)?;
                if let Value::Array(arr_ref) = val {
                    let arr = arr_ref.borrow();
                    for (i, name) in names.iter().enumerate() {
                        // Push current value to history before overwriting (supports [n] lookback).
                        if let Some(var) = self.variables.get(name) {
                            push_history(&mut self.user_series_history, name, var.value.clone());
                        }
                        let element_val = arr.get(i).cloned().unwrap_or(Value::Na);
                        self.variables.insert(
                            name.clone(),
                            Variable {
                                value: element_val,
                                is_const: false,
                                is_var_persistent: false,
                            },
                        );
                    }
                    Ok(None)
                } else {
                    Err(RuntimeError::TypeError(
                        "Expected array for tuple destructuring".to_string(),
                    ))
                }
            }

            Stmt::Expression(expr) => {
                self.eval_expr(expr)?;
                Ok(None)
            }

            Stmt::If {
                condition,
                then_branch,
                else_if_branches,
                else_branch,
            } => {
                let cond_value = self.eval_expr(condition)?;
                if cond_value.truthy_for_condition()? {
                    for stmt in then_branch {
                        self.execute_stmt(stmt)?;
                    }
                } else {
                    // Try each else if branch in order
                    let mut executed = false;
                    for (else_if_cond, else_if_body) in else_if_branches {
                        let else_if_value = self.eval_expr(else_if_cond)?;
                        if else_if_value.truthy_for_condition()? {
                            for stmt in else_if_body {
                                self.execute_stmt(stmt)?;
                            }
                            executed = true;
                            break;
                        }
                    }

                    // If no else if matched, try else branch
                    if !executed {
                        if let Some(else_stmts) = else_branch {
                            for stmt in else_stmts {
                                self.execute_stmt(stmt)?;
                            }
                        }
                    }
                }
                Ok(None)
            }

            Stmt::For {
                var_name,
                from,
                to,
                step,
                body,
                ..
            } => {
                let from_val = self.eval_expr(from)?.as_number()?;
                let to_val = self.eval_expr(to)?.as_number()?;

                // `by <step>` is a positive magnitude (default 1); the direction
                // comes from `from` vs `to`, so `for i = 3 to 0` counts down.
                let step_val = match step {
                    Some(expr) => self.eval_expr(expr)?.as_number()?.abs(),
                    None => 1.0,
                };
                if step_val == 0.0 {
                    return Err(RuntimeError::InvalidForLoop(from_val, to_val));
                }
                let down = from_val > to_val;

                let mut i = from_val as i64;
                let end = to_val as i64;
                let step = step_val as i64;

                while if down { i >= end } else { i <= end } {
                    self.variables.insert(
                        var_name.clone(),
                        Variable {
                            value: Value::Int(i),
                            is_const: false,
                            is_var_persistent: false,
                        },
                    );

                    let control = self.execute_loop_body(body)?;
                    if control == LoopControl::Break {
                        break;
                    }

                    if down {
                        i -= step;
                    } else {
                        i += step;
                    }
                }

                Ok(None)
            }

            Stmt::ForIn {
                index_var,
                item_var,
                collection,
                body,
                ..
            } => {
                let collection_value = self.eval_expr(collection)?;
                let arr = collection_value.as_array()?;
                let arr_borrowed = arr.borrow();

                for (index, item) in arr_borrowed.iter().enumerate() {
                    // Set index variable if tuple form
                    if let Some(idx_var) = index_var {
                        self.variables.insert(
                            idx_var.clone(),
                            Variable {
                                value: Value::Int(index as i64),
                                is_const: false,
                                is_var_persistent: false,
                            },
                        );
                    }

                    // Set item variable
                    self.variables.insert(
                        item_var.clone(),
                        Variable {
                            value: item.clone(),
                            is_const: false,
                            is_var_persistent: false,
                        },
                    );

                    let control = self.execute_loop_body(body)?;
                    if control == LoopControl::Break {
                        break;
                    }
                }

                Ok(None)
            }

            Stmt::While { condition, body } => {
                loop {
                    let cond_value = self.eval_expr(condition)?;
                    if !cond_value.truthy_for_condition()? {
                        break;
                    }

                    let control = self.execute_loop_body(body)?;
                    if control == LoopControl::Break {
                        break;
                    }
                }
                Ok(None)
            }

            Stmt::Break { .. } => Err(RuntimeError::BreakOutsideLoop),
            Stmt::Continue { .. } => Err(RuntimeError::ContinueOutsideLoop),

            Stmt::TypeDecl {
                name,
                fields,
                export,
                ..
            } => {
                // Create a Type value and store it as a variable
                let type_value = Value::Type {
                    name: name.clone(),
                    fields: fields.clone(),
                };
                self.user_types.insert(name.clone(), type_value.clone());
                self.variables.insert(
                    name.clone(),
                    Variable {
                        value: type_value.clone(),
                        is_const: false,
                        is_var_persistent: false,
                    },
                );

                // If exported, also store in exports
                if *export {
                    self.exports.insert(name.clone(), type_value);
                }
                Ok(None)
            }

            Stmt::EnumDecl {
                name,
                fields,
                export,
                ..
            } => {
                // Create an Object that contains all enum members as fields
                let mut enum_fields = HashMap::new();

                for field in fields {
                    let title = field.title.clone().unwrap_or_else(|| field.name.clone());
                    let enum_value = Value::Enum {
                        enum_name: name.clone(),
                        field_name: field.name.clone(),
                        title,
                    };
                    enum_fields.insert(field.name.clone(), enum_value);
                }

                let enum_object = Value::Object {
                    type_name: name.clone(),
                    fields: Rc::new(RefCell::new(enum_fields)),
                    call: None,
                };
                self.variables.insert(
                    name.clone(),
                    Variable {
                        value: enum_object.clone(),
                        is_const: false,
                        is_var_persistent: false,
                    },
                );

                // If exported, also store in exports
                if *export {
                    self.exports.insert(name.clone(), enum_object);
                }
                Ok(None)
            }

            Stmt::Export { item } => {
                // Mark the item for export
                match item {
                    pine_ast::ExportItem::Type(type_name) => {
                        // Export the type - it should already be in variables
                        if let Some(var) = self.variables.get(type_name) {
                            self.exports.insert(type_name.clone(), var.value.clone());
                        }
                    }
                    pine_ast::ExportItem::Function(func_name) => {
                        // Export the function - it should already be in variables
                        if let Some(var) = self.variables.get(func_name) {
                            self.exports.insert(func_name.clone(), var.value.clone());
                        }
                    }
                }
                Ok(None)
            }

            Stmt::Import { path, alias, .. } => {
                let source = match &self.library_loader {
                    Some(loader) => loader.load_library(path),
                    None => {
                        return Err(RuntimeError::LibraryError(
                            "Cannot import library: no library loader configured".to_string(),
                        ))
                    }
                }
                .map_err(|e| {
                    RuntimeError::LibraryError(format!("Failed to load library '{}': {}", path, e))
                })?;

                let library_program = pine_parser::Parser::parse_source(&source).map_err(|e| {
                    RuntimeError::LibraryError(format!("Failed to parse library '{}': {}", path, e))
                })?;

                // Seed the library with the same built-in namespaces/globals
                // (e.g. `library`, `math`) so its declaration and body resolve.
                let mut library_interp = Interpreter::new();
                for (name, value) in self.snapshot() {
                    library_interp.set_variable(&name, value);
                }
                library_interp.execute(&library_program)?;
                let library_exports = library_interp.exports();

                for (method_name, method_defs) in &library_interp.methods {
                    for method_def in method_defs {
                        self.methods
                            .entry(method_name.clone())
                            .or_default()
                            .push(method_def.clone());
                    }
                }

                let namespace: Value<O> = Value::Object {
                    type_name: alias.clone(),
                    fields: Rc::new(RefCell::new(library_exports.clone())),
                    call: None,
                };
                self.variables.insert(
                    alias.clone(),
                    Variable {
                        value: namespace,
                        is_const: false,
                        is_var_persistent: false,
                    },
                );
                Ok(None)
            }

            Stmt::MethodDecl {
                name,
                params,
                body,
                export,
                ..
            } => {
                // Extract the type name from the first parameter's type annotation
                let type_name = if let Some(first_param) = params.first() {
                    first_param.type_annotation.clone().ok_or_else(|| {
                        RuntimeError::TypeError(
                            "Method's first parameter must have a type annotation".to_string(),
                        )
                    })?
                } else {
                    return Err(RuntimeError::TypeError(
                        "Method must have at least one parameter (this)".to_string(),
                    ));
                };

                // Store the method definition
                let method_def = MethodDef {
                    type_name,
                    params: params.clone(),
                    body: body.clone(),
                };

                self.methods
                    .entry(name.clone())
                    .or_default()
                    .push(method_def);

                // If exported, store the method in exports
                // Methods are exported as part of their type, so we may need to handle this differently
                // For now, just mark it as exported (this might need more work)
                if *export {
                    // TODO: Handle method exports properly
                }

                Ok(None)
            }

            Stmt::FunctionDecl {
                name,
                params,
                body,
                export,
                ..
            } => {
                // Create a function value
                let func_value = Value::Function {
                    params: params.clone(),
                    body: body.clone(),
                };
                self.variables.insert(
                    name.clone(),
                    Variable {
                        value: func_value.clone(),
                        is_const: false,
                        is_var_persistent: false,
                    },
                );

                // If exported, also store in exports
                if *export {
                    self.exports.insert(name.clone(), func_value);
                }

                Ok(None)
            }
        }
    }

    /// Execute loop body, handling break/continue
    fn execute_loop_body(&mut self, body: &[Stmt]) -> Result<LoopControl, RuntimeError> {
        for stmt in body {
            match stmt {
                Stmt::Break { .. } => return Ok(LoopControl::Break),
                Stmt::Continue { .. } => return Ok(LoopControl::Continue),
                Stmt::If {
                    condition,
                    then_branch,
                    else_if_branches,
                    else_branch,
                } => {
                    let cond_value = self.eval_expr(condition)?;
                    let branch = if cond_value.truthy_for_condition()? {
                        then_branch
                    } else {
                        // Try each else if branch
                        let mut matched_branch = None;
                        for (else_if_cond, else_if_body) in else_if_branches {
                            let else_if_value = self.eval_expr(else_if_cond)?;
                            if else_if_value.truthy_for_condition()? {
                                matched_branch = Some(else_if_body);
                                break;
                            }
                        }

                        if let Some(branch) = matched_branch {
                            branch
                        } else if let Some(else_stmts) = else_branch {
                            else_stmts
                        } else {
                            continue;
                        }
                    };

                    let control = self.execute_loop_body(branch)?;
                    if control != LoopControl::None {
                        return Ok(control);
                    }
                }
                Stmt::For { .. } | Stmt::ForIn { .. } | Stmt::While { .. } => {
                    // Nested loops handle their own break/continue
                    self.execute_stmt(stmt)?;
                }
                _ => {
                    self.execute_stmt(stmt)?;
                }
            }
        }
        Ok(LoopControl::None)
    }

    fn eval_expr(&mut self, expr: &Expr) -> Result<Value<O>, RuntimeError> {
        match expr {
            Expr::Literal(lit) => Ok(self.eval_literal(lit)),

            Expr::Variable { name, .. } => self
                .variables
                .get(name)
                .map(|var| var.value.clone())
                .ok_or_else(|| RuntimeError::UndefinedVariable(name.clone())),

            Expr::Binary {
                left, op, right, ..
            } => {
                let left_val = self.eval_expr(left)?;
                // Pine `and`/`or` are lazy: when the left operand alone decides
                // the result (false-and / true-or), the right operand is NOT
                // evaluated — side effects inside it (e.g. stateful ta.* calls)
                // must not run. The three-valued na results are unchanged:
                // false absorbs na in `and`, true absorbs na in `or`, and an
                // na left operand still requires the right operand's value.
                if matches!(op, BinOp::And | BinOp::Or) {
                    match (op, left_val.to_bool()?) {
                        (BinOp::And, Some(false)) => return Ok(Value::Bool(false)),
                        (BinOp::Or, Some(true)) => return Ok(Value::Bool(true)),
                        _ => {}
                    }
                }
                let right_val = self.eval_expr(right)?;
                self.eval_binary_op(&left_val, op, &right_val)
            }

            Expr::Unary { op, expr } => {
                let val = self.eval_expr(expr)?;
                self.eval_unary_op(op, &val)
            }

            Expr::Ternary {
                condition,
                then_expr,
                else_expr,
            } => {
                let cond_val = self.eval_expr(condition)?;
                if cond_val.truthy_for_condition()? {
                    self.eval_expr(then_expr)
                } else {
                    self.eval_expr(else_expr)
                }
            }

            Expr::IfExpr {
                condition,
                then_expr,
                else_if_branches,
                else_expr,
            } => {
                let cond_val = self.eval_expr(condition)?;
                if cond_val.truthy_for_condition()? {
                    self.eval_expr(then_expr)
                } else {
                    // Try each else if branch
                    for (else_if_cond, else_if_expr) in else_if_branches {
                        let else_if_val = self.eval_expr(else_if_cond)?;
                        if else_if_val.truthy_for_condition()? {
                            return self.eval_expr(else_if_expr);
                        }
                    }
                    // No else if matched, evaluate else branch or return na
                    if let Some(expr) = else_expr {
                        self.eval_expr(expr)
                    } else {
                        Ok(Value::Na)
                    }
                }
            }

            Expr::Array(elements) => {
                let values: Result<Vec<_>, _> =
                    elements.iter().map(|e| self.eval_expr(e)).collect();
                Ok(Value::Array(Rc::new(RefCell::new(values?))))
            }

            Expr::Index { expr, index } => {
                let index_val = self.eval_expr(index)?.as_number()? as usize;

                // For user-computed variables with tracked history, look up
                // user_series_history: history[len-1] = previous bar. A tracked
                // variable with insufficient depth yields na (warm-up), never a
                // fall-through to Number indexing. Variables WITHOUT tracked
                // history (e.g. builtin Series like `close` fed by the host)
                // fall through to the Series/Array indexing below.
                if index_val > 0 {
                    if let Expr::Variable { name: var_name, .. } = expr.as_ref() {
                        if let Some(h) = self.user_series_history.get(var_name) {
                            return Ok(if h.len() >= index_val {
                                h[h.len() - index_val].clone()
                            } else {
                                Value::Na
                            });
                        }
                        // Non-Series plain values with no history (a user var
                        // assigned only this bar) still index as na rather
                        // than erroring below.
                        if let Some(var) = self.variables.get(var_name) {
                            if !matches!(var.value, Value::Series(_) | Value::Array(_)) {
                                return Ok(Value::Na);
                            }
                        }
                    }
                }

                let val = self.eval_expr(expr)?;

                match val {
                    Value::Array(arr_ref) => {
                        let arr = arr_ref.borrow();
                        arr.get(index_val)
                            .cloned()
                            .ok_or(RuntimeError::IndexOutOfBounds(index_val))
                    }
                    Value::Series(series) => {
                        // Index 0 is this bar. Anything further back lives in
                        // `user_series_history`, which the branch above already
                        // consulted for a named variable — reaching here means
                        // the series has no recorded history, which is na.
                        if index_val == 0 {
                            Ok((*series.current).clone())
                        } else {
                            Ok(Value::Na)
                        }
                    }
                    ref v => Err(RuntimeError::TypeError(format!(
                        "Cannot index non-array/non-series value: {:?}",
                        v
                    ))),
                }
            }

            Expr::Switch { value, cases } => {
                let switch_val = self.eval_expr(value)?;

                for (pattern, result) in cases {
                    // Check if pattern matches
                    let pattern_val = self.eval_expr(pattern)?;

                    // Special case: default pattern (true literal)
                    if pattern_val == Value::Bool(true)
                        && matches!(pattern, Expr::Literal(Literal::Bool(true)))
                    {
                        return self.eval_expr(result);
                    }

                    // Check equality
                    if self.values_equal(&switch_val, &pattern_val)? {
                        return self.eval_expr(result);
                    }
                }

                // No match found
                Ok(Value::Na)
            }

            Expr::Call {
                callee,
                type_args,
                args,
                id,
                ..
            } => {
                // Check if this is a method call (object.method())
                if let Expr::MemberAccess { object, member, .. } = callee.as_ref() {
                    // Try to find a method with this name
                    if let Some(method_defs) = self.methods.get(member).cloned() {
                        // Evaluate the object (this will be the first parameter)
                        let obj_value = self.eval_expr(object)?;

                        // Find the method that matches the object's type
                        let obj_type = self.get_object_type_name(&obj_value)?;

                        if let Some(method_def) =
                            method_defs.iter().find(|m| m.type_name == obj_type)
                        {
                            // Evaluate the other arguments
                            let mut evaluated_args: Vec<EvaluatedArg<O>> =
                                vec![EvaluatedArg::Positional(obj_value)];
                            evaluated_args.extend(self.evaluate_arguments(args, None)?);

                            // Call the method (treating it like a function),
                            // threading the call site id so method-local state
                            // persists per call site.
                            return self.call_method(
                                &method_def.params,
                                &method_def.body,
                                evaluated_args,
                                *id,
                            );
                        }
                    }
                }

                // Builtin method syntax: a collection receiver `x.m(args)` is
                // sugar for `namespace.m(x, args)` — the same builtins in
                // function form, with the receiver passed first. (Skip `Call`
                // receivers so a side-effecting `f().m()` is not evaluated twice.)
                if let Expr::MemberAccess { object, member, .. } = callee.as_ref() {
                    if !matches!(object.as_ref(), Expr::Call { .. }) {
                        let receiver = self.eval_expr(object)?;
                        if let Some(namespace) = builtin_namespace(&receiver) {
                            if let Some(Value::BuiltinFunction(builtin_fn)) =
                                self.namespace_member(namespace, member)
                            {
                                let mut evaluated_args = vec![EvaluatedArg::Positional(receiver)];
                                evaluated_args.extend(self.evaluate_arguments(args, None)?);
                                let call_args =
                                    FunctionCallArgs::new(type_args.clone(), evaluated_args)
                                        .with_call_id(*id);
                                return (builtin_fn.call)(self, call_args);
                            }
                        }
                    }
                }

                // Not a method call, proceed with regular function call.
                // Resolve the callee first so a builtin's lazy parameters can
                // capture their arguments unevaluated.
                let callee_value = self.eval_expr(callee)?;
                let signature = match &callee_value {
                    Value::BuiltinFunction(builtin) => Some(builtin.signature.clone()),
                    _ => None,
                };
                let evaluated_args = self.evaluate_arguments(args, signature.as_ref())?;

                // Call the function based on its type
                match callee_value {
                    Value::Function { params, body } => {
                        // Thread the call site's lexical id so function-local
                        // state persists per call site, not per function name.
                        self.call_user_function(&params, &body, args, evaluated_args, *id)
                    }
                    Value::BuiltinFunction(builtin_fn) => {
                        // Pass type_args from the parsed call expression, and the
                        // call node's lexical id for per-call-site builtin state.
                        let call_args = FunctionCallArgs::new(type_args.clone(), evaluated_args)
                            .with_call_id(*id);
                        (builtin_fn.call)(self, call_args)
                    }
                    // A callable namespace object, like `input(...)` alongside
                    // `input.int(...)`. Objects without a `call` are not callable.
                    Value::Object {
                        call: Some(builtin_fn),
                        ..
                    } => {
                        let call_args = FunctionCallArgs::new(type_args.clone(), evaluated_args)
                            .with_call_id(*id);
                        (builtin_fn)(self, call_args)
                    }
                    // Pine's `na` is a keyword that doubles as a function: na(x) → is x na?
                    Value::Na => {
                        let is_na = matches!(
                            evaluated_args.first(),
                            Some(EvaluatedArg::Positional(Value::Na)) | None
                        );
                        Ok(Value::Bool(is_na))
                    }
                    _ => Err(RuntimeError::TypeError(
                        "Attempted to call a non-function value".to_string(),
                    )),
                }
            }

            Expr::MemberAccess { object, member, .. } => {
                // `Type.new` / `Type.copy` resolve via the type namespace, so a
                // type may share its name with a shadowing function/variable.
                let obj_value = match object.as_ref() {
                    Expr::Variable { name, .. }
                        if (member == "new" || member == "copy")
                            && self.user_types.contains_key(name) =>
                    {
                        self.user_types[name].clone()
                    }
                    _ => self.eval_expr(object)?,
                };
                match obj_value {
                    Value::Object { fields, .. } => {
                        let obj = fields.borrow();
                        obj.get(member).cloned().ok_or_else(|| {
                            RuntimeError::TypeError(format!("Object has no member '{}'", member))
                        })
                    }
                    Value::Type { name, fields } => {
                        // Types have 'new' and 'copy' methods
                        if member == "new" {
                            // Return a constructor function
                            Ok(Value::BuiltinFunction(Builtin::untyped(
                                Self::create_constructor(name, fields),
                            )))
                        } else if member == "copy" {
                            // Return a copy function
                            Ok(Value::BuiltinFunction(Builtin::untyped(
                                Self::create_copy_function(),
                            )))
                        } else {
                            Err(RuntimeError::TypeError(format!(
                                "Type '{}' has no member '{}' (only 'new' and 'copy' are supported)",
                                name, member
                            )))
                        }
                    }
                    _ => Err(RuntimeError::TypeError(format!(
                        "Cannot access member '{}' on non-object value",
                        member
                    ))),
                }
            }

            Expr::Function { params, body } => {
                // params is already Vec<FunctionParam> from the AST
                Ok(Value::Function {
                    params: params.clone(),
                    body: body.clone(),
                })
            }
        }
    }

    fn eval_literal(&self, lit: &Literal) -> Value<O> {
        match lit {
            Literal::Int(n) => Value::Int(*n),
            Literal::Number(n) => Value::Number(*n),
            Literal::String(s) => Value::String(s.clone()),
            Literal::Bool(b) => Value::Bool(*b),
            Literal::Na => Value::Na,
            Literal::HexColor(hex) => Value::String(hex.clone()),
        }
    }

    fn eval_binary_op(
        &self,
        left: &Value<O>,
        op: &BinOp,
        right: &Value<O>,
    ) -> Result<Value<O>, RuntimeError> {
        match op {
            BinOp::Add => {
                // String concatenation or numeric addition
                if matches!(left, Value::String(_)) || matches!(right, Value::String(_)) {
                    Ok(Value::String(format!(
                        "{}{}",
                        left.as_string()?,
                        right.as_string()?
                    )))
                } else {
                    numeric_op(left, right, |a, b| Some(a + b))
                }
            }

            BinOp::Sub => numeric_op(left, right, |a, b| Some(a - b)),

            BinOp::Mul => numeric_op(left, right, |a, b| Some(a * b)),

            // Pine semantics: a zero divisor yields `na`, not an error. Two ints
            // divide as ints (`15 / 2 == 7`); any float operand divides as float.
            BinOp::Div => numeric_op(left, right, Num::checked_div),

            BinOp::Mod => numeric_op(left, right, Num::checked_rem),

            // Pine semantics: a comparison with an `na` operand yields `na`
            // (including `na == na` — testing for na requires the na() function).
            // `is_na_operand` also treats a `Value::Number(NaN)` as na (a
            // computed NaN such as math.sqrt(-1.0), or a ta.* window that
            // returns `Number(NaN)` rather than `Value::Na`). Eq/NotEq must not
            // leak a structural bool through values_equal, otherwise e.g.
            // `dayofweek != dayofweek[1]` evaluates true on the first bar.
            BinOp::Eq => {
                if is_na_operand(left) || is_na_operand(right) {
                    return Ok(Value::Na);
                }
                Ok(Value::Bool(self.values_equal(left, right)?))
            }

            BinOp::NotEq => {
                if is_na_operand(left) || is_na_operand(right) {
                    return Ok(Value::Na);
                }
                Ok(Value::Bool(!self.values_equal(left, right)?))
            }

            // Relational arms need the same guard: to_number() maps `Value::Na`
            // to None (caught by the match) but passes `Number(NaN)` through as
            // Some(NaN), where a raw float comparison yields false — a
            // structural bool that e.g. `not` then flips to true, instead of
            // the `na` TradingView produces.
            BinOp::Less => {
                if is_na_operand(left) || is_na_operand(right) {
                    return Ok(Value::Na);
                }
                match (left.to_number()?, right.to_number()?) {
                    (Some(l), Some(r)) => Ok(Value::Bool(l < r)),
                    _ => Ok(Value::Na),
                }
            }

            BinOp::Greater => {
                if is_na_operand(left) || is_na_operand(right) {
                    return Ok(Value::Na);
                }
                match (left.to_number()?, right.to_number()?) {
                    (Some(l), Some(r)) => Ok(Value::Bool(l > r)),
                    _ => Ok(Value::Na),
                }
            }

            BinOp::LessEq => {
                if is_na_operand(left) || is_na_operand(right) {
                    return Ok(Value::Na);
                }
                match (left.to_number()?, right.to_number()?) {
                    (Some(l), Some(r)) => Ok(Value::Bool(l <= r)),
                    _ => Ok(Value::Na),
                }
            }

            BinOp::GreaterEq => {
                if is_na_operand(left) || is_na_operand(right) {
                    return Ok(Value::Na);
                }
                match (left.to_number()?, right.to_number()?) {
                    (Some(l), Some(r)) => Ok(Value::Bool(l >= r)),
                    _ => Ok(Value::Na),
                }
            }

            // Three-valued logic: false absorbs na; true and na → na.
            BinOp::And => match (left.to_bool()?, right.to_bool()?) {
                (Some(false), _) | (_, Some(false)) => Ok(Value::Bool(false)),
                (Some(true), Some(true)) => Ok(Value::Bool(true)),
                _ => Ok(Value::Na),
            },

            // Three-valued logic: true absorbs na; false or na → na.
            BinOp::Or => match (left.to_bool()?, right.to_bool()?) {
                (Some(true), _) | (_, Some(true)) => Ok(Value::Bool(true)),
                (Some(false), Some(false)) => Ok(Value::Bool(false)),
                _ => Ok(Value::Na),
            },
        }
    }

    fn eval_unary_op(&self, op: &UnOp, val: &Value<O>) -> Result<Value<O>, RuntimeError> {
        match op {
            // Negating an int stays an int.
            UnOp::Neg => match val.as_int() {
                Some(n) => Ok(Value::Int(-n)),
                None => match val.to_number()? {
                    Some(n) => Ok(Value::Number(-n)),
                    None => Ok(Value::Na),
                },
            },
            UnOp::Not => match val.to_bool()? {
                Some(b) => Ok(Value::Bool(!b)),
                None => Ok(Value::Na),
            },
        }
    }

    fn values_equal(&self, left: &Value<O>, right: &Value<O>) -> Result<bool, RuntimeError> {
        match (left, right) {
            (Value::Int(l), Value::Int(r)) => Ok(l == r),
            // int and float compare by value, so `1 == 1.0`.
            (Value::Int(l), Value::Number(r)) | (Value::Number(r), Value::Int(l)) => {
                Ok((*l as f64 - r).abs() < f64::EPSILON)
            }
            (Value::Number(l), Value::Number(r)) => Ok((l - r).abs() < f64::EPSILON),
            (Value::String(l), Value::String(r)) => Ok(l == r),
            (Value::Bool(l), Value::Bool(r)) => Ok(l == r),
            (Value::Na, Value::Na) => Ok(true),
            (
                Value::Enum {
                    enum_name: a_enum,
                    field_name: a_field,
                    ..
                },
                Value::Enum {
                    enum_name: b_enum,
                    field_name: b_field,
                    ..
                },
            ) => Ok(a_enum == b_enum && a_field == b_field),
            _ => Ok(false),
        }
    }

    /// Check if an expression evaluates to a const value
    fn is_const_expr(&self, expr: &Expr) -> bool {
        match expr {
            // Literals are always const
            Expr::Literal(_) => true,
            // Variable is const if it's stored as const
            Expr::Variable { name, .. } => self
                .variables
                .get(name)
                .map(|var| var.is_const)
                .unwrap_or(false),
            // Member access is const if the base object is const
            Expr::MemberAccess { object, .. } => self.is_const_expr(object),
            // All other expressions are not const
            _ => false,
        }
    }

    fn call_user_function(
        &mut self,
        params: &[pine_ast::FunctionParam],
        body: &[Stmt],
        arg_exprs: &[Argument],
        args: Vec<EvaluatedArg<O>>,
        call_id: u32,
    ) -> Result<Value<O>, RuntimeError> {
        // Extract positional arguments (user functions don't support named args yet)
        let mut positional_values = Vec::new();
        let mut positional_exprs = Vec::new();

        for (i, arg) in args.iter().enumerate() {
            match arg {
                EvaluatedArg::Positional(value) => {
                    positional_values.push(value.clone());
                    if let Some(Argument::Positional(expr)) = arg_exprs.get(i) {
                        positional_exprs.push(expr);
                    }
                }
                EvaluatedArg::Named { .. } => {
                    return Err(RuntimeError::TypeError(
                        "User-defined functions do not support named arguments yet".to_string(),
                    ))
                }
            }
        }

        // Check argument count
        if positional_values.len() != params.len() {
            return Err(RuntimeError::TypeError(format!(
                "Expected {} arguments, got {}",
                params.len(),
                positional_values.len()
            )));
        }

        // Validate const parameters receive const arguments
        for (i, param) in params.iter().enumerate() {
            if matches!(param.type_qualifier, Some(pine_ast::TypeQualifier::Const)) {
                if let Some(arg_expr) = positional_exprs.get(i) {
                    if !self.is_const_expr(arg_expr) {
                        return Err(RuntimeError::TypeError(format!(
                            "Parameter '{}' requires a const argument, but received a non-const value",
                            param.name
                        )));
                    }
                }
            }
        }

        // Bind parameters to arguments with the appropriate const flag, then run
        // the body as a stateful call site.
        let param_bindings: Vec<(String, Variable<O>)> = params
            .iter()
            .zip(positional_values)
            .map(|(param, value)| {
                let is_const = matches!(param.type_qualifier, Some(pine_ast::TypeQualifier::Const));
                (
                    param.name.clone(),
                    Variable {
                        value,
                        is_const,
                        is_var_persistent: false,
                    },
                )
            })
            .collect();

        self.run_call_site_body(call_id, param_bindings, body)
    }

    /// Run a user function or method body as a stateful call site: restore this
    /// call site's persisted locals, bind the given parameters, execute the body
    /// under the call site's id (scoping `var` init-once), then persist the call
    /// site's locals and restore the outer scope. Keying state by call site —
    /// not by callable name — keeps two call sites of the same function/method
    /// independent, matching TradingView. A `call_id` of 0 (no stable identity)
    /// is not persisted.
    fn run_call_site_body(
        &mut self,
        call_id: u32,
        param_bindings: Vec<(String, Variable<O>)>,
        body: &[Stmt],
    ) -> Result<Value<O>, RuntimeError> {
        let param_names: std::collections::HashSet<String> =
            param_bindings.iter().map(|(n, _)| n.clone()).collect();

        // Save the outer scope.
        let saved_vars = self.variables.clone();

        // Restore this call site's locals (all locals persist across calls, not
        // just `var`s, so series indexing like `o[1]` works inside the body).
        // Parameters are excluded — they are freshly bound below.
        if call_id != 0 {
            if let Some(local_state) = self.function_local_state.get(&call_id) {
                for (var_name, var) in local_state {
                    if !param_names.contains(var_name) {
                        self.variables.insert(var_name.clone(), var.clone());
                    }
                }
            }
        }

        // Bind parameters (freshly each call).
        for (name, var) in param_bindings {
            self.variables.insert(name, var);
        }

        // Execute the body under this call site's id, so `var` init-once tracking
        // is scoped to the call site. Restored afterwards to support
        // nested/recursive calls. (Like the scope restore below, an error just
        // propagates and aborts the script.)
        let prev_call_id = self.current_call_id;
        self.current_call_id = call_id;
        let mut result: Value<O> = Value::Na;
        for stmt in body {
            if let Some(return_value) = self.execute_stmt(stmt)? {
                result = return_value;
            } else if let Stmt::Expression(expr) = stmt {
                // Last expression is the return value
                result = self.eval_expr(expr)?;
            }
        }
        self.current_call_id = prev_call_id;

        // Restore the outer scope. This call site's locals live only in
        // function_local_state (keyed by call_id) and are NOT leaked into the
        // outer/global scope, so two call sites keep independent state.
        let call_vars = std::mem::replace(&mut self.variables, saved_vars);
        if call_id != 0 {
            // Persist only the names the body actually ASSIGNS — its true locals
            // (both `var` and plain, so their series history advances). The scope
            // also holds read-only builtins/globals inherited from the outer scope
            // (`open`/`high`/`low`/`close`/…); saving one of those would restore it
            // stale on the next call, freezing any indicator that reads it inside
            // the function (e.g. a recursive Heikin-Ashi open).
            let mut assigned: std::collections::HashSet<String> = std::collections::HashSet::new();
            collect_assigned_names(body, &mut assigned);
            let local_state: HashMap<String, Variable<O>> = call_vars
                .into_iter()
                .filter(|(k, _)| !param_names.contains(k) && assigned.contains(k))
                .collect();
            self.function_local_state.insert(call_id, local_state);
        }

        Ok(result)
    }

    /// Get the type name for an object value
    fn get_object_type_name(&self, value: &Value<O>) -> Result<String, RuntimeError> {
        match value {
            Value::Object { type_name, .. } => Ok(type_name.clone()),
            _ => Err(RuntimeError::TypeError(
                "Cannot determine type of non-object value".to_string(),
            )),
        }
    }

    /// Call a method (similar to call_user_function but handles MethodParam with defaults)
    fn call_method(
        &mut self,
        params: &[MethodParam],
        body: &[Stmt],
        args: Vec<EvaluatedArg<O>>,
        call_id: u32,
    ) -> Result<Value<O>, RuntimeError> {
        // Resolve parameter bindings (positional, named, and defaults), then run
        // the body as a stateful call site. Defaults are evaluated in the caller
        // scope, before entering the method's scope.
        let mut positional_idx = 0;
        let mut param_bindings: Vec<(String, Variable<O>)> = Vec::with_capacity(params.len());

        for param in params {
            let param_value = if positional_idx < args.len() {
                match &args[positional_idx] {
                    EvaluatedArg::Positional(value) => {
                        positional_idx += 1;
                        value.clone()
                    }
                    EvaluatedArg::Named { name, value } => {
                        if name == &param.name {
                            positional_idx += 1;
                            value.clone()
                        } else if let Some(default_expr) = &param.default_value {
                            self.eval_expr(default_expr)?
                        } else {
                            Value::Na
                        }
                    }
                }
            } else if let Some(default_expr) = &param.default_value {
                self.eval_expr(default_expr)?
            } else {
                Value::Na
            };

            param_bindings.push((
                param.name.clone(),
                Variable {
                    value: param_value,
                    is_const: false,
                    is_var_persistent: false,
                },
            ));
        }

        self.run_call_site_body(call_id, param_bindings, body)
    }

    /// Create a constructor function for a user-defined type
    fn create_constructor(type_name: String, fields: Vec<TypeField>) -> BuiltinFn<O> {
        Rc::new(
            move |interp: &mut Interpreter<O>, call_args: FunctionCallArgs<O>| {
                let mut instance_fields = HashMap::new();

                // Match arguments to fields
                let mut positional_idx = 0;

                for arg in &call_args.args {
                    match arg {
                        EvaluatedArg::Positional(value) => {
                            // Assign to field by position
                            if positional_idx < fields.len() {
                                let field = &fields[positional_idx];
                                instance_fields.insert(field.name.clone(), value.clone());
                                positional_idx += 1;
                            } else {
                                return Err(RuntimeError::TypeError(format!(
                                    "Too many arguments for type '{}' (expected {} fields)",
                                    type_name,
                                    fields.len()
                                )));
                            }
                        }
                        EvaluatedArg::Named { name, value } => {
                            // Find field by name
                            if let Some(field) = fields.iter().find(|f| f.name == *name) {
                                instance_fields.insert(field.name.clone(), value.clone());
                            } else {
                                return Err(RuntimeError::TypeError(format!(
                                    "Type '{}' has no field '{}'",
                                    type_name, name
                                )));
                            }
                        }
                    }
                }

                // Fill in defaults for missing fields
                for field in &fields {
                    if !instance_fields.contains_key(&field.name) {
                        if let Some(default_expr) = &field.default_value {
                            let default_val = interp.eval_expr(default_expr)?;
                            instance_fields.insert(field.name.clone(), default_val);
                        } else {
                            // Field has no default and wasn't provided
                            instance_fields.insert(field.name.clone(), Value::Na);
                        }
                    }
                }

                Ok(Value::Object {
                    type_name: type_name.clone(),
                    fields: Rc::new(RefCell::new(instance_fields)),
                    call: None,
                })
            },
        )
    }

    /// Creates a copy function for types that takes an object and returns a shallow copy
    fn create_copy_function() -> BuiltinFn<O> {
        Rc::new(
            |_interp: &mut Interpreter<O>, call_args: FunctionCallArgs<O>| {
                // Expect exactly one positional argument (the object to copy)
                if call_args.args.len() != 1 {
                    return Err(RuntimeError::TypeError(
                        "copy() expects exactly one argument".to_string(),
                    ));
                }

                match &call_args.args[0] {
                    EvaluatedArg::Positional(value) => {
                        if let Value::Object {
                            type_name,
                            fields,
                            call,
                        } = value
                        {
                            // Create a shallow copy of the object's fields
                            let obj = fields.borrow();
                            let copied_fields = obj.clone();
                            Ok(Value::Object {
                                type_name: type_name.clone(),
                                fields: Rc::new(RefCell::new(copied_fields)),
                                call: call.clone(),
                            })
                        } else {
                            Err(RuntimeError::TypeError(
                                "copy() expects an object argument".to_string(),
                            ))
                        }
                    }
                    EvaluatedArg::Named { .. } => Err(RuntimeError::TypeError(
                        "copy() does not accept named arguments".to_string(),
                    )),
                }
            },
        )
    }
}

impl<O: PineOutput> Default for Interpreter<O> {
    fn default() -> Self {
        Self::new()
    }
}