pine_strategy_host.hpp

Go to the documentation of this file.

#pragma once
 
#include <pineforge/detail/scratch_store.hpp>
#include <pineforge/detail/feed_projection.hpp>
#include <pineforge/native_host.hpp>
#include <pineforge/session_time.hpp>
#include <pineforge/source/pine_adapter.hpp>
#include <pineforge/source/pine_scheduler.hpp>
 
#include <cstdint>
#include <limits>
#include <map>
#include <optional>
#include <string>
#include <vector>
 
// Generated strategies require this switched source-host surface. There is
// intentionally no compatibility execution path behind the capability gate.
#define PINEFORGE_HAS_EXPLICIT_PINE_CAP_V1 1
#define PINEFORGE_HAS_EXPLICIT_PINE_EXECUTION_ADAPTER_V1 1
#define PINEFORGE_HAS_NATIVE_LOWERING_V1 1
// The run-time symbol key overload of register_security_eval (lane XSYM-D):
// a request site of another symbol reads the feed installed for that symbol.
#define PINEFORGE_HAS_SYMBOL_SECURITY_EVAL_V1 1
#define PINEFORGE_HAS_TRADE_SCRATCH_V1 1
 
namespace pineforge::source {
 
// Hash domain of the per-site request.security semantics below. Folded into
// the source extension only when a site is registered, so a run without
// request.security hashes exactly as before; bumped whenever the folded
// field set changes.
inline constexpr char kSourceSecurityDomain[] = "pineforge-source-security/v6";
 
// Hash domain of the request data of other symbols (lane XSYM-D): the sites
// that read another symbol's feed, and the facts and recorded series the run
// was handed. Folded only when one is present, so every other run hashes as
// before.
inline constexpr char kSourceSymbolDataDomain[] = "pineforge-source-symbol-data/v1";
 
// One symbol's facts as a request site's expression reads them through
// syminfo.* (strategy_set_symbol_facts). Empty strings and a NaN mintick are
// facts nobody supplied.
struct SymbolFacts {
    std::string canonical;
    std::optional<bool> valid;
    std::string type;
    std::string timezone;
    std::string session;
    std::string currency;
    double mintick = std::numeric_limits<double>::quiet_NaN();
};
 
// A recorded request series (strategy_set_recorded_series): exact values in
// increasing chart-open order, read by logical bar index.
struct RecordedSeriesRow {
    std::int64_t open_ms = 0;
    double value = 0.0;
};
 
struct RecordedSeries {
    pineforge::detail::FeedProjection<RecordedSeriesRow> rows;
    // Physical setup only: an omitted capacity follows the admitted run policy.
    // Explicit zero and an explicit internal-default value are both overrides.
    std::optional<std::size_t> cache_capacity_override;
};
 
// One projected higher-timeframe bucket of the opt-in historical
// request.security lookahead projection (PineSecurityEvalState below).
struct HistoricalSecurityProjection {
    Bar bar{};
    // The instant the projection is dispatched on: the first retained
    // chart child's timestamp on the single-feed path, that child's first
    // auxiliary bar on the split-feed path (the requested-context
    // evaluator is fed the finer slice there). Keyed by instant, not by
    // feed-call index, so both paths consume one projection per bucket.
    int64_t first_child_ms = 0;
    bool is_complete = false;
};
 
// One auxiliary bar a first-bucket-latched site holds back until the chart
// body has run (PineSecurityEvalState::deferred_aux), with the cursor values
// it would have been fed under.
struct DeferredAuxBar {
    Bar bar;
    int64_t next_input_ms = 0;
    bool calling_bar_complete = false;
};
 
// Pine's publication semantics for ONE request.security site, kept beside the
// kernel's generic evaluator state of the same sec_id
// (BacktestEngine::SecurityEvalState: aggregator, current bar, feed counts,
// native feed routing). The kernel evaluator knows none of these rules; this
// host composes them around the kernel's aggregation, substitution and
// dispatch primitives (src/source/pine_security_eval.cpp).
struct PineSecurityEvalState {
    // barmerge.lookahead_on: the site reads the in-progress requested bucket.
    // Every input peeks the running aggregate (a partial evaluation), a
    // completion rewrites the slot its first peek opened instead of opening a
    // second one, and generated TA sites take their recompute path on every
    // sub-bar after a bucket's first (security_series_slot_is_new).
    bool lookahead_on = false;
    // barmerge.gaps_on: the site reads na on every input that completes no
    // requested bucket (clear_security on the generated series).
    bool gaps_on = false;
    // Plain ``request.security`` (not ``_lower_tf``) with a requested TF
    // STRICTLY FINER than script_tf (e.g. so2TF="5" read from a 15m
    // chart) under ``lookahead=barmerge.lookahead_ON``: the security's
    // own aggregator completes multiple times
    // (script_seconds / requested_seconds) per calling/script bar. A
    // history-offset read (``expr[1]`` inside the security call, see
    // the ``*_hist`` push/read machinery in codegen) is meant to expose
    // "the value already confirmed as of the close of the PREVIOUS
    // calling bar" — TV's lookahead_on merge takes the FIRST intrabar
    // of each calling bar, so the publish granularity is the CALLING
    // bar, not the security's own (finer) period. Without this, the
    // read-before-push ``hist[0]`` gets refreshed on every one of the
    // R completions inside the current calling bar, so by the time
    // on_bar() reads it the value has silently drifted to "one
    // security-period behind the LAST completion of THIS SAME calling
    // bar" (e.g. the middle of 3 sub-periods) instead of "the last
    // completion of the PREVIOUS calling bar" — an aliasing bug
    // confirmed against TradingView-exported trades on a triple-RSI
    // DCA strategy using so2Rsi = request.security(sym, "5",
    // ta.rsi(close,7)[1], lookahead=barmerge.lookahead_on) on a 15m
    // chart (finer target under lookahead + offset).
    //
    // ``lookahead_OFF`` is deliberately NOT gated (field stays 0): TV's
    // lookahead_off merge takes the LAST intrabar of the calling bar,
    // so the exposed value — and any ``[k]`` history offset off it —
    // advances at the security's own finer cadence (one hist.push per
    // completed security period), which is exactly the ungated
    // behavior. Gating lookahead_off regressed
    // masayanfx-multi-time-score-strategy
    // (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.
    //
    // When nonzero, this holds the requested TF's duration in seconds
    // (script_seconds % this == 0 verified at validate time) and gates
    // ``pine_feed_security_eval_state``'s aggregator branch: only the
    // completion whose bucket END aligns to a script_tf boundary is
    // passed through to ``evaluate_security`` as ``is_complete = true``
    // (letting codegen's ``hist.push()`` fire); all other completions
    // within the same calling bar are still evaluated (so the
    // underlying TA state keeps advancing at native/security
    // resolution) but are passed ``is_complete = false`` so they do not
    // advance the exposed history buffer. Zero (the default) means "not
    // applicable" (target TF coarser than or equal to script_tf, or
    // lookahead_off — the already-correct cases) and leaves behavior
    // unchanged.
    int publish_gate_tf_seconds = 0;
    // Plain ``request.security`` with a requested TF strictly finer than
    // script_tf, served by the auxiliary finer feed (the split-feed
    // path), under ``lookahead_off``: TradingView surfaces the LAST
    // intrabar of the calling chart bar at that bar's close whatever
    // the bucket's sub-bar count -- on the OANDA:XAUUSD 1D chart the
    // Thanksgiving 2025-11-26 bar's last 3m bucket (21:57Z, holding
    // the 21:59Z minute alone before the 22:00Z session close) is the
    // value ``request.security(tickerid, "3", ta.rsi(close, 14))``
    // reads at the daily close (72.64, lab tv dca-ltf-last-intrabar,
    // 2026-09-05), where the aggregator's count / real-end /
    // session-close rules leave that bucket partial until the next
    // chart bar's first sub-bar and the close read the 21:54Z bucket
    // (38.87). When set, pine_feed_security_eval_state
    // finalizes and publishes the pending partial bucket on the
    // calling bar's last auxiliary bar (TimeframeAggregator::
    // complete_pending_partial), once: the next chart bar's first
    // sub-bar resets the bucket without re-emitting it. Dense feeds
    // whose final bucket completes on its count are untouched (no
    // partial is pending), and so are lanes without the auxiliary
    // slice, lookahead_on (its gated publication is untouched: on this
    // shape it stays one bucket behind, as before -- the tape pins
    // lookahead_off only), lower-TF arrays and calendar / same-TF
    // requests. False (the default) means "not applicable".
    bool calling_close_completes_partial = false;
    // Plain ``request.security`` with a requested TF strictly finer than the
    // finest feed the host supplied (the auxiliary slice, or an input feed
    // already finer than the chart), e.g. "5S" or "15S" on a lane whose
    // finest bars are 1m: no bar of the requested timeframe is loaded, so
    // the site is never fed and reads na on every chart bar. That is
    // TradingView's own reading of a chart bar that holds no loaded bar of
    // the requested lower timeframe: it keeps the last 2,000,000 bars of
    // it, and on the BINANCE:ETHUSDT.P 15m and 1D charts over 2025-04-01..
    // 2026-05-01 ``request.security(tickerid, "5S", close)`` is na up to
    // 2026-01-04 22:45 UTC and ``"15S"`` up to 2025-05-18 03:15 UTC (lab tv
    // pf-krunerr-ltf-horizon / -ltf-count2, 2026-09-26), gaps_on reads na on
    // the chart bars holding no 5S bar. A chart fed without any intrabar
    // bars (input_tf == script_tf) still refuses a finer request, so its
    // host can supply finer bars. False (the default) means "loaded".
    bool no_loaded_bars = false;
    // Heikin-Ashi same-symbol read: request.security(ticker.heikinashi(
    // syminfo.tickerid), ...). When set, the completed (aggregated) bar's
    // OHLC is replaced by its Heikin-Ashi candle before the security
    // expression is evaluated, so close/open/high/low inside the call see
    // HA values. HA is stateful (ha_open depends on the prior HA bar), so
    // the running state lives here per sec_id.
    bool heikinashi = false;
    double ha_prev_open = 0.0;
    double ha_prev_close = 0.0;
    bool ha_seeded = false;
    // One entry per projected HTF bucket, populated only for an explicitly
    // opted-in finite historical batch. Empty for every default/streaming
    // run and for sites outside the narrow HTF lookahead_on+gaps_off
    // contract. The feed index advances once per retained input bar (bars
    // before an opt-in security range start are dropped by both producer
    // and consumer); the projection cursor advances only at the next
    // bucket's first child.
    std::vector<HistoricalSecurityProjection> historical_projections;
    std::size_t historical_projection_cursor = 0;
    // Which projection (cursor) has already been dispatched: every later
    // input of the same bucket is a no-op for the evaluator.
    bool historical_projection_dispatched = false;
    // request.security_lower_tf emulation: a requested TF finer than the
    // evaluator input is synthesized from each input bar's OHLC path
    // (``lower_tf_emulation``: ``lower_tf_ratio`` sub-bars of
    // ``lower_tf_seconds``); ``lower_tf_requested`` marks a site on either
    // lower-timeframe path.
    bool lower_tf_requested = false;
    bool lower_tf_emulation = false;
    int lower_tf_ratio = 0;
    int lower_tf_seconds = 0;
    // ``request.security_lower_tf`` returns one element per
    // synthesised sub-bar of the current chart bar, so the codegen
    // needs to know which sub-bar inside the current chart bar is
    // currently being processed by the per-sec_id evaluator method.
    // ``lower_tf_array_requested`` is set by
    // ``register_security_lower_tf_eval`` and forces an extra
    // lower-TF-emulation validity check in
    // ``validate_security_timeframes``. ``lower_tf_sub_bar_index``
    // is reset to 0 at the start of every
    // ``pine_feed_security_eval_state`` invocation in lower-TF
    // emulation mode and incremented after each per-sub-bar
    // dispatch so the codegen can clear its accumulator on index
    // 0 and then push for every subsequent sub-bar.
    bool lower_tf_array_requested = false;
    int lower_tf_sub_bar_index = 0;
    // ``lower_tf_use_input`` selects the input-passthrough LTF path:
    // when the requested TF is >= input_tf and < script_tf we hand
    // the per-script-bar window of real input bars to the codegen
    // (optionally roll-up aggregated when req > input). Mutually
    // exclusive with ``lower_tf_emulation`` (synthesis) — only one
    // is set per state. ``lower_tf_input_aggregation_ratio`` is
    // ``req_seconds / input_seconds`` (>=1; 1 means raw passthrough,
    // N means N raw input bars roll up into one returned LTF bar).
    // ``lower_tf_input_buffer`` accumulates raw input bars within
    // the current script-TF chunk and is flushed at chunk
    // completion (or at end of feed for trailing partial chunks).
    bool lower_tf_use_input = false;
    int lower_tf_input_aggregation_ratio = 1;
    std::vector<Bar> lower_tf_input_buffer;
    // Plain ``request.security`` with a requested TF strictly finer than
    // script_tf, served by the auxiliary finer feed (the split-feed
    // path), under ``lookahead_on``: TradingView merges the requested bar
    // opening at or before the calling bar's time and holds it -- on
    // the BINANCE:BTCUSDT 1D chart ``request.security(tickerid, "15",
    // ta.rsi(close, 14)[1], lookahead_on)`` reads, on every daily bar,
    // the 15m RSI of the previous day's LAST bucket, i.e. ``rsi[1]``
    // evaluated on the day's first 15m bucket, na on the range's first
    // bar (lab tv notrade-ltf-sample-btc1d, 2025-04-01..20, 18/18,
    // 2026-09-05), so a plain ``expr`` reads the day's first bucket and
    // ``expr[k]`` the k-th bucket before it, at the requested cadence.
    // The legacy gate above (publish_gate_tf_seconds) publishes one
    // bucket per calling bar -- the LAST one -- which reads right for
    // ``expr[1]`` alone and one bucket late for ``expr``. When set, the
    // evaluator publishes EVERY completed requested bucket (the exposed
    // history advances per bucket, as under lookahead_off), and
    // feed_aux_security_for_chart_bar feeds the calling bar's auxiliary
    // bars only up to the one completing its FIRST bucket before the
    // chart body runs; the rest of the slice is held in ``deferred_aux``
    // and fed by feed_deferred_aux_security_for_chart_bar right after the
    // chart body (PineScheduler::bar calls scheduler_feed_deferred_aux_security
    // once the bar is published), so the body reads the first-bucket
    // evaluation while the TA state still sees every sub-bar, in order,
    // before the next chart bar. publish_gate_tf_seconds stays 0 on this
    // path; lanes without the auxiliary slice keep the gate. False (the
    // default) means "not applicable".
    bool calling_open_latches_first = false;
    // Per calling chart bar: whether this state's first bucket of the
    // slice has been published (the deferral point), and the auxiliary
    // bars held back until after the chart body, each with the
    // security_next_input_ms_ / calling_bar_complete it was fed with.
    bool first_bucket_published = false;
    // The label (bucket open) of the slice's first requested bucket:
    // a completion published by this slice's first auxiliary bars that
    // carries an OLDER label is the boundary emission of the previous
    // slice's still-pending bucket (a tail the count / real-end /
    // session-close rules left partial), not this bar's first bucket.
    int64_t slice_open_label = 0;
    // The label of the latest completed bucket this evaluator published
    // through its aggregator (pine_feed_security_eval_state), whatever the
    // state's current bucket is afterwards.
    int64_t last_published_label = 0;
    std::vector<DeferredAuxBar> deferred_aux;
};
 
class PineStrategyHost : public NativeStrategyHost, public BrokerStateHashProvider {
public:
    explicit PineStrategyHost(
        compat::pine::CapAttachment cap = compat::pine::CapAttachment::None);
 
    std::uint64_t broker_state_hash_projection() const override;
 
    void prepare_native_begin(const NativeBeginArgs&) final;
    void on_native_run_begin() final;
    void on_native_input(const Bar&, const NativeInputContext&) final;
    void on_native_tick(const Bar&, const NativeTickContext&) final;
    void on_native_bar_open(const Bar&, const NativeDecisionContext&) final;
    void on_native_bar(const Bar&, const NativeDecisionContext&) final;
    // A magnified run's intrabar is done: its open-point fills are spent
    // (PineScheduler::sub_bar_complete).
    void on_native_sub_bar(const Bar&, const NativeDecisionContext&) final;
    // R6: every calculation of the run arrives here. BarClose forwards to
    // on_native_bar exactly as the kernel's default does; OrderFill is
    // calc_on_order_fills, which the consumer now schedules (spec
    // NativeCalculationTrigger::BarCloseAndFills) and the source layer only
    // executes — language-state rollback, publication, first-open chain.
    void on_native_recalculate(const Bar&, const NativeDecisionContext&,
                               NativeCalculationReason,
                               const native_order::ExecutionAppliedEvent*) final;
    void on_native_applied(const native_order::ExecutionAppliedEvent&,
                           const NativeDecisionContext&) final;
    // Lane XSYM-D: a bar of another symbol's feed, handed to a foreign site's
    // series; the site's payload runs on it in the requested context. A
    // same-symbol series the kernel steps needs nothing here.
    void on_native_timeframe_bar(const Bar&, const NativeTimeframeBarContext&) final;
    native_order::ExecutionTerms resolve_execution_terms(
        const NativeExecutionTermsFacts&) const final;
    NativePrecommitVerdict validate_execution_precommit(
        const NativePrecommitView&) const final;
    // R5: the kernel owns the margin mechanism; these three answer with the
    // TradingView policy the adapter holds.
    bool margin_check_allowed(const NativeMarginCheckPoint&) const final;
    std::optional<NativeMarginDecision> resolve_margin_requirement(
        const NativeMarginRequirementView&) const final;
    std::optional<double> resolve_margin_call_units(
        const NativeMarginCallView&) const final;
    // R5 lane R4d: the kernel arms a relative strategy.exit leg at its
    // parent's fill; TradingView's projection of that level is the adapter's.
    std::optional<double> resolve_anchored_level(
        const NativeAnchoredLevelView&) const final;
    // The R5 R2 sizing classification of the adapter, for tests and for hosts
    // that need to know whether the core or the source owns a default
    // quantity at this point.
    bool adapter_core_sizes_default_opening(bool is_long) const;
 
    virtual void on_source_bar(const Bar&) = 0;
    void configure_pine_strategy(const PineStrategyConfig&);
    // Run-owner provisioned, exclusive scratch; use trade_scratch_order().
    // Borrowed through the run, empty outside a recut or same-bar sort.
    void set_trade_scratch(detail::CommandScratchStore&);
    static detail::ScratchKeyOrder trade_scratch_order() noexcept;
    void set_strategy_override(const StrategyOverrides&);
    // A stream's historical warmup remains a configuration window until the
    // first realtime input.  The legacy stream path permits the feed to
    // finalize its session template in that window (the sparse-boundary
    // request.security probe relies on it); retain that source-host surface
    // while native staged ingress remains refused once realtime starts.
    void set_syminfo_session(const std::string&);
    void set_pine_risk_direction(int);
    void set_pine_risk_max_cons_loss_days(int);
    void set_pine_risk_max_drawdown(double, bool);
    void set_pine_risk_max_intraday_loss(double, bool);
    void set_pine_risk_max_intraday_filled_orders(int);
    void set_pine_risk_max_position_size(double);
 
    void strategy_entry(const std::string& id, bool is_long,
                        double limit_price = std::numeric_limits<double>::quiet_NaN(),
                        double stop_price = std::numeric_limits<double>::quiet_NaN(),
                        double qty = std::numeric_limits<double>::quiet_NaN(),
                        const std::string& comment = {},
                        const std::string& oca_name = {}, int oca_type = 0,
                        int qty_type = -1);
    void strategy_close(const std::string& id, const std::string& comment = {},
                        double qty = std::numeric_limits<double>::quiet_NaN(),
                        double qty_percent = std::numeric_limits<double>::quiet_NaN(),
                        bool immediately = false);
    void strategy_close(const std::string& id, const std::string& comment,
                        double qty, double qty_percent, bool immediately,
                        std::uint64_t callsite_token);
    void strategy_close_all();
    void strategy_exit(const std::string& id, const std::string& from_entry,
                       double limit_price, double stop_price,
                       double trail_points = std::numeric_limits<double>::quiet_NaN(),
                       double trail_offset = std::numeric_limits<double>::quiet_NaN(),
                       double trail_price = std::numeric_limits<double>::quiet_NaN(),
                       double qty_percent = 100.0, const std::string& comment = {},
                       double qty = std::numeric_limits<double>::quiet_NaN(),
                       const std::string& oca_name = {},
                       double profit_ticks = std::numeric_limits<double>::quiet_NaN(),
                       double loss_ticks = std::numeric_limits<double>::quiet_NaN());
    void strategy_exit_cancel_bracket(const std::string& exit_id,
                                      const std::string& from_entry,
                                      const std::string& comment = {});
    void strategy_cancel(const std::string& id);
    void strategy_cancel_all();
    void strategy_order(const std::string& id, bool is_long, double qty,
                        double limit_price = std::numeric_limits<double>::quiet_NaN(),
                        double stop_price = std::numeric_limits<double>::quiet_NaN(),
                        const std::string& oca_name = {}, int oca_type = 0);
 
    int pine_bar_index() const;
    int pine_last_bar_index() const;
    double prev_chart_close() const;
    bool is_first_tick() const noexcept;
    bool is_last_tick() const noexcept;
    bool history_advances_new_bar() const noexcept;
    bool security_series_slot_is_new(int) const noexcept;
    int last_bar_dual_entry_path() const;
    double live_position_size() const override;
    int pending_order_count() const;
    MarketAdmissionJournal& market_admission_journal();
    const MarketAdmissionJournal& market_admission_journal() const;
    std::vector<admission::Field> market_admission_fields() const;
    int probe_fill_qty(int index, double fill_price, double* qty,
                       int* close_only, int* partition) const;
    int pending_order_level_resolved(int index) const;
    int pending_order_effective_levels(int index, double* stop, double* limit,
                                       double* trail_activation) const;
    const PendingIntentView& pending_intent_view() const noexcept;
    int short_seed_collision_role_v1(native_order::RequestHandle) const noexcept;
    void enable_pine_intraday_cap();
    void attach_pine_execution_adapter();
    // The report-only terminal quote (docs/report-terminal-quote.md) has three
    // writers, and none stores once a selected-window run has sealed
    // (selected_window.h; the fence of query_refusal.hpp): set_syminfo_metadata,
    // for the two reserved keys report_terminal_quote_time_ms and
    // report_terminal_quote_close, and clear_report_terminal_quote throw
    // pineforge::SelectedWindowQueryAfterSeal before any store, and
    // set_report_terminal_quote returns false. The C export
    // strategy_set_syminfo_metadata is void and swallows the throw, so its
    // refusal is read through strategy_state_query_status_v1. The refusal latches
    // no run failure and leaves the error, the status, the first cause and the
    // captured report alone. A preset before the first admitted begin, and every
    // handle without selected-window provenance, keep their original behaviour.
    void set_syminfo_metadata(const std::string&, double) override;
    bool set_report_terminal_quote(std::int64_t time_ms, double close);
    void clear_report_terminal_quote();
    bool report_terminal_quote_applied(const ReportC&) const;
    // TradingView's session calendar for the chart's symbol (lane XAU-CAL):
    // per session day, its open and its close, ascending, each day opening
    // before it closes and no later than the next opens. Where it holds a
    // chart bar, the bar after it is the calendar's -- the next slot of an
    // intraday chart's timeframe in the day, else the next day's open; a 1D
    // chart's next day -- for session.islastbar / islastbar_regular and for
    // time() / time_close() reading a later bar, as TradingView reads them;
    // everywhere else (a W, M or multi-day chart's own bars among them), and
    // with no calendar (the default), the feed's own bars answer. False, and
    // nothing installed, for sessions out of order; an empty list removes the
    // calendar. The C ABI carries it as syminfo metadata ("symbol_calendar_*",
    // set_syminfo_metadata), installed when the run begins.
    bool set_symbol_calendar(std::vector<std::pair<std::int64_t, std::int64_t>> sessions);
    const std::vector<std::pair<std::int64_t, std::int64_t>>& symbol_calendar() const noexcept {
        return symbol_calendar_;
    }
    bool set_aux_security_feed(const Bar* bars, int n,
                               const std::string& input_tf) override;
    // The request-data doors (pineforge.h strategy_set_symbol_feed and its
    // siblings); see BacktestEngine for the contract (lane XSYM-D).
    bool set_symbol_feed(const std::string& key, const std::string& timeframe,
                         const Bar* bars, const int64_t* close_ms, int n) override; bool set_symbol_feed_borrowed(const std::string& key, const std::string& timeframe, const Bar* bars, const int64_t* close_ms, int n) override;
    bool set_symbol_feed_column(const std::string& key, const std::string& timeframe,
                                const std::string& name, const double* values,
                                int n) override;
    bool set_symbol_facts(const std::string& key, const std::string& field,
                          const std::string& value) override;
    bool set_recorded_series(const std::string& key, const int64_t* chart_open_ms,
                             const double* values, int n) override;
    // The raw-array setter still copies before returning. This overload
    // selects optional resident bytes for that tape, including page tags,
    // in preference to the run policy. The four-argument overload follows
    // the run policy.
    bool set_recorded_series(const std::string& key, const int64_t* chart_open_ms,
                             const double* values, int n, std::size_t cache_capacity_bytes);
    // The provider is a retained immutable snapshot with copy-out random
    // reads. A miss reads the provider even with zero resident bytes.
    // Omitting capacity follows the run policy; an explicit value overrides it.
    bool set_recorded_series_reader(
        const std::string& key, std::shared_ptr<const FeedReader<RecordedSeriesRow>> reader);
    bool set_recorded_series_reader(
        const std::string& key, std::shared_ptr<const FeedReader<RecordedSeriesRow>> reader,
        std::size_t cache_capacity_bytes);
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
    bool source_aux_security_feed_enabled() const override;
    void source_aux_security_input_view(const Bar*&, int&) const override;
#endif
    int observe_last_bar_dual_entry_path_v1() const override;
    int observe_pending_count_v1() const override;
    int observe_pending_copy_v1(int, pf_pending_order_v1_t*) const override;
    int observe_probe_fill_qty(int, double, double*, int*, int*) const override;
    int observe_pending_level_resolved(int) const override;
    int observe_pending_effective_levels(int, double*, double*, double*) const override;
    double observe_trail_best_price_v1() const override;
 
    // Fixture-only adapter projections retained for the L2 literal twins.
    // They are read-only and never participate in execution or matching.
    enum class FixtureIntentKind { MARKET, EXIT, ENTRY, RAW_ORDER };
    struct FixtureIntentRow {
        std::string id;
        FixtureIntentKind type = FixtureIntentKind::MARKET;
        double default_stop_placement_qty = std::numeric_limits<double>::quiet_NaN();
        double default_stop_sizing_price = std::numeric_limits<double>::quiet_NaN();
        double frozen_market_own_units = std::numeric_limits<double>::quiet_NaN();
        double frozen_market_transaction_units = std::numeric_limits<double>::quiet_NaN();
        // These are immutable adapter placement facts, exposed only to test
        // facades which formerly read the retired source PendingOrder owner.
        std::string from_entry;
        bool is_long = true;
        double qty = std::numeric_limits<double>::quiet_NaN();
        double qty_percent = std::numeric_limits<double>::quiet_NaN();
        std::int64_t created_bar = -1;
        std::int64_t created_seq = 0;
        std::uint64_t incarnation = 0;
        bool over_pyramiding_cap_at_placement = false;
        std::int64_t paired_flat_market_peer_seq = 0;
        double paired_flat_market_transaction_qty = std::numeric_limits<double>::quiet_NaN();
        double frozen_default_qty = std::numeric_limits<double>::quiet_NaN();
        double default_stop_placement_equity = std::numeric_limits<double>::quiet_NaN();
        double default_stop_placement_signal_close = std::numeric_limits<double>::quiet_NaN();
        double affordability_placement_equity = std::numeric_limits<double>::quiet_NaN();
        // The adapter currently has no pair-review receipt for this request;
        // an empty Draft truthfully represents that absence to a fixture.
        MarketAdmissionDraft market_admission{};
    };
 
public:
    // Toggle TradingView's forced-liquidation (margin call) emulation.
    // Defaults ON to match TV; set false for the hold-the-position behaviour.
    // TV runs the broker margin-call emulator by default.  It is a no-op for
    // the validation corpus (long-only positions at the default 100% margin
    // can never be liquidated — the formula denominator ``margin/100 -
    // direction`` is 0 — and no corpus short is sized at full equity).
    //
    // R5 lane L12 (2.ii k): this used to be BacktestEngine state.  The kernel
    // toggle is the presence of `spec.margin` since L4/L4b, so the TV emulator
    // switch belongs to the adapter that implements that emulator.  The value
    // reaches `PineExecutionAdapter::source_margin_call_enabled_` at the
    // native begin boundary, exactly as before.
    void set_margin_call_enabled(bool enabled) {
        guard_native_mutation("set_margin_call_enabled");
        margin_call_enabled_ = enabled;
    }
    bool margin_call_enabled() const { return margin_call_enabled_; }
 
    // Live-runtime tail semantics (spec §3.1, ABI v4): the caller's fed array
    // ends with a still-forming bar rather than the chart's rightmost
    // historical bar. When `on`, the LAST bar of every subsequent run() (this
    // is persistent configuration, not a one-shot flag -- it stays set until
    // a caller passes on=false, and reset_run_state() does not touch it)
    // gets barstate.islast == false, session.islastbar computed from the
    // bucket calendar (no i+1 bar to peek at), pine_last_bar_index() /
    // last_bar_time_ frozen at the horizon bar (`horizon_bars - 1`), and no
    // range-end close row/trade. Default off: every historical run is
    // byte-identical to before this flag existed.
    //
    // R5 lane N14: this and probe tail suppression used to be BacktestEngine
    // state. Both are the live runner's probe / settle protocol expressed in
    // Pine language state (barstate, session flags, the range-end row), so
    // they belong to the host that implements that protocol; the frozen C
    // setters reach them through the kernel's virtual seams.
    bool set_realtime_tail(bool on, int horizon_bars) override {
        guard_native_mutation("set_realtime_tail");
        realtime_tail_ = on;
        realtime_tail_horizon_bars_ = horizon_bars;
        return true;
    }
    bool realtime_tail() const { return realtime_tail_; }
 
    // Live probe tail suppression (spec §3.2, ABI v4): when `on`, the LAST
    // script bar of every subsequent run() is matched but not calculated:
    // the kernel settles the resting book against it, and PineScheduler::bar
    // publishes it through scheduler_publish_suppressed_tail instead of
    // on_source_bar (source history and bar_index advance, the already-
    // matched receipts settle, the report point is marked; no range-end
    // row). on_native_bar still runs adapter_.on_bar_close after the
    // scheduler, so the risk-state update and the TradingView margin-call
    // checkpoint see the forming bar, and a margin call due against it is
    // booked there. This is persistent configuration, like
    // set_realtime_tail, and independent of it — do not couple the two
    // flags. Honoured on every batch path (single-TF, timeframe-aware,
    // magnifier; under aggregation, the last completed script bar). Under
    // calc_on_order_fills a fill on the forming bar still triggers the fill
    // recalculation, which runs the script there; COOF and the magnifier
    // stay gated in live v1. A stream begin refuses the flag
    // (prepare_native_begin); see pineforge.h. Default off (@p on == 0):
    // every historical run stays byte-identical to before this flag existed.
    bool set_probe_suppress_tail_logic(bool on) override {
        guard_native_mutation("set_probe_suppress_tail_logic");
        probe_suppress_tail_logic_ = on;
        return true;
    }
    bool probe_suppress_tail_logic() const { return probe_suppress_tail_logic_; }
 
    // Keep every event of the following runs readable after they end
    // (NativeEventRetention::Full as a readback, R5 lane V19-B). The adapter
    // declares Window and acknowledges what it reads, so a fixture that reads
    // a whole run's native_events() asks for this before the run. The spec,
    // its digest and every decision stay the adapter's.
    void fixture_retain_all_events();
 
protected:
    // The observer seam: on_native_applied is final, so a host that has to
    // observe an applied event after the host itself has settled its rows
    // overrides THIS instead. Called exactly once per applied event, at the
    // end of on_native_applied and after finish_applied_admission -- never
    // per bar. Empty by default, so a host that does not override it behaves
    // byte for byte as before and folds the same hash. It observes; it does
    // not admit, price or seal anything.
    virtual void on_native_applied_event(const native_order::ExecutionAppliedEvent&,
                                         const NativeDecisionContext&) {}
    // Narrow test-facade configuration slots keep the frozen L0 oracle bodies
    // unchanged while routing their setup through the source configuration
    // projected at the native begin boundary.
    PineStrategyConfig& fixture_configuration() noexcept { return config_; }
    const PineStrategyConfig& fixture_configuration() const noexcept { return config_; }
#ifdef PINEFORGE_VALUE_INVALID_SIZING_MARGIN_FIXTURES
    // Stateless test injection at the derived sizing tuple, inside a real
    // source callback. Absent from normal builds; no layout or kernel seam.
    double fixture_default_sizing_units(const PineSizingSnapshot& sizing) const {
        return adapter_.default_sizing_units(sizing);
    }
#endif
    bool fixture_intraday_cap_latched();
    compat::pine::CapClock fixture_cap_clock() const;
    compat::pine::Calculation fixture_cap_calculation() const;
    BarTime fixture_chart_time(std::int64_t timestamp_ms) const;
    std::int64_t fixture_chart_day_key(std::int64_t timestamp_ms) const noexcept {
        return adapter_.chart_day_key(timestamp_ms);
    }
    std::uint64_t fixture_applied_receipt_count() const;
#ifdef PINEFORGE_VALUE_INVALID_FIXTURES
    void fixture_value_invalid_drawdown_limit(double value, bool percent) noexcept {
        adapter_.fixture_value_invalid_drawdown_limit(value, percent);
    }
#endif
    bool fixture_cap_due_pending() const noexcept {
        return adapter_.cap.due_cause().has_value();
    }
    class FixtureQtyTypeSlot {
    public:
        explicit FixtureQtyTypeSlot(PineStrategyHost& host) noexcept : host_(host) {}
        FixtureQtyTypeSlot& operator=(QtyType value) noexcept {
            host_.config_.default_qty_type = static_cast<int>(value);
            return *this;
        }
        operator QtyType() const noexcept {
            return static_cast<QtyType>(host_.config_.default_qty_type);
        }
    private:
        PineStrategyHost& host_;
    };
    FixtureQtyTypeSlot fixture_default_qty_type_slot() noexcept {
        return FixtureQtyTypeSlot(*this);
    }
    class FixtureCommissionTypeSlot {
    public:
        explicit FixtureCommissionTypeSlot(PineStrategyHost& host) noexcept : host_(host) {}
        FixtureCommissionTypeSlot& operator=(CommissionType value) noexcept {
            host_.config_.commission_type = static_cast<int>(value);
            return *this;
        }
        operator CommissionType() const noexcept {
            return static_cast<CommissionType>(host_.config_.commission_type);
        }
    private:
        PineStrategyHost& host_;
    };
    FixtureCommissionTypeSlot fixture_commission_type_slot() noexcept {
        return FixtureCommissionTypeSlot(*this);
    }
    class FixtureRiskDirectionSlot {
    public:
        explicit FixtureRiskDirectionSlot(PineStrategyHost& host) noexcept : host_(host) {}
        FixtureRiskDirectionSlot& operator=(int value) noexcept {
            host_.adapter_.set_risk_direction(value);
            return *this;
        }
    private:
        PineStrategyHost& host_;
    };
    FixtureRiskDirectionSlot fixture_risk_direction_slot() noexcept {
        return FixtureRiskDirectionSlot(*this);
    }
    class SourceIdLedgerView {
    public:
        struct value_type { double second = 0.0; };
        class const_iterator {
        public:
            const value_type* operator->() const noexcept { return &value_; }
            bool operator==(const const_iterator& other) const noexcept {
                return present_ == other.present_;
            }
            bool operator!=(const const_iterator& other) const noexcept {
                return !(*this == other);
            }
        private:
            friend class SourceIdLedgerView;
            bool present_ = false;
            value_type value_{};
        };
        const_iterator find(const std::string& id) const noexcept {
            const double units = host_ ? host_->adapter_.source_unclosed_qty_for(id) : 0.0;
            const_iterator result;
            result.present_ = units > 0.0;
            result.value_.second = units;
            return result;
        }
        const_iterator end() const noexcept { return {}; }
    private:
        friend class PineStrategyHost;
        explicit SourceIdLedgerView(const PineStrategyHost* host) noexcept : host_(host) {}
        const PineStrategyHost* host_ = nullptr;
    };
    SourceIdLedgerView source_id_ledger_view() const noexcept {
        return SourceIdLedgerView(this);
    }
    // strategy.netprofit and, through current_equity(), strategy.equity and
    // the netprofit/openprofit percentages. TradingView charges an entry's
    // commission when the entry fills, so the entry fees the open lots have
    // paid (the share still on each lot) are already out of net profit;
    // strategy.openprofit (open_profit) stays gross of them
    // (tests/fixtures/open_entry_fee_charged). The engine's own accessors
    // keep the closed trades' figures.
    double net_profit() const { return BacktestEngine::net_profit() - open_entry_fees_paid(); }
    double current_equity() const {
        return BacktestEngine::current_equity() - open_entry_fees_paid();
    }
    // strategy.openprofit and the open part of strategy.equity, as generated
    // code reads them (open_profit(current_bar_.close)). TradingView marks the
    // open position at the tick-built close floor(close / mintick + 0.5) *
    // mintick, not at an off-grid close: NYSE:F 15m closes on half cents
    // (10.155 marks 10.15, 10.265 marks 10.27;
    // tests/fixtures/explicit_qty_floor). An on-grid close is read as it is.
    // The kernel's own marks (equity extremes, reports, sizing) keep
    // BacktestEngine::open_profit. The tick is syminfo_mintick_: a host that
    // sets no mintick marks on the engine's 0.01 default, the tick its fills
    // already round to, and a close within 1e-9 of a tick (relative to the
    // tick count) counts as on the grid.
    double open_profit(double current_price) const {
        return BacktestEngine::open_profit(script_mark_price(current_price));
    }
    // The price open_profit marks the position at: `price` itself, or its
    // tick when it lies off the mintick grid (ScriptRuleSwitches).
    double script_mark_price(double price) const;
    // Initial capital plus the closed trades' net profit: current_equity()
    // before the open lots' paid entry fees are charged.
    double closed_trade_equity() const { return BacktestEngine::current_equity(); }
    double open_entry_fees_paid() const;
    double signed_position_size() const;
    void freeze_script_position_view();
    void clear_script_position_view();
    // After a fill at the call flattened the book under a frozen position
    // view (the current-close exit, PoocCloseFillViewSwitches), the generated
    // strategy.position_avg_price read -- position_entry_price_ behind a
    // non-zero signed_position_size() -- keeps the pre-fill `average` until
    // the pass ends; release_script_average_price() then restores the flat
    // book's 0. Transient: never held across a pass boundary.
    void hold_script_average_price(double average);
    void release_script_average_price() noexcept;
    const Series<double>& source_series(const std::string&) const;
    const Series<double>& source_input_series(const std::string& key,
                                              const Series<double>& fallback) const;
    // Generated input.source() calls retain this established surface spelling.
    const Series<double>& get_input_source(const std::string& key,
                                           const Series<double>& fallback) const {
        return source_input_series(key, fallback);
    }
    // Generated strategy.margin_liquidation_price reads this: the kernel's
    // native_liquidation_price() in TradingView's tick spelling.
    double margin_liquidation_price() const;
    void fixture_publish_source_series(const Bar& bar, bool new_history_slot) {
        scheduler_.fixture_publish_source_series(bar, new_history_slot);
    }
    int64_t time_close() const {
        // Inside a foreign site's payload the requested context's bar closes
        // when its feed says it does: no calendar is guessed for the symbol.
        if (foreign_context_ != nullptr) return foreign_context_->close_ms;
        return chart_time_close();
    }
    int64_t chart_time_close() const;  // the chart bar's own (pine_strategy_host.cpp)
    // The close of the chart bar stamped `stamp`, as chart_time_close reads it.
    int64_t chart_bar_close_ms(int64_t stamp) const;
    // Pine v6 time() / time_close() reading another bar: bars_back and
    // timeframe_bars_back (pine_strategy_host.cpp). From the chart bar opening
    // at `bar_open_ms` (the current one), `bars_back` chart bars back -- na
    // before the first -- or, when negative, forward; then the `tf` bar (on
    // `session` / `tz`, as time() reads them) holding that chart bar, stepped
    // `timeframe_bars_back` of its own bars: back when positive, forward when
    // negative. Returns its open, or its close with `close`.
    int64_t pine_time_offset(int64_t bar_open_ms, int bars_back, const std::string& tf,
                             const std::string& session, const std::string& tz,
                             int timeframe_bars_back, bool close) const;
    // The symbol calendar's session day holding `ms` (open <= ms < close), or
    // null: no calendar, or an instant outside its days.
    const std::pair<std::int64_t, std::int64_t>* symbol_calendar_day(std::int64_t ms) const;
    // The first chart bar the symbol calendar opens at or after `at` -- a
    // slot of the chart's timeframe from its day's open, or the day's open on
    // a D/W/M chart -- or na outside the calendar's span.
    std::int64_t symbol_calendar_open_from(std::int64_t at) const;
    // The last chart bar the symbol calendar opens before `before`, or na
    // outside the calendar's span.
    std::int64_t symbol_calendar_open_before(std::int64_t before) const;
    // ab9714be pine_strategy_host.hpp:348-358: generated three-argument
    // session predicates are class-scope calls whose chart timeframe changes
    // the D/W/M meaning.  Keep that Pine policy in the source host; the
    // namespace-level overload remains the raw intraday time-of-day query.
    bool pine_session_ismarket(const std::string& session,
                               const std::string& timezone,
                               std::int64_t bar_ms) const {
        return pineforge::pine_session_ismarket(session, timezone, bar_ms, script_tf_);
    }
    bool pine_session_ispremarket(const std::string& session,
                                  const std::string& timezone,
                                  std::int64_t bar_ms) const {
        return pineforge::pine_session_ispremarket(session, timezone, bar_ms, script_tf_);
    }
    bool pine_session_ispostmarket(const std::string& session,
                                   const std::string& timezone,
                                   std::int64_t bar_ms) const {
        return pineforge::pine_session_ispostmarket(session, timezone, bar_ms, script_tf_);
    }
    const std::vector<FixtureIntentRow>& source_pending_view() const;
    // request.security registration, as generated configure_security_evaluators()
    // spells it. The kernel registers the aggregating evaluator; Pine's
    // publication semantics for the site (barmerge.lookahead, barmerge.gaps,
    // ticker.heikinashi, the lower-timeframe emulation a finer request
    // selects) are this host's, recorded for the sec_id it just registered.
    void register_security_eval(int sec_id, const std::string& requested_tf,
                                const std::string& input_tf, bool lookahead_on,
                                bool gaps_on = false, bool heikinashi = false);
    // request.security of ANOTHER symbol (lane XSYM-D): `symbol` is the
    // run-time string the script passes. The site reads the feed installed
    // for (symbol, requested_tf) through a kernel InstrumentFeed series: its
    // expression runs on every bar of that feed, in order -- history offsets
    // and TA state over the context's own bars, bar_index the context's,
    // time_close the bar's own close, syminfo.* the symbol's facts -- and the
    // chart bar reads the last bar the kernel's merge rule makes visible
    // (lookahead_on: open by the chart bar's open; otherwise closed by its
    // close). gaps_on reads na on a chart bar that received no new bar. A
    // symbol whose facts say it is invalid reads na with
    // ignore_invalid_symbol, and fails the run closed without it; so does a
    // site whose feed was not installed, naming the symbol and timeframe.
    void 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 = false,
                                bool ignore_invalid_symbol = false);
    // A string literal where input_tf stands, in five or six arguments, would
    // bind the same-symbol overload above (a pointer converts to bool ahead of
    // std::string) and read the symbol as its timeframe; it does not compile.
    void register_security_eval(int sec_id, const std::string& symbol,
                                const std::string& requested_tf, const char* input_tf,
                                bool lookahead_on, bool gaps_on = false) = delete;
    // The named column (strategy_set_symbol_feed_column) of the context bar a
    // foreign site is evaluating, or last evaluated; NaN when the site, the
    // column or the bar is unknown. Generated payload code reads it.
    double security_column_value(int sec_id, const std::string& name) const;
    // The recorded request series `key` on the current chart bar: the value
    // recorded for the bar that opened at current_bar_.timestamp, NaN where
    // the tape has no row. A key nobody installed fails the read closed,
    // naming it.
    double recorded_series_value(const std::string& key) const;
    // ``request.security_lower_tf`` registers the same per-sec_id eval
    // state but with the additional contract that the requested TF must
    // resolve to a finer-than-input TF emulation. This wrapper sets the
    // ``lower_tf_array_requested`` flag so ``validate_security_timeframes``
    // can throw a precise error if the chart's input TF turns out to be
    // <= the requested TF (mirroring TradingView's "lower timeframe
    // required" error for ``request.security_lower_tf``).
    void register_security_lower_tf_eval(int sec_id, const std::string& requested_tf,
                                         const std::string& input_tf);
    // Sub-bar index (0-based) of the current ``request.security_lower_tf``
    // synthesis within the current chart bar. Returns 0 outside the
    // synthesis loop. Used by codegen to clear its per-call vector at
    // sub-bar 0 and push one element per sub-bar after.
    int security_lower_tf_sub_bar_index(int sec_id) const;
    // TradingView's request.security / request.security_lower_tf timeframe
    // rules for the registered sites against the run's evaluator input
    // timeframe: the diagnostics a script author reads, the lower-timeframe
    // emulation each array site selects, and the publication gates a
    // finer-than-chart site runs under.
    void validate_security_timeframes(const std::string& input_tf);
    void source_stream_entry_comment(const PyramidEntry&, std::string&) const override;
    // The adapter's durable state rides the kernel's generic host seam.
    void hash_host_extension(BrokerStateHashSink&) const override;
    // Deprecated spelling, kept forwarding so a caller written against it
    // still reads this host's fold. final: the kernel folds
    // hash_host_extension, so an override of this name would never be folded.
    void hash_source_extension(BrokerStateHashSink& sink) const final {
        hash_host_extension(sink);
    }
 
private:
    friend class PineScheduler;
    friend class PineExecutionAdapter;
    friend struct ReportSinkEquityTestAccess;
    // One request.security site of ANOTHER symbol (register_security_eval with a
    // symbol key). Its payload runs in the requested context: on every bar of the
    // symbol's feed, in order, as the kernel hands the bars over through the
    // site's NativeSeriesSource::InstrumentFeed series -- or, on a calendar
    // chart, as soon as TradingView's merge rule makes a bar visible
    // (read_ahead_foreign_security_sites). The registration fields are the
    // site's; the rest is per run.
    struct ForeignSecuritySite {
        std::string symbol;         // the run-time key, exactly as the script passes it
        std::string requested_tf;   // the literal as registered ("" = the chart's)
        bool lookahead = false;       // barmerge.lookahead_on
        bool gaps = false;            // barmerge.gaps_on
        bool ignore_invalid = false;  // ignore_invalid_symbol
        // Per run: the feed key's timeframe (canonical spelling), whether the
        // symbol is invalid (the site then reads na throughout), the kernel
        // series the site reads (-1 when none), the feed the kernel serves it
        // from (an index into the installed feeds), the context bars the
        // payload has run on so far (the next one's bar_index and feed index),
        // and the close of the bar it ran on last. `eval` carries the
        // requested-context bar index into the payload's TA members; `syminfo`
        // is the context's SymInfo.
        std::string tf;
        bool invalid = false;
        std::int64_t subscription = -1;
        std::size_t feed = 0;
        std::int64_t delivered = 0;
        std::int64_t close_ms = 0;
        // The input the payload last ran on (-1: none yet): a gaps_on site
        // that received nothing on the current input reads na.
        std::int64_t last_input = -1;
        // The bars the kernel's series has handed over so far, the next one's
        // feed index. A bar the payload already ran on, because the merge
        // rule made it visible on an earlier chart bar, is handed over below
        // `delivered` and is not run again.
        std::int64_t handed = 0;
        SecurityEvalState eval{};
        SymInfo syminfo{};
    };
 
    StagedConfiguration staged_configuration() const;
    static PineStrategyConfig apply_overrides(PineStrategyConfig,
                                              const StrategyOverrides&);
    std::uint64_t adapter_broker_fill_event_sequence() const noexcept {
        return broker_fill_event_seq_;
    }
    void scheduler_prepare_script_run(PineScheduler::InputView,
                                      bool static_eligible, int expected_script_bars,
                                      bool script_bar_geometry);
    void scheduler_configure_security_evaluators();
    bool scheduler_uses_aux_security_feed() const noexcept;
    void scheduler_prepare_security_sequence(PineScheduler::InputView);
    // R5 lane R3b: the plain request.security sites of a batch run whose
    // input and script timeframes coincide are declared to the kernel as
    // NativeTimeframeSubscription series instances at the L6c begin-time hook
    // -- one per site, sec_id by index, barmerge.gaps_on as the kernel's
    // `gaps` -- and the kernel's own pump steps them; this host's evaluator
    // registration, per-run preparation and pump stand down for that run.
    // False, keeping this host's own drive, when the run or any site needs a
    // Pine-only rule the kernel step does not have: a stream (the kernel
    // takes confirmed bars only), the bar magnifier or an aggregated chart
    // (the calling-bar deferrals), the auxiliary feed, the range-start
    // cut and its OTC-daily pins, the historical lookahead projection,
    // barmerge.lookahead_on, ticker.heikinashi, request.security_lower_tf,
    // sec_ids that are not the registration order, or a declaration the
    // kernel refuses.
    bool declare_security_sites_to_kernel();
    // The same-symbol half of that predicate: true, with `declared` holding
    // one Input series per site, when every same-symbol site can be stepped
    // by the kernel; false (and `declared` untouched) otherwise.
    bool same_symbol_sites_routable(std::vector<NativeTimeframeSubscription>& declared);
    // Lane XSYM-D: the foreign sites' per-run resolution. Each site's feed and
    // facts are looked up, an InstrumentFeed series is appended to `declared`
    // for every site that reads one, and a site that can read nothing fails
    // the run closed (thrown, naming the symbol and timeframe).
    void prepare_foreign_security_sites(std::vector<NativeTimeframeSubscription>& declared);
    // The site's payload on the next bar of its feed, in the requested
    // context: `bar` and `close_ms` are that bar's own.
    void run_foreign_site_bar(ForeignSecuritySite& site, const Bar& bar, std::int64_t close_ms);
    // On a calendar chart, every foreign bar TradingView's merge rule makes
    // visible at `chart_bar` that the kernel has not handed over yet, run in
    // feed order after the input's deliveries (pine_security_eval.cpp).
    void read_ahead_foreign_security_sites(const Bar& chart_bar);
    // gaps_on foreign sites read na on an input that ran their payload on no
    // new bar: cleared at every chart bar, after the input's deliveries.
    void clear_gapped_foreign_security_sites();
    std::int64_t find_symbol_feed(const std::string& key, const std::string& tf) const;
    bool 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);
    bool set_recorded_series_reader_impl(
        const std::string& key, std::shared_ptr<const FeedReader<RecordedSeriesRow>> reader,
        std::optional<std::size_t> cache_capacity_bytes);
    void refresh_symbol_data_digest();
    std::uint64_t calculate_symbol_data_digest(
        const std::string* replacement_key = nullptr,
        const RecordedSeries* replacement = nullptr) const;
    // AR-R4: feed i's bars, closes and column values, wherever they are held:
    // this host's store, or the kernel's run spec while they are lent to it.
    const NativeInstrumentFeed& installed_symbol_feed(std::size_t i) const;
    // Copies lent bytes back from the kernel's spec, which keeps its own.
    void restore_symbol_feeds(); void stage_symbol_feed_views();
    // The same for a request-data door: the reason it failed, or empty.
    std::string restore_symbol_feeds_reason();
    // True while the running spec names this host's sites: the kernel steps
    // them and the scheduler feeds nothing.
    bool security_sites_kernel_routed() const noexcept;
    void init_security_eval_states_for_run(const std::string& effective_input_tf);
    void prepare_historical_security_lookahead_projections(
        const Bar* input_bars, int n_input, const std::string& effective_input_tf);
    void clear_historical_security_lookahead_projections();
    bool scheduler_feed_security_input(const Bar&, std::int64_t next_input_ms,
                                       bool calling_bar_complete,
                                       bool defer_boundary_gate);
    void scheduler_publish_security_boundary();
    void scheduler_feed_deferred_security_input(const Bar&, std::int64_t next_input_ms);
    void scheduler_feed_aux_security(int chart_index);
    void scheduler_feed_deferred_aux_security(int chart_index);
    void scheduler_finish_security_sequence();
    // Pine's evaluator step for one request.security site and one evaluator
    // input bar: the kernel's aggregation, native-bar substitution and
    // dispatch primitives, composed under TradingView's publication rules
    // (src/source/pine_security_eval.cpp).
    void pine_feed_security_eval_state(SecurityEvalState& state, const Bar& input_bar,
                                       bool calling_bar_complete = false);
    // The site's Pine semantics; a sec_id registered outside this host's
    // register_security_eval (none today) reads as a plain site.
    PineSecurityEvalState& pine_security_state(int sec_id) {
        return pine_security_states_[sec_id];
    }
    const PineSecurityEvalState& pine_security_state(int sec_id) const {
        static const PineSecurityEvalState plain{};
        const auto found = pine_security_states_.find(sec_id);
        return found == pine_security_states_.end() ? plain : found->second;
    }
    // Drops the entries of sec_ids the evaluator registry no longer holds.
    void prune_pine_security_states();
    // Range-start gate for one evaluator: true when the input bar at
    // `input_ts` belongs to an HTF bucket that opened before the cut --
    // security_range_start_ms_ under the flag, else the run's first chart
    // bar for a coarser-than-chart / chart-timeframe evaluator
    // (security_first_chart_bar_ms_, split-feed runs with the auxiliary feed
    // proving prior trading, or single-feed historical intraday forex/cfd D
    // requests keyed to their session's actual open; false for lower TFs). The
    // progressive feed and the historical lookahead projection builder must
    // agree on this predicate so projected child indexes line up with the
    // per-state feed cursor.
    bool security_input_precedes_range_start(const SecurityEvalState& state,
                                             int64_t input_ts) const;
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
    // True when the auxiliary request.security feed holds a bar in
    // [from_ms, to_ms): the evidence that an HTF bucket whose nominal open
    // precedes the run's first chart bar was in progress at the range start.
    bool aux_security_traded_between(int64_t from_ms, int64_t to_ms) const;
#endif
    // The calling chart bar's publication boundary for a gated site
    // (publish_gate_tf_seconds): re-publish the completed caller's final
    // requested value before the retained boundary input is fed.
    void publish_security_eval_state_at_calling_boundary(SecurityEvalState& state);
    void scheduler_record_range_end(const Bar&);
    void present_report(ReportC*) const override;
    // Pine presentation re-marks owning trade/equity arrays, including an
    // unbound host's future terminal quote. No bounded-state adapter exists.
    bool report_presenter_supports_non_full() const noexcept override { return false; }
    bool report_terminal_quote_eligible() const;
    std::int64_t report_quote_time_ms_ = -1;
    double report_quote_close_ = std::numeric_limits<double>::quiet_NaN();
    // One report point per published source slot. The kernel records it
    // (NativeReportPolicy::KernelRecordedAtHostMarks); this host owns only
    // the Pine cadence that says where the points fall.
    void scheduler_mark_report_point(std::int64_t script_bar_ts);
    void scheduler_record_broker_hash();
    void capture_script_continuation_hash();
    // The one writer of the session flags below: it selects the kernel's
    // session-day facts of the script bar being published, and widens the
    // chart's day by the pre- and post-market bars an extended chart holds.
    void scheduler_update_session_state();
    void update_extended_session_day(const NativeDecisionContext& facts);
    void adapter_label_bracket_trades(
        const native_order::ExecutionAppliedEvent&, bool from_bracket);
    bool adapter_has_open_entry_id(const std::string&) const;
    void scheduler_publish_source_bar(const Bar&, bool first_tick,
                                      bool advance_source_index = true);
    void scheduler_publish_suppressed_tail(const Bar&);
    // The selected window's pre-roll capture hooks (src/source/pine_intent_state.hpp):
    // nonvirtual, and no member of this class; the state is the consumer's host
    // state. Begin resets the buffer to the evaluation labelled `label_ms` and
    // opens its capture bracket; it answers false, doing nothing, unless the run is
    // selected and the label precedes the window. Finish records the evaluation's
    // end configuration and closes the bracket. A suppressed pre-roll tail runs no
    // body and clears the buffer to an empty evaluation.
    bool selected_begin_evaluation(std::int64_t label_ms);
    void selected_finish_evaluation() noexcept;
    void selected_clear_suppressed_evaluation(std::int64_t label_ms);
    // The selected window's replay of that buffer, nonvirtual like the hooks above.
    // At the first Open labelled inside the window, ahead of adapter_.on_bar_open,
    // the last pre-roll evaluation's rows go to the adapter's own doors once, in
    // their original order, each under its own configuration and retained point,
    // inside the consumer's open activation scope; then the same drains a source
    // evaluation ends with and the terminal explicit-market policy, submit-only.
    // It does nothing, and allocates nothing, for a run that is not selected and
    // for a label before the window. A broken precondition or a native failure
    // throws engine_invariant: the replay is never skipped quietly.
    void selected_replay_at_open(const Bar&, const NativeDecisionContext&);
    // The drains that close a source evaluation once its body has run: pending
    // closes, pending entries, bracket legs, relative exits and the same-point
    // entry order. The one list scheduler_publish_source_bar and the replay share.
    void finish_adapter_evaluation();
    void project_short_seed_report_rows(const native_order::ExecutionAppliedEvent&);
    void order_global_exit_children(const native_order::ExecutionAppliedEvent&);
    detail::CommandScratchStore* trade_scratch_ = nullptr;
    detail::CommandScratchStore& trade_scratch();
    std::optional<std::size_t> sort_same_bar_exit_trades(
        TradeLedger&, PineExecutionAdapter&);
    bool scheduler_coof_enabled() const noexcept { return config_.calc_on_order_fills; }
    // The range-end row an applied execution may complete. It stays ordered
    // after the fill's calc_on_order_fills recalculation, which can advance
    // the source bar counter, so it runs in whichever of the two callbacks is
    // last for that event.
    void record_applied_range_end();
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
    void clear_aux_security_chart_ranges();
    void prepare_aux_security_chart_ranges(const Bar*, int, const std::string&);
    std::int64_t aux_security_calling_close_ms() const;
    void feed_aux_security_for_chart_bar(int);
    void feed_deferred_aux_security_for_chart_bar(int);
#endif
 
protected:
    // @source-state begin
    PineExecutionAdapter adapter_;
    class SourceCloseObligationView {
    public:
        explicit SourceCloseObligationView(const PineExecutionAdapter& adapter) noexcept
            : adapter_(&adapter) {}
        bool pending() const noexcept {
            return adapter_ && adapter_->cap.due_cause().has_value();
        }
    private:
        const PineExecutionAdapter* adapter_ = nullptr;
    };
    // Retained protected spelling for source fixtures/generated code.  The
    // authoritative due request lives in IntradayCap; this read-only facade
    // prevents a second mutable close-obligation owner.
    SourceCloseObligationView position_close_obligation_{adapter_};
    PineStrategyConfig config_{};
    StrategyOverrides override_{};
    PineScheduler scheduler_{};
    // Generated strategies still use this source-series spelling directly.
    // The state remains scheduler-owned and is hashed by PineScheduler.
    bool& _src_series_active_;
    Series<double>& _src_open_;
    Series<double>& _src_high_;
    Series<double>& _src_low_;
    Series<double>& _src_close_;
    Series<double>& _src_volume_;
    Series<double>& _src_hl2_;
    Series<double>& _src_hlc3_;
    Series<double>& _src_ohlc4_;
    Series<double>& _src_hlcc4_;
    const bool& is_last_tick_;
    int source_bar_index_ = -1;
    int source_last_bar_index_ = -1;
    std::uint64_t source_callback_count_ = 0;
    bool source_configuration_captured_ = false;
    bool source_prepare_failed_ = false;
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
    std::vector<Bar> aux_security_bars_;
    std::string aux_security_input_tf_;
    std::vector<std::size_t> aux_security_chart_begin_;
    std::vector<std::size_t> aux_security_chart_end_;
    // R5 lane V19-E: the four above as the v4 extension folds them, digested
    // whenever they are set (never during a run): the fold reads one word
    // instead of every auxiliary bar.
    std::uint64_t aux_security_digest_ = 1469598103934665603ULL;
    void refresh_aux_security_digest() noexcept;
#endif
    // Per-sec_id request.security semantics (PineSecurityEvalState), keyed and
    // folded in sec_id order. An entry lives exactly as long as the kernel
    // evaluator state registered under the same sec_id: generated
    // configure_security_evaluators() opens with security_eval_states_.clear(),
    // so the first registration into an empty registry starts this table over.
    std::map<int, PineSecurityEvalState> pine_security_states_;
    // Lane XSYM-D: other symbols' data, installed before a run
    // (strategy_set_symbol_feed / _column / _facts, strategy_set_recorded_series)
    // and read by the foreign request sites. The feeds become the projected
    // spec's instrument feeds (keyed by the run-time symbol string and the
    // canonical timeframe spelling), so the kernel digests their bars; the
    // facts and tapes are this host's alone and fold through the digest
    // below, taken whenever they are set (never during a run).
    // AR-R4: one copy of the bytes. A configure the kernel applies takes each
    // feed's bars, closes and column values into its run spec (lent, below);
    // while lent, an entry here keeps its instrument, tf and column names --
    // all generated code reads of it -- and its bytes are read through
    // installed_symbol_feed(i). A door or the next begin copies them back.
    std::vector<NativeInstrumentFeed> symbol_feeds_;
    bool symbol_feeds_lent_ = false;
    std::map<std::string, SymbolFacts> symbol_facts_;
    std::map<std::string, RecordedSeries> recorded_series_;
    std::uint64_t symbol_data_digest_ = 1469598103934665603ULL;
    // The foreign sites in sec_id order, and per kernel series index the
    // foreign sec_id it serves (-1: a same-symbol series). Generated
    // configure_security_evaluators() registers the sites; on_native_run_begin
    // starts the table over.
    std::map<int, ForeignSecuritySite> foreign_security_sites_;
    std::vector<int> foreign_security_series_;
    // The accepted input being processed, as on_native_input last saw it; a
    // foreign site's deliveries are stamped with it.
    std::int64_t foreign_input_index_ = -1;
    // @source-state end
    // The foreign site whose payload is being evaluated: its requested
    // context answers pine_bar_index(), time_close() and syminfo_ for the
    // length of the dispatch, and nothing outside one. Never durable.
    struct BorrowedFeedSlot { const Bar* bars = nullptr; const std::int64_t* close_ms = nullptr; std::size_t size = 0; bool present = false; }; std::vector<BorrowedFeedSlot> symbol_feed_views_; const ForeignSecuritySite* foreign_context_ = nullptr;
 
    // Provider configuration, not book state: it is staged before a run and
    // projected into the adapter at begin, so it is waived from the durable
    // fold like the other configuration slots.
    bool margin_call_enabled_ = true;
 
    // Live-runtime tail overrides (spec §3.1 / §3.2), provider configuration
    // like margin_call_enabled_ above: consumed at begin and by the
    // scheduler's publication of the last script bar, never by broker
    // settlement. See set_realtime_tail / set_probe_suppress_tail_logic.
    bool realtime_tail_ = false;
    int realtime_tail_horizon_bars_ = 0;
    bool probe_suppress_tail_logic_ = false;
 
    // The script bar's session flags. Generated code reads session.isfirstbar
    // and session.islastbar from the next two -- and, as the transpiler lowers
    // them today, their _regular spellings as well, which the last two answer:
    // the plain pair is the chart's session day, widened by the pre- and
    // post-market bars an extended-hours chart holds, the _regular pair the
    // regular session's day, the kernel's facts as they are.
    // session_ismarket_ is the kernel's in-session fact. A generated chart
    // session.ismarket does not read it: it asks the session calendar at the
    // bar's open (the transpiler's _pf_session_market_ helper, e.g.
    // corpus/validation/symbol-specified/AAPL/session-ismarket-nyse-rth-01),
    // and one inside a request.security payload calls pine_session_ismarket
    // above. The flags were BacktestEngine members the kernel only cleared (R5
    // lane F5 moved them here). scheduler_update_session_state writes them
    // before each source callback and on_native_run_begin clears them;
    // derived from the kernel's session-day facts, they fold into no hash, as
    // the facts do not.
    bool session_ismarket_ = false;
    bool session_isfirstbar_ = false;
    bool session_islastbar_ = false;
    bool session_isfirstbar_regular_ = false;
    bool session_islastbar_regular_ = false;
    // TradingView's session calendar for the chart's symbol
    // (set_symbol_calendar), and the days the C ABI's syminfo metadata has
    // named since the last run began (index -> open / close,
    // "symbol_calendar_*"), installed and consumed when a run begins. Run
    // inputs, as the feed is: they fold into no hash.
    std::vector<std::pair<std::int64_t, std::int64_t>> symbol_calendar_;
    std::map<long long, double> symbol_calendar_opens_;
    std::map<long long, double> symbol_calendar_closes_;
    long long symbol_calendar_days_ = -1;
    void install_symbol_calendar_metadata();
 
    // Live-runtime tail (spec §3.1): once script_tf_seconds_ is known for
    // this run, freeze pine_last_bar_index()/last_bar_time_ at the horizon
    // bar instead of the fed array's actual last index. No-op unless
    // realtime_tail_ is on and realtime_tail_horizon_bars_ > 0.
    //
    // `script_bar_geometry` says whether `bars` is script-bar geometry:
    //   true  -- every run without aggregation (input_tf == script_tf, the
    //            single-TF run(bars, n) included: PineScheduler::run_begin
    //            passes !needs_aggregation), where the horizon
    //            indexes `bars` directly; last_bar_time_ is the EXACT
    //            timestamp of bars[horizon_bars - 1] when that bar exists,
    //            else extrapolated from the array's actual final bar.
    //   false -- `bars` is the *input* array under aggregation
    //            (needs_aggregation, input_tf < script_tf): indexing it by
    //            a script-bar horizon would land on the wrong input bar
    //            (final-rereview.md N1), so instead extrapolate from the
    //            first input bar's timestamp, one script-TF step per
    //            horizon bar (the pre-fix formula, restored for this path
    //            only).
    void apply_realtime_tail_horizon(const Bar* bars, int n, bool script_bar_geometry);
 
    // Opt-in chart warmup parity (see set_syminfo_metadata,
    // "chart_ema_na_warmup"). When enabled, chart-timeframe ta.ema instances
    // first used by on_bar na-warm per TV built-in semantics. This selector is
    // scoped independently from request.security so the two execution contexts
    // cannot leak their warmup mode into each other. Default OFF.
    bool chart_ema_na_warmup_ = false;
    // Independent opt-in HTF warmup parity. When enabled,
    // request.security series aggregate from security_range_start_ms_ instead
    // of the feed start and their embedded ta.ema na-warm per TV built-in
    // semantics. The cut is taken per evaluator on HTF-BUCKET opens, not on
    // input timestamps: an input bar is dropped when the D/W/M (or intraday
    // grid) bucket it belongs to opened before the range start, so the first
    // HTF bar every series sees is a whole bucket that opened at/after the
    // range start (security_input_precedes_range_start). Default OFF;
    // consulted only by pine_feed_security_eval_state, the auxiliary
    // lower-timeframe slice and the historical lookahead projection builder.
    bool security_range_start_na_warmup_ = false;
    int64_t security_range_start_ms_ = 0;
    // The run's first chart bar (0 outside a run). Without the flag above
    // this is the default cut for every coarser-than-chart and chart-
    // timeframe request.security aggregation: TradingView's deep-backtest
    // series of a timeframe hold the bars of that timeframe whose OPEN lies
    // at or after the range start, and the bucket in progress at the range
    // start is absent -- on every lane (round 8, family P: masayanfx
    // multi-time-score; lab tv famp-sense-{es15full,nq15full,f15full,
    // nifty15full,nifty1d,xau1d,xau15,eur15,eth15,btc1d}, 2026-09-05: "D"
    // on CME_MINI:ES1! 15m first reads on the 05-01 20:45Z bar (bucket 0 is
    // the 04-02 trade date; the 04-01 date opened 03-31 22:00Z before the
    // 04-01 00:00Z range start), "240" on 04-04 13:45Z (the 22:00Z bucket
    // dropped), "W" on the 08-29 / 08-28 bar on every 15m and 1D lane (the
    // Mon 03-31 week dropped), while "60" on a 00:00Z start and "D" on the
    // NYSE / NSE lanes (the chart's first bar IS the session open) keep
    // their first bucket). Whether the bucket was in progress is read from
    // the auxiliary 1m feed (did it trade between the bucket's nominal open
    // and the first chart bar? the NSE week whose Monday was a holiday opens
    // on Tuesday and is kept). Historical intraday single-feed forex/cfd D
    // requests also omit their partial first session, using its actual trading
    // open rather than its label. Other single-feed series keep their feed-start
    // behavior; native feeds retain their own rules. Lower-TF evaluators are
    // untouched (their slices begin at the first chart bar anyway), and the
    // flag above keeps its explicit epoch plus the EMA na-warmup semantics.
    int64_t security_first_chart_bar_ms_ = 0;
 
    // Nominal close (TradingView's time_close) of the CALLING chart bar the
    // input bar being fed belongs to; 0 = the input bar is the chart bar
    // (single-feed runs, streams). Set per native chart bar on the
    // split-feed path, where a finer auxiliary slice advances
    // request.security under a D/W/M chart bar whose close an OTC
    // calendar bucket compares against the period's nominal close
    // (TimeframeAggregator::feed(bar, next_input_ms, calling_close_ms)).
    int64_t security_calling_close_ms_ = 0;
 
    // Opt-in historical-only request.security lookahead projection. TradingView
    // can merge a completed higher-timeframe bar onto the first chart child
    // when a finite historical batch is already known. The normal path
    // remains progressive, and stream warmup/realtime deliberately ignore this
    // selector so future data can never leak into a live continuation.
    bool historical_security_lookahead_projection_ = false;
    bool historical_security_lookahead_projection_active_ = false;
 
    // Boundary-fallback publication replays the completed caller's already
    // evaluated final requested value. Force generated TA sites down their
    // recompute path so the replay advances merged history only, never the
    // requested-context TA cadence. True only inside
    // publish_security_eval_state_at_calling_boundary's own scope.
    bool security_history_publication_replay_ = false;
 
    // Read-only test projection cache; no future execution can observe it.
    mutable std::vector<FixtureIntentRow> source_pending_view_cache_;
 
    // Held units the applied request's precommit saw (the owner's pre-fill
    // position_qty_); cleared after the applied notification.
    mutable double precommit_held_units_ =
        std::numeric_limits<double>::quiet_NaN();
 
    // hold_script_average_price() wrote position_entry_price_ on the flat
    // book this pass; release_script_average_price() clears it.
    bool script_average_held_ = false;
    void finish_applied_admission(const native_order::ExecutionAppliedEvent&,
                                  const NativeDecisionContext&);
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
    void release_aux_security_chart_ranges();
#endif
};
 
using PineNativeHost = PineStrategyHost;
using FixtureIntentRow = PineStrategyHost::FixtureIntentRow;
using FixtureIntentKind = PineStrategyHost::FixtureIntentKind;
 
} // namespace pineforge::source