pine_security_eval.cpp

Go to the documentation of this file.

#include <pineforge/source/pine_strategy_host.hpp>
/*
 * pine_security_eval.cpp — Pine's request.security evaluator semantics
 *
 * The kernel owns the higher-timeframe feed store and its routing: the
 * evaluator registry, the timeframe aggregator, the native feed store, the
 * dispatch into evaluate_security(). What TradingView does with a completed
 * or in-progress bucket -- barmerge.lookahead / barmerge.gaps publication,
 * ticker.heikinashi substitution, the range-start warmup, the historical
 * lookahead projection, request.security_lower_tf emulation, the calling
 * chart bar's publication boundary -- is this source host's, composed here
 * around the kernel's primitives.
 */
 
#include "../engine_internal.hpp"
#include "../native_execution_consumer.hpp"
#include "pine_run_failure.hpp"
 
#include <pineforge/ta.hpp>
#include <pineforge/timeframe.hpp>
 
#include <algorithm>
#include <cmath>
#include <iterator>
#include <limits>
#include <stdexcept>
#include <string>
#include <utility>
 
namespace pineforge {
 
using namespace internal;
 
namespace {
 
// The request door owns literal parse failures. Catch only the numeric
// parser's failures here; registration and other arguments keep their codes.
int request_timeframe_seconds(const std::string& tf, bool lower_tf_array_requested) {
    int requested_seconds = 0;
    try {
        requested_seconds = tf_to_seconds(tf);
    } catch (const std::invalid_argument&) {
        // Refuse the unparseable request below.
    } catch (const std::out_of_range&) {
        // Refuse the unrepresentable request below.
    }
    // Calendar month has no fixed second count: -1 is its parsed marker,
    // valid for scalar HTF requests but never for the intrabar array API.
    const bool is_calendar_month = requested_seconds == -1 && !lower_tf_array_requested;
    if (requested_seconds <= 0 && !is_calendar_month) {
        const char* api = lower_tf_array_requested
            ? "request.security_lower_tf" : "request.security";
        throw coded<std::runtime_error>(
            RunFailureCode::request_timeframe_invalid, {{"api", api}},
            std::string(api) + ": invalid timeframe literal '" + tf + "'"
        );
    }
    return requested_seconds;
}
 
// TradingView's request.security_lower_tf accepts only the default merge
// flags: lookahead_on and gaps_on are refused at validation. This is a rule
// of the source language, not of the kernel's sub-bar synthesis, so it lives
// here beside the evaluator that applies it (the source-runtime extraction: it used to be
// internal::ensure_supported_lower_tf_emulation_flags in engine_lower_tf.cpp;
// the message and the refusal are unchanged).
void ensure_supported_lower_tf_emulation_flags(bool lookahead_on, bool gaps_on) {
    if (lookahead_on || gaps_on) {
        throw coded<std::runtime_error>(
            RunFailureCode::request_unsupported, {{"reason", "lower_tf_lookahead_or_gaps"}},
            "request.security lower TF emulation only supports lookahead=barmerge.lookahead_off and gaps=barmerge.gaps_off"
        );
    }
}
 
}  // namespace
 
 
// --- register_security_eval ---
void source::PineStrategyHost::register_security_eval(
        int sec_id, const std::string& requested_tf, const std::string& input_tf,
        bool lookahead_on, bool gaps_on, bool heikinashi) {
    const std::string& evaluator_input_tf =
        security_input_tf_.empty() ? input_tf : security_input_tf_;
    // Match the kernel's parse condition. With no input yet, validation
    // remains deferred; an empty request retains its existing passthrough.
    if (!evaluator_input_tf.empty() && !requested_tf.empty()) {
        request_timeframe_seconds(requested_tf, false);
    }
    const std::size_t before = security_eval_states_.size();
    // Generated configure_security_evaluators() opens with
    // security_eval_states_.clear(): the first site registered into an empty
    // registry starts this host's per-site table over with it.
    if (before == 0) pine_security_states_.clear();
    BacktestEngine::register_security_eval(sec_id, requested_tf, input_tf);
    if (security_eval_states_.size() <= before) return;
    SecurityEvalState& state = security_eval_states_.back();
    PineSecurityEvalState& pine = pine_security_states_[sec_id];
    pine = PineSecurityEvalState{};
    pine.gaps_on = gaps_on;
    pine.lookahead_on = lookahead_on;
    pine.heikinashi = heikinashi;
 
    if (evaluator_input_tf.empty()) return;
    int lower_ratio = 0;
    int lower_seconds = 0;
    if (supports_lower_tf_emulation(evaluator_input_tf, requested_tf,
                                    &lower_ratio, &lower_seconds)) {
        // Registration precedes the final input-timeframe validation and
        // cannot yet distinguish request.security_lower_tf from a plain
        // request.security evaluator. The latter retains its own
        // lookahead/gaps contract, so the lower-TF-array restriction is
        // applied only after that identity is known below.
        pine.lower_tf_requested = true;
        pine.lower_tf_emulation = true;
        pine.lower_tf_ratio = lower_ratio;
        pine.lower_tf_seconds = lower_seconds;
        // A lower-timeframe site synthesizes its sub-bars; it has no
        // aggregator of its own.
        state.aggregator = TimeframeAggregator();
    }
}
 
 
// --- register_security_lower_tf_eval ---
// ``request.security_lower_tf`` is a strict subset of ``request.security``:
// the requested TF must be finer than the chart's input TF and lookahead /
// gaps are pinned off (TV does not expose them on this builtin). We reuse
// the existing eval-state plumbing and set ``lower_tf_array_requested``
// so ``validate_security_timeframes`` can produce a precise diagnostic
// when the chart's input TF makes lower-TF emulation impossible.
void source::PineStrategyHost::register_security_lower_tf_eval(
    int sec_id,
    const std::string& requested_tf,
    const std::string& input_tf
) {
    const std::string& evaluator_input_tf =
        security_input_tf_.empty() ? input_tf : security_input_tf_;
    // The lower-TF door must own a malformed literal before delegating to
    // scalar registration, which does not yet know this site's array API.
    if (!evaluator_input_tf.empty() && !requested_tf.empty()) {
        request_timeframe_seconds(requested_tf, true);
    }
    auto before = security_eval_states_.size();
    register_security_eval(sec_id, requested_tf, input_tf, false, false);
    if (security_eval_states_.size() > before) {
        pine_security_state(sec_id).lower_tf_array_requested = true;
    }
}
 
 
bool source::PineStrategyHost::security_series_slot_is_new(int sec_id) const noexcept {
    if (security_history_publication_replay_) {
        return false;
    }
    for (const auto& state : security_eval_states_) {
        if (state.sec_id != sec_id) {
            continue;
        }
        const auto pine = pine_security_states_.find(sec_id);
        const bool lookahead_on =
            pine != pine_security_states_.end() && pine->second.lookahead_on;
        return !lookahead_on || state.current_sub_bar_count <= 1;
    }
    return true;
}
 
 
int source::PineStrategyHost::security_lower_tf_sub_bar_index(int sec_id) const {
    for (const auto& state : security_eval_states_) {
        if (state.sec_id == sec_id) {
            return pine_security_state(sec_id).lower_tf_sub_bar_index;
        }
    }
    return 0;
}
 
 
void source::PineStrategyHost::prune_pine_security_states() {
    for (auto it = pine_security_states_.begin(); it != pine_security_states_.end();) {
        bool registered = false;
        for (const auto& state : security_eval_states_) {
            if (state.sec_id == it->first) {
                registered = true;
                break;
            }
        }
        it = registered ? std::next(it) : pine_security_states_.erase(it);
    }
}
 
 
// Safe wrapper around tf_to_seconds: returns <=0 on any parse failure
// (including std::invalid_argument from stoi on garbage like "abc").
// We use this instead of letting stoi escape so we can attach the
// offending literal to the diagnostic.
static int safe_tf_to_seconds(const std::string& tf) {
    try {
        return tf_to_seconds(tf);
    } catch (...) {
        return 0;
    }
}
 
void source::PineStrategyHost::validate_security_timeframes(const std::string& input_tf) {
    if (input_tf.empty()) {
        if (!security_eval_states_.empty()) {
            throw coded<std::runtime_error>(
                RunFailureCode::run_options_rejected, {{"option", "input_timeframe"}},
                "request.security cannot infer input timeframe from available input bars; pass input_tf explicitly"
            );
        }
        return;
    }
 
    // Note: script_tf >= input_tf is enforced separately in
    // BacktestEngine::run() (see engine_run.cpp ~line 199), which throws
    // "script timeframe must be coarser than or equal to input timeframe"
    // when the script_tf/input_tf ratio is invalid. We do not re-check
    // that invariant here.
    int input_seconds = tf_to_seconds(input_tf);
    int script_seconds = script_tf_seconds_;
    for (auto& state : security_eval_states_) {
        PineSecurityEvalState& pine = pine_security_state(state.sec_id);
        pine.lower_tf_requested = false;
        pine.lower_tf_emulation = false;
        pine.lower_tf_ratio = 0;
        pine.lower_tf_seconds = 0;
        pine.lower_tf_use_input = false;
        pine.lower_tf_input_aggregation_ratio = 1;
        pine.lower_tf_input_buffer.clear();
        pine.publish_gate_tf_seconds = 0;
        pine.calling_close_completes_partial = false;
        pine.no_loaded_bars = false;
        pine.calling_open_latches_first = false;
        pine.first_bucket_published = false;
        pine.deferred_aux.clear();
        if (state.tf.empty()) continue;
 
        // Deferred requests must also be checked before the emulation
        // predicate can parse their timeframe.
        const int requested_seconds =
            request_timeframe_seconds(state.tf, pine.lower_tf_array_requested);
        const bool is_calendar_month = requested_seconds == -1;
        int lower_ratio = 0;
        int lower_seconds = 0;
        bool ltf_supported = supports_lower_tf_emulation(
            input_tf, state.tf, &lower_ratio, &lower_seconds);
        if (ltf_supported && pine.lower_tf_array_requested) {
            // Only request.security_lower_tf may opt into LTF emulation.
            // Scalar request.security remains a validate-time refusal even
            // when registration recognized an integer-divisor lower TF.
            pine.lower_tf_requested = true;
            ensure_supported_lower_tf_emulation_flags(pine.lookahead_on, pine.gaps_on);
            pine.lower_tf_emulation = true;
            pine.lower_tf_ratio = lower_ratio;
            pine.lower_tf_seconds = lower_seconds;
            continue;
        }
 
        if (!is_calendar_month && requested_seconds < input_seconds) {
            // Finer than input — only valid for security_lower_tf with
            // an integer divisor ratio.
            if (!pine.lower_tf_array_requested) {
                // The host already supplied bars finer than the chart (the
                // auxiliary slice, or an input finer than the script TF), so
                // nothing finer is loaded: the site reads na on every chart
                // bar, TradingView's reading of a chart bar holding no loaded
                // bar of the requested timeframe (see no_loaded_bars). A chart
                // fed without intrabar bars keeps the refusal below, which
                // asks its host for finer bars.
                const bool intrabar_bars_supplied = input_seconds > 0
                    && (script_seconds == -1 || input_seconds < script_seconds);
                if (intrabar_bars_supplied) {
                    pine.no_loaded_bars = true;
                    continue;
                }
                throw coded<std::runtime_error>(
                    RunFailureCode::request_timeframe_unsupported,
                    {{"reason", "finer_than_input"}, {"input_tf", input_tf}},
                    "request.security: requested timeframe '" + state.tf
                    + "' is finer than input '" + input_tf
                    + "'. Use request.security_lower_tf for sub-input timeframes."
                );
            }
            // LTF case: must be an exact integer divisor.
            if (input_seconds % requested_seconds != 0) {
                throw coded<std::runtime_error>(
                    RunFailureCode::request_timeframe_unsupported,
                    {{"reason", "lower_tf_not_divisor_of_input"}, {"input_tf", input_tf}},
                    "request.security_lower_tf: requested timeframe '" + state.tf
                    + "' is not an integer divisor of input '" + input_tf
                    + "' (ratio " + std::to_string(
                        static_cast<double>(input_seconds) / requested_seconds)
                    + " is non-integer; chart bars cannot be evenly subdivided)"
                );
            }
            // Defensive: integer-ratio finer LTF should already have been
            // accepted by supports_lower_tf_emulation above. Reaching
            // here implies a mismatch between the two checks (e.g. a
            // non-fixed-intraday TF on one side).
            throw coded<std::runtime_error>(
                RunFailureCode::engine_invariant, {},
                "request.security_lower_tf: internal error - passed integer-ratio check but emulation support returned false (requested '"
                + state.tf + "', input '" + input_tf + "')"
            );
        }
 
        // requested_seconds >= input_seconds: HTF or same TF. Valid for
        // request.security; for request.security_lower_tf this is the
        // input-passthrough path when the requested TF is also strictly
        // finer than the script TF.
        if (pine.lower_tf_array_requested) {
            if (script_seconds <= 0) {
                throw coded<std::runtime_error>(
                    RunFailureCode::request_timeframe_unsupported,
                    {{"reason", "lower_tf_script_unknown"}},
                    "request.security_lower_tf: script timeframe is unknown — cannot validate '"
                    + state.tf + "' against script TF"
                );
            }
            if (requested_seconds >= script_seconds) {
                throw coded<std::runtime_error>(
                    RunFailureCode::request_timeframe_unsupported,
                    {{"reason", "lower_tf_not_finer_than_script"}, {"script_tf", script_tf_}},
                    "request.security_lower_tf: requested timeframe '" + state.tf
                    + "' must be finer than script timeframe '" + script_tf_
                    + "'. Lower-TF API requires a strictly finer timeframe."
                );
            }
            if (script_seconds % requested_seconds != 0) {
                throw coded<std::runtime_error>(
                    RunFailureCode::request_timeframe_unsupported,
                    {{"reason", "lower_tf_not_divisor_of_script"}, {"script_tf", script_tf_}},
                    "request.security_lower_tf: requested timeframe '" + state.tf
                    + "' must evenly divide script timeframe '"
                    + script_tf_ + "' (script_tf must be an integer multiple of requested TF)"
                );
            }
            if (requested_seconds % input_seconds != 0) {
                throw coded<std::runtime_error>(
                    RunFailureCode::request_timeframe_unsupported,
                    {{"reason", "lower_tf_not_multiple_of_input"}, {"input_tf", input_tf}},
                    "request.security_lower_tf: requested timeframe '" + state.tf
                    + "' is not an integer multiple of input '" + input_tf
                    + "' (cannot aggregate raw input bars to requested TF)"
                );
            }
            pine.lower_tf_requested = true;
            pine.lower_tf_use_input = true;
            pine.lower_tf_input_aggregation_ratio =
                requested_seconds / input_seconds;
            pine.lower_tf_ratio = script_seconds / requested_seconds;
            pine.lower_tf_seconds = requested_seconds;
        } else if (!is_calendar_month && pine.lookahead_on
                   && script_seconds > 0
                   && requested_seconds < script_seconds
                   && script_seconds % requested_seconds == 0) {
            // Plain request.security with a target TF finer than the
            // script/chart TF (e.g. so2TF="5" on a 15m chart) and
            // lookahead=barmerge.lookahead_ON: TradingView merges the
            // FIRST intrabar of each calling bar, so a history-offset
            // read (``expr[1]``) must expose the value confirmed as of
            // the PREVIOUS calling bar's boundary, not whatever native
            // sub-period last completed inside the CURRENT calling bar.
            // Gate publication (see feed_security_eval_state) to only
            // the completion whose bucket end aligns with a script_tf
            // boundary.
            //
            // lookahead_OFF is deliberately EXCLUDED: TV's lookahead_off
            // merge takes the LAST intrabar of the calling bar, so the
            // exposed value (and any ``[k]`` offset off it) advances at
            // the security's own finer cadence — one push per completed
            // security period, exactly the ungated behavior. Gating it
            // regressed the multi-timeframe scoring probe
            // (request.security(sym, "5", ta.highest(high, 20)[1],
            // barmerge.gaps_off, barmerge.lookahead_off) on a 15m chart)
            // from 100.0% to 93.7% trade parity vs TradingView, while
            // the gated lookahead_on case (the triple-RSI DCA probe,
            // so2Rsi = request.security(sym, "5", ta.rsi(close,7)[1],
            // lookahead=barmerge.lookahead_on)) needs the latch to hold
            // 100.0%.
            pine.publish_gate_tf_seconds = requested_seconds;
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
            // Served by the auxiliary finer feed (the split-feed path every
            // @1D lane runs): TradingView reads the calling bar's FIRST
            // intrabar, so the evaluator publishes every completed bucket
            // and the chart body runs right after the first one of its
            // slice (feed_aux_security_for_chart_bar defers the rest) --
            // see calling_open_latches_first. The gate served the legacy
            // single-feed loop and stays there.
            if (aux_security_feed_enabled()) {
                pine.publish_gate_tf_seconds = 0;
                pine.calling_open_latches_first = true;
            }
#endif
        }
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
        else if (!is_calendar_month && !pine.lookahead_on
                 && aux_security_feed_enabled()
                 && script_seconds > 0
                 && requested_seconds < script_seconds) {
            // Plain request.security, lookahead_OFF, target TF strictly
            // finer than the script/chart TF, served by the auxiliary finer
            // feed: TV's merge takes the LAST intrabar of the calling bar,
            // whatever its sub-bar count -- see the field's note. The
            // aggregator's own completions stay ungated (the multi-timeframe scoring probe above);
            // only a bucket still partial on the calling bar's last
            // auxiliary bar is finalized and published there.
            pine.calling_close_completes_partial = true;
        }
#endif
    }
}
 
 
void source::PineStrategyHost::publish_security_eval_state_at_calling_boundary(
        SecurityEvalState& state) {
    if (pine_security_state(state.sec_id).publish_gate_tf_seconds <= 0
            || state.feed_count <= 0) {
        return;
    }
 
    struct ReplayScope {
        bool& active;
        bool previous;
        explicit ReplayScope(bool& flag)
            : active(flag), previous(flag) { active = true; }
        ~ReplayScope() { active = previous; }
    } replay_scope(security_history_publication_replay_);
 
    // The boundary-triggering input belongs to the next calling bar. Publish
    // the final requested value that was already evaluated for the completed
    // caller, before the chart body runs and before that retained input is fed.
    // security_series_slot_is_new() returns false in this scope, so generated
    // TA sites recompute the current slot instead of advancing their cadence —
    // under the same requested-context bar index as the evaluation replayed.
    dispatch_security_eval(state, state.current_bar, true,
                           state.ta_bar_index >= 0 ? state.ta_bar_index
                                                   : state.eval_complete_count);
}
 
 
bool source::PineStrategyHost::security_input_precedes_range_start(
        const SecurityEvalState& state, int64_t input_ts) const {
    const PineSecurityEvalState& pine = pine_security_state(state.sec_id);
    if (security_range_start_na_warmup_) {
        // TradingView's deep-backtest request.security series are built from the
        // HTF bars whose OPEN lies inside the loaded chart range: a bucket that
        // opened before the range start is not a partial first bar, it is absent.
        // Keying the cut on the bucket open (session_period_open_ms for D/W/M,
        // the session-anchored intraday grid otherwise) reproduces that; keying
        // on the input timestamp would let the pre-range remainder of that bucket
        // pose as HTF bar 1 and shift every SMA-seeded EMA/RSI/ATR/Stoch by one
        // bucket (OANDA:EURUSD 1700-1700: the week opening Sun 17:00 ET before
        // the range start, the month opening Feb 28 17:00 ET before it). With a
        // range start on the bucket grid — 24x7 UTC midnight for every intraday
        // TF and D, Monday for W, the 1st for M — this is the timestamp cut.
        // Lower-TF (passthrough) evaluators keep the timestamp cut exactly.
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
        // A strictly-coarser-than-chart calendar evaluator whose partition is
        // the chart's own dailies (a "W" / "M" on a 1D chart: the implicit
        // native feed of prepare_native_security_feeds, which begins at the
        // range start) labels the bucket in progress at the epoch by its
        // first IN-RANGE stamp -- Tue 2025-04-01 for the week that opened Mon
        // 03-31 -- so the bucket-open cut above keeps it as bar 0 and every
        // SMA-seeded weekly EMA runs one bar early (round 8, family P:
        // the weekly MACD probe on BINANCE:BTCUSDT 1D under the ladder's
        // range-start-na-warmup candidate, lab tv famp-sense-hp-btc1d
        // 2026-09-05: TradingView's weekly EMA26 first reads on the 09-29
        // week and its signal EMA9 on the 11-24 week -- weekly bar 0 is the
        // 04-07 week -- while the engine's read one week earlier; on the
        // 11-24 week TradingView's hist[1] is still na (score -6) where the
        // engine's is numeric (score -10), and the 11-25 reversal waited for
        // 11-28). TradingView's rule is the default path's: the bucket is
        // absent iff its NOMINAL open precedes the epoch and the symbol
        // traded between the two (the auxiliary 1m feed is the evidence, so
        // the NSE week whose holiday Monday never traded stays kept). The
        // chart's own timeframe keeps the chart series' first bar, and a
        // native partition with pre-range history (the 15m lanes' explicit
        // daily feed) already opened that bucket before the epoch, so the
        // rule below agrees with the cut above wherever both apply.
        if (aux_security_feed_enabled() && !pine.lower_tf_requested
            && !pine.lower_tf_array_requested) {
            const CalendarPeriod period = calendar_period_for(state.tf);
            const CalendarPeriod chart_period = calendar_period_for(script_tf_);
            const bool strictly_coarser = period != CalendarPeriod::NONE
                && static_cast<int>(period) > static_cast<int>(chart_period);
            if (strictly_coarser) {
                const int64_t nominal_open = session_period_open_ms(
                    input_ts, syminfo_.timezone, syminfo_.session, period);
                if (nominal_open < security_range_start_ms_
                    && aux_security_traded_between(nominal_open,
                                                   security_range_start_ms_)) {
                    return true;
                }
            }
        }
#endif
        return state.aggregator.bucket_open_ms(input_ts) < security_range_start_ms_;
    }
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
    // R19 OTC daily pins: a historical intraday chart beginning mid-session
    // has no partial first D bar in request.security, even when this run has
    // only the chart feed. XAUUSD from Apr1 00:00Z reads D time/close as na
    // that day and ATR14[1] first becomes numeric Apr23; counting the partial
    // Mar31 session seeds ATR a day early. Restrict the no-aux inference to
    // the pinned daily OTC clock. W/M need trading-history evidence to retain
    // a holiday-open period, and native/aux feeds keep their existing rules.
    if (!aux_security_feed_enabled() && native_security_feeds_.empty()
        && security_first_chart_bar_ms_ > 0
        && script_tf_seconds_ > 0 && script_tf_seconds_ < 86400
        && (state.tf == "D" || state.tf == "1D")
        && !pine.lower_tf_requested && !pine.lower_tf_array_requested
        && (syminfo_.type == "forex" || syminfo_.type == "cfd")) {
        const int64_t stamp = session_period_open_ms(
            input_ts, syminfo_.timezone, syminfo_.session, CalendarPeriod::DAY);
        // Metals stamp the D bar at 17:00 ET but first trade at 18:00.
        // Starting at that actual open keeps the complete first session.
        const int64_t trading_open = session_covered_instant_ms(
            stamp, syminfo_.timezone, syminfo_.session);
        return trading_open < security_first_chart_bar_ms_;
    }
    // Default cut (round 8, family P), split-feed runs only: a coarser-than-
    // chart or chart-timeframe series starts at the first bucket that OPENS at
    // or after the run's first chart bar -- the deep-backtest range start --
    // and the bucket in progress at that instant is absent, exactly as
    // TradingView's is (security_first_chart_bar_ms_). "In progress" is a
    // fact about trading, not the calendar: TradingView dates a bar by its
    // first traded bar, so the NSE week whose Monday 2025-03-31 was a holiday
    // opens on Tuesday 04-01 -- the range start -- and is kept (famp-sense-
    // nifty15full: "W" first reads 08-22), while the NYSE week that traded
    // Monday 03-31 (F: 08-29), the CME trade date that opened Mon 22:00Z
    // (ES/NQ "D": 05-01) and the OANDA week that opened Sun 21:00Z (XAUUSD
    // 1D "W": 08-28) are absent. The auxiliary 1m feed holds the pre-range
    // bars (the lanes' finer feeds begin in 2021), so the bucket whose
    // nominal open precedes the first chart bar is dropped iff the feed
    // traded between that open and the first chart bar. A finer-than-chart
    // evaluator is never cut (its slice begins at the first chart bar), and
    // a single-feed run has no evidence and keeps its feed-start series.
    if (security_first_chart_bar_ms_ <= 0 || !aux_security_feed_enabled()
        || pine.lower_tf_requested || pine.lower_tf_array_requested
        || script_tf_seconds_ <= 0) {
        return false;
    }
    const int requested_seconds = safe_tf_to_seconds(state.tf);
    const bool coarser_or_chart = requested_seconds == -1
        || requested_seconds >= script_tf_seconds_;
    if (!coarser_or_chart) {
        return false;
    }
    const CalendarPeriod period = calendar_period_for(state.tf);
    const int64_t nominal_open = period != CalendarPeriod::NONE
        ? session_period_open_ms(input_ts, syminfo_.timezone, syminfo_.session,
                                 period)
        : session_intraday_bucket_open_ms(input_ts, requested_seconds,
                                          syminfo_.timezone, syminfo_.session);
    if (nominal_open >= security_first_chart_bar_ms_) {
        return false;
    }
    return aux_security_traded_between(nominal_open, security_first_chart_bar_ms_);
#else
    return false;
#endif
}
 
 
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
bool source::PineStrategyHost::aux_security_traded_between(int64_t from_ms,
                                                 int64_t to_ms) const {
    const Bar* bars = nullptr;
    int n = 0;
    source_aux_security_input_view(bars, n);
    if (bars == nullptr || n <= 0) return false;
    auto it = std::lower_bound(
        bars, bars + n, from_ms,
        [](const Bar& bar, int64_t ts) { return bar.timestamp < ts; });
    return it != bars + n && it->timestamp < to_ms;
}
#endif
 
 
void source::PineStrategyHost::pine_feed_security_eval_state(
        SecurityEvalState& state, const Bar& input_bar,
        bool calling_bar_complete) {
    // Opt-in HTF warmup parity (security_range_start_na_warmup run flag):
    //   (a) start every request.security aggregation at range_start_ms, not the
    //       feed start — drop every input bar whose HTF bucket opened before
    //       the range start (security_input_precedes_range_start) so the
    //       aggregator, its TA members, and the exposed history all begin at
    //       the first WHOLE bucket opening at/after the range start;
    //   (b) its embedded lookback ta.ema na-warms per TV built-in semantics —
    //       scoped by raising ta::ema_na_warmup_flag() for the duration of this
    //       call, which covers every evaluate_security() dispatch below (each of
    //       which is the only place the security's EMA members compute());
    //   (c) plain security expressions (e.g. `close`) read na until the first
    //       COMPLETED HTF bar from the range start — a consequence of (a): under
    //       lookahead_off no evaluate_security() fires until that first whole
    //       bucket completes; a bucket straddling the range start never counts.
    // All three collapse to no-ops when the flag is unset (byte-identical).
    if (security_input_precedes_range_start(state, input_bar.timestamp)) {
        return;
    }
    PineSecurityEvalState& pine = pine_security_state(state.sec_id);
    // No bar of the requested timeframe is loaded (no_loaded_bars): the
    // site is never evaluated, so it and its TA read na throughout.
    if (pine.no_loaded_bars) return;
    // On the pump's runtime block when it has one (the per-pump state cache).
    internal::AmbientEmaSeedingScope _na_warmup_scope(
        NativeExecutionConsumer::bound(*this).pump_ambient(),
        security_range_start_na_warmup_);
 
    // Heikin-Ashi same-symbol read: replace an aggregated bar's OHLC with its
    // HA candle before evaluating the security expression. The completed
    // state advances once per committed HTF bucket; a partial/projection peek
    // derives from the prior state without committing it.
    auto apply_ha = [&pine](Bar& b, bool commit) {
        double ha_close = (b.open + b.high + b.low + b.close) / 4.0;
        double ha_open = pine.ha_seeded
                             ? (pine.ha_prev_open + pine.ha_prev_close) / 2.0
                             : (b.open + b.close) / 2.0;
        double ha_high = std::max(b.high, std::max(ha_open, ha_close));
        double ha_low = std::min(b.low, std::min(ha_open, ha_close));
        b.open = ha_open;
        b.high = ha_high;
        b.low = ha_low;
        b.close = ha_close;
        if (commit) {
            pine.ha_prev_open = ha_open;
            pine.ha_prev_close = ha_close;
            pine.ha_seeded = true;
        }
    };
 
    if (pine.lower_tf_use_input) {
        // Buffer raw input bars until we accumulate one full script-TF
        // chunk, then aggregate (if req > input) and dispatch each
        // resulting LTF bar to the codegen via evaluate_security. The
        // codegen detects ``lower_tf_sub_bar_index == 0`` to clear its
        // accumulator vector and pushes once per dispatch.
        //
        // Bucket-aware dispatch (mirrors feed_ratio_mode in
        // src/timeframe.cpp:1100): when the incoming bar belongs to a
        // different wall-clock script-TF bucket than the buffered
        // window, we MUST flush the buffer (even if partial) BEFORE
        // pushing — otherwise a feed gap, warmup misalignment, or
        // sparse-data run leaks bars across the chart-bar boundary
        // (e.g. a 16-bar window dispatched per 15m chart bar instead
        // of 15). Pure count-based dispatch is preserved as a
        // secondary trigger so dense gap-free feeds still flush
        // promptly when the chunk fills.
        int input_seconds = tf_to_seconds(security_input_tf_);
        int script_seconds = script_tf_seconds_;
        if (input_seconds <= 0 || script_seconds <= 0) {
            // Cannot compute bucket math — fall back to original
            // count-only behaviour.
            pine.lower_tf_input_buffer.push_back(input_bar);
            return;
        }
        int chunk_size = script_seconds / input_seconds;
        if (chunk_size <= 0) {
            pine.lower_tf_input_buffer.push_back(input_bar);
            return;
        }
        // The buffer fills to at most chunk_size input bars before it is
        // dispatched and cleared. Reserve once (no-op when capacity already
        // suffices) so the repeated fill/clear cycle reuses one allocation.
        pine.lower_tf_input_buffer.reserve(static_cast<std::size_t>(chunk_size));
        int64_t bucket_ms = static_cast<int64_t>(script_seconds) * 1000;
        int64_t this_bucket = input_bar.timestamp / bucket_ms;
        bool boundary_crossed = false;
        if (!pine.lower_tf_input_buffer.empty()) {
            int64_t buffer_bucket =
                pine.lower_tf_input_buffer.front().timestamp / bucket_ms;
            if (this_bucket != buffer_bucket) {
                boundary_crossed = true;
            }
        }
 
        // Lambda: aggregate + dispatch the current buffer (length may
        // be < chunk_size on a boundary-triggered partial flush) and
        // clear it. Uses the same agg_ratio rollup as before but is
        // length-driven by the actual buffer size rather than
        // chunk_size, so partial windows don't index out of bounds.
        auto dispatch_and_clear = [&]() {
            int agg_ratio = pine.lower_tf_input_aggregation_ratio;
            if (agg_ratio < 1) agg_ratio = 1;
            int buf_len = static_cast<int>(pine.lower_tf_input_buffer.size());
            std::vector<Bar> ltf_bars;
            ltf_bars.reserve(static_cast<std::size_t>(buf_len / agg_ratio + 1));
            if (agg_ratio == 1) {
                for (const Bar& b : pine.lower_tf_input_buffer) {
                    ltf_bars.push_back(b);
                }
            } else {
                for (int i = 0; i + agg_ratio <= buf_len; i += agg_ratio) {
                    Bar acc = pine.lower_tf_input_buffer[
                        static_cast<std::size_t>(i)];
                    double vol = acc.volume;
                    for (int j = 1; j < agg_ratio; ++j) {
                        const Bar& nxt = pine.lower_tf_input_buffer[
                            static_cast<std::size_t>(i + j)];
                        if (nxt.high > acc.high) acc.high = nxt.high;
                        if (nxt.low < acc.low) acc.low = nxt.low;
                        acc.close = nxt.close;
                        vol += nxt.volume;
                    }
                    acc.volume = vol;
                    ltf_bars.push_back(acc);
                }
            }
            pine.lower_tf_sub_bar_index = 0;
            for (const Bar& b : ltf_bars) {
                state.feed_count++;
                state.current_bar = b;
                state.current_sub_bar_count = 1;
                state.eval_complete_count++;
                dispatch_security_eval(state, b, true,
                                       state.eval_complete_count - 1);
                pine.lower_tf_sub_bar_index++;
            }
            pine.lower_tf_input_buffer.clear();
        };
 
        if (boundary_crossed) {
            // Flush stale bucket BEFORE pushing the new bar so the
            // new bar starts a fresh window aligned to its own bucket.
            dispatch_and_clear();
        }
 
        pine.lower_tf_input_buffer.push_back(input_bar);
 
        // Secondary trigger: if the buffer happens to fill to
        // chunk_size mid-bucket (the dense gap-free case), flush
        // immediately. This preserves the original count-based
        // behaviour for the common path.
        if (static_cast<int>(pine.lower_tf_input_buffer.size()) >= chunk_size) {
            dispatch_and_clear();
        }
        return;
    }
    if (pine.lower_tf_emulation) {
        std::vector<Bar> synthetic_bars =
            synthesize_lower_tf_bars(input_bar, pine.lower_tf_ratio, pine.lower_tf_seconds);
        if (synthetic_bars.empty()) {
            throw coded<std::runtime_error>(
                RunFailureCode::request_timeframe_unsupported,
                {{"reason", "lower_tf_synthesis_failed"}, {"input_tf", security_input_tf_}},
                "request.security lower TF emulation could not synthesize bars for requested "
                + state.tf + " from input timeframe " + security_input_tf_
            );
        }
        // Reset the sub-bar counter at the start of every chart bar's
        // synthesis so a ``request.security_lower_tf`` codegen path can
        // detect index 0 and clear its accumulator vector before pushing
        // each per-sub-bar value. The counter is incremented after every
        // dispatch so callers see 0, 1, ..., ratio-1 in sequence.
        pine.lower_tf_sub_bar_index = 0;
        for (const auto& synthetic_bar : synthetic_bars) {
            state.feed_count++;
            state.current_bar = synthetic_bar;
            state.current_sub_bar_count = 1;
            state.eval_complete_count++;
            dispatch_security_eval(state, synthetic_bar, true,
                                   state.eval_complete_count - 1);
            pine.lower_tf_sub_bar_index++;
        }
        return;
    }
 
    if (historical_security_lookahead_projection_active_
            && !pine.historical_projections.empty()) {
        // Keyed by the input's instant, not by a feed-call index: on the
        // split-feed path this evaluator is fed the finer auxiliary slice
        // (hundreds of inputs per chart bar), and the projection of a bucket
        // is dispatched on the first input at or after its first retained
        // child (that child's own first auxiliary bar) -- exactly the chart
        // bar TradingView's lookahead_on leaks the bucket's FINAL values
        // from. On the single-feed path the first input at or after the
        // child's timestamp is that child itself, as the index cut was.
        const int64_t input_ms = input_bar.timestamp;
        while (pine.historical_projection_cursor + 1
                    < pine.historical_projections.size()
                && pine.historical_projections[
                       pine.historical_projection_cursor + 1]
                       .first_child_ms <= input_ms) {
            ++pine.historical_projection_cursor;
            pine.historical_projection_dispatched = false;
        }
        const auto& projection = pine.historical_projections[
            pine.historical_projection_cursor];
        state.feed_count++;
        if (pine.historical_projection_dispatched
                || input_ms < projection.first_child_ms) {
            // gaps_off holds the first-child projection unchanged until the
            // next HTF bucket. No evaluator call means TA/security histories
            // also advance exactly once per projected bucket.
            return;
        }
        pine.historical_projection_dispatched = true;
 
        Bar projected_bar = projection.bar;
        // A projected bucket is the exchange's bar wherever a native feed
        // serves this timeframe -- complete or not. TradingView's
        // lookahead_on leaks the period's FINAL values from its first chart
        // bar, so the trailing period still in progress at the range end
        // carries the whole native period whenever the feed holds it (lab tv
        // wm-m-f15-jul, 2026-09-05: August's final o/h/l/c 10.92/11.99/
        // 10.68/11.77 from 08-01 09:30 on a chart ending 08-08). A partial
        // with no native bar keeps the available aggregate, uncounted as a
        // miss.
        substitute_native_security_bar(state, projected_bar,
                                       /*count_miss=*/projection.is_complete);
        if (pine.heikinashi) {
            apply_ha(projected_bar, projection.is_complete);
        }
        state.current_bar = projected_bar;
        // The projected HTF bucket is introduced on its first chart child, so
        // generated security series must allocate a fresh history/TA slot even
        // though projected_bar itself already contains every available child.
        state.current_sub_bar_count = 1;
        if (projection.is_complete) {
            state.eval_complete_count++;
        } else {
            state.eval_partial_count++;
        }
        dispatch_security_eval(state, projected_bar, projection.is_complete,
                               projection.is_complete
                                   ? state.eval_complete_count - 1
                                   : state.eval_complete_count);
        return;
    }
 
    // The next input bar's timestamp (0 when unknown) lets a calendar
    // bucket complete on the period's actual last chart bar -- see
    // security_next_input_ms_ -- and the calling chart bar's nominal close
    // (split-feed path, else 0) lets an OTC bucket do so exactly when that
    // close reaches the period's -- see security_calling_close_ms_.
    AggregatedBar ab = state.aggregator.feed(input_bar, security_next_input_ms_,
                                             security_calling_close_ms_);
    // timeframe.cpp excludes target_seconds >= kSecPerDay from its sub-day
    // session-close rule. A minute-spelled day closes at the day's close,
    // deliberately not at an intermediate session window's close.
    const bool minute_day = calendar_period_for(state.tf) == CalendarPeriod::NONE
        && tf_to_seconds(state.tf) == 86400;
    if (!ab.is_complete && minute_day && !pine.lookahead_on
        && state.aggregator.has_pending_partial()) {
        const int input_seconds = tf_to_seconds(security_input_tf_);
        const auto session_open = session_period_open_ms(
            input_bar.timestamp, syminfo_.timezone, syminfo_.session,
            CalendarPeriod::DAY);
        const bool next_session = state.aggregator.early_close_completes()
            && security_next_input_ms_ > 0
            && session_period_open_ms(security_next_input_ms_, syminfo_.timezone,
                                      syminfo_.session, CalendarPeriod::DAY)
                != session_open;
        const auto session_close = session_period_close_ms(
            input_bar.timestamp, syminfo_.timezone, syminfo_.session,
            CalendarPeriod::DAY);
        const bool reaches_close = input_seconds > 0
            && input_bar.timestamp + static_cast<int64_t>(input_seconds) * 1000
                >= session_close;
        if (next_session || reaches_close) {
            ab = state.aggregator.complete_pending_partial();
        }
    }
    state.feed_count++;
    state.current_sub_bar_count = ab.sub_bar_count;
    if (ab.is_complete) {
        // The aggregator decided WHEN the bucket completes; a native feed for
        // this timeframe decides WHAT it closed at (the settlement / official
        // print), before any Heikin-Ashi derivation. Partial (lookahead_on)
        // peeks keep the running aggregate.
        substitute_native_security_bar(state, ab.bar);
        if (pine.heikinashi) apply_ha(ab.bar, /*commit=*/true);
        state.current_bar = ab.bar;
        state.eval_complete_count++;
        // For a plain request.security whose target TF is strictly finer
        // than script_tf (publish_gate_tf_seconds > 0), the security's own
        // aggregator completes multiple times per calling/script bar.
        // Only the completion whose bucket END lands on a script_tf
        // boundary is "the last completion of THIS calling bar" — that's
        // the one a history-offset read (``expr[1]``) should latch as
        // "confirmed as of the previous calling bar" the NEXT time the
        // calling script reads it. Suppress ``is_complete`` (so codegen's
        // gated hist.push() does not fire) for every other, intermediate
        // completion; the underlying TA state keeps advancing regardless
        // (compute()/recompute() dispatch is driven by
        // current_sub_bar_count, not by this flag) — only the exposed
        // history buffer's advance is gated. eval_complete_count/current_bar
        // bookkeeping above stays driven by the real completion.
        bool publish = true;
        if (pine.publish_gate_tf_seconds > 0 && script_tf_seconds_ > 0) {
            // Merge finer-context history on the event that the calling chart
            // aggregator actually completes. Unlike a fixed seconds modulus,
            // this includes session-clipped calling bars.
            // The requested-context evaluator still runs once
            // per input update; only its is_complete publication signal is
            // replaced.
            publish = calling_bar_complete;
        }
        // A boundary emission: the input bar opened a NEW bucket and the
        // aggregator emitted the previous one, still partial (a singleton the
        // count / real-end / session-close rules never reached: OANDA:XAUUSD
        // Thanksgiving's 21:54 bucket holding the 21:56 minute, emitted when
        // 21:59 opens the 21:57 bucket). Under lookahead_on that bucket's
        // history slot was already opened by its first sub-bar's partial
        // peek (compute), so the completion must REWRITE it (recompute) --
        // a fresh compute here committed a phantom copy of the bucket and
        // shifted every later requested value (the RSI diverged from the
        // lookahead_off twin's on the same buckets). And the input bar that
        // opened the new bucket got no peek of its own in this feed, so open
        // its slot now, exactly as the merge branch below does for a first
        // sub-bar. Count, real-end and session-close completions carry the
        // input bar's own bucket (the label matches) and are untouched, as
        // is lookahead_off (no peeks: every completion is a new slot).
        // The emitted bucket is a boundary emission exactly when it is not
        // the aggregator's CURRENT bucket: a boundary completion hands back
        // the previous bucket and re-seats the aggregator on the one the
        // input opened (feed_calendar_mode / feed_ratio_mode), while every
        // eager completion (count, real end, session close, the calendar
        // period's last input) leaves the completed bucket current. The
        // former test compared the label against bar_label_ms(input), which
        // is the intraday grid open for a fixed-TF bucket but the DAY stamp
        // for a calendar W / M bucket -- so every weekly completion on its
        // last daily bar looked like a boundary and committed a phantom copy
        // of the week as one more requested bar (round 7, family I: the
        // weekly MACD probe's f_count carry decayed twice per week, hist ties
        // compared the week with its own copy).
        const bool boundary_emission = pine.lookahead_on
            && state.aggregator.is_active()
            && ab.bar.timestamp != state.aggregator.current().timestamp;
        if (boundary_emission && state.current_sub_bar_count < 2) {
            state.current_sub_bar_count = 2;
        }
        pine.last_published_label = ab.bar.timestamp;
        dispatch_security_eval(state, ab.bar, publish,
                               state.eval_complete_count - 1);
        if (boundary_emission) {
            Bar fresh = state.aggregator.current();
            if (pine.heikinashi) apply_ha(fresh, /*commit=*/false);
            state.current_bar = fresh;
            state.current_sub_bar_count = 1;
            state.eval_partial_count++;
            const bool peek_publish = pine.publish_gate_tf_seconds > 0
                && calling_bar_complete;
            dispatch_security_eval(state, fresh, peek_publish,
                                   state.eval_complete_count);
        }
    } else if (pine.lookahead_on) {
        if (pine.heikinashi) apply_ha(ab.bar, /*commit=*/false);
        state.current_bar = ab.bar;
        state.eval_partial_count++;
        // A shortened calling bar can complete while the finer requested
        // bucket is partial. Publish that current requested-context value to
        // merged history without adding a second evaluator/TA dispatch.
        const bool publish = pine.publish_gate_tf_seconds > 0
            && calling_bar_complete;
        // Partial (in-progress) bucket: the index the completion will carry.
        dispatch_security_eval(state, ab.bar, publish,
                               state.eval_complete_count);
    } else {
        state.current_bar = ab.bar;
        if (pine.gaps_on) {
            clear_security(state.sec_id);
        }
    }
 
    // The calling chart bar's last auxiliary bar left the finer bucket it
    // opened (or merged into) partial: its count, real end and session
    // close all lie beyond the chart bar's last sub-bar (the Thanksgiving
    // 21:57 3m bucket holding the 21:59 minute alone; the 2-minute 20:57
    // bucket of a day whose 20:59 minute did not trade). TradingView reads
    // that bucket at the chart bar's close (lab tv dca-ltf-last-intrabar,
    // 2026-09-05: 72.64, the 21:59 minute's RSI, where the previous bucket
    // reads 38.87), so finalize it now, exactly as a count / real-end /
    // session-close completion would have, and publish it as one more
    // completed requested-context bar. The aggregator marks it emitted:
    // the next chart bar's first sub-bar starts a fresh bucket without
    // re-emitting this one, and a later sub-bar of the same bucket (not a
    // completed chart bar's, but guarded) merges without completing it
    // again. A dense feed whose final bucket completed on its count has no
    // pending partial and is untouched (calling_close_completes_partial).
    if (calling_bar_complete && pine.calling_close_completes_partial
        && state.aggregator.has_pending_partial()) {
        AggregatedBar tail = state.aggregator.complete_pending_partial();
        if (tail.is_complete) {
            state.current_sub_bar_count = tail.sub_bar_count;
            substitute_native_security_bar(state, tail.bar);
            if (pine.heikinashi) apply_ha(tail.bar, /*commit=*/true);
            state.current_bar = tail.bar;
            state.eval_complete_count++;
            pine.last_published_label = tail.bar.timestamp;
            dispatch_security_eval(state, tail.bar, true,
                                   state.eval_complete_count - 1);
        }
    }
}
 
 
// ---- request.security of another symbol (lane XSYM-D) ----------------------
//
// A site of ANOTHER symbol reads that symbol's own bars, installed before the
// run (strategy_set_symbol_feed) and served by the kernel as the site's
// NativeSeriesSource::InstrumentFeed series: the kernel owns the merge by
// interval (NativeInstrumentFeed), this host the Pine semantics around it --
// the barmerge flags mapped onto the series, the payload evaluated on every
// bar handed over, in the requested context, ignore_invalid_symbol, and on a
// calendar chart TradingView's merge against the chart bar's own time and
// close (read_ahead_foreign_security_sites).
 
namespace {
 
// The one timeframe spelling of the symbol-data stores, the requests
// manifest's: whole minutes as a bare integer ("15", "240"), days, weeks,
// months and seconds as <n>D|W|M|S, Pine's bare "D"/"W"/"M"/"S" folded to a
// count of one. Any other text is kept as it is, and no feed will match it.
std::string canonical_symbol_timeframe(const std::string& tf) {
    if (tf.size() == 1 && (tf[0] == 'D' || tf[0] == 'W' || tf[0] == 'M' || tf[0] == 'S'))
        return "1" + tf;
    return tf;
}
 
// syminfo.ticker of a requested symbol: the key without its exchange prefix.
std::string symbol_ticker(const std::string& key) {
    const auto colon = key.rfind(':');
    return colon == std::string::npos ? key : key.substr(colon + 1);
}
 
bool parse_fact_number(const std::string& text, double& value) {
    if (text.empty()) return false;
    std::size_t used = 0;
    try {
        value = std::stod(text, &used);
    } catch (...) {
        return false;
    }
    return used == text.size();
}
 
// The doors install before a run: a run in progress (a stream's warmup or
// realtime leg included) has already staged and hashed what it reads.
constexpr const char* kRunInProgress =
    "a run is in progress; request data is installed before a run begins";
 
bool run_in_progress(const NativeStrategyHost& host) {
    return host.native_state().kind == NativeLifecycleKind::Running;
}
 
}  // namespace
 
void source::PineStrategyHost::register_security_eval(
        int sec_id, const std::string& symbol, const std::string& requested_tf,
        const std::string& input_tf, bool lookahead_on, bool gaps_on,
        bool ignore_invalid_symbol) {
    // The evaluator input is the symbol's own feed, not the chart's: the
    // chart's input timeframe plays no part in the site.
    (void)input_tf;
    ForeignSecuritySite site;
    site.symbol = symbol;
    site.requested_tf = requested_tf;
    site.lookahead = lookahead_on;
    site.gaps = gaps_on;
    site.ignore_invalid = ignore_invalid_symbol;
    foreign_security_sites_[sec_id] = std::move(site);
}
 
std::int64_t source::PineStrategyHost::find_symbol_feed(const std::string& key,
                                                        const std::string& tf) const {
    for (std::size_t i = 0; i < symbol_feeds_.size(); ++i) {
        if (symbol_feeds_[i].instrument == key && symbol_feeds_[i].tf == tf)
            return static_cast<std::int64_t>(i);
    }
    return -1;
}
 
// AR-R4: an applied configure holds the feeds' bytes in the kernel's run spec
// (prepare_native_begin), which keeps them, in this host's order, from that
// configure to the next one: the spec is moved, never rewritten, from Ready to
// Running to Completed, and a failure carries it into Failed.
const NativeInstrumentFeed& source::PineStrategyHost::installed_symbol_feed(
        std::size_t i) const {
    if (!symbol_feeds_lent_) return symbol_feeds_[i];
    const NativeRunSpec* spec = native_state().spec;
    if (spec == nullptr || i >= spec->instrument_feeds.size())
        throw coded<std::logic_error>(
            RunFailureCode::engine_invariant, {},
            "request data: the run spec no longer holds the symbol feeds");
    return spec->instrument_feeds[i];
}
 
void source::PineStrategyHost::restore_symbol_feeds() {
    if (!symbol_feeds_lent_) return;
    const NativeRunSpec* spec = native_state().spec;
    if (spec == nullptr || spec->instrument_feeds.size() != symbol_feeds_.size())
        throw coded<std::logic_error>(
            RunFailureCode::engine_invariant, {},
            "request data: the run spec no longer holds the symbol feeds");
    // Every entry is the one lent at that index -- its key and its column
    // names -- before a byte is copied back, so a mismatch changes nothing.
    for (std::size_t i = 0; i < symbol_feeds_.size(); ++i) {
        const NativeInstrumentFeed& held = spec->instrument_feeds[i];
        const NativeInstrumentFeed& feed = symbol_feeds_[i];
        bool same = held.instrument == feed.instrument && held.tf == feed.tf
            && held.columns.size() == feed.columns.size();
        for (std::size_t c = 0; same && c < feed.columns.size(); ++c)
            same = held.columns[c].name == feed.columns[c].name;
        if (!same)
            throw coded<std::logic_error>(
                RunFailureCode::engine_invariant, {},
                "request data: the run spec holds other symbol feeds");
    }
    for (std::size_t i = 0; i < symbol_feeds_.size(); ++i) {
        const NativeInstrumentFeed& held = spec->instrument_feeds[i];
        NativeInstrumentFeed& feed = symbol_feeds_[i];
        const auto views = NativeExecutionConsumer::bound(*this).bar_views();
        const auto* slot = views.instrument_feed_count == 0
            ? nullptr : views.instrument_feeds[i];
        if (slot == nullptr) {
            feed.bars = held.bars;
            feed.close_ms = held.close_ms;
        }
        for (std::size_t c = 0; c < feed.columns.size(); ++c)
            feed.columns[c].values = held.columns[c].values;
    }
    symbol_feeds_lent_ = false;
}
 
// A door's restore: the reason it failed, empty when the store holds its
// bytes, so the door refuses with that text rather than with none.
std::string source::PineStrategyHost::restore_symbol_feeds_reason() {
    try {
        restore_symbol_feeds();
    } catch (const std::exception& error) {
        return std::string("request data could not be restored: ") + error.what();
    }
    return {};
}
 
void source::PineStrategyHost::prepare_foreign_security_sites(
        std::vector<NativeTimeframeSubscription>& declared) {
    foreign_security_series_.assign(declared.size(), -1);
    if (foreign_security_sites_.empty()) return;
    // The merge is judged per chart bar, and the kernel hands feed bars over
    // per accepted input: the two agree only while the input IS the chart
    // (a chart aggregated from finer input would publish, peek and clear on
    // the finer cadence).
    const int ratio = input_tf_.empty() || script_tf_.empty() ? 0
                                                              : tf_ratio(input_tf_, script_tf_);
    if (input_tf_.empty() || ratio > 1 || ratio == -1) {
        RunFailureArgs aggregated{{"reason", "chart_input_aggregated"}};
        if (!input_tf_.empty()) aggregated.emplace_back("input_tf", input_tf_);
        if (!script_tf_.empty()) aggregated.emplace_back("script_tf", script_tf_);
        throw coded<std::runtime_error>(
            RunFailureCode::symbol_feeds_refused, aggregated,
            "request.security of another symbol needs the chart's own bars as input; input '"
            + input_tf_ + "' aggregated to chart '" + script_tf_ + "' is not supported");
    }
    for (auto& entry : foreign_security_sites_) {
        const int sec_id = entry.first;
        ForeignSecuritySite& site = entry.second;
        site.tf = canonical_symbol_timeframe(site.requested_tf.empty() ? script_tf_
                                                                       : site.requested_tf);
        site.invalid = false;
        site.subscription = -1;
        site.feed = 0;
        site.delivered = 0;
        site.close_ms = 0;
        site.last_input = -1;
        site.handed = 0;
        site.eval = SecurityEvalState{};
        site.eval.sec_id = sec_id;
        site.eval.tf = site.tf;
        const auto facts = symbol_facts_.find(site.symbol);
        const SymbolFacts* known = facts == symbol_facts_.end() ? nullptr : &facts->second;
        if (known != nullptr && known->valid && !*known->valid) {
            // TradingView reads na for an invalid symbol under
            // ignore_invalid_symbol and raises a runtime error without it.
            if (!site.ignore_invalid) {
                throw coded<std::runtime_error>(RunFailureCode::request_symbol_invalid, {},
                                                "request.security: symbol '" + site.symbol
                                                    + "' is invalid");
            }
            site.invalid = true;
            continue;
        }
        const std::int64_t feed = find_symbol_feed(site.symbol, site.tf);
        if (feed < 0) {
            // The timeframe is an argument only when it is the run's own chart
            // timeframe (no requested timeframe), never the script's.
            RunFailureArgs missing;
            if (site.requested_tf.empty()) missing.emplace_back("timeframe", site.tf);
            throw coded<std::runtime_error>(RunFailureCode::other_symbol_feed_missing, missing,
                                            "request.security: no feed is installed for symbol '"
                                                + site.symbol + "' at timeframe '" + site.tf
                                                + "'");
        }
        site.feed = static_cast<std::size_t>(feed);
        // The requested context's syminfo: the symbol's own facts, and nothing
        // of the chart's. TradingView's syminfo.tickerid inside the request is
        // the string the script passed (a bare ticker stays bare). A fact the
        // host did not supply reads empty (NaN for a number).
        SymInfo info;
        info.ticker = symbol_ticker(site.symbol);
        info.tickerid = site.symbol;
        info.currency.clear();
        info.basecurrency.clear();
        info.type.clear();
        info.timezone.clear();
        info.session.clear();
        info.volumetype.clear();
        info.description.clear();
        info.mintick = std::numeric_limits<double>::quiet_NaN();
        info.pointvalue = std::numeric_limits<double>::quiet_NaN();
        info.qty_step = 0.0;
        if (known != nullptr) {
            info.type = known->type;
            info.timezone = known->timezone;
            info.session = known->session;
            info.currency = known->currency;
            info.mintick = known->mintick;
        }
        site.syminfo = std::move(info);
        NativeTimeframeSubscription series;
        series.tf = site.tf;
        series.source = NativeSeriesSource::InstrumentFeed;
        series.instrument = site.symbol;
        series.lookahead = site.lookahead;
        series.gaps = site.gaps;
        site.subscription = static_cast<std::int64_t>(declared.size());
        declared.push_back(std::move(series));
        foreign_security_series_.push_back(sec_id);
    }
}
 
void source::PineStrategyHost::on_native_timeframe_bar(
        const Bar& bar, const NativeTimeframeBarContext& context) {
    if (source_prepare_failed_) return;
    if (context.subscription >= foreign_security_series_.size()) return;
    const int sec_id = foreign_security_series_[context.subscription];
    if (sec_id < 0) return;
    const auto found = foreign_security_sites_.find(sec_id);
    if (found == foreign_security_sites_.end()) return;
    ForeignSecuritySite& site = found->second;
    // The kernel hands every bar over once, in order, so the count so far is
    // the bar's feed index. A bar the payload already ran on, made visible on
    // an earlier chart bar by the merge rule below, is not run again; any
    // other is the context's next bar, its close the feed's own.
    const std::int64_t index = site.handed;
    site.handed = index + 1;
    if (index < site.delivered) return;
    run_foreign_site_bar(site, bar, context.interval.last_traded_close_ms);
}
 
void source::PineStrategyHost::run_foreign_site_bar(ForeignSecuritySite& site, const Bar& bar,
                                                    std::int64_t close_ms) {
    const std::int64_t index = site.delivered;
    site.delivered = index + 1;
    site.close_ms = close_ms;
    site.last_input = foreign_input_index_;
    // The requested context answers pine_bar_index(), time_close() and
    // syminfo_ while its payload runs, and the chart's once it returns.
    struct ContextScope {
        PineStrategyHost& host;
        ForeignSecuritySite& site;
        const ForeignSecuritySite* previous_context;
        double previous_mintick;
        ContextScope(PineStrategyHost& h, ForeignSecuritySite& s)
            : host(h), site(s), previous_context(h.foreign_context_),
              previous_mintick(h.syminfo_mintick_) {
            std::swap(host.syminfo_, site.syminfo);
            host.syminfo_mintick_ = host.syminfo_.mintick;
            host.foreign_context_ = &site;
        }
        ~ContextScope() {
            host.foreign_context_ = previous_context;
            host.syminfo_mintick_ = previous_mintick;
            std::swap(host.syminfo_, site.syminfo);
        }
    } scope(*this, site);
    dispatch_security_eval(site.eval, bar, true, index);
}
 
// TradingView merges another symbol's bars into a calendar (D/W/M) chart bar
// by the chart bar's own period, from its time to its time_close (tapes
// tg-xau1d-requests, w11-tclose-xau1d and w11-tclose-la-xau1d,
// tests/fixtures/daily_break_close):
//   lookahead_off: the last requested bar closed by the chart bar's close;
//   lookahead_on, an intraday requested timeframe: the last requested bar
//     opened by the chart bar's time.
// The kernel hands a series the bars visible at its input's calendar
// interval, which is that period wherever the chart bar's stamp opens its own
// session, so nothing is left here to run. OANDA stamps its XAUUSD daily bars
// at 17:00 ET, inside the break of the 1800-1700 session, and the kernel reads
// such a label as the session that closes at it (test_daily_stamp_in_the_break
// in tests/test_native_instrument_feed.cpp): a lookahead-off request would
// read one bar late, a lookahead-on hourly one a session early. The bars the
// rule makes visible run here, in feed order, after the input's deliveries;
// the kernel hands them over again on a later input, below `delivered`.
// lookahead_on of a D/W/M timeframe, which TradingView aligns by trading date
// (the requested bar opening inside the chart bar there), keeps the kernel's
// reading.
void source::PineStrategyHost::read_ahead_foreign_security_sites(const Bar& chart_bar) {
    if (calendar_period_for(script_tf_) == CalendarPeriod::NONE) return;
    const std::int64_t chart_close = chart_bar_close_ms(chart_bar.timestamp);
    for (auto& entry : foreign_security_sites_) {
        ForeignSecuritySite& site = entry.second;
        if (site.invalid || site.subscription < 0 || site.feed >= symbol_feeds_.size()) continue;
        if (site.lookahead ? calendar_period_for(site.tf) != CalendarPeriod::NONE
                           : is_na(chart_close)) {
            continue;
        }
        const auto views = NativeExecutionConsumer::bound(*this).bar_views();
        const auto* slot = views.instrument_feed_count == 0
            ? nullptr : views.instrument_feeds[site.feed];
        const auto feed = native_instrument_feed_view(installed_symbol_feed(site.feed), slot);
        while (static_cast<std::size_t>(site.delivered) < feed.bars.size) {
            const auto at = static_cast<std::size_t>(site.delivered);
            const bool visible = site.lookahead ? feed.bars.data[at].timestamp <= chart_bar.timestamp
                                                : feed.close_ms[at] <= chart_close;
            if (!visible) break;
            run_foreign_site_bar(site, feed.bars.data[at], feed.close_ms[at]);
        }
    }
}
 
void source::PineStrategyHost::clear_gapped_foreign_security_sites() {
    for (const auto& entry : foreign_security_sites_) {
        const ForeignSecuritySite& site = entry.second;
        if (!site.gaps || site.subscription < 0) continue;
        if (site.last_input != foreign_input_index_) clear_security(entry.first);
    }
}
 
double source::PineStrategyHost::security_column_value(int sec_id,
                                                       const std::string& name) const {
    const auto found = foreign_security_sites_.find(sec_id);
    if (found == foreign_security_sites_.end()) return std::numeric_limits<double>::quiet_NaN();
    const ForeignSecuritySite& site = found->second;
    if (site.subscription < 0 || site.delivered <= 0 || site.feed >= symbol_feeds_.size())
        return std::numeric_limits<double>::quiet_NaN();
    const NativeInstrumentFeed& feed = installed_symbol_feed(site.feed);
    const auto at = static_cast<std::size_t>(site.delivered - 1);
    for (const auto& column : feed.columns) {
        if (column.name != name) continue;
        return at < column.values.size() ? column.values[at]
                                         : std::numeric_limits<double>::quiet_NaN();
    }
    return std::numeric_limits<double>::quiet_NaN();
}
 
double source::PineStrategyHost::recorded_series_value(const std::string& key) const {
    const auto found = recorded_series_.find(key);
    if (found == recorded_series_.end()) {
        throw coded<std::runtime_error>(RunFailureCode::recorded_request_missing, {},
                                        "request data: no recorded series is installed for key '"
                                            + key + "'");
    }
    const RecordedSeries& series = found->second;
    std::size_t first = 0, last = series.rows.size();
    while (first < last) {
        const auto middle = first + (last - first) / 2;
        if (series.rows[middle].open_ms < current_bar_.timestamp) first = middle + 1;
        else last = middle;
    }
    if (first == series.rows.size())
        return std::numeric_limits<double>::quiet_NaN();
    const RecordedSeriesRow row = series.rows[first];
    return row.open_ms == current_bar_.timestamp
        ? row.value : std::numeric_limits<double>::quiet_NaN();
}
 
// ---- the request-data doors ------------------------------------------------
 
bool source::PineStrategyHost::set_symbol_feed(const std::string& key,
                                               const std::string& timeframe,
                                               const Bar* bars, const int64_t* close_ms,
                                               int n) {
    guard_native_mutation("set_symbol_feed");
    const auto refuse = [this](const char* reason, const std::string& why,
                               const char* field = nullptr) {
        RunFailureArgs args{{"reason", reason}};
        if (field) args.emplace_back("field", field);
        note_run_failure(*this, "strategy_set_symbol_feed: " + why,
                         RunFailureCode::symbol_feeds_refused, args);
        return false;
    };
    if (run_in_progress(*this)) return refuse("run_in_progress", kRunInProgress);
    if (key.empty()) return refuse("empty_key", "empty symbol key");
    const std::string tf = canonical_symbol_timeframe(timeframe);
    if (tf.empty() || !native_calendar::parse_timeframe(tf)) {
        return refuse("timeframe_unparsable", "timeframe '" + timeframe + "' does not parse");
    }
    if (n < 0 || (n > 0 && (bars == nullptr || close_ms == nullptr)))
        return refuse("invalid_bars", "invalid bar array");
    const std::int64_t existing = find_symbol_feed(key, tf);
    // n == 0 is a symbol with no bars over the run (a feed file with a header
    // only): installed, so its sites read na rather than fail as unfed. The
    // feed is built inside the one-feed list it is judged in, then moved out.
    std::vector<NativeInstrumentFeed> judged_feeds(1);
    NativeInstrumentFeed& feed = judged_feeds.front();
    feed.instrument = key;
    feed.tf = tf;
    if (n > 0) {
        feed.bars.assign(bars, bars + n);
        feed.close_ms.assign(close_ms, close_ms + n);
    }
    // The kernel's own judgement of the feed, so a refusal names its field
    // here rather than at the next begin.
    const auto judged = validate_native_instrument_feeds(judged_feeds);
    if (!judged) {
        return refuse("kernel_refused", "feed refused (NativeRunSpecError "
                      + std::to_string(static_cast<int>(judged.error)) + ", field "
                      + std::to_string(static_cast<int>(judged.field)) + ")",
                      instrument_feed_field_name(judged.field));
    }
    // Every refusal above reads keys only; a store whose bytes are lent
    // (restore_symbol_feeds) gets them back before one of its feeds changes.
    if (const std::string why = restore_symbol_feeds_reason(); !why.empty())
        return refuse("restore_failed", why);
    if (existing >= 0) {
        const std::size_t at = static_cast<std::size_t>(existing);
        symbol_feeds_[at] = std::move(feed);
        symbol_feed_views_[at] = {};
    } else {
        symbol_feeds_.reserve(symbol_feeds_.size() + 1);
        symbol_feed_views_.reserve(symbol_feed_views_.size() + 1);
        symbol_feeds_.push_back(std::move(feed));
        symbol_feed_views_.push_back({});
    }
    refresh_symbol_data_digest();
    clear_run_failure(*this);
    return true;
}
 
bool source::PineStrategyHost::set_symbol_feed_column(const std::string& key,
                                                      const std::string& timeframe,
                                                      const std::string& name,
                                                      const double* values, int n) {
    guard_native_mutation("set_symbol_feed_column");
    const auto refuse = [this](const char* reason, const std::string& why,
                               const char* field = nullptr) {
        RunFailureArgs args{{"reason", reason}};
        if (field) args.emplace_back("field", field);
        note_run_failure(*this, "strategy_set_symbol_feed_column: " + why,
                         RunFailureCode::symbol_feeds_refused, args);
        return false;
    };
    if (run_in_progress(*this)) return refuse("run_in_progress", kRunInProgress);
    const std::int64_t found = find_symbol_feed(key, canonical_symbol_timeframe(timeframe));
    if (found < 0) {
        return refuse("no_feed", "no feed is installed for symbol '" + key + "' at timeframe '"
                      + timeframe + "'");
    }
    if (name.empty()) return refuse("empty_column", "empty column name");
    // The refusals above read keys only; the count check below reads the
    // feed's bars, so a lent store gets its bytes back first.
    if (const std::string why = restore_symbol_feeds_reason(); !why.empty())
        return refuse("restore_failed", why);
    NativeInstrumentFeed& feed = symbol_feeds_[static_cast<std::size_t>(found)];
    const auto data = native_instrument_feed_view(feed, nullptr);
    const std::size_t feed_count = static_cast<std::size_t>(found) < symbol_feed_views_.size()
        && symbol_feed_views_[static_cast<std::size_t>(found)].present
        ? symbol_feed_views_[static_cast<std::size_t>(found)].size : data.bars.size;
    if (n < 0 || static_cast<std::size_t>(n) != feed_count || (n > 0 && values == nullptr))
        return refuse("column_length", "column '" + name + "' has " + std::to_string(n)
                      + " values for " + std::to_string(feed_count) + " bars");
    // The kernel's judgement of the name, here rather than at the next begin:
    // a feed of the same key without bars carries it (the count is checked
    // above, and no column value is refused).
    NativeInstrumentFeed named;
    named.instrument = feed.instrument;
    named.tf = feed.tf;
    named.columns.push_back(NativeInstrumentColumn{name, {}});
    if (const auto judged = validate_native_instrument_feeds({named}); !judged) {
        return refuse("column_refused", "column '" + name + "' refused (NativeRunSpecError "
                      + std::to_string(static_cast<int>(judged.error)) + ", field "
                      + std::to_string(static_cast<int>(judged.field)) + ")",
                      instrument_feed_field_name(judged.field));
    }
    NativeInstrumentColumn column{name, n > 0 ? std::vector<double>(values, values + n)
                                              : std::vector<double>{}};
    bool replaced = false;
    for (auto& existing : feed.columns) {
        if (existing.name != name) continue;
        existing = std::move(column);
        replaced = true;
        break;
    }
    if (!replaced) feed.columns.push_back(std::move(column));
    refresh_symbol_data_digest();
    clear_run_failure(*this);
    return true;
}
 
bool source::PineStrategyHost::set_symbol_facts(const std::string& key,
                                                const std::string& field,
                                                const std::string& value) {
    guard_native_mutation("set_symbol_facts");
    const auto refuse = [this](const char* reason, const std::string& why) {
        note_run_failure(*this, "strategy_set_symbol_facts: " + why,
                         RunFailureCode::symbol_feeds_refused, {{"reason", reason}});
        return false;
    };
    if (run_in_progress(*this)) return refuse("run_in_progress", kRunInProgress);
    if (key.empty()) return refuse("empty_key", "empty symbol key");
    SymbolFacts candidate = symbol_facts_.count(key) ? symbol_facts_[key] : SymbolFacts{};
    if (field == "canonical") {
        candidate.canonical = value;
    } else if (field == "valid") {
        if (value == "true") candidate.valid = true;
        else if (value == "false") candidate.valid = false;
        else return refuse("valid_not_boolean",
                           "valid must be \"true\" or \"false\", got '" + value + "'");
    } else if (field == "type") {
        candidate.type = value;
    } else if (field == "timezone") {
        candidate.timezone = value;
    } else if (field == "session") {
        candidate.session = value;
    } else if (field == "currency") {
        candidate.currency = value;
    } else if (field == "mintick") {
        double parsed = 0.0;
        if (!parse_fact_number(value, parsed) || !std::isfinite(parsed) || parsed <= 0.0)
            return refuse("mintick_invalid",
                          "mintick must be a positive decimal, got '" + value + "'");
        candidate.mintick = parsed;
    } else {
        return refuse("unknown_field", "unknown field '" + field + "'");
    }
    // The digest below reads the feeds' sizes: a lent store gets its bytes
    // back first, after every refusal.
    if (const std::string why = restore_symbol_feeds_reason(); !why.empty())
        return refuse("restore_failed", why);
    symbol_facts_[key] = std::move(candidate);
    refresh_symbol_data_digest();
    clear_run_failure(*this);
    return true;
}
 
bool source::PineStrategyHost::set_recorded_series(const std::string& key,
                                                   const int64_t* chart_open_ms,
                                                   const double* values, int n) {
    return set_recorded_series_impl(key, chart_open_ms, values, n, std::nullopt);
}
 
bool source::PineStrategyHost::set_recorded_series(const std::string& key,
                                                   const int64_t* chart_open_ms,
                                                   const double* values, int n,
                                                   std::size_t cache_capacity_bytes) {
    return set_recorded_series_impl(key, chart_open_ms, values, n, cache_capacity_bytes);
}
 
bool source::PineStrategyHost::set_recorded_series_impl(
        const std::string& key, const int64_t* chart_open_ms, const double* values, int n,
        std::optional<std::size_t> cache_capacity_bytes) {
    guard_native_mutation("set_recorded_series");
    const auto refuse = [this](const char* reason, const std::string& why) {
        note_run_failure(*this, "strategy_set_recorded_series: " + why,
                         RunFailureCode::recorded_request_refused, {{"reason", reason}});
        return false;
    };
    if (run_in_progress(*this)) return refuse("run_in_progress", kRunInProgress);
    if (key.empty()) return refuse("empty_key", "empty key");
    if (n < 0 || (n > 0 && (chart_open_ms == nullptr || values == nullptr)))
        return refuse("invalid_arrays", "invalid arrays");
    for (int i = 1; i < n; ++i) {
        if (chart_open_ms[i] <= chart_open_ms[i - 1])
            return refuse("times_not_increasing",
                          "chart open times must be strictly increasing (row "
                          + std::to_string(i) + ")");
    }
    // n == 0 is a request that returned na on every chart bar (a tape with a
    // header only): installed, so every read is na rather than a failure.
    pineforge::detail::FeedProjectionBuilder<RecordedSeriesRow> builder(report_scratch_directory(), true);
    for (int i = 0; i < n; ++i)
        builder.append(RecordedSeriesRow{chart_open_ms[i], values[i]});
    RecordedSeries series{builder.finish(cache_capacity_bytes.value_or(
        pineforge::detail::kFeedProjectionCacheBytes)), cache_capacity_bytes};
    // As in set_symbol_facts: the bytes back before the digest, after every
    // refusal.
    if (const std::string why = restore_symbol_feeds_reason(); !why.empty())
        return refuse("restore_failed", why);
    const auto digest = calculate_symbol_data_digest(&key, &series);
    recorded_series_[key] = std::move(series);
    symbol_data_digest_ = digest;
    clear_run_failure(*this);
    return true;
}
 
bool source::PineStrategyHost::set_recorded_series_reader(
        const std::string& key, std::shared_ptr<const FeedReader<RecordedSeriesRow>> reader) {
    return set_recorded_series_reader_impl(key, std::move(reader), std::nullopt);
}
 
bool source::PineStrategyHost::set_recorded_series_reader(
        const std::string& key, std::shared_ptr<const FeedReader<RecordedSeriesRow>> reader,
        std::size_t cache_capacity_bytes) {
    return set_recorded_series_reader_impl(key, std::move(reader), cache_capacity_bytes);
}
 
bool source::PineStrategyHost::set_recorded_series_reader_impl(
        const std::string& key, std::shared_ptr<const FeedReader<RecordedSeriesRow>> reader,
        std::optional<std::size_t> cache_capacity_bytes) {
    guard_native_mutation("set_recorded_series_reader");
    const auto refuse = [this](const char* reason, const std::string& why) {
        note_run_failure(*this, "set_recorded_series_reader: " + why,
                         RunFailureCode::recorded_request_refused, {{"reason", reason}});
        return false;
    };
    if (run_in_progress(*this)) return refuse("run_in_progress", kRunInProgress);
    if (key.empty()) return refuse("empty_key", "empty key");
    if (!reader) return refuse("invalid_arrays", "missing reader");
    RecordedSeries series{pineforge::detail::FeedProjection<RecordedSeriesRow>(
        std::move(reader), cache_capacity_bytes.value_or(
            pineforge::detail::kFeedProjectionCacheBytes)), cache_capacity_bytes};
    std::int64_t previous = 0;
    for (std::size_t i = 0; i < series.rows.size(); ++i) {
        const auto open = series.rows[i].open_ms;
        if (i && open <= previous)
            return refuse("times_not_increasing",
                          "chart open times must be strictly increasing (row "
                          + std::to_string(i) + ")");
        previous = open;
    }
    if (const std::string why = restore_symbol_feeds_reason(); !why.empty())
        return refuse("restore_failed", why);
    const auto digest = calculate_symbol_data_digest(&key, &series);
    recorded_series_[key] = std::move(series);
    symbol_data_digest_ = digest;
    clear_run_failure(*this);
    return true;
}
 
// The facts and tapes as the extension folds them, and the feeds' keys and
// sizes (their bars are the projected spec's, which the continuation digest
// folds). Taken whenever the stores change, never during a run.
void source::PineStrategyHost::refresh_symbol_data_digest() {
    symbol_data_digest_ = calculate_symbol_data_digest();
}
 
std::uint64_t source::PineStrategyHost::calculate_symbol_data_digest(
        const std::string* replacement_key, const RecordedSeries* replacement) const {
    BrokerStateHashSink f;
    f.u(symbol_feeds_.size());
    for (const auto& feed : symbol_feeds_) {
        f.s(feed.instrument);
        f.s(feed.tf);
        const auto data = native_instrument_feed_view(feed, nullptr);
        const std::size_t count = (&feed - symbol_feeds_.data()) < symbol_feed_views_.size()
            && symbol_feed_views_[static_cast<std::size_t>(&feed - symbol_feeds_.data())].present
            ? symbol_feed_views_[static_cast<std::size_t>(&feed - symbol_feeds_.data())].size
            : data.bars.size;
        f.u(count);
        f.u(feed.columns.size());
        for (const auto& column : feed.columns) f.s(column.name);
    }
    f.u(symbol_facts_.size());
    for (const auto& [key, facts] : symbol_facts_) {
        f.s(key);
        f.s(facts.canonical);
        f.b(facts.valid.has_value());
        if (facts.valid) f.b(*facts.valid);
        f.s(facts.type);
        f.s(facts.timezone);
        f.s(facts.session);
        f.s(facts.currency);
        f.d(facts.mintick);
    }
    const bool inserting = replacement_key && recorded_series_.find(*replacement_key)
        == recorded_series_.end();
    f.u(recorded_series_.size() + (inserting ? 1 : 0));
    const auto fold_series = [&f](const std::string& key, const RecordedSeries& series) {
        f.s(key);
        f.u(series.rows.size());
        for (std::size_t i = 0; i < series.rows.size(); ++i) {
            const RecordedSeriesRow row = series.rows[i];
            f.i(row.open_ms);
            f.d(row.value);
        }
    };
    // Stage a replacement in the same lexical key order as the original map,
    // without publishing it before every provider read and the fold succeed.
    bool emitted = false;
    for (const auto& [key, series] : recorded_series_) {
        if (replacement_key && !emitted && *replacement_key <= key) {
            fold_series(*replacement_key, *replacement);
            emitted = true;
        }
        if (!replacement_key || key != *replacement_key) fold_series(key, series);
    }
    if (replacement_key && !emitted) fold_series(*replacement_key, *replacement);
    return f.h;
}
 
}  // namespace pineforge
 
namespace pineforge {
 
bool source::PineStrategyHost::set_symbol_feed_borrowed(
        const std::string& key, const std::string& timeframe,
        const Bar* bars, const int64_t* close_ms, int n) {
    guard_native_mutation("set_symbol_feed_borrowed");
    const auto refuse = [this](const char* reason, const std::string& why,
                               const char* field = nullptr) {
        RunFailureArgs args{{"reason", reason}};
        if (field) args.emplace_back("field", field);
        note_run_failure(*this, "strategy_set_symbol_feed_borrowed_v1: " + why,
                         RunFailureCode::symbol_feeds_refused, args);
        return false;
    };
    if (run_in_progress(*this)) return refuse("run_in_progress", kRunInProgress);
    if (key.empty()) return refuse("empty_key", "empty symbol key");
    const std::string tf = canonical_symbol_timeframe(timeframe);
    if (tf.empty() || !native_calendar::parse_timeframe(tf))
        return refuse("timeframe_unparsable", "timeframe '" + timeframe + "' does not parse");
    if (n < 0 || (n > 0 && (bars == nullptr || close_ms == nullptr)))
        return refuse("invalid_bars", "invalid bar array");
 
    const std::size_t count = static_cast<std::size_t>(n);
    NativeInstrumentFeedView view{{bars, count}, close_ms};
    const NativeInstrumentFeedView* slots[] = {&view};
    NativeBarViews views{slots, 1};
    std::vector<NativeInstrumentFeed> judged_feeds(1);
    judged_feeds.front().instrument = key;
    judged_feeds.front().tf = tf;
    const auto judged = validate_native_instrument_feeds(judged_feeds, views);
    if (!judged) {
        return refuse("kernel_refused", "feed refused (NativeRunSpecError "
                      + std::to_string(static_cast<int>(judged.error)) + ", field "
                      + std::to_string(static_cast<int>(judged.field)) + ")",
                      instrument_feed_field_name(judged.field));
    }
    if (const std::string why = restore_symbol_feeds_reason(); !why.empty())
        return refuse("restore_failed", why);
 
    const std::int64_t existing = find_symbol_feed(key, tf);
    const BorrowedFeedSlot replacement{bars, close_ms, count, true};
    if (existing >= 0) {
        const std::size_t at = static_cast<std::size_t>(existing);
        NativeInstrumentFeed& feed = symbol_feeds_[at];
        feed.instrument = key;
        feed.tf = tf;
        feed.bars.clear();
        feed.close_ms.clear();
        feed.columns.clear();
        symbol_feed_views_[at] = replacement;
    } else {
        symbol_feeds_.reserve(symbol_feeds_.size() + 1);
        symbol_feed_views_.reserve(symbol_feed_views_.size() + 1);
        NativeInstrumentFeed feed;
        feed.instrument = key;
        feed.tf = tf;
        symbol_feeds_.push_back(std::move(feed));
        symbol_feed_views_.push_back(replacement);
    }
    refresh_symbol_data_digest();
    clear_run_failure(*this);
    return true;
}
 
}  // namespace pineforge