openpine_vm/

instance.rs

use std::collections::HashMap;

use gc_arena::{Arena, CollectionPhase};
use openpine_compiler::{CompileError, loader::LibraryLoader, program::Program};
use openpine_error::ErrorWithSourceFile;
use serde::{Deserialize, Serialize};

use crate::{
    Error, Exception, ExecutionLimits, InputSessions, OutputMode, Series, StrategyState,
    SymbolInfo, TimeFrame,
    bar_state::BarState,
    context::{ExecuteContext, SecurityCapture},
    currency::CurrencyConverter,
    data_provider::InternalProvider,
    events::{BarStartEvent, Event},
    gc_serde::{SerializedObject, SerializedRawValue},
    inst_executor::Interrupt,
    quote_types::{Candlestick, CandlestickItem},
    script_info::ScriptInfo,
    security::{CandlestickBuffer, SecurityLowerTfSubState, SecuritySubState},
    snapshot::save::serialize_value_in_arena,
    state::{ArenaType, State},
    strategy::report::StrategyReport,
    visuals::Chart,
};

const COLLECTOR_GRANULARITY: f64 = 1024.0;

/// Determines how a candlestick is processed by [`Instance::execute()`].
#[derive(Debug, Copy, Clone)]
pub(crate) enum ExecuteMode {
    /// Realtime bar update.
    Realtime(Candlestick),
    /// Confirmed (historical) bar execution.
    Confirmed(Candlestick),
    /// Confirms the last realtime bar.
    Confirm,
}

/// The last information about the input candlesticks.
/// Metadata about the last available input bar.
#[derive(Debug, Copy, Clone, Serialize, Deserialize)]
pub struct LastInfo {
    /// The index of the last candlestick (base 0).
    pub index: usize,
    /// The time of the last candlestick (in milliseconds since UNIX epoch).
    pub time: i64,
}

impl LastInfo {
    /// Creates a new `LastInfo`.
    #[inline]
    pub const fn new(index: usize, time: i64) -> Self {
        Self { index, time }
    }
}

/// An instance used to execute a compiled program.
pub struct Instance {
    pub(crate) program: Program,
    pub(crate) arena: ArenaType,
    pub(crate) timeframe: TimeFrame,
    pub(crate) symbol_info: SymbolInfo,
    pub(crate) candlesticks: Series<Candlestick>,
    pub(crate) last_info: Option<LastInfo>,
    pub(crate) bar_index: usize,
    pub(crate) input_index: usize,
    pub(crate) script_info: ScriptInfo,
    pub(crate) chart: Chart,
    pub(crate) events: Vec<Event>,
    pub(crate) input_sessions: InputSessions,
    pub(crate) strategy_state: Option<Box<StrategyState>>,
    pub(crate) currency_converter: Box<dyn CurrencyConverter>,
    pub(crate) execution_limits: ExecutionLimits,
    /// Provider for symbol metadata and `request.security()` data.
    pub(crate) data_provider: Option<Box<dyn InternalProvider>>,
    /// Shared candlestick buffers keyed by symbol then timeframe.
    pub(crate) candlestick_buffers: HashMap<String, HashMap<TimeFrame, CandlestickBuffer>>,
    /// Per-call-site execution states for `request.security()`.
    pub(crate) security_sub_states: HashMap<usize, Box<SecuritySubState>>,
    /// Per-call-site execution states for `request.security_lower_tf()`.
    pub(crate) security_lower_tf_sub_states: HashMap<usize, Box<SecurityLowerTfSubState>>,
    /// Whether the last executed bar has been confirmed.
    ///
    /// History bars are always confirmed immediately after execution.
    /// A realtime bar becomes confirmed only after `RealtimeConfirmed` runs
    /// (either explicitly via [`ExecuteMode::Confirm`] or automatically when
    /// a new realtime timestamp arrives). This flag prevents the auto-confirm
    /// step from firing — and using an already-advanced `bar_index` — after
    /// a sequence of confirmed bars.
    pub(crate) last_bar_confirmed: bool,
    /// Pending security capture set by `execute_security_bar`.
    ///
    /// `do_execute` reads this instead of a hardcoded `None` so that
    /// sub-instance executions triggered by `request.security()` can capture
    /// their expression value without going through the full `execute()` path.
    pub(crate) pending_security_capture: Option<SecurityCapture>,
    /// Controls whether series graph data is written to the chart or emitted
    /// as [`DrawEvent`](crate::DrawEvent) events.
    pub(crate) output_mode: OutputMode,
}

impl Instance {
    /// Returns the warnings generated during compilation.
    #[inline]
    pub fn warnings(&self) -> &[CompileError] {
        self.program.warnings()
    }

    fn gc_collect(&mut self) {
        if self.arena.metrics().allocation_debt() > COLLECTOR_GRANULARITY {
            if self.arena.collection_phase() == CollectionPhase::Collecting {
                self.arena.collect_debt();
            } else {
                self.arena.mark_debt();
            }
        }
    }

    /// Emits a `BarStart` event using the current candlestick's timestamp.
    fn emit_bar_start(&mut self, bar_state: BarState) {
        let timestamp = self.candlesticks.last().map(|c| c.time).unwrap_or_default();
        self.emit_bar_start_with_timestamp(bar_state, timestamp);
    }

    /// Emits a `BarStart` event with an explicit timestamp.
    fn emit_bar_start_with_timestamp(&mut self, bar_state: BarState, timestamp: i64) {
        self.events.push(Event::BarStart(BarStartEvent {
            bar_index: self.bar_index,
            timestamp,
            bar_state,
        }));
    }

    pub(crate) fn before_execute(&mut self, bar_state: BarState) {
        match bar_state {
            BarState::RealtimeNew => {
                self.arena.mutate_root(|_, state| {
                    for variable_value in state.variables.iter_mut() {
                        variable_value.append_new();
                    }
                });
                self.candlesticks.append_new();
                self.chart.append_new();
            }
            BarState::RealtimeUpdate => {
                self.arena
                    .mutate_root(|_, state| state.do_rollback_actions(&mut self.chart));
            }
            BarState::History => {
                self.arena.mutate_root(|_, state| {
                    for variable_value in state.variables.iter_mut() {
                        variable_value.append_new();
                    }
                    state.rollback_actions.clear();
                });
                self.candlesticks.append_new();
                self.chart.append_new();
            }
            BarState::RealtimeConfirmed => self
                .arena
                .mutate_root(|_, state| state.do_rollback_actions(&mut self.chart)),
        }
    }

    pub(crate) fn after_execute(&mut self, bar_state: BarState) {
        match bar_state {
            BarState::History => {
                self.bar_index += 1;
                self.input_index += 1;
                self.last_bar_confirmed = true;
            }
            BarState::RealtimeNew | BarState::RealtimeUpdate => {
                self.input_index += 1;
                self.last_bar_confirmed = false;
            }
            BarState::RealtimeConfirmed => {
                self.bar_index += 1;
                self.last_bar_confirmed = true;
            }
        }
    }

    fn process_strategy(&mut self) {
        if let Some(strategy_state) = &mut self.strategy_state {
            strategy_state.step(&self.candlesticks[self.bar_index]);
            strategy_state.process_pending_orders(&mut self.chart, self.bar_index);
            strategy_state.process_exit_orders(&mut self.chart, self.bar_index);
            strategy_state.check_margin_call(&mut self.chart, self.bar_index);
            strategy_state.step_update_trades();
            strategy_state.update_equity_extremes();
            strategy_state.record_equity_curve();
            strategy_state.check_risk_limits(&mut self.chart, self.bar_index);
        }
    }

    /// When `process_orders_on_close = true`, fills any pending orders placed
    /// during `do_execute()` at the current bar's close price and updates
    /// equity extremes accordingly.
    fn process_strategy_on_close(&mut self) {
        if let Some(strategy_state) = &mut self.strategy_state
            && strategy_state.should_process_on_close()
        {
            strategy_state.process_pending_orders_on_close(&mut self.chart, self.bar_index);
            strategy_state.update_equity_extremes();
            strategy_state.check_risk_limits(&mut self.chart, self.bar_index);
            strategy_state.clear_immediate_flag();
        }
    }

    /// When `calc_on_order_fills` is enabled, simulates intrabar ticks
    /// (O, H, L, C or O, L, H, C) and re-executes the script whenever an
    /// order fills at a tick. Each re-execution rolls back variable state
    /// (like a realtime update) so the script sees the updated strategy
    /// state. Up to 3 re-executions per bar (4 total including the initial).
    async fn process_intrabar_fills(&mut self, bar_state: BarState) -> Result<(), Error> {
        let should = self
            .strategy_state
            .as_ref()
            .is_some_and(|s| s.should_calc_on_order_fills());
        if !should {
            return Ok(());
        }

        let tick_prices = self.strategy_state.as_ref().unwrap().intrabar_tick_prices();

        // We allow up to 3 re-executions (ticks after the first one can
        // trigger fills). The first tick (open) is included because the
        // script may have placed new orders during the initial do_execute().
        let max_reexecutions = 3;
        let mut reexecutions = 0;

        for &tick_price in &tick_prices {
            if reexecutions >= max_reexecutions {
                break;
            }

            let had_fill = self
                .strategy_state
                .as_mut()
                .unwrap()
                .process_orders_at_tick(&mut self.chart, self.bar_index, tick_price);

            if had_fill {
                reexecutions += 1;

                // Roll back variable state (same mechanism as RealtimeUpdate)
                // so the script re-executes with updated strategy state.
                self.arena
                    .mutate_root(|_, state| state.do_rollback_actions(&mut self.chart));

                let provider_ptr: Option<*const dyn InternalProvider> =
                    self.data_provider.as_deref().map(|p| p as *const _);
                let provider = provider_ptr.map(|p| unsafe { &*p as &dyn InternalProvider });
                self.do_execute(bar_state, provider, 0).await?;
            }
        }

        Ok(())
    }

    /// Executes the compiled program body for the current bar state.
    ///
    /// Unlike [`execute`](Self::execute), this does **not** update
    /// `bar_index`, run strategy logic, or collect GC debt. It is the raw
    /// execution primitive used by both the public API and by sub-instance
    /// executions for `request.security()`.
    ///
    /// The `security_provider` and `security_depth` parameters are forwarded
    /// into the [`ExecuteContext`] so that nested `request.security()` calls
    /// receive the correct provider and depth guard.
    pub(crate) async fn do_execute(
        &mut self,
        bar_state: BarState,
        security_provider: Option<&dyn InternalProvider>,
        security_depth: usize,
    ) -> Result<(), Error> {
        let execution_limits = self.execution_limits;
        let program = self.program.clone();
        let security_capture = self.pending_security_capture.take();
        let mut ctx = ExecuteContext {
            program: &program,
            arena: &mut self.arena,
            candlesticks: &self.candlesticks,
            last_info: self.last_info.as_ref(),
            bar_state,
            bar_index: self.bar_index,
            input_index: self.input_index,
            partial_script_info: None,
            script_info: Some(&self.script_info),
            chart: &mut self.chart,
            events: &mut self.events,
            current_span: None,
            module_stack: vec![],
            timeframe: &self.timeframe,
            symbol_info: &self.symbol_info,
            input_sessions: self.input_sessions,
            strategy_state: self.strategy_state.as_deref_mut(),
            currency_converter: Some(self.currency_converter.as_ref()),
            loop_iterations_remaining: execution_limits.max_loop_iterations_per_bar,
            security_provider,
            candlestick_buffers: &mut self.candlestick_buffers,
            security_sub_states: &mut self.security_sub_states,
            security_lower_tf_sub_states: &mut self.security_lower_tf_sub_states,
            security_depth,
            execution_limits,
            security_capture,
            output_mode: self.output_mode,
        };
        let res = crate::inst_executor::execute(program.instruction(), &mut ctx).await;
        // Write back the captured result so `execute_security_bar` can read it.
        self.pending_security_capture = ctx.security_capture.take();

        match res {
            Ok(_) => Ok(()),
            Err(Interrupt::RuntimeError { error, backtrace }) => {
                Err(Error::Exception(Exception::new(
                    ErrorWithSourceFile::new(
                        openpine_error::Error::new(vec![error.span], error.value),
                        self.program.source_files().clone(),
                    ),
                    backtrace,
                )))
            }
            Err(_) => unreachable!("Unhandled interrupt in top-level execution"),
        }
    }

    fn check_input_candlestick(&self, candlestick: &Candlestick) -> Result<(), Error> {
        if !self.input_sessions.allow(candlestick.trade_session) {
            return Err(Error::SessionNotAllowed(candlestick.trade_session));
        }
        Ok(())
    }

    /// Executes one step using the given mode and input values.
    ///
    /// For realtime execution this may perform a bar confirmation step when the
    /// incoming candlestick timestamp advances.
    ///
    /// # Execution modes
    ///
    /// - [`ExecuteMode::Confirmed`] — Feed a confirmed (historical) bar. Each
    ///   call advances `bar_index` by one.
    /// - [`ExecuteMode::Realtime`] — Feed a live bar. If the timestamp matches
    ///   the previous bar, it updates in-place; if the timestamp advances, the
    ///   previous bar is confirmed first, then a new bar begins.
    /// - [`ExecuteMode::Confirm`] — Explicitly confirm the current realtime bar
    ///   without providing new data.
    ///
    /// Prefer [`run()`](Self::run) over calling this method directly.
    async fn execute(&mut self, mode: ExecuteMode) -> Result<(), Error> {
        // Use a raw pointer to avoid holding an immutable borrow across mutable
        // method calls.  Safety: `data_provider` outlives all calls within this
        // method and is not replaced during execution.
        let provider_ptr: Option<*const dyn InternalProvider> =
            self.data_provider.as_deref().map(|p| p as *const _);
        let provider = |ptr: Option<*const dyn InternalProvider>| -> Option<&dyn InternalProvider> {
            ptr.map(|p| unsafe { &*p })
        };
        match mode {
            ExecuteMode::Realtime(candlestick) => {
                self.check_input_candlestick(&candlestick)?;

                let bar_state = match self.candlesticks.last() {
                    Some(last_candlestick) if last_candlestick.time == candlestick.time => {
                        BarState::RealtimeUpdate
                    }
                    Some(_) => {
                        // Auto-confirm the previous bar only if it was an open
                        // realtime bar. History bars are already confirmed, so
                        // skipping this step avoids using an out-of-bounds
                        // `bar_index` that was advanced past the last history bar.
                        if !self.last_bar_confirmed {
                            let bar_state = BarState::RealtimeConfirmed;
                            self.emit_bar_start(bar_state);
                            self.before_execute(bar_state);
                            self.process_strategy();
                            self.do_execute(bar_state, provider(provider_ptr), 0)
                                .await?;
                            self.process_strategy_on_close();
                            self.after_execute(bar_state);
                            self.events.push(Event::BarEnd);
                        }
                        BarState::RealtimeNew
                    }
                    None => BarState::RealtimeNew,
                };

                // calculate for new bar
                self.emit_bar_start_with_timestamp(bar_state, candlestick.time);
                self.before_execute(bar_state);
                self.process_strategy();
                self.candlesticks.update(candlestick);
                self.do_execute(bar_state, provider(provider_ptr), 0)
                    .await?;
                self.process_strategy_on_close();
                self.after_execute(bar_state);
                self.events.push(Event::BarEnd);
            }
            ExecuteMode::Confirmed(candlestick) => {
                // calculate for confirmed (historical) bar
                self.check_input_candlestick(&candlestick)?;
                let bar_state = BarState::History;
                self.emit_bar_start_with_timestamp(bar_state, candlestick.time);
                self.before_execute(bar_state);
                self.candlesticks.update(candlestick);
                self.process_strategy();
                self.do_execute(bar_state, provider(provider_ptr), 0)
                    .await?;
                self.process_intrabar_fills(bar_state).await?;
                self.process_strategy_on_close();
                self.after_execute(bar_state);
                self.events.push(Event::BarEnd);
            }
            ExecuteMode::Confirm => {
                // confirm the last realtime bar
                let bar_state = BarState::RealtimeConfirmed;
                self.emit_bar_start(bar_state);
                self.before_execute(bar_state);
                self.process_strategy();
                self.do_execute(bar_state, provider(provider_ptr), 0)
                    .await?;
                self.process_strategy_on_close();
                self.after_execute(bar_state);
                self.events.push(Event::BarEnd);
            }
        }

        self.gc_collect();
        Ok(())
    }

    /// Runs the script against the full candlestick stream supplied by the
    /// injected [`DataProvider`](crate::DataProvider), starting from the
    /// beginning of available data.
    ///
    /// This is equivalent to calling [`run_from`](Self::run_from) with
    /// `from_time = 0`.
    ///
    /// - [`CandlestickItem::Confirmed`](crate::CandlestickItem::Confirmed) —
    ///   advances `bar_index`.
    /// - [`CandlestickItem::Realtime`](crate::CandlestickItem::Realtime) —
    ///   same-timestamp ticks become `RealtimeUpdate` automatically; confirmed
    ///   at stream end.
    /// - [`CandlestickItem::HistoryEnd`](crate::CandlestickItem::HistoryEnd) —
    ///   skipped (internal boundary marker).
    ///
    /// Returns immediately with `Ok(())` if no
    /// [`DataProvider`](crate::DataProvider) was passed to
    /// [`Instance::builder`](crate::Instance::builder).
    /// Returns a stream of events produced by running the script against the
    /// candlestick stream from the injected
    /// [`DataProvider`](crate::DataProvider).
    ///
    /// Equivalent to [`run_from`](Self::run_from) with `from_time = 0`.
    pub fn run(
        &mut self,
        symbol: &str,
        timeframe: TimeFrame,
    ) -> impl futures_util::Stream<Item = Result<Event, Error>> + '_ {
        self.run_from(symbol, timeframe, 0)
    }

    /// Returns a stream of events produced by running the script, starting
    /// at `from_time`.
    ///
    /// Each bar's execution yields [`Event::BarStart`], any log/alert/draw
    /// events, then [`Event::BarEnd`]. The stream yields
    /// [`Event::HistoryEnd`] when the boundary marker is received.
    pub fn run_from(
        &mut self,
        symbol: &str,
        timeframe: TimeFrame,
        from_time: i64,
    ) -> impl futures_util::Stream<Item = Result<Event, Error>> + '_ {
        use futures_util::StreamExt;

        let symbol = symbol.to_owned();
        async_stream::stream! {
            let Some(provider) = self.data_provider.as_deref() else {
                return;
            };
            let mut candlestick_stream = provider.candlesticks(&symbol, timeframe, from_time);
            let mut last_confirmed = true;

            while let Some(result) = candlestick_stream.next().await {
                let item = result.map_err(|e| Error::DataProvider(e.to_string()))?;
                let mode = match item {
                    CandlestickItem::Confirmed(c) => {
                        last_confirmed = true;
                        ExecuteMode::Confirmed(c)
                    }
                    CandlestickItem::Realtime(c) => {
                        last_confirmed = false;
                        ExecuteMode::Realtime(c)
                    }
                    CandlestickItem::HistoryEnd => {
                        yield Ok(Event::HistoryEnd);
                        continue;
                    }
                };
                self.execute(mode).await?;
                for event in self.events.drain(..) {
                    yield Ok(event);
                }
            }

            if !last_confirmed {
                self.execute(ExecuteMode::Confirm).await?;
                for event in self.events.drain(..) {
                    yield Ok(event);
                }
            }
        }
    }

    /// Runs the script to completion, discarding all events.
    ///
    /// This is a convenience wrapper around [`run`](Self::run) for callers
    /// that only need the final [`chart`](Self::chart) state.
    pub async fn run_to_end(&mut self, symbol: &str, timeframe: TimeFrame) -> Result<(), Error> {
        self.run_from_to_end(symbol, timeframe, 0).await
    }

    /// Runs the script to completion starting at `from_time`, discarding all
    /// events.
    pub async fn run_from_to_end(
        &mut self,
        symbol: &str,
        timeframe: TimeFrame,
        from_time: i64,
    ) -> Result<(), Error> {
        use std::pin::pin;

        use futures_util::StreamExt;

        let mut stream = pin!(self.run_from(symbol, timeframe, from_time));
        while let Some(result) = stream.next().await {
            result?;
        }
        Ok(())
    }

    /// Returns a reference to the chart containing the visuals.
    ///
    /// The [`Chart`] holds all plots, lines, labels, boxes, and other visuals
    /// produced by the script. Query it after calling
    /// `execute()`.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # use openpine_vm::*;
    /// # async fn example() {
    /// # let source = "//@version=6\nindicator(\"\")\nplot(close)";
    /// # let provider = Vec::<Candlestick>::new();
    /// # let mut instance = Instance::builder(provider, source, TimeFrame::days(1),
    /// #     "NASDAQ:AAPL").build().await.unwrap();
    /// # instance.run_to_end("NASDAQ:AAPL", TimeFrame::days(1)).await.unwrap();
    /// let chart = instance.chart();
    ///
    /// // Iterate over per-bar series graphs (plot, bgcolor, fill, etc.)
    /// for (id, series_graph) in chart.series_graphs() {
    ///     if let Some(plot) = series_graph.as_plot() {
    ///         println!("Plot '{:?}': {} bars", plot.title, plot.series.len());
    ///     }
    /// }
    ///
    /// // Iterate over non-series graphs (label, line, box, table, etc.)
    /// for (id, graph) in chart.graphs() {
    ///     if let Some(label) = graph.as_label() {
    ///         println!("Label at ({}, {}): {:?}", label.x, label.y, label.text);
    ///     }
    /// }
    /// # }
    /// ```
    #[inline]
    pub fn chart(&self) -> &Chart {
        &self.chart
    }

    /// Returns a reference to the script info (script type, inputs, etc.).
    #[inline]
    pub fn script_info(&self) -> &ScriptInfo {
        &self.script_info
    }

    /// Returns a reference to the candlestick series accumulated during
    /// execution.
    #[inline]
    pub fn candlesticks(&self) -> &Series<Candlestick> {
        &self.candlesticks
    }

    /// Returns the strategy backtest report, or `None` if the script is
    /// not a strategy.
    pub fn strategy_report(&self) -> Option<StrategyReport> {
        self.strategy_state.as_ref().map(|s| s.to_report())
    }

    /// Consumes the instance and returns the chart data.
    ///
    /// This avoids cloning the chart when the instance is no longer needed
    /// (e.g. in a WASM playground that only needs the chart for rendering).
    #[inline]
    pub fn into_chart(self) -> Chart {
        self.chart
    }

    /// Creates a sub-instance for `request.security()` expression evaluation.
    ///
    /// The sub-instance shares the compiled program but has its own GC arena,
    /// candlestick series, and chart (for isolation). No strategy state.
    pub(crate) fn new_for_security(
        program: Program,
        timeframe: TimeFrame,
        symbol_info: SymbolInfo,
        script_info: ScriptInfo,
        execution_limits: ExecutionLimits,
        currency_converter: Box<dyn CurrencyConverter>,
    ) -> Self {
        let arena = Arena::new(|mc| State::new(mc, &program, Some(&script_info)));
        Instance {
            program,
            arena,
            timeframe,
            symbol_info,
            candlesticks: Series::new(),
            last_info: None,
            bar_index: 0,
            input_index: 0,
            script_info,
            chart: Chart::default(),
            events: Vec::new(),
            input_sessions: InputSessions::ALL,
            strategy_state: None,
            currency_converter,
            execution_limits,
            data_provider: None,
            candlestick_buffers: HashMap::new(),
            security_sub_states: HashMap::new(),
            security_lower_tf_sub_states: HashMap::new(),
            last_bar_confirmed: true,
            pending_security_capture: None,

            output_mode: OutputMode::default(),
        }
    }

    /// Executes the full program body for the given MTF bar in capture mode,
    /// returning the value produced by the `request.security` call identified
    /// by `call_key`.
    ///
    /// Unlike the previous instruction-block approach, this runs the complete
    /// program so that `var`/`varip` state is correctly accumulated before the
    /// expression is evaluated.  When the matching `request.security` call is
    /// reached during execution, `request_security` stores the expression
    /// value in `ExecuteContext::security_capture` and returns `NA`; all other
    /// `request.security` calls also return `NA` to prevent recursion.
    ///
    /// `bar_state` must be computed by the caller (`request_security.rs`)
    /// based on whether this is a confirmed, new-realtime, or
    /// update-realtime execution.
    ///
    /// Returns the captured value (serialised for arena-independence) together
    /// with its object table.
    #[allow(clippy::too_many_arguments)]
    pub(crate) async fn execute_security_bar(
        &mut self,
        bar: Candlestick,
        bar_state: BarState,
        call_key: usize,
        return_type: &openpine_compiler::instructions::TypeDescriptor,
        security_depth: usize,
        _execution_limits: ExecutionLimits,
        provider: Option<&dyn InternalProvider>,
    ) -> Result<(SerializedRawValue, Vec<SerializedObject>), Error> {
        use crate::raw_value::RawValue;

        self.before_execute(bar_state);
        self.candlesticks.update(bar);

        self.pending_security_capture = Some(SecurityCapture {
            call_key,
            result: None,
        });

        self.do_execute(bar_state, provider, security_depth).await?;

        self.after_execute(bar_state);

        // Retrieve the captured result written back by do_execute.
        let captured = self.pending_security_capture.take().and_then(|c| c.result);

        // `return_type` is `TypeDescriptor` for `instructions<T>`, so extract
        // the inner type `T` to determine whether the result value is a
        // reference type and to pass the correct descriptor to the serializer.
        let inner_type = return_type.instructions_return_type().into_owned();
        let is_ref = inner_type.is_reference_type();
        let raw_value = captured.unwrap_or(RawValue::NA);
        let serialized = serialize_value_in_arena(&mut self.arena, raw_value, is_ref, &inner_type);
        Ok(serialized)
    }
}

pub(crate) fn builtins_loader() -> impl LibraryLoader {
    openpine_builtins::builtins_loader()
}

pub(crate) fn builtins_load_options() -> openpine_compiler::loader::LoadOptions {
    openpine_builtins::load_options()
}