engine.hpp

Go to the documentation of this file.

#pragma once
#include <atomic>
#include <deque>
#include <vector>
#include <string>
#include <cstddef>
#include <cstdint>
#include <cmath>
#include <ctime>
#include <iterator>
#include <limits>
#include <memory>
#include <utility>
#include <set>
#include <algorithm>
#include <unordered_map>
#include <unordered_set>
#include <stdexcept>
#include <optional>
#include <functional>
#include <pineforge/execution_consumer.hpp>
#include "na.hpp"
#include "bar.hpp"
#include "broker_events.hpp"
#include "quantity_intent.hpp"
#include "execution.hpp"
#include "execution_close_scope.hpp"
#include "execution_close_selection.hpp"
#include "execution_projection.hpp"
#include "execution_reverse_to.hpp"
#include "position_close_obligation.hpp"
#include "order_cancellation.hpp"
#include "leg_activation.hpp"
#include "exit_leg_lifecycle.hpp"
#include "order_birth.hpp"
#include "series.hpp"
#include "timeframe.hpp"
#include "magnifier.hpp"
#include "session_time.hpp"
#include <pineforge/trade_ledger.hpp>
#include <pineforge/report_sequence.hpp>
// Suppress per-strategy function declarations (strategy_create, run_backtest, etc.) whose pf_*_t parameter types conflict with the internal C++ types
// used in codegen-emitted extern "C" blocks that include this header.
// NOTE: this macro leaks into every TU that includes engine.hpp; include
// pineforge.h FIRST in any TU that needs the per-strategy declarations
// (see src/c_abi.cpp).
#define PINEFORGE_NO_STRATEGY_DECLS
// Angle-bracket form is the installed public path (deliberate).
#include <pineforge/pineforge.h>
#include <pineforge/report_mode.h>
#include <pineforge/report_pages.hpp>
#include <pineforge/metrics_fold.hpp>
#include <pineforge/report_sink_writer.hpp>
#include <pineforge/detail/scratch_slab.hpp>
#include <pineforge/runtime_context.hpp>
// Generated script lifecycle users must be rebuilt against this runtime.
// These internal C++ capabilities change no public C POD or C signature.
#define PINEFORGE_HAS_TRADE_HISTORY_POLICY_V1 1
#define PINEFORGE_HAS_SCRIPT_RUN_PREPARE_V1 1
#define PINEFORGE_HAS_NATIVE_LIVE_V1 1
#define PINEFORGE_HAS_EQUITY_METRICS_FOLD_V1 1
namespace pineforge {
struct CacheCapacity;
struct CacheDefaults;
namespace metrics { struct ScratchCurveRegion; }
enum class PositionSide { FLAT, LONG, SHORT };
namespace report_sink { class ScratchCurveWriter; }
namespace report {
class SelectedReportStream;
class ReportReplay;
enum class EquityBasis : std::uint8_t;
}
// Physical emulator lot entry/exit in execution order; no range-end report rows. A reversal may produce several exits followed by an entry.
struct StreamOrderAction {
    uint64_t sequence = 0;
    int64_t timestamp_ms = 0;
    int32_t bar_index = 0;
    bool is_entry = false;
    bool is_long = false;
    double quantity = 0.0;
    double price = 0.0;
    std::string order_id;
    std::string comment;
    uint64_t entry_incarnation = 0;
    size_t closed_trade_index = static_cast<size_t>(-1); // engine-private provenance
};
 
// Forward declaration of an internal enum used by some BacktestEngine
// method signatures. The full definition lives in src/engine_internal.hpp
// (private to libruntime); only the underlying-type pin is needed here.
namespace internal {
enum class DualEntryStopPathWinner : int;
}
 
// ────────────────────────────────────────────────────────────────────
// Host-owned per-lot excursion accounting (RULING A48, one generic
// capability).  A host that declares ownership of a lot's favorable/adverse
// excursion supplies the closed-lot result from its own sampler; the kernel
// then neither samples excursion at matched trigger prices nor folds bar-path
// extremes into the closing row.  Everything below is source-blind: the facts
// are the lot's own booking coordinates plus the carried extremes, and the
// result is the two magnitudes the row reports, recorded exactly as answered
// (the row's account currency; any reporting basis is the owner's to apply).
// ────────────────────────────────────────────────────────────────────
struct ClosedLotExcursionFacts {
    uint64_t entry_incarnation = 0;
    int64_t entry_time_ms = 0;
    double entry_price = 0.0;
    double lot_qty = 0.0;
    double closed_qty = 0.0;
    double fill_price = 0.0;
    double carried_favorable = 0.0;
    double carried_adverse = 0.0;
    bool is_long = true;
    int entry_bar_index = -1;
    int exit_bar_index = -1;
    // The lot's own entry-bar excursion masks (PyramidEntry): the booking
    // facts of a priced intrabar fill, carried across the boundary so the
    // owner never has to be reachable from the closing row.
    bool entry_bar_high_masked = false;
    bool entry_bar_low_masked = false;
    // The closed slice's share of the lot's entry commission, in account
    // currency: the entry half of the closing row's `commission`.
    double entry_commission = 0.0;
    // The account-currency rate the closing row converts at: the rate its
    // P&L and its own excursion columns take, so an owner answering in the
    // row's currency converts at it too.
    double account_fx = 1.0;
};
 
struct ClosedLotExcursion {
    double favorable = 0.0;
    double adverse = 0.0;
};
 
using LotExcursionHook = std::function<ClosedLotExcursion(const ClosedLotExcursionFacts&)>;
 
// Where an opened lot's own fill sits on its entry bar's modeled path — the
// entry-side half of the excursion capability above, and the only thing the
// owner of a lot's excursion has to say about it.  OnPath names a fill at a
// price the path reaches, so the kernel derives which end (if either) the
// path had already reached before it; AfterPath names a fill at the bar's
// closing point, after the whole path, so both ends precede it.  The geometry
// is the kernel's: which leg is walked first and where a price is first
// touched are the same rules the matcher uses, and a host that forces the leg
// order does it once, through NativeRunSpec::path_order.
enum class OpenedLotFillPoint : std::uint8_t {
    OnPath = 0,
    AfterPath = 1,
};
 
struct PyramidEntry {
    double price;
    int64_t time;
    double qty;
    std::string entry_id;
    int entry_bar_index = -1;
    std::string entry_comment;
    double max_runup = 0.0;
    double max_drawdown = 0.0;
    // The lot's entry-bar excursion mask: which end of its entry bar the
    // modeled path had already reached before the lot's own opening fill.
    // The kernel derives both flags from the bar's path, walked in the leg
    // order the run declares, when the lot's excursion owner declares where
    // its fill sat (declare_opened_lot_entry_bar_mask), and hands them back
    // on the closing row's ClosedLotExcursionFacts; no kernel sampler reads
    // them. Both default false (nothing declared masks nothing).
    bool skip_entry_bar_high = false;
    bool skip_entry_bar_low = false;
    // Entry-leg commission in account currency at this slice's actual fill
    // boundary. Percentage commission depends on quote->account FX, so an
    // effective-time provider must not retroactively reprice this already-paid
    // fee when a later rate becomes active. Partial realization allocates this
    // paid cost proportionally and leaves only the unconsumed cost on the lot,
    // independently of the current fee schedule. NaN is reserved for legacy/
    // synthetic injection; every production entry path captures a real quote.
    double entry_commission_account =
        std::numeric_limits<double>::quiet_NaN();
    // Monotonic per-run identity of the request record object whose broker fill
    // created this physical lot. Unlike Pine's user-visible entry_id, an
    // incarnation is never reused by same-id replacements or later calls.
    // Every partial-close fragment copied from this lot therefore retains the
    // same physical-entry provenance. Zero is reserved for legacy/test-only
    // synthetic lots that were not created by a request record.
    uint64_t entry_incarnation = 0;
};
 
struct Trade {
    int64_t entry_time;
    int64_t exit_time;
    double entry_price;
    double exit_price;
    double qty;
    double pnl;
    double pnl_pct;
    bool is_long;
    int entry_bar_index = -1;
    int exit_bar_index = -1;
    std::string entry_id;
    std::string entry_comment;
    std::string exit_comment;
    std::string exit_id;
    // True when this trade's exit fill came from a REAL strategy.exit
    // bracket leg (stop/limit/trail/profit/loss), as opposed to a
    // strategy.close/close_all market close, a reversal-driven close, a
    // margin-call slice, or an intraday-cap close. The kernel never sets it:
    // its one writer is the Pine adapter, which labels the rows an exit-leg
    // fill closed (source::PineStrategyHost::adapter_label_bracket_trades). A
    // bare host's bracket leg reads BRACKET through close_cause below instead,
    // which the kernel records when the leg's owner armed it.
    // ABI v4 task 9: closed_trade_close_cause() reads this to distinguish
    // BRACKET (2) from SCRIPT (1), after the row's recorded close_cause, which
    // a margin-call or intraday-cap row carries instead.
    bool exit_from_bracket = false;
    double max_runup = 0.0;
    double max_drawdown = 0.0;
    double commission = 0.0;
    // Physical-entry provenance copied from PyramidEntry. This is deliberately
    // separate from entry_id: Pine permits user-visible IDs to be reused.
    uint64_t entry_incarnation = 0;
    // True for the range-end close of a position still open after the final
    // bar -- a report-only mark-to-market row
    // (NativeExecutionConsumer::append_open_position_report_rows); false for
    // every script-driven or bracket exit. Mirrors pf_trade_t::open_at_end.
    bool open_at_end = false;
    // Why this row exited, when the closer knew. A kernel-originated
    // liquidation or risk flatten carries its own cause through the settling
    // execution::Fill, and so does a close its owner's fill armed (Bracket;
    // the relation native_toolkit::submit_bracket builds); a host that runs
    // its own forced-close policy records its cause on the row. Unspecified
    // leaves closed_trade_close_cause() to the generic facts above
    // (open_at_end, exit_from_bracket).
    execution::CloseCause close_cause = execution::CloseCause::Unspecified;
};
 
struct TradeC {
    int64_t entry_time;
    int64_t exit_time;
    double entry_price;
    double exit_price;
    double pnl;
    double pnl_pct;
    int is_long;
    // Max Adverse/Favorable Excursion for the whole trade in account currency,
    // net of entry fees. max_runup is the peak favorable amount;
    // max_drawdown is the peak adverse amount.
    double max_runup;
    double max_drawdown;
    double qty;
    double commission;           // mirrors pf_trade_t tail; semantics documented in pineforge.h
    int32_t entry_bar_index;
    int32_t exit_bar_index;
    int32_t open_at_end;         // ABI v3: 1 on the range-end close row (pineforge.h)
};
 
struct SecurityDiagC {
    int sec_id;
    int64_t feed_count;
    int64_t eval_complete_count;
    int64_t eval_partial_count;
};
 
// Per-bar runtime trace entry. The transpiler's ``trace`` pragma emits
// ``trace(name, value)`` calls inside the generated ``on_bar`` so the
// validator can replay engine-internal series alongside TradingView's own
// per-bar plot data and pinpoint the bar/filter where divergence appears.
//
// ``name_id`` indexes into ``ReportC::trace_names`` — names are interned
// once per unique label so the per-call cost is push_back of a 24-byte POD
// rather than a string copy.
struct TraceEntryC {
    int64_t timestamp;
    int32_t bar_index;
    int32_t name_id;
    double value;
};
 
struct ReportC {
    int total_trades;
    TradeC* trades;
    int trades_len;
    double net_profit;
    int64_t input_bars_processed;
    int64_t script_bars_processed;
    int64_t security_feeds_total;
    int64_t security_eval_complete_total;
    int64_t security_eval_partial_total;
    int64_t magnifier_sub_bars_total;
    int64_t magnifier_sample_ticks_total;
    int input_tf_seconds;
    int script_tf_seconds;
    int script_tf_ratio;
    int needs_aggregation;
    int bar_magnifier_enabled;
    SecurityDiagC* security_diag;
    int security_diag_len;
    // Per-bar trace records emitted by ``BacktestEngine::trace`` calls. Both
    // arrays are heap-allocated by ``fill_report`` and freed by
    // ``free_report``; both are nullptr / 0-length when tracing was disabled
    // or no calls were made. ``trace_names`` is a flat name table — each
    // ``TraceEntryC.name_id`` indexes into it. Pointers in ``trace_names``
    // are stable C-strings owned by the live ``BacktestEngine`` instance
    // (its ``trace_names_`` vector); they remain valid until ``strategy_free``.
    TraceEntryC* trace;
    int trace_len;
    const char** trace_names;
    int trace_names_len;
    pf_metrics_t metrics;
    pf_equity_point_t* equity_curve;
    int64_t equity_curve_len;
    // ABI v4: per-script-bar broker-state hash (empty unless recording enabled).
    uint64_t* broker_state_hash;
    int64_t   broker_state_hash_len;
};
 
// Same words/values as docs/design/o1-report-contract.md in o1w-contract.
// The envelope lane owns the versioned provider API and its eligibility gate.
// O1 report envelope v1. Data and method declarations do not advertise
// runtime support; ReportC retains the layout introduced in ABI 4.
enum class ReportMode : std::uint32_t {
    FULL = PF_REPORT_MODE_FULL,
    SUMMARY_ONLY = PF_REPORT_MODE_SUMMARY_ONLY,
    STREAMED = PF_REPORT_MODE_STREAMED
};
 
struct ReportEnvelopeV1 {
    pf_report_metadata_v1 metadata;
    ReportC report;
};
 
// Engine-side admission input only. CGI emits the versioned module
// declaration alongside strategy.ids.freshPerBar; the loader binds that
// declaration to the actual module/presenter/mark implementation. A missing
// or unknown declaration, or an overridden presenter/mark, means PLAIN=no
// and today's byte-identical curve route.
struct MetricsPlainDeclarationV1 {
    std::uint32_t struct_size = sizeof(MetricsPlainDeclarationV1);
    std::uint32_t version = 1;
    std::uint32_t builtin_presenter = 0;
    std::uint32_t builtin_marks = 0;
    std::uint32_t builtin_scheduler = 0;
    std::uint32_t security_sites = 0;
    std::uint32_t lower_tf_sites = 0;
    std::uint32_t magnifier_declared = 0;
    std::uint32_t calculation_trigger = 0; // NativeCalculationTrigger word
    std::uint32_t calc_on_every_history_tick = 0;
};
struct MetricsPlainInputsV1 {
    const MetricsPlainDeclarationV1* declaration = nullptr;
    std::uint32_t module_contract_bound = 0;
    std::uint32_t historical_batch = 0;
    std::uint32_t equal_resolved_timeframes = 0;
    std::uint32_t timeframe_undetected = 0;
    std::uint32_t begin_bar_magnifier = 0;
    std::uint32_t intrabar_none = 0;
    std::uint32_t pending_selected_window = 0;
    std::uint32_t admitted_selected_window = 0;
    std::uint32_t realtime_tail = 0;
    std::uint32_t probe_suppress_tail_logic = 0;
    std::uint32_t builtin_host_marks = 0;
    std::uint32_t feed_tolerant_passthrough = 0;
    std::uint32_t calculation_trigger = 0;
    std::uint32_t final_admitted_view_bound = 0;
};
 
static_assert(sizeof(ReportC) == sizeof(pf_report_t),
              "legacy C and C++ report sizes must match");
static_assert(offsetof(ReportEnvelopeV1, report)
                  == offsetof(pf_report_envelope_v1, report),
              "versioned report payload offsets must match");
static_assert(sizeof(ReportEnvelopeV1) == sizeof(pf_report_envelope_v1),
              "versioned C and C++ report sizes must match");
 
// Reopened here so the row source and the engine it borrows live in the same
// ABI epoch (the inline namespace is the same one that holds BacktestEngine).
inline namespace engine_script_run_v20 {
class BacktestEngine;
 
// O1 R12: the terminal range-end row source.
//
// A run that ends with P physical lots open reports one row per lot. The mark
// resolves a host's excursion answers once, retains those numeric facts in
// bounded scratch, and validates every row before publishing the generation.
// Every reader then rebuilds one row at a time from the lot, terminal mark,
// account FX and retained answer through the same builder a full close uses.
// Resident storage is constant in P: no row array and no per-lot string copy.
//
// materialize() is the legacy borrowed-pointer boundary. Only the C accessors
// that hand out a string pointer (materialize_report_trade and its callers)
// need a row that outlives the call; it keeps exactly those rows, as
// the old vector did, and is documented non-flat. Report construction, folds
// and sink emission never call it.
class OpenReportRowSource {
public:
    OpenReportRowSource() = default;
    explicit OpenReportRowSource(const BacktestEngine* owner) : owner_(owner) {}
    OpenReportRowSource(const OpenReportRowSource&) = default;
    OpenReportRowSource& operator=(const OpenReportRowSource&) = default;
    // A new run's terminal mark replaces the previous one; the C accessors'
    // retained rows belong to the replaced generation.
    void clear() noexcept;
    void begin(double mark_price, std::int64_t mark_time_ms, int interval_index,
               double account_fx, bool was_long, std::size_t count);
    // The exact left fold append_open_position_report_rows returned.
    void set_pnl(double pnl) noexcept { pnl_ = pnl; }
    bool empty() const noexcept { return size() == 0; }
    std::size_t size() const noexcept { return present_ ? count_ : synthetic_.size(); }
    double pnl() const noexcept { return pnl_; }
    // One detached row, built exactly as the range-end append builds it.
    Trade row(std::size_t index) const;
    // Legacy borrowed-pointer materialization, for the C string accessors and
    // for tests that seed a row with no live lot.
    const Trade& materialize(std::size_t index) const;
    const Trade& operator[](std::size_t index) const { return materialize(index); }
    // Reference-oracle seeding only: a synthetic report row with no live lot.
    // Production writers pin a terminal mark instead; the two never coexist
    // because begin() replaces the generation.
    void push_back(const Trade& row) { synthetic_.push_back(row); pnl_ += row.pnl; }
    void push_back(Trade&& row) { pnl_ += row.pnl; synthetic_.push_back(std::move(row)); }
    class const_iterator {
    public:
        using iterator_category = std::forward_iterator_tag;
        using value_type = Trade;
        using difference_type = std::ptrdiff_t;
        using reference = Trade;
        using pointer = void;
        const_iterator() = default;
        Trade operator*() const { return source_->row(index_); }
        const_iterator& operator++() { ++index_; return *this; }
        const_iterator operator++(int) { auto old = *this; ++*this; return old; }
        bool operator==(const const_iterator& other) const {
            return source_ == other.source_ && index_ == other.index_;
        }
        bool operator!=(const const_iterator& other) const { return !(*this == other); }
    private:
        friend class OpenReportRowSource;
        const_iterator(const OpenReportRowSource* source, std::size_t index)
            : source_(source), index_(index) {}
        const OpenReportRowSource* source_ = nullptr;
        std::size_t index_ = 0;
    };
    const_iterator begin() const { return const_iterator(this, 0); }
    const_iterator end() const { return const_iterator(this, size()); }
private:
    struct OwnedExcursions;
    Trade build_row(std::size_t index, bool consult_excursion_hook) const;
    const BacktestEngine* owner_ = nullptr;
    bool present_ = false;
    bool was_long_ = false;
    double mark_price_ = 0.0;
    std::int64_t mark_time_ms_ = 0;
    int interval_index_ = 0;
    double account_fx_ = 1.0;
    std::size_t count_ = 0;
    double pnl_ = 0.0;
    // Published generations share immutable report facts, not continuation
    // state. Only a host-owned excursion needs this external numeric store.
    std::shared_ptr<const OwnedExcursions> excursions_;
    // A deque gives every retained row a stable address, so a reference a C
    // accessor handed out survives the next row's materialization, as a
    // reference into the old vector did.
    mutable std::deque<Trade> materialized_;
    // Reference-oracle rows with no live lot (tests only; production leaves
    // this empty).
    std::vector<Trade> synthetic_;
};
}  // inline namespace engine_script_run_v20
 
using ExitLegLifecycle = exit_legs::Lifecycle;
 
// default_qty_type constants (matches TradingView)
enum class QtyType { FIXED = 0, PERCENT_OF_EQUITY = 1, CASH = 2 };
 
// commission_type constants
enum class CommissionType { PERCENT = 0, CASH_PER_ORDER = 1, CASH_PER_CONTRACT = 2 };
 
// Pine user enum → str.tostring (field payloads). Transpiler enforces enum decl before
// input.enum; this clamps the index so bad values never read past the table.
struct SymInfo {
    std::string ticker = "UNKNOWN";
    std::string tickerid = "UNKNOWN";
    std::string currency = "USD";
    std::string basecurrency = "";
    std::string type = "crypto";
    std::string timezone = "UTC";
    std::string session = "24x7";
    std::string volumetype = "base";
    std::string description = "";
    double mintick = 0.01;
    double pointvalue = 1.0;
    // Per-instrument quantity step (syminfo.* "qty_step", the smallest tradable
    // lot increment, e.g. 0.0004 for BINANCE:ETHUSDT.P). A declared qty_step, or
    // a finite mincontract > 0 while no qty_step is declared, sets the grid.
    // 0 = disabled (the engine default): no quantization, corpus instruments
    // stay byte-identical. A host that sizes in lots declares it as the run
    // spec's quantity_grid, where admission requires on-grid units and the
    // kernel's liquidation floors an off-grid slice onto it.
    double qty_step = 0.0;
};
 
// Value-owned runtime input transport shared by the public rich run overload
// and the generic native pre-begin provider.  It contains no frontend policy.
using InputsMap = std::unordered_map<std::string, std::string>;
 
// The C++ subclass contract is internal, unlike pineforge.h's stable C ABI.
// Changing its layout or vtable requires all generated/native C++ objects to be rebuilt.
// v6 adds explicit owner-bound exit-leg activation and Pine placement evidence.
// Version the mangled class name so older headers' member offsets/vtable cannot
// silently bind out-of-line members of this different object layout.
inline namespace engine_script_run_v20 {
// The fold broker_state_hash() is built on: FNV-1a over a canonical byte
// spelling of each value (-0.0 folds as 0.0, every NaN as one quiet NaN, a
// string as its length then its bytes). It is a public, complete type because
// a host writes into it: BacktestEngine::hash_host_extension receives the sink
// the kernel has already folded its own broker state into, and whatever the
// host folds after that is part of every scalar, per-bar and stream hash of
// the run. Begin an extension with a domain tag of your own (`sink.s(...)`),
// then fold each durable value in a fixed order.
class BrokerStateHashSink {
public:
    uint64_t h = 1469598103934665603ULL;
 
    void bytes(const void* p, size_t n) {
        const unsigned char* c = static_cast<const unsigned char*>(p);
        for (size_t i = 0; i < n; ++i) { h ^= c[i]; h *= 1099511628211ULL; }
    }
 
    void d(double v) {
        if (v == 0.0) v = 0.0;
        if (v != v) v = std::numeric_limits<double>::quiet_NaN();
        bytes(&v, sizeof v);
    }
 
    void i(int64_t v) { bytes(&v, sizeof v); }
    void u(uint64_t v) { bytes(&v, sizeof v); }
    void b(bool v) { const unsigned char c = v ? 1 : 0; bytes(&c, 1); }
    void s(const std::string& v) { u(v.size()); bytes(v.data(), v.size()); }
};
// Optional frontend projection interface retained for source compatibility.
// Broker dispatch itself is virtual on BacktestEngine and never discovers a
// host kind with RTTI.
class BrokerStateHashProvider {
public:
    virtual ~BrokerStateHashProvider() = default;
    virtual std::uint64_t broker_state_hash_projection() const = 0;
};
class BacktestEngine {
protected:
    // The consumer is the kernel's own execution authority, so this
    // friendship is also the access path for the request.security feed
    // machinery a native higher-timeframe subscription drives:
    // register_security_eval, prepare_native_security_feeds and
    // feed_security_eval_state stay protected members of this class and are
    // still out of reach of host code, while the consumer calls them at
    // begin and from its accepted-input path. No member moved and no
    // behaviour changed for this.
    friend class NativeExecutionConsumer;
    friend class NativeStrategyHost;
    // The terminal range-end row source rebuilds rows through the engine's
    // non-mutating close builder and reads the live lots.
    friend class OpenReportRowSource;
    struct NativeConsumerBindTag { explicit NativeConsumerBindTag() = default; };
    explicit BacktestEngine(NativeConsumerBindTag);
    IExecutionConsumer& execution_consumer();
    const IExecutionConsumer& execution_consumer() const;
    // The host's own durable state, folded last into broker_state_hash():
    // called exactly once per hash, after the kernel's generic broker state.
    // A host whose next decision depends on state the kernel does not own — a
    // regime, a counter, a model — overrides this and folds it, under its own
    // domain tag, so a replay that diverges there diverges in the hash. The
    // override replaces the default; call BacktestEngine::hash_host_extension
    // first to keep the default's bytes and append to them. A host that
    // overrides nothing folds exactly what it always folded: the default
    // forwards to the deprecated spelling below, whose default is the
    // "source:none" marker.
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    virtual void hash_host_extension(BrokerStateHashSink&) const;
    // Deprecated spelling of hash_host_extension, named by the source layer
    // before a bare host could extend the fold. Still folded when it is the
    // only one overridden, so an existing subclass compiles and hashes
    // unchanged; the kernel itself calls hash_host_extension only.
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    virtual void hash_source_extension(BrokerStateHashSink&) const;
    virtual std::uint64_t broker_state_hash_projection() const;
    std::uint64_t broker_state_hash_from_execution_hash(std::uint64_t) const;
    // --- Position state ---
    // @broker-state begin
    PositionSide position_side_ = PositionSide::FLAT;
    double position_entry_price_ = 0.0;   // volume-weighted average (for strategy calculations)
    // Owned, consumable post-fill checkpoint. The shared successful-fill
    // dispatcher supplies its producer and position identities; economic
    // eligibility is decided there, independently of this lifecycle model.
    broker::OpeningObligations opening_obligations_;
    int64_t position_entry_time_ = 0;
    // Position is FLAT until the first opening fill. The canonical accessor
    // ``signed_position_size`` already reads 0 when FLAT whatever this holds,
    // but the settlement and every host that reads position_qty_ directly
    // must see the same 0 on the first call of a run, so the default is 0
    // and the two reads stay aligned.
    double position_qty_ = 0.0;
    int position_entry_count_ = 0;  // number of entries in current direction (for pyramiding)
    int position_open_bar_ = -1;    // bar_index_ when position was opened (for exit delay)
    // Exact position-instance provenance for pending orders whose semantics
    // depend on the position cycle in which they were placed. A fresh open or
    // reversal gets a new nonzero id; same-direction pyramid adds retain it.
    int64_t position_cycle_seq_ = 0;
    int64_t next_position_cycle_seq_ = 1;
    std::vector<PyramidEntry> pyramid_entries_;  // individual entries for trade reporting
 
    // --- Strategy parameters (set from strategy() declaration) ---
    double initial_capital_ = 1000000.0;
    // Detached on bare native construction. Only the explicit Pine frontend
    // attachment can select its source-shape priority interpretation.
    CommissionType commission_type_ = CommissionType::PERCENT;
    double commission_value_ = 0.0;
    int slippage_ = 0;              // slippage in ticks
    double syminfo_mintick_ = 0.01; // tick size for slippage calculation
    // Per-instrument lot-size step (the instrument's quantity increment).
    // 0 = disabled (default; corpus no-op). Fed via the syminfo_metadata channel
    // ("qty_step", or a finite "mincontract" > 0 while no qty_step is declared)
    // or the SymInfo struct on the explicit run() path. The kernel's own readers
    // are the apply_*qty_step floors below; a host that sizes in lots declares
    // the step as the run spec's quantity_grid (the source host projects it).
    double qty_step_ = 0.0;
    // Account-currency FX multiplier for every quote->account money path:
    // equity is denominated in the account currency and a position's notional
    // in the quote currency, so commission, P&L and the margin comparison
    // convert the notional at this rate (a Pine ``currency=currency.XXX``
    // that differs from the symbol's quote currency, e.g. currency.INR on a
    // USDT-quoted perp, is how the adapter comes to set it). The engine
    // otherwise assumes account == quote (FX 1.0). Injected via the syminfo metadata
    // channel (key "account_currency_fx"); defaults to 1.0 so every corpus
    // strategy (which never sets it) is byte-identical. A timestamped provider
    // may override it as bars advance; the configured scalar remains the
    // fallback before the provider's first effective point and across reruns.
    double account_currency_fx_ = 1.0;
    std::vector<int64_t> account_currency_fx_timestamps_;
    std::vector<double> account_currency_fx_rates_;
    // Per-run broker clock for timestamped FX.  The epoch is the number of
    // provider points effective at the current script-bar open (0 means the
    // scalar fallback).  Consuming an epoch even while flat prevents a later
    // entry from being mistaken for a carried position when the rate has not
    // changed again.
    bool account_currency_fx_broker_epoch_initialized_ = false;
    std::size_t account_currency_fx_broker_epoch_ = 0;
    double account_currency_fx_broker_rate_ = 1.0;
 
    int64_t trade_start_time_ = std::numeric_limits<int64_t>::min();
 
 
    // --- SymInfo + Input injection ---
    SymInfo syminfo_;
    int64_t last_bar_time_ = 0;
    int last_bar_index_ = 0;
    // Forced intrabar path order (ABI v4 live-runtime surface, task 4): 0
    // AUTO, 1 HIGH_FIRST, 2 LOW_FIRST. Any other value is clamped to AUTO by
    // set_path_order() -- this member is always one of {0,1,2}. Persistent
    // configuration -- reset_run_state() does not touch it. See
    // set_path_order(). No kernel path reads it: native-bound source hosts
    // project it into NativeRunSpec::path_order at begin, so the native
    // driver owns the active batch/stream path order.
    int path_order_mode_ = 0;
    // Retained last-array-bar visibility flag (waived from the fold). The
    // probe tail suppression it once gated is the source host's (see
    // set_probe_suppress_tail_logic below); no kernel path reads it.
    bool is_tail_bar_ = false;
    // Chart's display timezone — separate from ``syminfo_.timezone`` (the
    // exchange TZ). Set by ``set_chart_timezone`` / the C ABI's
    // ``strategy_set_chart_timezone``. See the doc on ``set_chart_timezone``
    // for why these two TZ slots must NOT alias.
    std::string chart_timezone_;
    std::unordered_map<std::string, std::string> inputs_;
 
    // Injected symbol metadata (syminfo.shares_outstanding_*,
    // recommendations_*, target_price_*, pricescale, minmove, …). These
    // have no source in an OHLCV feed, so the engine returns na<double>()
    // unless a data feed pushes a value via ``set_syminfo_metadata``. Keyed
    // by the Pine member name (e.g. "shares_outstanding_total").
    std::unordered_map<std::string, double> syminfo_metadata_;
 
    // Input injection helpers for generated code
    double get_input_double(const std::string& key, double default_val) const;
    int get_input_int(const std::string& key, int default_val) const;
    int64_t get_input_int64(const std::string& key, int64_t default_val) const;
    bool get_input_bool(const std::string& key, bool default_val) const;
    std::string get_input_string(const std::string& key, const std::string& default_val) const;
 
    // syminfo.* fundamental/exchange metadata that has no OHLCV source.
    // Returns the value injected via ``set_syminfo_metadata`` for ``key``,
    // or na<double>() when none was injected. Codegen routes the
    // na-by-default SYMINFO_MEMBER_MAP double fields here.
    double get_syminfo_metadata(const std::string& key) const {
        auto it = syminfo_metadata_.find(key);
        return it != syminfo_metadata_.end() ? it->second : na<double>();
    }
 
    // --- Runtime state ---
    Bar current_bar_;
    int bar_index_ = 0;
    // Timestamp of the input bar that FOLLOWS the one being fed to the
    // request.security evaluators; 0 = unknown (streams, the feed's last
    // bar). A historical run holds its whole feed, and the calendar
    // aggregator uses the hint to finalize a D/W/M bucket on the period's
    // actual last chart bar -- early closes and exchange holidays included
    // (TimeframeAggregator::feed(bar, next_input_ms)). Set by whoever pumps
    // the evaluators, for each bar it feeds; never for a stream's live input.
    int64_t security_next_input_ms_ = 0;
    uint64_t next_order_incarnation_ = 1;
    // Transient companion for trail exits: the trail's best (peak) price at
    // fill time, a pre-fill favorable excursion of the closing trade that
    // first_touch_position cannot place on the bar path (the level is only
    // active after the peak). The settlement hands it to
    // build_close_trade_with_costs as the context's preceding_exit_trail_peak.
    // NaN = not a trail fill -- and nothing in the tree assigns it anything
    // else today (reset_run_state writes the NaN), so that fold never fires;
    // it stays because it is hashed broker state (engine_state_hash.cpp).
    double fold_exit_trail_peak_ = std::numeric_limits<double>::quiet_NaN();
    TradeLedger trades_;
    // Report-only rows for a position still open when the feed ends, produced
    // by NativeExecutionConsumer::record_open_position_report_rows when the
    // spec asks for them (NativeRunSpec::report_open_position_at_end). They
    // are merged behind trades_ by fill_trades_section and never enter
    // trades_, the realized sums, or the live position (a stream continues it).
    // R12: the source stores only the terminal mark; see OpenReportRowSource.
    OpenReportRowSource range_end_trades_{this};
 
    // Best favorable price is updated by the physical open/add helpers for
    // every host. Source policy may consume the same value through
    // inheritance, while the public C observer uses the virtual projection.
    double trail_best_price_ = std::numeric_limits<double>::quiet_NaN();
 
    // Generic synchronous close obligation. Pine quota/cause/beneficiary
    // state remains exclusively in the compatibility facade above.
    broker::PositionCloseObligation position_close_obligation_;
 
    // --- Cached trade metrics (updated incrementally by record_close_trade) ---
    double net_profit_sum_ = 0.0;
    // Conservative absolute roundoff accumulated by additions to the cached
    // net-profit sum. This is numerical provenance only: reported PnL and
    // equity continue to use the unchanged sum above. Infinity means a
    // narrower margin comparison cannot be justified from this history.
    double net_profit_roundoff_bound_ = 0.0;
    // The net value whose additions this bound tracked. Direct/synthetic or
    // future restore writes without matching provenance cannot narrow the
    // established margin comparison; the next trade makes them unbounded.
    double net_profit_roundoff_value_ = 0.0;
    double gross_profit_sum_ = 0.0;
    double gross_loss_sum_ = 0.0;
    int win_trades_count_ = 0;
    int loss_trades_count_ = 0;
 
    // --- Equity extremes for max_drawdown / max_runup ---
    double max_equity_ = 0.0;    // peak equity for drawdown
    double max_drawdown_ = 0.0;  // maximum drawdown (positive number)
    double max_runup_ = 0.0;     // maximum runup (positive number)
    double min_equity_ = 0.0;    // trough equity for runup
 
    // --- Per-script-bar equity curve (metrics + pf_report_t exposure) ---
    // SUMMARY_ONLY uses exactly one editable point; the fixed prefix lives
    // outside the broker-state region below.
    std::vector<pf_equity_point_t> equity_curve_;
    int64_t bars_in_market_ = 0;     // script bars with an open position at close
    double first_bar_open_ = std::numeric_limits<double>::quiet_NaN();  // buy&hold basis
 
    // --- Per-script-bar broker-state hash recording (ABI v4 live-runtime
    // surface, task 6). Default off: empty vector, empty report array,
    // every historical run byte-identical to before this flag existed. See
    // set_broker_state_hash_recording() and broker_state_hash(). ---
    bool broker_state_hash_recording_ = false;
    std::vector<uint64_t> broker_state_hashes_;
 
    // --- Position-size extremes (strategy.max_contracts_held_*) ---
    double max_contracts_held_all_ = 0.0;
    double max_contracts_held_long_ = 0.0;
    double max_contracts_held_short_ = 0.0;
 
    // --- Even-trade counter (strategy.eventrades) ---
    int eventrades_count_ = 0;
 
    // @broker-state end
 
    // Output-only O1W state, deliberately outside the broker-state region.
    // Like equity_curve_, it never supplies an execution decision. The
    // derived broker-prefix helper restores the ALREADY HASHED four extrema;
    // it adds no broker leaf and changes no existing hash domain.
    ReportMode pending_equity_report_mode_ = ReportMode::FULL;
    ReportMode active_equity_report_mode_ = ReportMode::FULL;
    metrics::EquityMetricsFold summary_equity_fold_;
    mutable metrics::EquityFoldSnapshot summary_equity_snapshot_;
    mutable bool summary_equity_snapshot_valid_ = false;
    mutable bool summary_equity_ratios_ready_ = false;
    std::optional<metrics::EquityRatioResult> summary_equity_ratios_;
    double summary_broker_equity_prefix_[4]{};
 
    // Output-only streaming-ratio state, like the summary fold above: no broker decision
    // reads it and report policy must not change continuation hashes. The
    // fold witnesses its ordered FINAL points. Copies inherit preferences,
    // never another attempt's admission, provider, fold or receipt.
    struct MetricsStreamingStateV1 {
        metrics::MetricsStreamingConfigV1 configuration;
        metrics::MetricsStreamingConfigV1 prepared_configuration;
        metrics::MetricsStreamingConfigV1 run_configuration;
        metrics::MetricsExtentPlanV1 pending_plan;
        bool pending_plain = false, prepared = false;
        std::uint64_t pending_failed_plain_inputs = 0;
        bool active = false, plain = false, no_curve = false;
        std::int64_t points = 0;
        std::unique_ptr<metrics::StreamingEquityRatiosV1> fold;
        metrics::MetricsExtentReceiptV1 receipt;
        metrics::MetricsStreamingResultV1 result;
        bool receipt_final = false;
        MetricsStreamingStateV1() = default;
        MetricsStreamingStateV1(const MetricsStreamingStateV1& other) {
            configuration.streaming_sharpe = other.configuration.streaming_sharpe;
            configuration.metrics_needed = other.configuration.metrics_needed;
        }
        MetricsStreamingStateV1& operator=(const MetricsStreamingStateV1& other) {
            if (this != &other) *this = MetricsStreamingStateV1(other);
            return *this;
        }
        MetricsStreamingStateV1(MetricsStreamingStateV1&&) noexcept = default;
        MetricsStreamingStateV1& operator=(MetricsStreamingStateV1&&) noexcept = default;
    };
    mutable MetricsStreamingStateV1 metrics_streaming_;
    class MetricsStreamingAttemptV1 {
        BacktestEngine& engine_;
    public:
        explicit MetricsStreamingAttemptV1(BacktestEngine& engine) : engine_(engine) {}
        ~MetricsStreamingAttemptV1() {
            // A refused preflight also consumes the external attempt binding.
            // Construction inspects no plan/feed and changes no failure order.
            auto& s = engine_.metrics_streaming_;
            s.pending_plain = s.prepared = false;
            s.pending_plan = {};
            s.pending_failed_plain_inputs = 0;
        }
        MetricsStreamingAttemptV1(const MetricsStreamingAttemptV1&) = delete;
        MetricsStreamingAttemptV1& operator=(const MetricsStreamingAttemptV1&) = delete;
    };
    void begin_metrics_streaming_v1(bool admitted_shape);
    void sync_metrics_streaming_held_v1() const;
    void finish_metrics_streaming_v1(
        metrics::MetricsRatioCurveV1, pf_equity_stats_t* = nullptr) const;
    template<class Source>
    void observe_metrics_curve_v1(const Source& curve, std::int64_t count,
                                  pf_equity_stats_t* equity = nullptr) const {
        finish_metrics_streaming_v1(
            {const_cast<Source*>(&curve), count,
             [](void* context, std::int64_t index) {
                 return (*static_cast<const Source*>(context))[index];
             }}, equity);
    }
 
public:
    // Separate equity-mode helper; set_report_mode_v1 does not call it. The envelope owner must
    // first establish replay/presentation eligibility and all OTHER sequence
    // policies. This helper alone does not advertise a complete mode provider.
    // Status values follow the versioned contract: accepted=0, invalid=-1,
    // busy=-3, conflict=-4, replay unavailable=-5 (SUMMARY_ONLY with a
    // registered execution observer). A refusal preserves the pending mode.
    // Configuration takes effect at the next run begin.
    int set_equity_report_mode(ReportMode mode);
    ReportMode equity_report_mode() const {
        return active_equity_report_mode_;
    }
    std::int64_t equity_logical_point_count() const {
        return active_equity_report_mode_ == ReportMode::SUMMARY_ONLY
                || metrics_streaming_.no_curve
            ? summary_equity_fold_.first_pass().point_count
            : static_cast<std::int64_t>(equity_curve_.size());
    }
    // Frozen presented first pass from the latest equity-metric assembly.
    // The envelope copies its count with captured=0/external=0. No curve
    // pointer is exposed. A pending second pass cannot certify completion.
    const metrics::EquityFoldSnapshot* equity_summary_snapshot() const {
        return summary_equity_snapshot_valid_ ? &summary_equity_snapshot_ : nullptr;
    }
    bool equity_summary_ratios_ready() const { return summary_equity_ratios_ready_; }
    bool install_equity_ratio_result(const metrics::EquityRatioResult& result) {
        if (!summary_equity_snapshot_valid_ || !result.matches(summary_equity_snapshot_))
            return false;
        summary_equity_ratios_ = result;
        summary_equity_ratios_ready_ = true;
        return true;
    }
 
protected:
    // Consumer terminal/range-end integration calls this BEFORE its legacy
    // full-array refold. No history is reread. The prefix excludes the held
    // point, including when a host just rewrote last_equity_point().
    bool refold_summary_equity_tail() {
        if (active_equity_report_mode_ != ReportMode::SUMMARY_ONLY
            && !metrics_streaming_.no_curve) return false;
        max_equity_ = summary_broker_equity_prefix_[0];
        min_equity_ = summary_broker_equity_prefix_[1];
        max_drawdown_ = summary_broker_equity_prefix_[2];
        max_runup_ = summary_broker_equity_prefix_[3];
        if (!equity_curve_.empty()) fold_equity_extreme(equity_curve_.back().equity);
        return true;
    }
 
    // Host-installed excursion capability (RULING A48).  Transient run
    // wiring, not durable broker state: reset_run_state clears it and the
    // consumer reinstalls it once per run when the host declares ownership.
    LotExcursionHook lot_excursion_hook_;
    // The entry-side declaration of that capability: the owner of a lot's
    // excursion names where the lot's opening fill sits on its entry bar, and
    // the kernel derives the two entry-bar mask flags of every lot booked
    // under `entry_incarnation` from the bar's path, walked in the leg order
    // the run declares (NativeRunSpec::path_order, the order the matcher
    // walks).  A fill the path never reaches leaves that lot's flags as they
    // were.  The flags are durable lot state: they are folded into the run
    // hash and handed back to the owner on the closing row's
    // ClosedLotExcursionFacts.
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    void declare_opened_lot_entry_bar_mask(uint64_t entry_incarnation,
                                           const Bar& entry_bar,
                                           OpenedLotFillPoint fill_point);
    // Continuation digest at the last script point. Native batch teardown
    // moves the consumer into Completed and would otherwise change the scalar
    // relative to the recorded array; source state is still folded live so
    // post-run mutations remain visible.
    uint64_t last_script_continuation_hash_ = 0;
    bool last_script_continuation_valid_ = false;
    // --- Per-trade extreme tracking ---
    execution::Result settle_native_execution_at(
        const execution::Action& action, const execution::Fill& fill,
        const execution::PhysicalExecutionContext& context);
    execution::Result settle_with_context(
        const execution::Action& action, const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle,
        const execution::PhysicalExecutionContext& context);
    execution::SettlementInspection inspect_native_settlement(
        const execution::Action& action, const execution::Fill& fill) const;
    // Synchronous selected-close extensions. Book preserves the original
    // action semantics; OpeningExposure permits only Flatten/Reduce and is
    // revalidated against the current physical book on every call.
    execution::SettlementInspection inspect_native_settlement_scoped(
        const execution::Action& action, const execution::Fill& fill,
        execution::CloseScope scope) const;
    // The same inspection at an explicit account-currency rate: the resulting
    // notional and the quoted charges convert at `fx` and no clock is read.
    // inspect_native_settlement_scoped() is this at the presented clock's rate.
    execution::SettlementInspection inspect_native_settlement_scoped_at(
        const execution::Action& action, const execution::Fill& fill,
        execution::CloseScope scope, double fx) const;
    execution::Result settle_native_execution_scoped_at(
        const execution::Action& action, const execution::Fill& fill,
        const execution::PhysicalExecutionContext& context,
        execution::CloseScope scope);
    // --- Additive selected close (not a CloseScope overload) ---
    execution::SettlementInspection inspect_native_settlement_selected(
        const execution::Action& action,
        const execution::Fill& fill,
        const execution::SelectedOpeningSet& selection) const;
    // The selected inspection at an explicit account-currency rate, as
    // inspect_native_settlement_scoped_at is the scoped one.
    execution::SettlementInspection inspect_native_settlement_selected_at(
        const execution::Action& action,
        const execution::Fill& fill,
        const execution::SelectedOpeningSet& selection, double fx) const;
    execution::Result settle_native_execution_selected_at(
        const execution::Action& action,
        const execution::Fill& fill,
        const execution::PhysicalExecutionContext& context,
        const execution::SelectedOpeningSet& selection);
    // Source lifecycle coordinator: current_bar_/fold context, source-day
    // preflight, selected commit, then observation of its committed close rows.
    // Empty lifecycle is valid. Do not fold selection into LifecycleEffects.
    execution::Result settle_execution_selected_with_lifecycle(
        const execution::Action& action,
        const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle,
        const execution::SelectedOpeningSet& selection);
    // --- Additive non-applying account/effect projection ---
    execution::AccountEffectProjection project_native_settlement_v1(
        const execution::Action& action,
        const execution::Fill& fill) const;
    // The same projection at an explicit account-currency rate: its rows, its
    // quoted charges, its notional and its marked equity convert at `fx`, and
    // no clock is read. project_native_settlement_v1() is this at the
    // presented clock's rate.
    execution::AccountEffectProjection project_native_settlement_at(
        const execution::Action& action,
        const execution::Fill& fill, double fx) const;
    execution::AccountEffectProjection project_native_settlement_scoped_v1(
        const execution::Action& action,
        const execution::Fill& fill,
        execution::CloseScope scope) const;
    execution::AccountEffectProjection project_native_settlement_selected_v1(
        const execution::Action& action,
        const execution::Fill& fill,
        const execution::SelectedOpeningSet& selection) const;
    // Opposite-book reversal to an exact signed exposure. Unlike Transact,
    // the opening is not a remainder of transaction units minus held units.
    // These synchronous extensions share the settlement owner and do not
    // introduce a queued native request or saved commit authority.
    execution::SettlementInspection inspect_native_reversal_v1(
        const execution::ReverseTo& reversal,
        const execution::Fill& fill) const;
    // The reversal inspection at an explicit account-currency rate.
    execution::SettlementInspection inspect_native_reversal_at(
        const execution::ReverseTo& reversal,
        const execution::Fill& fill, double fx) const;
    execution::AccountEffectProjection project_native_reversal_v1(
        const execution::ReverseTo& reversal,
        const execution::Fill& fill) const;
    execution::Result settle_native_reversal_at_v1(
        const execution::ReverseTo& reversal,
        const execution::Fill& fill,
        const execution::PhysicalExecutionContext& context);
    // Source reversal coordinator with current chart context and source days.
    execution::Result settle_reversal_with_lifecycle_v1(
        const execution::ReverseTo& reversal,
        const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle);
    // Native account value: realized balance plus marked physical lots minus
    // their remaining paid entry costs, for every fee type. No Pine sizing or
    // end-of-range reporting convention participates in this value.
    double marked_equity(double price) const;
    // The same value at an explicit account-currency rate, and its only
    // implementation: marked_equity(price) is this at the presented clock's
    // rate, a margin check point calls it at its own cursor's rate.
    double marked_equity_at(double price, double fx) const;
 
    // --- Fill rounding helpers ---
    // Nearest-tick rounding, floor(price / mintick + 0.5) * mintick with NO
    // epsilon: a tie goes where the binary quotient puts it, never to a
    // decimal half-up rule (ADR-0001 Section B, `round_to_mintick`; the
    // instrument's ladder is its declared tick).
    //
    // Calibration record (finding-446): TradingView's NASDAQ:AAPL and
    // OANDA:EURUSD series carry sub-tick prints (x.xx5 and a few 4-dp
    // values), and every fill taken at one of those RAW BAR PRICES is
    // exactly this function of it: 24,582 /
    // 24,582 half-cent AAPL closes (22,122 rounded up, 2,460 rounded DOWN
    // because the binary quotient lands just under the midpoint —
    // synthetic 35.035 / 0.01 = 3503.4999999999995 -> 35.03, while
    // 25.005 / 0.01 = 2500.5 -> 25.01) and 142,938 / 142,938 EURUSD
    // fills at tick 1e-5. Any epsilon nudge (floor(r + 0.5 + 1e-6)) or a
    // decimal half-up rule forces every binary midpoint up and breaks the
    // 2,460 down cases. For r >= 1 the form below is bit-identical to
    // std::round(r) (adding 0.5 is exact inside one binade), so the legacy
    // std::round shape was already the right function; it is spelled out so
    // the code reads as the census formula it was fitted to.
    // Money is not rounded here at all: ten-significant-digit money is the
    // source adapter's own arithmetic, and the kernel's money is exact.
    double round_to_mintick(double price) const {
        if (std::isnan(price) || syminfo_mintick_ <= 0.0) return price;
        return std::floor(price / syminfo_mintick_ + 0.5) * syminfo_mintick_;
    }
 
    // A fill taken AT A RAW BAR PRICE — a market fill at a bar point (the
    // close, or the next open), a resting stop/limit the open gapped
    // through, a stop-limit whose limit is already marketable at an OHLC
    // path point, a liquidation slice at the open or adverse extreme — books
    // the raw print rounded to the NEAREST tick and only then carries
    // slippage ticks. The FEED is never quantized (indicators consume the raw
    // sub-tick values); only the fill is on-tick. The directional snap
    // (native_matching::grid_round_directional, src/native_matching.hpp) is
    // reserved for COMPUTED stop / limit LEVELS that fall between ticks;
    // applying it to a raw bar price was the finding-432/446 defect (sells
    // floored, buys ceiled — 43 AAPL slugs off by one tick). The result is
    // on-tick, so the matcher's directional snap downstream is an identity
    // on it (its ladder-exactness test absorbs the n*tick/tick FP residue).
    double bar_fill_price(double raw_bar_price) const {
        return round_to_mintick(raw_bar_price);
    }
 
    // The nearest-tick grid point of a price (the finding-446 formula),
    // materialized as k / (1/mintick) when 1/mintick is integral (every
    // decimal tick) — the double a decimal literal on that tick parses to,
    // so an on-grid level compares EQUAL to a quantized price bit-for-bit
    // (14.04 vs k*0.01 = 14.040000000000001 would not). Non-decimal ticks
    // fall back to k*mintick.
    //
    // No production code calls it. Testing a resting stop / limit against
    // the bar quantized to the tick is TradingView's per-order-kind rule,
    // and the Pine adapter owns it (its tick rules in
    // src/source/pine_adapter.cpp; ADR-0001's `price_grid` native-only
    // ruling), while a native host declares its ladder through the run
    // spec's price grid. It stays because the twin-parity-frozen
    // test_stop_tick_rounding_l4d pins it. Calibration record
    // (NYSE:F 1D tapes; synthetic prices here): sell-stops
    // 25.04624 / 25.0451 / 25.0449 /
    // 25.045 skip a bar (low 25.045 -> 25.05) and fill later at 25.04 while
    // 25.3449 fills at a low of 25.3448 -> 25.34; buy-stops fill on the high
    // rounded to NEAREST (26.0351 -> 26.04; 25.225 skips a 25.2202 high); the
    // open is quantized too (synthetic 35.036 over a 35.035 open fills at 35.03); the
    // exit-limit, entry-stop / -limit and order-stop tapes reproduce, and
    // stopround-ohlc-0/1 show the prints themselves are raw, so the
    // quantization is the broker's. Trail legs, stop-limit entries and the
    // after-close / fill-recalculation cursors were not pinned and stay raw.
    double tick_grid_price(double price) const {
        if (std::isnan(price) || syminfo_mintick_ <= 0.0) return price;
        const double k = std::floor(price / syminfo_mintick_ + 0.5);
        const double inv = 1.0 / syminfo_mintick_;
        const double inv_int = std::floor(inv + 0.5);
        if (inv_int > 0.0 && std::abs(inv - inv_int) <= 1e-6 * inv_int) {
            return k / inv_int;
        }
        return k * syminfo_mintick_;
    }
    // A level on the instrument's PRICE GRID: multiples of 1 / pricescale,
    // pricescale = 10^(the tick's decimals). A level within
    // kLevelGridBandPoints / pricescale^2 of a grid price IS that grid
    // price, materialized as k / pricescale — the double the decimal literal
    // parses to, bit-for-bit equal to tick_grid_price's output — which
    // absorbs the residue a level computed as avg_price +/- k * mintick
    // carries (9.99 + 0.05 = 10.040000000000001); a level outside the band
    // is returned untouched. A binary tick (1/128 = 0.0078125) resolves to a
    // 7-decimal grid whose band is 1e-16: effectively untouched; a tick with
    // no short decimal expansion has no grid and is untouched.
    //
    // No production code calls it. Storing a resting level on the grid is
    // TradingView's rule, and the Pine adapter owns it (its own copy,
    // source_level_on_price_grid, src/source/pine_adapter.cpp; ADR-0001's
    // `price_grid` native-only ruling). It stays because the
    // twin-parity-frozen test_level_grid_snap_l4d pins it. Calibration
    // record (round 8 family T, 40 `lab tv` sensor tapes on NYSE:F /
    // CME_MINI:ES1! / OANDA:EURUSD 15m, 2026-09-05): the band is 1e-6 on a
    // 2-decimal symbol (tick 0.01; synthetic 25.040001 IS 25.04, inclusive;
    // 25.0400011 is not and fills at 25.05), same on ES1! (tick 0.25, pricescale 100) and
    // 1e-12 on EURUSD (pricescale 1e5); comparing the raw level against the
    // tick-quantized bar instead cost 148 of the 179 exit-time mismatches of
    // the F@15 lane.
    static constexpr double kLevelGridBandPoints = 0.01;  // x 1/pricescale
    int price_grid_decimals() const {
        if (syminfo_mintick_ <= 0.0) return -1;
        double scaled = syminfo_mintick_;
        for (int n = 0; n <= 10; ++n) {
            const double k = std::floor(scaled + 0.5);
            if (k >= 1.0 && std::abs(scaled - k) <= 1e-6 * k) return n;
            scaled *= 10.0;
        }
        return -1;
    }
    double level_on_price_grid(double level) const {
        if (std::isnan(level) || !std::isfinite(level)) return level;
        const int n = price_grid_decimals();
        if (n < 0) return level;
        double pricescale = 1.0;
        for (int i = 0; i < n; ++i) pricescale *= 10.0;
        // Points as level / pointsize (pointsize = 1 / pricescale as a
        // double): of the candidate arithmetics this is the one that
        // reproduces every tape at the band's FP boundary (EURUSD
        // synthetic levels near 2.00000 and ES 5000.00 illustrate the bands;
        // F 25.04 + 8e-7 snaps, while + 1.2e-6 does not).
        const double pointsize = 1.0 / pricescale;
        const double p = level / pointsize;
        const double k = std::floor(p + 0.5);
        if (std::abs(p - k) <= kLevelGridBandPoints / pricescale) {
            return k / pricescale;
        }
        return level;
    }
    // --- Commission helper ---
    // PERCENT commission is a % of the order's notional value. The notional
    // (fill_price × qty × pointvalue) is in the symbol's QUOTE currency; the
    // commission a strategy() reports is in ACCOUNT currency, so it needs the
    // same instrument->account conversion as the margin gate below
    // (account_currency_fx_, default 1.0 — no-op for the corpus). Cash-per-
    // order / cash-per-contract are already account-currency-native (a
    // trader configures "$20 per contract" in their own currency), so they
    // are untouched.
    double calc_commission(double fill_price, double qty) const {
        // Only a percentage converts, so only it reads the presented clock.
        return calc_commission_at(fill_price, qty,
                                  commission_type_ == CommissionType::PERCENT
                                      ? active_account_currency_fx() : 1.0);
    }
    // calc_commission at an explicit account-currency rate `fx`: what a row
    // that converts at a rate of its own charges.
    double calc_commission_at(double fill_price, double qty, double fx) const {
        switch (commission_type_) {
            case CommissionType::PERCENT:
                return fill_price * qty * syminfo_.pointvalue
                       * fx
                       * (commission_value_ / 100.0);
            case CommissionType::CASH_PER_ORDER:
                return commission_value_;
            case CommissionType::CASH_PER_CONTRACT:
                return commission_value_ * qty;
        }
        return 0.0;
    }
 
    // Read the paid entry fee for a still-open pyramid slice. Production entry
    // paths always initialize the snapshot. The fallback keeps hand-constructed
    // PyramidEntry fixtures source-compatible without weakening real lifecycle
    // behavior.
    double open_entry_commission(const PyramidEntry& pe) const {
        return std::isfinite(pe.entry_commission_account)
            ? pe.entry_commission_account
            : calc_commission(pe.price, pe.qty);
    }
 
    double allocated_entry_commission(const PyramidEntry& pe, double units) const {
        if (units <= 0.0) return 0.0;
        const double paid = open_entry_commission(pe);
        return units >= pe.qty ? paid : paid * (units / pe.qty);
    }
 
    void snapshot_entry_commission(PyramidEntry& pe) const {
        pe.entry_commission_account = calc_commission(pe.price, pe.qty);
    }
 
    // --- Lot-increment floors ---
    // Floor a quantity to the instrument's lot increment (qty_step_). A
    // quotient that is only binary64 residue below an integer is treated as
    // that integer (a 1e-6-of-a-step tolerance), so an on-grid request such
    // as 1 / 0.00001 does not lose a whole lot because the quotient
    // materializes as 99999.999999..., while a genuinely off-grid request
    // still floors. When the floor would be a no-op the original double is
    // returned, so the tolerance never increases a requested quantity;
    // qty_step_ == 0 (the corpus default) leaves every quantity untouched,
    // and a quantity may floor to zero (no floor-to-one-step fallback).
    //
    // No production code calls either floor: the Pine adapter sizes and
    // floors its own lots (src/source/pine_adapter.cpp, measured by
    // test_adapter_sizing_relower), and a native host sizes with Sized /
    // native_sized_units over the run spec's quantity_grid. They stay
    // because twin-parity-frozen suites pin them
    // (test_qty_step_epsilon_floor_l4b, the frozen-size oracle rows).
    // Calibration record: the floor-not-round rule was verified row-for-row
    // on TradingView's DCA / safety-order quantities (baseOrderSize/close).
    double apply_qty_step(double qty) const {
        if (qty_step_ <= 0.0 || !std::isfinite(qty) || qty <= 0.0) return qty;
        double floored = std::floor(qty / qty_step_ + 1e-6) * qty_step_;
        return floored < qty ? floored : qty;
    }
 
    // The same floor for a percent-derived exit leg: 50% of an on-grid
    // position is often exactly on-grid in real numbers but lands one ulp
    // below the grid ratio in doubles (2.7051/0.0001 = 27050.999999…), and a
    // plain floor would knock such a leg a FULL step down; the tolerance
    // (1e-6 of a step) sits far above double representation error at
    // realistic qty/step magnitudes yet far below any genuine sub-step
    // remainder. When the floor is a no-op the ORIGINAL double is returned:
    // reconstructing it as floor(...)*step lands one ulp away (0.3 ->
    // 0.30000000000000004), jitter that would leak into printed P&L.
    // Calibration record: TradingView's BINANCE:ETHUSDT.P (qty_step 0.0001)
    // splits a qty_percent=50/50 short bracket; synthetic 7.0003 becomes
    // 3.5001 + 3.5001, leaving 0.0001 dust short open (39 of
    // the EMA swing probe's 56 unmatched trades were
    // such rows); the exact-fraction bracket probe's 30%-of-1 legs pin the no-op.
    double apply_exit_qty_step(double qty) const {
        if (qty_step_ <= 0.0 || !std::isfinite(qty) || qty <= 0.0) return qty;
        double floored = std::floor(qty / qty_step_ + 1e-6) * qty_step_;
        return floored < qty ? floored : qty;
    }
 
    // The basis of a default-sized request is the request's own: SizeTime says
    // WHEN it resolves (AtMatch / AtAcceptance) and SizePrice says WHICH price
    // it converts at (Resolved / Signal / SignalOnTick), so this class freezes
    // no sizing of its own (ADR-0001 rule 5).
    // When a forced liquidation is tested is the spec's NativeLiquidationCheck;
    // this class keeps no intrabar-liquidation rule of its own.
    // What a script-visible position accessor reads around a close is decided
    // by NativeCloseExecution, not by a freeze in this class.
    // --- Strategy variable accessors ---
    double net_profit() const { return net_profit_sum_; }
    double gross_profit() const { return gross_profit_sum_; }
    double gross_loss() const { return gross_loss_sum_; }
    double current_equity() const { return initial_capital_ + net_profit_sum_; }
 
    double max_runup_percent() const {
        return (initial_capital_ > 0.0) ? (max_runup_ / initial_capital_) * 100.0 : 0.0;
    }
    double grossprofit_percent() const {
        return (initial_capital_ > 0.0) ? (gross_profit_sum_ / initial_capital_) * 100.0 : 0.0;
    }
    double grossloss_percent() const {
        return (initial_capital_ > 0.0) ? (gross_loss_sum_ / initial_capital_) * 100.0 : 0.0;
    }
    double avg_trade() const {
        int n = (int)trades_.size();
        return (n > 0) ? (net_profit_sum_ / (double)n) : 0.0;
    }
    double avg_trade_percent() const {
        double s = trade_percent_prefix_.all_sum;
        std::size_t n = trade_percent_prefix_.all_count;
        // Continue the original left fold over the resident rows.
        for (const auto& t : trades_) { s += t.pnl_pct; ++n; }
        return n > 0 ? s / static_cast<double>(n) : 0.0;
    }
    double avg_winning_trade() const {
        return (win_trades_count_ > 0) ? (gross_profit_sum_ / (double)win_trades_count_) : 0.0;
    }
    double avg_losing_trade() const {
        return (loss_trades_count_ > 0) ? (gross_loss_sum_ / (double)loss_trades_count_) : 0.0;
    }
    double avg_winning_trade_percent() const {
        if (win_trades_count_ <= 0) return 0.0;
        double s = trade_percent_prefix_.win_sum;
        std::size_t c = trade_percent_prefix_.win_count;
        for (const auto& t : trades_) {
            if (t.pnl > 0.0) { s += t.pnl_pct; ++c; }
        }
        return (c > 0) ? (s / (double)c) : 0.0;
    }
    double avg_losing_trade_percent() const {
        if (loss_trades_count_ <= 0) return 0.0;
        double s = trade_percent_prefix_.loss_sum;
        std::size_t c = trade_percent_prefix_.loss_count;
        for (const auto& t : trades_) {
            if (t.pnl < 0.0) { s += t.pnl_pct; ++c; }
        }
        return (c > 0) ? (s / (double)c) : 0.0;
    }
    double open_trades_capital_held() const {
        if (position_side_ == PositionSide::FLAT) return 0.0;
        return std::abs(position_qty_ * position_entry_price_) * syminfo_.pointvalue;
    }
 
    // Mark-to-market open profit in account currency. The point-value
    // multiplier keeps this consistent with realized PnL
    // (build_close_trade_with_costs)
    // so equity = capital + net_profit + open_profit stays in one unit.
    double open_profit(double current_price) const {
        if (position_side_ == PositionSide::FLAT) return 0.0;
        return open_profit_at(current_price, active_account_currency_fx());
    }
    // open_profit at an explicit account-currency rate `fx`.
    double open_profit_at(double current_price, double fx) const {
        if (position_side_ == PositionSide::FLAT) return 0.0;
        double diff = (position_side_ == PositionSide::LONG)
            ? (current_price - position_entry_price_)
            : (position_entry_price_ - current_price);
        // Account-currency, matching build_close_trade_with_costs /
        // open_trade_profit —
        // callers combine this with initial_capital_ + net_profit_sum_ (both
        // account-currency) to get total equity. fx=1.0 is a no-op.
        return diff * position_qty_ * syminfo_.pointvalue * fx;
    }
 
    int count_wintrades() const { return win_trades_count_; }
    int count_losstrades() const { return loss_trades_count_; }
 
    // --- Time/date extraction from bar timestamp ---
    // The current bar's time components in UTC, the engine's storage
    // timezone, memoized per stamp. Protected, so generated code could call
    // them, but the codegen transpiler does not: it spells Pine's bare
    // ``hour`` / ``minute`` / ``dayofweek`` ... as pine_hour(current_bar_.
    // timestamp, syminfo_.timezone) and its siblings (session_time.hpp), on
    // the symbol's exchange timezone, and no generated corpus strategy names
    // one of these. Their callers are the tests that pin the UTC reading
    // (test_chart_timezone, test_intraday_rollover_chart_tz_l4a).
    struct BarTime {
        int year, month, dayofmonth, hour, minute, second, dayofweek, weekofyear;
    };
 
    // Single-entry memo: generated scripts commonly read several time
    // components per bar (hour + minute + dayofweek); decompose once per
    // distinct bar timestamp instead of per accessor. Keyed on the raw
    // timestamp, so no per-run invalidation is needed (same ts -> same
    // UTC decomposition, run-independent).
    mutable int64_t bar_time_memo_ts_ = std::numeric_limits<int64_t>::min();
    mutable BarTime bar_time_memo_{};
 
    BarTime _decompose_bar_time() const {
        if (current_bar_.timestamp == bar_time_memo_ts_) return bar_time_memo_;
        time_t secs = (time_t)(current_bar_.timestamp / 1000);
        struct tm tm_buf;
        gmtime_r(&secs, &tm_buf);
        BarTime bt;
        bt.year = tm_buf.tm_year + 1900;
        bt.month = tm_buf.tm_mon + 1;
        bt.dayofmonth = tm_buf.tm_mday;
        bt.hour = tm_buf.tm_hour;
        bt.minute = tm_buf.tm_min;
        bt.second = tm_buf.tm_sec;
        bt.dayofweek = tm_buf.tm_wday + 1;
        bt.weekofyear = (tm_buf.tm_yday + 7 - ((tm_buf.tm_wday + 6) % 7)) / 7;
        bar_time_memo_ts_ = current_bar_.timestamp;
        bar_time_memo_ = bt;
        return bt;
    }
 
    // The components of _decompose_bar_time(), one accessor each (UTC).
    int _bar_hour() const { return _decompose_bar_time().hour; }
    int _bar_minute() const { return _decompose_bar_time().minute; }
    int _bar_second() const { return _decompose_bar_time().second; }
    int _bar_dayofmonth() const { return _decompose_bar_time().dayofmonth; }
    int _bar_dayofweek() const { return _decompose_bar_time().dayofweek; }
    int _bar_month() const { return _decompose_bar_time().month; }
    int _bar_year() const { return _decompose_bar_time().year; }
    int _bar_weekofyear() const { return _decompose_bar_time().weekofyear; }
 
    // --- Bar magnifier state ---
    bool bar_magnifier_enabled_ = false;
    bool barstate_islast_ = false;
    int magnifier_samples_ = 4;
    MagnifierDistribution magnifier_dist_ = MagnifierDistribution::ENDPOINTS;
    // When true, the intrabar path scales per-sub-bar sample count by
    // (sub_bar.volume / mean_sub_bar_volume) within each script bar — dense
    // tick approximation on high-volume sub-bars without real tick data.
    // The flag reaches the host as NativeBeginArgs::magnifier_volume_weighted;
    // a host that projects the magnifier into the run's IntrabarPath carries
    // it as that path's volume_weighted, which the execution consumer's
    // deliver_intrabar_script samples by (sample_price_path_volume_weighted).
    bool magnifier_volume_weighted_ = false;
 
    // @broker-state begin
    // Monotonic cross-bar fill sequence counter, folded with the broker
    // state. The Pine adapter advances it (PineStrategyHost, one step per
    // applied broker instruction) and compares its placement fact
    // `signal_close_mc_fill_seq` against it in fill-time gates that cross the
    // bar boundary; the kernel only resets and folds it.
    uint64_t broker_fill_event_seq_ = 0;
    // @broker-state end
 
    // Session-day facts are the native decision context's
    // (NativeDecisionContext::in_session and its neighbours, market_driver.hpp);
    // a host that keeps flags of its own stores them itself.
    // --- Timeframe state ---
    std::string input_tf_;
    std::string script_tf_;
    // Cached tf_to_seconds(script_tf_). MUST be refreshed immediately after
    // every assignment to script_tf_ (the one writer is the Pine host's
    // scheduler_prepare_script_run). Avoids a string parse per read.
    int script_tf_seconds_ = 0;
    TimeframeAggregator script_tf_agg_;
    int64_t prev_bar_timestamp_ = 0;
 
    // --- Historical -> realtime stream lifecycle ---
    // stream_begin() executes the historical warmup through the normal run()
    // path exactly once, then these fields carry the SAME broker, Pine series,
    // TA and timeframe-aggregator state forward while normalized trades arrive.
    enum class StreamPhase { IDLE, REALTIME, ENDED };
    StreamPhase stream_phase_ = StreamPhase::IDLE;
    bool stream_warmup_mode_ = false;
    // A host that keeps the legacy no-op refusal for in-run C-ABI setters
    // sets this for the handle lifetime so
    // guard_native_mutation stays a no-op (ab9714be LegacyCompatibilityConsumer::refuse).
    // Native hosts leave it false; their in-run setter still throws.
    bool host_mutation_guard_inert_ = false;
    int64_t stream_input_tf_ms_ = 0;
    int64_t stream_next_input_open_ms_ = 0;
    int64_t stream_clock_ms_ = 0;
    int64_t stream_last_tick_ms_ = 0;
    uint64_t stream_last_sequence_ = 0;
    bool stream_seen_sequence_ = false;
    bool stream_has_input_bar_ = false;
    Bar stream_input_bar_{};
    double stream_last_price_ = 0.0;
    bool stream_has_last_price_ = false;
    int stream_next_script_bar_index_ = 0;
    bool stream_script_bar_had_tick_ = false;
    bool stream_script_tick_seen_ = false;
    enum class StreamInputMode { UNSET, TICKS, BARS };
    StreamInputMode stream_input_mode_ = StreamInputMode::UNSET;
    bool stream_observe_actions_ = false;
    uint64_t stream_action_sequence_ = 0;
    std::vector<StreamOrderAction> stream_order_actions_;
 
    // --- request.security state ---
    struct SecurityEvalState {
        int sec_id = 0;
        std::string tf;
        TimeframeAggregator aggregator;
        Bar current_bar{};
        int current_sub_bar_count = 0;
        int64_t feed_count = 0;
        int64_t eval_complete_count = 0;
        int64_t eval_partial_count = 0;
        // Requested-context bar index of the latest dispatch_security_eval()
        // (the ring address its TA members saw, see ta::bar_context()); -1
        // before the first dispatch. A host that replays its latest
        // evaluation re-dispatches the same bar under the same index.
        int64_t ta_bar_index = -1;
        // Native higher-timeframe feed routing, rebuilt per run by
        // prepare_native_security_feeds(): the index into
        // native_security_feeds_ serving this state's requested timeframe
        // (-1: none, the aggregate stands), and that feed's bars keyed by
        // the label this state's aggregator stamps on the same bucket --
        // TimeframeAggregator::bar_label_ms of the native bar's covered
        // session instant -- so a completed bucket finds its exchange bar by
        // the timestamp the aggregate already carries. The same call installs
        // the feed's stamps into this state's aggregator as its period
        // partition (TimeframeAggregator::set_native_periods): the bucket's
        // span, label and completion bar are the native bar's own.
        int native_feed_index = -1;
        std::unordered_map<int64_t, Bar> native_bars_by_label;
    };
 
    std::vector<SecurityEvalState> security_eval_states_;
    // The raw feed used by security aggregators in the active run. This is the
    // chart input TF on the legacy path and the auxiliary TF on the split path.
    std::string security_input_tf_;
 
    // Native higher-timeframe request.security feeds: the exchange's own
    // bars of one timeframe each (TradingView's "D" bar on an intraday chart
    // is the settlement / official close, not the last intraday close). A
    // completed request.security bucket of a fed timeframe takes the native
    // bar's OHLCV; timing, other timeframes, chart and broker are untouched.
    // Layout-unconditional like the aux feed's siblings above.
    struct NativeSecurityFeed {
        std::string tf;
        int seconds = 0;
        std::vector<Bar> bars;
    };
    std::vector<NativeSecurityFeed> native_security_feeds_;
    int64_t diag_native_security_substitutions_ = 0;
    int64_t diag_native_security_misses_ = 0;
    // The chart symbol's own daily partition, built per run from the native
    // "D" feed's stamps on an intraday chart (prepare_chart_day_partition)
    // and installed for the run's bar loop (NativeDayPartitionScope) so the
    // chart-level D consumers -- time("D") / time_close("D"),
    // timeframe.change("1D"), ta.change(time("D")), ta.vwap's daily anchor --
    // read TradingView's trade-date daily bars (timeframe.hpp). Empty on a
    // run without the feed or on a calendar chart: every rule nominal.
    NativeDayPartition chart_day_partition_;
 
    // --- Runtime trace state ---
    // Gated by ``trace_enabled_`` (default false) so production strategies
    // pay zero cost; the validator flips it on per-strategy when it needs
    // engine-internal per-bar values for TV cross-referencing.
    //
    // ``trace_buffer_`` is a flat vector of POD records (no string allocs
    // per call); each entry holds a ``name_id`` indexing into
    // ``trace_names_``, which is the unique-name table built by
    // ``intern_trace_name``. A first-time name pays one ``unordered_map``
    // insert + ``string`` push_back; subsequent calls with the same name
    // are a single map lookup.
    bool trace_enabled_ = false;
 
    // Live-runtime surface (ABI v4). All default off/zero; historical runs are
    // byte-identical when untouched (tests/test_live_flags_off_identity.cpp).
    int last_run_status_ = 0;               // 0 completed, 1 NOT_COMPLETED (abort)
 
    // Cooperative abort (spec §3.5): set from any thread via request_abort();
    // consumed by the run in progress at the top of each bar-loop iteration
    // via check_abort(), which unwinds the run with AbortRequested. Cleared
    // at every run() entry, so a request made while idle is a no-op.
    //
    // AbortFlag wraps std::atomic<bool> in a copy/move-constructible shell:
    // std::atomic itself has its copy/move members deleted, and some tests
    // (e.g. tests/test_pooc_global_full_exit.cpp's ``run_case``) return a
    // BacktestEngine subclass by value, which needs the class to stay
    // implicitly copyable. Copying/moving never carries an in-flight abort
    // request across — there is no "run in progress" on a copy — so the
    // copy always starts cleared.
    struct AbortFlag {
        std::atomic<bool> value{false};
        AbortFlag() = default;
        AbortFlag(const AbortFlag&) noexcept {}
        AbortFlag(AbortFlag&&) noexcept {}
        AbortFlag& operator=(const AbortFlag&) noexcept {
            value.store(false, std::memory_order_relaxed);
            return *this;
        }
        AbortFlag& operator=(AbortFlag&&) noexcept {
            value.store(false, std::memory_order_relaxed);
            return *this;
        }
        bool load(std::memory_order order) const { return value.load(order); }
        void store(bool v, std::memory_order order) { value.store(v, order); }
    };
    AbortFlag abort_requested_;
    struct AbortRequested {};               // thrown inside the bar loops only
    void check_abort() {
        if (abort_requested_.load(std::memory_order_relaxed)) throw AbortRequested{};
    }
 
    std::vector<TraceEntryC> trace_buffer_;
    std::vector<std::string> trace_names_;
    std::unordered_map<std::string, int32_t> trace_name_index_;
 
    int32_t intern_trace_name(const std::string& name);
 
    int64_t diag_input_bars_processed_ = 0;
    int64_t diag_script_bars_processed_ = 0;
    int64_t diag_magnifier_sub_bars_processed_ = 0;
    int64_t diag_magnifier_sample_ticks_processed_ = 0;
    int diag_script_tf_ratio_ = 0;
    bool diag_needs_aggregation_ = false;
 
    // Captured by the public run() wrappers when the underlying engine logic
    // throws. Cleared at the start of every run(). Surfaces through
    // last_error() / strategy_get_last_error() so the C ABI never
    // unwinds a C++ exception across the extern "C" boundary.
    std::string last_error_;
 
    // Registers one aggregating evaluator: the requested timeframe's buckets
    // built from the run's evaluator input timeframe, passthrough when the
    // two are equal. Publication modes are not the kernel's: a source host
    // keeps its own per-sec_id semantics beside this state and a native
    // subscription's modes are the consumer's delivery rules.
    void register_security_eval(int sec_id, const std::string& requested_tf,
                                const std::string& input_tf);
    // The one path to evaluate_security(): installs the requested context's
    // bar index for the evaluator's TA members (ta::bar_context()) for the
    // duration of the dispatch. `bar_index` is the 0-based index of the
    // requested-context bar being evaluated — the just-completed bucket for a
    // complete evaluation (eval_complete_count - 1), the in-progress bucket
    // for a partial one (eval_complete_count) — so every
    // compute()/recompute() dispatch of one requested bar rewrites the same
    // ring slot, and a conditional window call inside the security expression
    // is addressed exactly like TradingView addresses it.
    void dispatch_security_eval(SecurityEvalState& state, const Bar& bar,
                                bool publish, int64_t bar_index);
    // The generic evaluator step for one input bar: aggregate, take the
    // native bar of a completed bucket where a feed serves the timeframe,
    // and dispatch the completed bucket. Publication at the last contributing
    // input is the consumer's; a source host composes its own step.
    void feed_security_eval_state(SecurityEvalState& state, const Bar& input_bar);
 
    // A new batch run (including stream_begin's historical warmup) starts a
    // fresh script lifecycle. Called once after broker reset, before any
    // requested/chart computation or per-bar checkpoint. Generated subclasses
    // reset their own persistent state here, then optionally prepare the
    // current run's static TA cache. Config/inputs/feeds belong to the engine
    // and survive. Streaming ticks and fill recalculations never call this.
    virtual void prepare_script_run(const Bar*, int, bool) {}
 
    virtual void configure_security_evaluators() {}
    virtual void evaluate_security(int sec_id, const Bar& bar, bool is_complete) {}
    virtual void clear_security(int sec_id) {}
 
    // Generated-state transaction hooks for calc_on_order_fills. Snapshot is
    // called once before the broker walks a historical bar; restore precedes
    // every fill recalc and the ordinary close execution. The completed
    // ordinary-close execution becomes the committed checkpoint. Historical
    // post-C fill recalculations start from it, recompute its current-bar
    // history slot, and are rolled back after their broker effects persist.
    virtual void snapshot_script_state() {}
    virtual void restore_script_state() {}
    virtual void commit_script_state() {}
 
    // Magnifier helpers
 
 
    virtual void finalize_bar() {}
 
    // --- Equity extremes update (called after each on_bar) ---
    // NOTE: the dd/runup walk in src/engine_metrics.cpp (compute_equity_stats)
    // MUST mirror this trough-reset logic; keep in lockstep. The fold is one
    // per script calculation and the kernel performs it under EVERY report
    // policy (native_execution_consumer.cpp): these scalars measure the run,
    // not the report. A policy that also records the curve folds and appends
    // at one instant, so a re-walk of the curve through fold_equity_extreme
    // reproduces the scalars bit for bit (scheduler_record_range_end uses it).
    void fold_equity_extreme(double eq) {
        if (eq > max_equity_) {
            max_equity_ = eq;
            min_equity_ = eq;  // reset trough on new peak
        }
        if (eq < min_equity_) {
            min_equity_ = eq;
        }
        double dd = max_equity_ - eq;
        if (dd > max_drawdown_) max_drawdown_ = dd;
        double ru = eq - min_equity_;
        if (ru > max_runup_) max_runup_ = ru;
    }
    void update_equity_extremes() {
        fold_report_equity_extreme(initial_capital_ + net_profit_sum_ + open_profit(current_bar_.close));
 
        // --- Update max_contracts_held_* running peaks ---
        double abs_qty = std::abs(position_qty_);
        if (position_side_ != PositionSide::FLAT) {
            if (abs_qty > max_contracts_held_all_) max_contracts_held_all_ = abs_qty;
            if (position_side_ == PositionSide::LONG && abs_qty > max_contracts_held_long_)
                max_contracts_held_long_ = abs_qty;
            if (position_side_ == PositionSide::SHORT && abs_qty > max_contracts_held_short_)
                max_contracts_held_short_ = abs_qty;
        }
    }
 
    int report_equity_month_key(std::int64_t time_ms) const {
        // An out-of-domain no-curve attempt is unpublishable: the monthly
        // fold requests whole-report recovery. Avoid invoking the legacy
        // int month-key expression speculatively on that attempt.
        if (metrics_streaming_.no_curve && !metrics::monthly_replay_time_supported_v1(time_ms))
            return 0;
        return metrics::equity_month_key(time_ms, chart_timezone_);
    }
 
    // Record one equity point per SCRIPT bar. ``script_bar_ts`` must be the
    // script-bar open timestamp captured BEFORE dispatch — current_bar_.timestamp
    // is overwritten by the magnifier sub-bar walk (engine_run.cpp), which would
    // make the curve differ between magnifier on/off.
    void record_equity_point(int64_t script_bar_ts) {
        // M05/M06 may have edited the preceding held slot since its append.
        // Consume that edit BEFORE either storage path releases the point.
        sync_metrics_streaming_held_v1();
        const bool summary = active_equity_report_mode_ == ReportMode::SUMMARY_ONLY
            || metrics_streaming_.no_curve;
        if (summary ? equity_curve_.empty() : prepare_equity_point())
            first_bar_open_ = current_bar_.open;
        pf_equity_point_t p;
        p.time_ms = script_bar_ts;
        p.open_profit = open_profit(current_bar_.close);
        p.equity = initial_capital_ + net_profit_sum_ + p.open_profit;
        if (summary) {
            if (!equity_curve_.empty()) {
                const auto& held = equity_curve_.back();
                summary_equity_fold_.replace_last(
                    held, report_equity_month_key(held.time_ms));
                auto& prefix = summary_broker_equity_prefix_;
                const double eq = held.equity;
                if (eq > prefix[0]) prefix[0] = prefix[1] = eq;
                if (eq < prefix[1]) prefix[1] = eq;
                const double dd = prefix[0] - eq;
                if (dd > prefix[2]) prefix[2] = dd;
                const double ru = eq - prefix[1];
                if (ru > prefix[3]) prefix[3] = ru;
            }
            summary_equity_fold_.fold(
                p, report_equity_month_key(p.time_ms),
                true, position_side_ != PositionSide::FLAT);
            if (equity_curve_.empty()) equity_curve_.push_back(p);
            else equity_curve_.back() = p;
            summary_equity_snapshot_valid_ = summary_equity_ratios_ready_ = false;
            summary_equity_ratios_.reset();
        } else {
            store_equity_point(p);
        }
        if (metrics_streaming_.fold) {
            metrics_streaming_.fold->append(
                p, report_equity_month_key(p.time_ms));
            ++metrics_streaming_.points;
            metrics_streaming_.receipt.stop_boundary.completed_marks = metrics_streaming_.points;
            metrics_streaming_.receipt.stop_boundary.kind =
                metrics::MetricsStopBoundaryKindV1::CompletedMark;
        }
        metrics_streaming_.receipt_final = false;
        if (position_side_ != PositionSide::FLAT) ++bars_in_market_;
    }
 
    // --- Trade history accessors (for strategy.closedtrades.*) ---
    double closed_trade_profit(int index) const {
        if (index >= 0 && index < (int)trades_.size())
            return trades_.pnl_at(index);
        return 0.0;
    }
    double closed_trade_profit_percent(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::numeric_limits<double>::quiet_NaN();
        return trades_.pnl_pct_at(idx);
    }
    double closed_trade_commission(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::numeric_limits<double>::quiet_NaN();
        return trades_.commission_at(idx);
    }
    int closed_trade_entry_bar_index(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return na<int>();
        return trades_.entry_bar_index_at(idx);
    }
    int closed_trade_exit_bar_index(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return na<int>();
        return trades_.exit_bar_index_at(idx);
    }
    std::string closed_trade_entry_comment(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::string();
        return trades_.entry_comment_at(idx);
    }
    std::string closed_trade_exit_comment(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::string();
        return trades_.exit_comment_at(idx);
    }
    std::string closed_trade_entry_id(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::string();
        return trades_.entry_id_at(idx);
    }
    std::string closed_trade_exit_id(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::string();
        return trades_.exit_id_at(idx);
    }
    uint64_t closed_trade_entry_incarnation(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return 0;
        return trades_.entry_incarnation_at(idx);
    }
    double closed_trade_entry_price(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::numeric_limits<double>::quiet_NaN();
        return trades_.entry_price_at(idx);
    }
    double closed_trade_exit_price(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::numeric_limits<double>::quiet_NaN();
        return trades_.exit_price_at(idx);
    }
    int64_t closed_trade_entry_time(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return 0;
        return trades_.entry_time_at(idx);
    }
    int64_t closed_trade_exit_time(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return 0;
        return trades_.exit_time_at(idx);
    }
    double closed_trade_size(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return std::numeric_limits<double>::quiet_NaN();
        return trades_.qty_at(idx);
    }
    double closed_trade_max_runup(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return 0.0;
        return trades_.max_runup_at(idx);
    }
    // Percent excursions: trade.max_runup / max_drawdown are stored in
    // account currency (× pointvalue, see build_close_trade_with_costs), so the entry
    // cost denominator must be in currency too (entry × qty × pointvalue).
    // pointvalue=1 cancels out and matches the legacy ratio bit-for-bit.
    double closed_trade_max_runup_percent(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return 0.0;
        double cost = trades_.entry_price_at(idx) * trades_.qty_at(idx) * syminfo_.pointvalue;
        return (cost > 0.0) ? (trades_.max_runup_at(idx) / cost) * 100.0 : 0.0;
    }
    double closed_trade_max_drawdown(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return 0.0;
        return trades_.max_drawdown_at(idx);
    }
    double closed_trade_max_drawdown_percent(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return 0.0;
        double cost = trades_.entry_price_at(idx) * trades_.qty_at(idx) * syminfo_.pointvalue;
        return (cost > 0.0) ? (trades_.max_drawdown_at(idx) / cost) * 100.0 : 0.0;
    }
 
    // --- Direction accessors ---
    std::string closed_trade_direction(int idx) const {
        if (idx < 0 || idx >= (int)trades_.size()) return "";
        return trades_.is_long_at(idx) ? "long" : "short";
    }
    std::string open_trade_direction(int idx) const {
        if (position_side_ == PositionSide::FLAT || idx < 0 || idx >= (int)pyramid_entries_.size()) return "";
        return (position_side_ == PositionSide::LONG) ? "long" : "short";
    }
 
    // --- Open position trade accessors (strategy.opentrades.*) ---
    double open_trade_profit(int idx) const;
    double open_trade_profit_percent(int idx) const;
    double open_trade_commission(int idx) const;
    int open_trade_entry_bar_index(int idx) const;
    std::string open_trade_entry_comment(int idx) const;
    std::string open_trade_entry_id(int idx) const;
    double open_trade_entry_price(int idx) const;
    int64_t open_trade_entry_time(int idx) const;
    double open_trade_size(int idx) const;
    double open_trade_max_drawdown(int idx) const;
    double open_trade_max_drawdown_percent(int idx) const;
    double open_trade_max_runup(int idx) const;
    double open_trade_max_runup_percent(int idx) const;
 
    std::string position_entry_name() const {
        if (position_side_ == PositionSide::FLAT || pyramid_entries_.empty()) return "";
        return pyramid_entries_.back().entry_id;
    }
 
    double max_drawdown_percent() const {
        return (initial_capital_ > 0.0) ? (max_drawdown_ / initial_capital_) * 100.0 : 0.0;
    }
 
protected:
    execution::Result settle_with_context_scoped(
        const execution::Action& action, const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle,
        const execution::PhysicalExecutionContext& context,
        execution::CloseScope scope);
    execution::Result settle_with_context_selected(
        const execution::Action& action, const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle,
        const execution::PhysicalExecutionContext& context,
        const execution::SelectedOpeningSet& selection);
    execution::AccountEffectProjection project_with_membership(
        const execution::Action& action,
        const execution::Fill& fill,
        execution::CloseScope book_or_opening,
        const execution::SelectedOpeningSet* selected, double fx) const;
    execution::SettlementInspection inspect_with_membership(
        const execution::Action& action,
        const execution::Fill& fill,
        execution::CloseScope book_or_opening,
        const execution::SelectedOpeningSet* selected, double fx) const;
    execution::Result settle_with_membership(
        const execution::Action& action, const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle,
        const execution::PhysicalExecutionContext& context,
        execution::CloseScope book_or_opening,
        const execution::SelectedOpeningSet* selected);
    // Runtime-private preview of the exact existing pre-source prefix. The
    // caller pins the quoted ticket before entering this method.
    execution::Status preview_native_settlement_commit(
        const execution::Action& action, const execution::Fill& fill,
        const execution::PhysicalExecutionContext& context,
        execution::CloseScope scope, const execution::SelectedOpeningSet* selected,
        execution::AccountEffectProjection& account, std::vector<double>& row_pnl) const;
    execution::Status preview_native_settlement_commit(
        const execution::ReverseTo& reversal, const execution::Fill& fill,
        const execution::PhysicalExecutionContext& context,
        execution::AccountEffectProjection& account, std::vector<double>& row_pnl) const;
    struct NativeSettlementStage;
    struct NativeSettlementRows;
    execution::Status validate_native_settlement_book(double& held) const;
    execution::Status allocate_native_settlement_closes(
        NativeSettlementStage& stage,
        const execution::CloseScope& book_or_opening,
        double& remaining) const;
    void finish_native_settlement_stage(
        NativeSettlementStage& stage, const execution::Fill& fill) const;
    execution::SettlementInspection inspect_native_settlement_stage(
        const NativeSettlementStage& stage, const execution::Fill& fill) const;
    execution::AccountEffectProjection project_native_settlement_stage(
        const NativeSettlementStage& stage, const execution::Fill& fill) const;
    execution::Result commit_native_settlement_stage(
        NativeSettlementStage& stage, const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle,
        const execution::PhysicalExecutionContext& context);
    void build_native_settlement_close_rows(
        const NativeSettlementStage& stage, const execution::Fill& fill,
        const execution::PhysicalExecutionContext& context,
        NativeSettlementRows& rows) const;
    execution::Status prepare_native_settlement_commit(
        const NativeSettlementStage& stage, const execution::Fill& fill,
        const execution::PhysicalExecutionContext& context,
        NativeSettlementRows& rows) const;
    execution::Status preflight_native_settlement_effects(
        const NativeSettlementStage& stage,
        const execution::LifecycleEffects& lifecycle,
        const NativeSettlementRows& rows);
    execution::Result commit_prepared_native_settlement_stage(
        NativeSettlementStage& stage, const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle,
        const execution::PhysicalExecutionContext& context,
        NativeSettlementRows& rows);
    execution::Result settle_source_staged_execution(
        NativeSettlementStage& stage, const execution::Fill& fill,
        const execution::LifecycleEffects& lifecycle,
        const execution::PhysicalExecutionContext& context);
    void stage_native_settlement(
        NativeSettlementStage& stage,
        const execution::Action& action,
        const execution::Fill& fill,
        execution::CloseScope book_or_opening,
        const execution::SelectedOpeningSet* selected,
        const execution::LifecycleEffects* lifecycle, double fx) const;
    void stage_native_settlement(
        NativeSettlementStage& stage,
        const execution::ReverseTo& reversal,
        const execution::Fill& fill,
        const execution::LifecycleEffects* lifecycle, double fx) const;
    void append_quoted_lot(PyramidEntry lot, double total_qty, double average_price);
    // Opens a new position cycle with `lot` as its only lot: a fresh cycle
    // id, the per-position state reset, and the stream observation recorded.
    void open_quoted_position(PositionSide requested, PyramidEntry lot);
 
    void record_close_trade(Trade trade);
    void validate_close_trade_counters(const Trade* rows, size_t count) const;
    // Quote one resolved execution's current charges, a percent schedule at
    // the account-currency rate `fx` its stage converts at. Entry costs on the
    // closed rows are historical allocations. Returns close shares in FIFO
    // order followed by the opening share (zero when there is no opening).
    std::vector<double> quote_execution_commissions(
        const std::vector<double>& closed_units, double opening_units,
        const execution::Fill& fill, double fx) const;
    // The Trade row a close of ``close_qty`` of ``pe`` at ``fill_price`` on
    // the current bar would record (pnl, pnl_pct, commission, excursions, bar
    // indexes), without its bookkeeping: the settlement builds it here and
    // commits it through record_close_trade; the range-end report row builds
    // only.
 
    Trade build_close_trade_with_costs(const PyramidEntry& pe, double close_qty,
        double fill_price, bool was_long, double entry_commission,
        double exit_commission,
        const execution::PhysicalExecutionContext& context) const;
    // A terminal-row read supplies its retained answer (or the kernel model)
    // and never consults the host again. Settlement uses the overload above.
    Trade build_close_trade_with_costs(const PyramidEntry& pe, double close_qty,
        double fill_price, bool was_long, double entry_commission,
        double exit_commission,
        const execution::PhysicalExecutionContext& context,
        const ClosedLotExcursion* retained_excursion, bool consult_excursion_hook) const;
    void reset_position_state_to_flat();
    // Reset ALL per-run state (trades, accumulators, position, pending orders,
    // equity extremes, risk latches, intraday/day counters, source-series
    // history) so a reused handle's run N is bit-identical to a fresh handle's
    // run 1. Preserves configuration (initial_capital_, slippage_,
    // commission_*, syminfo_, inputs_) — those are set before run() and must
    // survive it. Called at the top of every
    // run() loop entrypoint. See tests/test_handle_reuse_reset.cpp.
    void reset_run_state();
    double account_currency_fx_at(int64_t timestamp_ms) const;
    double active_account_currency_fx() const;
 
    // Native HTF feed routing (engine_aux_security.cpp): per-state label maps
    // built after the evaluators' aggregators exist for this run, and the
    // substitution a completed bucket applies. Returns whether `bar` was
    // replaced by its native sibling.
    void prepare_native_security_feeds(const Bar* input_bars, int n_input);
    void prepare_chart_day_partition(const Bar* input_bars, int n_input);
    const std::string& report_scratch_directory() const noexcept { return report_sink_state_.scratch_dir; }
    bool substitute_native_security_bar(SecurityEvalState& state, Bar& bar,
                                        bool count_miss = true);
 
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
    virtual bool source_aux_security_feed_enabled() const;
    virtual void source_aux_security_input_view(const Bar*& bars, int& n) const;
    bool aux_security_feed_enabled() const {
        return source_aux_security_feed_enabled();
    }
#endif
 
    void stream_observe_entry(const PyramidEntry& pe);
    virtual void source_stream_entry_comment(const PyramidEntry&, std::string&) const;
    void stream_observe_exit(size_t trade_index);
    void stream_refresh_action_metadata(size_t first_action, size_t first_trade);
 
    // fill_report helpers (defined in engine_report.cpp).
    void fill_trades_section(ReportC* out) const;
    virtual void present_report(ReportC*) const {}
    // Host declaration, not an override detector: true covers the engine's
    // empty presenter and is inherited by native subclasses. Any host that
    // overrides present_report MUST also override this hook: return false
    // until its exact bounded-state adapter supports non-FULL capture.
    // Eligibility must be known before begin; inheriting true does not prove
    // an arbitrary whole-array presenter eligible.
    virtual bool report_presenter_supports_non_full() const noexcept { return true; }
    void fill_metrics_section(ReportC* out) const;
    void fill_security_diag_section(ReportC* out) const;
    void fill_trace_section(ReportC* out) const;
 
    void guard_native_mutation(const char* operation);
 
    struct ExecutionConsumerSlot {
        bool native = false;
        mutable std::unique_ptr<IExecutionConsumer> ptr;
        ExecutionConsumerSlot() = default;
        ExecutionConsumerSlot(const ExecutionConsumerSlot& other) noexcept
            : native(other.native) {}
        ExecutionConsumerSlot& operator=(const ExecutionConsumerSlot& other) noexcept {
            if (this != &other) {
                native = other.native;
                ptr.reset();
            }
            return *this;
        }
        ExecutionConsumerSlot(ExecutionConsumerSlot&& other) noexcept : native(other.native) {
            other.ptr.reset();
        }
        ExecutionConsumerSlot& operator=(ExecutionConsumerSlot&& other) noexcept {
            if (this != &other) {
                native = other.native;
                ptr.reset();
                other.ptr.reset();
            }
            return *this;
        }
    };
    ExecutionConsumerSlot execution_consumer_slot_;
 
public:
    virtual ~BacktestEngine();
    int execution_contract() const;
    bool native_bound() const;
    virtual void on_bar(const Bar& bar) = 0;
 
    // All run() overloads preflight the entire chart array before modifying
    // configuration, resetting state, preparing scripts or dispatching bars.
    // Require n >= 0, a non-null pointer when n > 0, finite enclosed OHLC,
    // volume that is finite >= 0 or NaN (unavailable), and strictly increasing
    // timestamps with representable positive int64 deltas. Finite signed/zero
    // prices, off-grid prices and gaps are structurally admitted, without a
    // guarantee about their financial or extreme-calendar arithmetic.
    // Rejection sets last_error() and preserves state except entry-time error,
    // run-status and abort bookkeeping. n == 0 retains empty-new-run semantics.
    // Processing exceptions after preflight do not imply state rollback.
    void run(const Bar* bars, int n);
 
    void run(const Bar* input_bars, int n_input,
             const std::string& input_tf,
             const std::string& script_tf,
             bool bar_magnifier = false,
             int magnifier_samples = 4,
             MagnifierDistribution magnifier_dist = MagnifierDistribution::ENDPOINTS);
 
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
    // Copies a finer request.security-only feed for subsequent historical
    // runs. n == 0 clears it. Validation that depends on native chart bars is
    // intentionally deferred to run(), where failures reach last_error().
    virtual bool set_aux_security_feed(const Bar* bars, int n,
                               const std::string& input_tf);
#endif
 
    // Copies the exchange's own bars of one higher timeframe for the
    // request.security evaluators that request exactly it (see
    // strategy_set_native_security_feed in pineforge.h). n == 0 clears that
    // timeframe's feed. Routing is built per run once the evaluators exist.
    bool set_native_security_feed(const std::string& timeframe,
                                  const Bar* bars, int n);
    bool native_security_feed_enabled() const {
        return !native_security_feeds_.empty();
    }
    // Per-run diagnostics: completed buckets that took a native bar, and
    // completed buckets of a fed timeframe that found none (kept aggregate).
    int64_t native_security_substitutions() const {
        return diag_native_security_substitutions_;
    }
    int64_t native_security_misses() const {
        return diag_native_security_misses_;
    }
    // Whether the last run built the chart symbol's native daily partition
    // (an intraday chart with a native "D" feed installed).
    bool chart_day_partition_installed() const {
        return !chart_day_partition_.empty();
    }
 
    // Another symbol's bars, facts and recorded request values, for a source
    // host whose request sites name them (strategy_set_symbol_feed and its
    // three siblings in pineforge.h). These are that host's doors: the kernel
    // base keeps none of it and answers false without a word, as it does for
    // set_aux_security_feed. A host with no source layer installs another
    // instrument's bars in its run spec (NativeRunSpec::instrument_feeds).
    virtual bool set_symbol_feed(const std::string& key, const std::string& timeframe,
                                 const Bar* bars, const int64_t* close_ms, int n);
    virtual bool set_symbol_feed_column(const std::string& key, const std::string& timeframe,
                                        const std::string& name, const double* values, int n);
    virtual bool set_symbol_facts(const std::string& key, const std::string& field,
                                  const std::string& value);
    virtual bool set_recorded_series(const std::string& key, const int64_t* chart_open_ms,
                                     const double* values, int n);
 
    // Execute confirmed historical bars, then keep this exact instance alive
    // for realtime trade updates. The warmup feed must contain at least one
    // complete input-timeframe bar. Normalized ticks begin at or after the next
    // input bar's open; in-session gaps are materialized as zero-volume
    // carry-forward bars when a later tick or stream_advance_time() crosses
    // their close boundary. Configured out-of-session intervals are skipped.
    bool stream_begin(const Bar* warmup_bars, int n_warmup,
                      const std::string& input_tf,
                      const std::string& script_tf = "");
    // Confirmed input bars use the same OHLC broker kernel as batch. The first
    // tick/bar locks the input mode; mixing them is rejected. Missing in-session
    // bars are rejected rather than padded. Closed-session gaps may be skipped.
    bool stream_push_bar(const Bar& bar);
    bool stream_push_tick(const TradeTick& tick);
    bool stream_push_ticks(const TradeTick* ticks, int n);
    bool stream_advance_time(int64_t timestamp_ms);
    bool stream_end(bool finalize_partial_input_bar = false);
    bool stream_is_realtime() const { return stream_phase_ == StreamPhase::REALTIME; }
    int stream_order_actions_len() const { return static_cast<int>(stream_order_actions_.size()); }
    const StreamOrderAction& stream_order_action_at(int i) const {
        return stream_order_actions_.at(static_cast<size_t>(i));
    }
    void stream_order_actions_clear() { stream_order_actions_.clear(); }
    // Observable broker + stream cursors/forming bars, not a serialization of
    // arbitrary strategy members. Deterministic strategy code is required.
    uint64_t stream_state_hash() const;
 
    // Install an effective-time FX curve (account-currency units per one unit
    // of symbol quote currency). Points are copied and must have strictly
    // increasing epoch-ms timestamps plus positive finite rates. The latest
    // point whose timestamp is <= the current broker event is active. Passing
    // n=0 clears the curve and restores the scalar metadata fallback.
    bool set_account_currency_fx_series(const int64_t* timestamps_ms,
                                        const double* rates, int n);
 
    void run(const Bar* input_bars, int n_input,
             const std::string& input_tf,
             const std::string& script_tf,
             const std::unordered_map<std::string, std::string>& inputs,
             const SymInfo& syminfo,
             // Opaque host-override handle: the kernel only forwards it to
             // prepare_native_begin() as NativeBeginArgs::overrides_opaque
             // and never dereferences it. A host layer that defines its own
             // override record passes its address and casts it back there.
             const void* overrides = nullptr,
             bool bar_magnifier = false,
             int magnifier_samples = 4,
             MagnifierDistribution magnifier_dist = MagnifierDistribution::ENDPOINTS);
 
    int trade_count() const { return (int)trades_.size(); }
    Trade get_trade(int i) const { return trades_.read(static_cast<std::size_t>(i)); }
    // Read-only run diagnostics, outside reports and broker-state hashes.
    int report_cache_stats(std::uint64_t* resident_bytes,
                           std::uint64_t* allocation_bypass_count) const noexcept;
    // The same closed rows under the `closed_trade_*` name a host reads them
    // by (RP6). The per-field `closed_trade_*` family below stays protected
    // Pine plumbing: one owning row value answers all of it, and a host
    // that owns its report needs the row, not twenty wrappers. Range-end
    // report rows are NOT here — report_trade_count() / get_report_trade()
    // below span both spaces. Index against closed_trade_count(); reads below
    // base refuse with engine_invariant only on an admitted retiring sink run.
    std::size_t closed_trade_count() const noexcept { return trades_.size(); }
    Trade closed_trade(std::size_t i) const { return trades_.read(i); }
    // Newest first, preserving global indices across resident and external
    // rows. Start at closed_trade_count(); crossing a retired base refuses.
    bool previous_closed_trade(std::size_t& cursor, Trade& value) const {
        return trades_.previous(cursor, value);
    }
    // The REPORT's row space: trades_ followed by range_end_trades_, in the
    // order fill_trades_section lays pf_report_t::trades out. trade_count()
    // / get_trade() stay the Pine-visible closed trades (strategy.closedtrades
    // never sees a range-end row); the report-indexed C ABI accessors
    // (strategy_closed_trade_entry_incarnation) must index THIS space, or
    // every range-end row reads as index-out-of-range (round-4b F3).
    int report_trade_count() const {
        return (int)(trades_.size() + range_end_trades_.size());
    }
    // A range-end row is rebuilt from its terminal lot mark on every value read.
    Trade get_report_trade(int i) const {
        const int n_closed = (int)trades_.size();
        return i < n_closed ? trades_[(size_t)i]
                            : range_end_trades_.row((std::size_t)(i - n_closed));
    }
    // The legacy C string ABI promises pointer lifetime until the next run.
    // Asking for that borrowed storage explicitly materializes the requested
    // row. Ordinary report/value readers never enter this compatibility path.
    const Trade& materialize_report_trade(int i) const {
        const int n_closed = static_cast<int>(trades_.size());
        return i < n_closed ? trades_.materialize(static_cast<std::size_t>(i))
                            : range_end_trades_.materialize(static_cast<std::size_t>(i - n_closed));
    }
    // Why a report row closed, from the row's own recorded facts; the report
    // index form below adds the row-space bounds. Kept together so a caller
    // holding a row value does not need a reference into the row space.
    static int classify_report_close_cause(const Trade& row);
 
    // ABI v4 live-runtime surface (task 9): classify why a REPORT-row
    // closed trade exited -- report-row scope (spans trades_ then
    // range_end_trades_, like get_report_trade above), so this cannot reuse
    // the existing protected closed_trade_* names below (strategy.
    // closedtrades.* scope: trades_ only, std::string returns). 0 UNKNOWN
    // (bad index), 1 SCRIPT, 2 BRACKET, 3 MARGIN_CALL, 4 INTRADAY_LOSS_CAP,
    // 5 INTRADAY_FILL_CAP, 6 RANGE_END. Defined in engine_trade_accessors.cpp;
    // see strategy_closed_trade_close_cause (pineforge.h) for the exact
    // derivation order.
    int closed_trade_close_cause(int i) const;
 
    // --- Position-size extremes (strategy.max_contracts_held_*) ---
    double max_contracts_held_all() const { return max_contracts_held_all_; }
    double max_contracts_held_long() const { return max_contracts_held_long_; }
    double max_contracts_held_short() const { return max_contracts_held_short_; }
 
    // --- Even-trade count (strategy.eventrades) ---
    int eventrades() const { return eventrades_count_; }
 
    void fill_report(ReportC* out) const;
    static void free_report(ReportC* report);
 
    // O1 report envelope v1 (include/pineforge/report_mode.h). Select before
    // execution; inspect the returned status constant (PF_REPORT_MODE_ACCEPTED
    // on success). Rejection is atomic. SUMMARY_ONLY must never fall back to
    // FULL.
    //
    // SUMMARY_ONLY and STREAMED keep the logical trade total and the exact
    // folds, and return no resident TradeC array: trade rows are rebuilt one
    // at a time from the closed ledger and the terminal lot mark.
    int set_report_mode_v1(ReportMode mode);
    // Streaming-ratio report-only routing and diagnostics.
    // New engines default to streaming Sharpe On. Explicit Off keeps the
    // exact curve route when SharpeBar is needed; Returns always keeps it.
    // Preferences apply at the next begin; an existing receipt stays bound
    // to the configuration of the attempt it describes.
    metrics::MetricsStreamingStatusV1 set_metrics_streaming_v1(
        metrics::StreamingSharpeV1, metrics::MetricsNeedMaskV1);
    // The receipt also observes the final metric equity mark when nonempty;
    // this observation never participates in the planned extent's identity.
    metrics::MetricsStreamingStatusV1 metrics_extent_receipt_v1(
        metrics::MetricsExtentReceiptV1*) const;
    metrics::MetricsStreamingStatusV1 admit_metrics_plain_v1(
        const MetricsPlainInputsV1&, const metrics::MetricsExtentPlanV1&,
        metrics::MetricsExtentReceiptV1*);
    // Recovery is a separate host proof, never implied by PLAIN. A prepared
    // no-curve adapter MUST resolve a LegacyRerun receipt before publication;
    // that speculative attempt exposes no owning report until resolution.
    metrics::MetricsStreamingStatusV1 prepare_metrics_streaming_v1(
        const metrics::MetricsStreamingConfigV1&,
        const metrics::MetricsExtentPlanV1&);
    // Initialize metadata.struct_size/version before reading. A successful
    // read assembles through fill_report; without an execution observer or selected generation, FULL and STREAMED present on every read; the first STREAMED read after a completed run writes the sink.
    // Release the owned payload with free_report(&out->report).
    int fill_report_envelope_v1(ReportEnvelopeV1* out) const;
 
    // Returns the error message captured by the most recent run() if it
    // failed, or an empty string if the run completed normally. Cleared at
    // the start of every run(). The C ABI exposes this via
    // strategy_get_last_error().
    const std::string& last_error() const { return last_error_; }
 
    // Per-input override (title -> serialized value). Must be set before run()
    // so get_input_*() lookups pick up the TV-tester value rather than the
    // Pine default.
    void set_input(const std::string& key, const std::string& value) {
        guard_native_mutation("set_input");
        inputs_[key] = value;
    }
    void clear_inputs() {
        guard_native_mutation("clear_inputs");
        inputs_.clear();
    }
    void set_trade_start_time(int64_t timestamp_ms) {
        guard_native_mutation("set_trade_start_time");
        trade_start_time_ = timestamp_ms;
    }
 
    // Set the chart's display timezone. Stored in a dedicated slot so it
    // does NOT clobber ``syminfo_.timezone`` (the symbol/exchange TZ).
    //
    // Pre-fix this method wrote the chart TZ into ``syminfo_.timezone``,
    // which the codegen reads as the default tz argument of the 1-arg
    // ``hour(time)`` / ``minute(time)`` / ``dayofweek(time)`` form. That
    // conflated two distinct TV concepts and silently shifted the result
    // by the chart-vs-exchange offset (e.g. Asia/Hong_Kong vs UTC = +8h)
    // for crypto symbols. The shift cascaded into ``hour``-bucketed
    // accumulators — see
    // ``validation_typed_matrix/typed-matrix-probe-01-bool-regime-mask``,
    // whose 24x7 ``matrix<bool>`` regime mask filled in 8 hours earlier
    // than TV and produced ~9% trade-count divergence (TV 773, engine 714
    // before this fix; ~778 after).
    //
    // TV semantics (Pine v6 reference docs):
    //   * Bare variable ``hour`` / ``minute`` / ``dayofweek``: exchange
    //     timezone (``syminfo.timezone``). Already correct via
    //     ``_decompose_bar_time()``'s hardcoded ``gmtime_r``, which
    //     matches the corpus' ETH-USDT (UTC) data.
    //   * 1-arg function form ``hour(time)``: defaults its tz arg to
    //     ``syminfo.timezone`` (NOT the chart display TZ). With this
    //     change, ``syminfo_.timezone`` retains its constructor default
    //     ("UTC") and the codegen lambda lands on the cheap gmtime_r
    //     branch — matching TV.
    //   * 2-arg function form ``hour(time, tz)``: honours the explicit
    //     argument, unchanged by this fix.
    void set_chart_timezone(const std::string& tz) {
        guard_native_mutation("set_chart_timezone");
        chart_timezone_ = tz;
    }
    const std::string& chart_timezone() const { return chart_timezone_; }
 
    // --- Symbol metadata injection (data feed → syminfo.*) ---
    // The exchange timezone + session feed session.ismarket / time(session)
    // predicates. They default to UTC / 24x7 (crypto); a data feed pushes
    // the real values via these setters before run().
    //
    // The source-layer intraday cap consumes a valid explicit session and this
    // timezone through its risk-day policy. Other risk-day rules keep
    // chart_timezone_, as do continuous/unconfigured order-counter clocks;
    // the existing crypto-on-shifted-chart contract therefore remains intact.
    void set_syminfo_timezone(const std::string& tz) {
        guard_native_mutation("set_syminfo_timezone");
        syminfo_.timezone = tz;
    }
    void set_syminfo_session(const std::string& s) {
        guard_native_mutation("set_syminfo_session");
        syminfo_.session = s;
    }
    // ``syminfo.type`` ("crypto" default; "forex" / "stock" / "futures" /
    // "index" / "fund" / "cfd" per TradingView). Scripts branch on it for
    // instrument conventions — the canonical one being the pip size
    // (``syminfo.type == "forex" ? 0.0001 : syminfo.mintick``), which on a
    // 5-digit FX symbol under the crypto default computed every pip-scaled
    // stop/target 10x too tight (finding 454). Empty is ignored.
    void set_syminfo_type(const std::string& t) {
        guard_native_mutation("set_syminfo_type");
        if (!t.empty()) syminfo_.type = t;
    }
    /// Whether TradingView's session template for this symbol carries the
    /// exchange's early closes and holidays, so a D/W/M request.security
    /// bucket completes on a shortened session's actual last chart bar
    /// (TimeframeAggregator::set_early_close_completes): exchange-listed
    /// kinds (stock, futures, index, fund, dr, ...) yes -- NYSE:F's 12:45 ET
    /// half-day bar and CME's 11:45 CT early-close bar are pinned; the OTC
    /// quote streams -- forex, cfd, crypto -- no: their period ends at the
    /// nominal close and a session ending early completes lazily on the
    /// next period's first bar (OANDA:XAUUSD 15m, lab tv oanda pin, ledger
    /// log-20260905t034240z-30be11fe). syminfo.type comes from the harness
    /// (strategy_set_syminfo_type <- PINEFORGE_VERIFY_SYMTYPE); the
    /// constructor default "crypto" keeps an untyped run on the lazy rule.
    bool session_template_knows_early_close() const;
    // Generic string-field injection for the remaining OHLCV-less syminfo
    // members (ticker / tickerid / currency / basecurrency / description /
    // volumetype / type). Unknown keys and empty values are ignored; returns
    // true when a field was set.
    bool set_syminfo_string(const std::string& key, const std::string& value) {
        guard_native_mutation("set_syminfo_string");
        if (value.empty()) return false;
        if (key == "type") { syminfo_.type = value; return true; }
        if (key == "ticker") { syminfo_.ticker = value; return true; }
        if (key == "tickerid") { syminfo_.tickerid = value; return true; }
        if (key == "currency") { syminfo_.currency = value; return true; }
        if (key == "basecurrency") { syminfo_.basecurrency = value; return true; }
        if (key == "description") { syminfo_.description = value; return true; }
        if (key == "volumetype") { syminfo_.volumetype = value; return true; }
        return false;
    }
    // Runtime syminfo injection (by design — the engine stores no instrument
    // metadata of its own; the harness supplies it per run). mintick drives the
    // directional fill snap + slippage*tick economics; pointvalue is the
    // futures $-per-point multiplier applied to every money path (realized
    // PnL + excursions, open profit / equity, percent/cash sizing, percent
    // commission notionals, margin check — see tests/test_pointvalue.cpp).
    // Both default to crypto/equity values (0.01 / 1.0) and only matter when the
    // harness sets a non-default instrument.
    void set_syminfo_mintick(double m) {
        guard_native_mutation("set_syminfo_mintick");
        if (m > 0.0) { syminfo_.mintick = m; syminfo_mintick_ = m; }
    }
    void set_syminfo_pointvalue(double pv) {
        guard_native_mutation("set_syminfo_pointvalue");
        if (pv > 0.0) { syminfo_.pointvalue = pv; }
    }
 
    virtual void set_syminfo_metadata(const std::string& key, double value);
 
    // Returns the script's active timeframe string (e.g. "15" for 15-minute,
    // "D" for daily). Backs timeframe.main_period in generated Pine v6 code.
    const std::string& main_period() const { return script_tf_; }
 
    // Host run-mode overrides behind the frozen C setters
    // strategy_set_realtime_tail / strategy_set_probe_suppress_tail_logic
    // (pineforge.h). The kernel keeps no forming-tail state of its own: a
    // batch is complete input and the forward path is the stream, so
    // "the last fed bar is still forming" and "run only the broker steps on
    // the last bar" are a host's live-probe protocol, not a kernel mode. A
    // host that models one (source::PineStrategyHost, for the live runner's
    // probe / settle cycle) overrides both, owns the state and answers true.
    // The kernel default keeps the C ingress contract these setters always
    // had on a bare host -- accepted before begin, guarded like every other
    // setter, and inert (no kernel path ever read the flags on a native
    // host) -- so it stores nothing, leaves last_error() untouched and
    // answers false, meaning "no such mode here". The source-runtime extraction: the flags
    // were BacktestEngine members until then.
    virtual bool set_realtime_tail(bool on, int horizon_bars);
    virtual bool set_probe_suppress_tail_logic(bool on);
 
    // Force this run's intrabar path order (ABI v4 live-runtime surface,
    // task 4): 0 AUTO (the unchanged |H-O| vs |O-L| rule), 1 HIGH_FIRST
    // (O -> H -> L -> C), 2 LOW_FIRST (O -> L -> H -> C). Any other value is
    // clamped to AUTO. A live probe runs the SAME forming bar under both
    // forced orders and keeps only the fills that agree between the two --
    // a fill that depends on which leg TradingView's own still-forming bar
    // will resolve to is path-dependent and must be suppressed rather than
    // guessed.
    // Persistent configuration, like set_realtime_tail -- stays set until a
    // caller passes mode=0. It only stores the mode: a native-bound source
    // provider projects it into NativeRunSpec::path_order at begin (a bare
    // native host declares that field itself), and the native driver walks
    // the spec field, handing the declared order to the intrabar sampler
    // itself (internal::sample_price_path_ordered).
    // Default AUTO (mode=0): every historical run stays byte-identical to
    // before this flag existed.
    void set_path_order(int mode) {
        guard_native_mutation("set_path_order");
        path_order_mode_ = (mode == 1 || mode == 2) ? mode : 0;
    }
 
    // Live runtime G1 (spec §3.4): a deterministic, order-independent
    // FNV-1a 64 hash over every piece of broker state that decides the next
    // bar's fills (position, book, pyramid lots, trail scalars, cycle/
    // intraday/risk latches, frozen sizing, equity sums). Two engines with
    // equal broker state hash equally regardless of unordered-container
    // insertion history; any difference in that state changes the hash.
    // Implemented in engine_state_hash.cpp; coverage of the marked
    // broker-state region(s) below (grep this file for "broker-state") is
    // enforced by scripts/check_broker_state_hash_coverage.py.
    uint64_t broker_state_hash() const;
 
    // The live position's volume-weighted average entry price
    // (position_entry_price_; 0 when flat -- the engine keeps 0 there, the
    // C ABI reports NaN when flat), its cycle id (position_cycle_seq_; 0
    // when flat, a fresh nonzero id per open/reversal, kept across
    // same-direction adds) and the trail extreme the exit trail legs ride
    // (trail_best_price_; NaN until a position fills).
    double position_avg_price() const { return position_entry_price_; }
    int64_t position_cycle_seq() const { return position_cycle_seq_; }
    double trail_best_price() const { return trail_best_price_; }
    // ABI v4 live-runtime surface (task 9): public forwarders for the C
    // ABI, which -- being extern "C" free functions -- cannot reach the
    // protected signed_position_size() / current_equity() above.
    // signed_position_size() is strategy.position_size (freeze-aware:
    // reads the pre-close position while a same-bar POOC close is frozen).
    // current_equity() is initial capital plus realized net profit
    // (strategy.initial_capital + strategy.netprofit). NOT Pine's
    // strategy.equity, which adds open profit on top of this (see the
    // sizing_equity formula and the equity-curve remark below, both
    // current_equity() + open_profit(...)).
    double initial_capital() const;
    virtual double live_position_size() const {
        if (position_side_ == PositionSide::LONG) return position_qty_;
        if (position_side_ == PositionSide::SHORT) return -position_qty_;
        return 0.0;
    }
    // The live-runtime observation seam (ABI v4, spec 3.6): read-only views
    // of the arbitration this run's last bar decided, of the resting-order
    // book in force for the next bar and of the engine-computed derived
    // values of one resting order. Every one is a pure const read, so a run
    // is byte-identical whether or not a caller reads it. The kernel's own
    // answer is "not available" (0 / -1 / NaN): the host that owns the book
    // overrides them, and the C surface documents what each value means
    // (strategy_last_bar_dual_entry_path, strategy_pending_orders_len,
    // strategy_pending_order_get, strategy_pending_order_fill_qty,
    // strategy_pending_order_level_resolved,
    // strategy_pending_order_effective_levels, strategy_trail_best_price --
    // include/pineforge/pineforge.h).
    virtual int observe_last_bar_dual_entry_path_v1() const;
    virtual int observe_pending_count_v1() const;
    virtual int observe_pending_copy_v1(int index, pf_pending_order_v1_t* out) const;
    virtual int observe_probe_fill_qty(int index, double fill_price, double* qty,
                                       int* close_only, int* partition) const;
    virtual int observe_pending_level_resolved(int index) const;
    virtual int observe_pending_effective_levels(int index, double* stop,
                                                 double* limit,
                                                 double* trail_activation) const;
    virtual double observe_trail_best_price_v1() const; virtual bool set_symbol_feed_borrowed(const std::string&, const std::string&, const Bar*, const int64_t*, int) { guard_native_mutation("set_symbol_feed_borrowed"); return false; }
    double live_current_equity() const { return current_equity(); }
    // ABI v4 live-runtime surface (task 9): total SCRIPT bars dispatched by
    // the most recent run() (mirrors pf_report_t::script_bars_processed,
    // engine_report.cpp), including the stream warmup leg and every
    // realtime tick-driven bar after strategy_stream_begin.
    int64_t script_bars_processed() const { return diag_script_bars_processed_; }
 
    // ABI v4 live-runtime surface (task 6): when on, every report point
    // appends broker_state_hash() to broker_state_hashes_
    // immediately after that bar's record_equity_point() call -- under
    // KernelRecorded the execution consumer's record_script_report_point,
    // which every script calculation it delivers reaches (confirmed,
    // intrabar and aggregated bars, in a batch run and across a stream's
    // warmup and realtime legs); a host that records or marks its own report
    // points appends its own row at each -- so a completed run's recorded
    // array has one row per report point (and, under KernelRecorded, matches
    // script_bars_processed and pf_report_t::broker_state_hash_len 1:1) --
    // including on strategy_stream_fill_report, whose report is the
    // cumulative warmup + realtime run. Default off: broker_state_hashes_
    // stays empty, fill_report emits a null/zero-length array, and every
    // historical run stays byte-identical to before this flag existed.
    // reset_run_state() clears the recorded array on every run() (the
    // warmup leg of stream_begin included) regardless of this flag's
    // value; the flag itself is persistent configuration, like
    // set_realtime_tail, so it must be set BEFORE stream_begin to also
    // cover the warmup bars.
    //
    // What a row is, and what it is for. A row is the run's CONTINUATION
    // IDENTITY at that bar, not its trade outcome: broker_state_hash() is
    // broker_state_hash_from_execution_hash(continuation_hash()), so it folds
    // the kernel's broker state AND, ahead of it, the state a resume would
    // continue from. NativeRunPhase (Batch/Warmup/Realtime, readable as
    // native_state().phase) is part of that continuation on purpose, because a
    // consumer mid-warmup and one mid-realtime are not interchangeable
    // continuations. So the array is a replay check WITHIN one driving mode
    // and deliberately not across modes:
    //   * same driving -- two runs driven the same way record the same rows,
    //     and the row after bar k is the last row of a run driven the same way
    //     that ended at bar k (a batch and a stream at any warmup split);
    //   * different driving -- run(), stream_begin(warmup=1)+push and
    //     stream_begin(warmup=all) over the same bars booking the same trades
    //     record different rows from index 0; only the length identity above
    //     survives. Without subscriptions, streams share their Warmup prefix.
    //   * the broker half alone IS driving-mode invariant: factor the
    //     continuation out with broker_state_hash_from_execution_hash(fixed)
    //     and the remaining fold is identical at every bar in every driving.
    // The batch<->stream oracle is therefore the OUTCOME, not this array:
    // tests/test_native_margin_fx_roll.cpp section 8 and
    // tests/test_native_report_truth.cpp are the kernel witnesses;
    // tests/test_streaming.cpp is the source-layer companion, and
    // scripts/check_corpus_parity.sh covers the Pine adapter.
    // Both directions are pinned in tests/test_native_report_truth.cpp.
    void set_broker_state_hash_recording(bool on) {
        guard_native_mutation("set_broker_state_hash_recording");
        broker_state_hash_recording_ = on;
    }
 
    // Toggle volume-weighted per-sub-bar sampling of the intrabar path (see
    // magnifier_volume_weighted_). Has no effect unless bar magnifier is
    // enabled.
    void set_magnifier_volume_weighted(bool on) {
        guard_native_mutation("set_magnifier_volume_weighted");
        magnifier_volume_weighted_ = on;
    }
 
    // --- Runtime trace API ---
    // Default off so existing strategies pay zero cost. The validator
    // flips this on per-strategy via ``strategy_set_trace_enabled`` (the
    // FFI shim defined in c_abi.cpp) before running a backtest whose
    // per-bar values it wants to cross-reference against TradingView.
    void set_trace_enabled(bool on) {
        guard_native_mutation("set_trace_enabled");
        trace_enabled_ = on;
    }
    bool trace_enabled() const { return trace_enabled_; }
 
    // --- Live-runtime status API (ABI v4) ---
    int last_run_status() const { return last_run_status_; }
 
    // Request cooperative abort of the run in progress on this handle (a
    // live runtime supersedes an in-flight probe run). Safe to call from any
    // thread; consumed by the running loop at its next bar. A request made
    // while idle is cleared at the next run() entry and is a no-op.
    void request_abort() { abort_requested_.store(true, std::memory_order_relaxed); }
 
    // Push a typed per-bar value into the trace buffer. Cheap when
    // disabled — a single bool branch and return. When enabled, name
    // interning amortises to a single hash lookup per call after the
    // first occurrence; the actual record is a 24-byte POD push_back.
    //
    // The bool / int overloads internally cast to double so the
    // transpiler pragma can emit a single call shape regardless of the
    // source variable's Pine type — keeping codegen rewrites trivial.
    void trace(const std::string& name, double value);
    void trace(const std::string& name, bool value)  { trace(name, value ? 1.0 : 0.0); }
    void trace(const std::string& name, int value)   { trace(name, static_cast<double>(value)); }
 
    // --- Recorded outputs (docs/outputs.md) ---
    // Named slots of doubles kept per bar, values kept once per run, and
    // events with an optional text, written by a generated module or a C++
    // host and read through the strategy_outputs_* C exports. Off until a
    // caller enables recording; no matching, fill, margin, sizing, report or
    // hash path reads the record, and none of it is hashed. The host states
    // the shape once (declare_outputs), the boundary of every run
    // (output_run_begin) and the identity of every row (output_bar): a row is
    // a bar the host published, keyed by its open time. A violated
    // precondition throws std::logic_error coded engine_invariant; a cap the
    // run reached (outputs_limit) or a bar recalculated after its events were
    // cleared (outputs_rejected) throws std::runtime_error. Either fails the
    // run inside a callback with its text and code. See src/engine_report.cpp.
public:
    struct OutputEvent {
        uint64_t sequence = 0;        // 1-based per run; a cleared one is never issued again
        int32_t output_index = 0;
        int32_t bar_index = 0;        // the row it was recorded on
        int64_t bar_open_ms = 0;
        int64_t bar_close_ms = 0;
        uint32_t ordinal_in_bar = 0;  // per output, from 0 within the row
        uint32_t phase = 0;           // the run's NativeRunPhase when recorded
        uint32_t confirmed = 1;       // 0 on a calculation of a partially finalized bar
        double value = 0.0;
        uint64_t message_hash64 = 0;  // FNV-1a 64 of the message bytes; 0 without one
        bool has_message = false;
        std::string message;
    };
 
    bool outputs_declared() const { return outputs_declared_; }
    // false: refused (nothing declared, or a change while the host is Running);
    // last_error() says which unless it holds a failed run's error, and a
    // success leaves it as it is. A change of the flag clears the record.
    bool set_outputs_enabled(bool on);
    // The readers behind the C exports. While recording is off the record is
    // empty and the counts are 0.
    int output_series_count() const { return outputs_enabled_ ? outputs_slots_ : 0; }
    int64_t output_bars_len() const { return static_cast<int64_t>(output_open_ms_.size()); }
    bool output_bar_times_copy(int64_t from_bar, int64_t* open_ms, int64_t* close_ms,
                               int64_t capacity, int64_t* written) const;
    bool output_series_copy(int slot, int64_t from_bar, double* out, int64_t capacity,
                            int64_t* written) const;
    int output_events_len() const { return static_cast<int>(output_events_.size()); }
    const OutputEvent* output_event_at(int index) const;
    // Drops the queued events; rows, ordinals and the sequence stay.
    void output_events_clear();
    int output_constants_count() const { return outputs_enabled_ ? outputs_constants_ : 0; }
    // NaN for na, for a value not written this run, or out of range.
    double output_constant_value(int index) const;
 
protected:
    // Read by generated code before each recorder call, as trace_enabled_ is.
    bool outputs_enabled_ = false;
    // Once, before the first run: the slots per row, the outputs an event may
    // name and the values kept per run. Repeating it repeats the same counts.
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    void declare_outputs(int series_slots, int outputs, int run_constants = 0);
    // At every run's beginning (a C++ host: on_native_run_begin): an empty
    // record, the sequence from 1, every run value unwritten. Idempotent.
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    void output_run_begin();
    // Opens the row of the bar being calculated: a new row above the last
    // row's open, the last row again (a recalculation) at an equal one; a
    // lower open throws. The writers below return at once while recording is
    // off.
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    void output_bar(int64_t open_ms, int64_t close_ms);
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    void output_value(int slot, double value);
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    void output_event(int output, double value);
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    void output_event(int output, double value, const std::string& message);
    // The run's first write of an index stores it; a later one must be equal.
    // @host-seam (native_c_api.h, COVERAGE / BASE-CLASS SEAMS)
    void output_constant(int index, double value);
 
private:
    void clear_output_record();
    bool output_host_running() const;
    void record_output_event(int output, double value, const std::string* message);
    int outputs_slots_ = 0;
    int outputs_count_ = 0;
    int outputs_constants_ = 0;
    bool outputs_declared_ = false;
    bool output_run_begun_ = false;
    std::vector<double> output_series_;          // row-major, rows x slots; NaN unwritten
    std::vector<int64_t> output_open_ms_;
    std::vector<int64_t> output_close_ms_;
    std::vector<OutputEvent> output_events_;     // since the run began or the last clear
    uint64_t output_sequence_ = 0;               // the last sequence issued
    uint64_t output_row_seq_base_ = 0;           // its value when the last row opened
    uint64_t output_cleared_sequence_ = 0;       // the highest sequence a clear dropped
    std::vector<uint32_t> output_ordinals_;      // per output, within the last row
    std::vector<double> output_constants_;
    std::vector<uint8_t> output_constant_written_;
 
private:
    // The run spec's quantity tolerance (NativeRunSpec::quantity_tolerance),
    // 0 when the run declares none, which keeps the settlement exact. The FIFO
    // close walk and the opening beside a surviving book read it
    // (src/engine_execution.cpp); the execution consumer, a friend, projects
    // it from the spec at every begin, and the spec digest folds the spec's
    // value. Private, so no host writes it (the representable-quantity refusal change).
    double native_quantity_tolerance_ = 0.0;
 
    // Physical scratch policy and run ownership, independent of the report
    // sink. Neither participates in trading decisions or durable hash leaves;
    // the logical tables keep their existing folds. Copies retain only policy.
    detail::ScratchTableConfig scratch_table_config_{};
    struct ScratchTableRun {
        std::shared_ptr<detail::ScratchSlab> slab;
        ScratchTableRun() = default;
        ScratchTableRun(const ScratchTableRun&) noexcept {}
        ScratchTableRun& operator=(const ScratchTableRun& other) noexcept {
            if (this != &other) slab.reset();
            return *this;
        }
        ScratchTableRun(ScratchTableRun&&) noexcept = default;
        ScratchTableRun& operator=(ScratchTableRun&&) noexcept = default;
    };
    ScratchTableRun scratch_table_run_;
    void prepare_scratch_table_run(const detail::ScratchTableConfig& config);
 
    // Reporting configuration and run-local output ownership. Copies retain
    // configuration, never a writer, receipt, or an active-call barrier.
    struct ReportSinkState {
        bool enabled = false;
        bool trade_history_streamable = false;
        std::string path, run_id, scratch_dir;
        int fd = -1; // borrowed stream; -1 selects the owned path writer
        std::uint64_t fd_device = 0;
        std::uint64_t fd_inode = 0;
        bool fd_identity_valid = false;
        std::uint32_t active_calls = 0;
        std::uint32_t stream_calls = 0;
        std::unique_ptr<report_sink::LineWriter> writer;
        // Shared ordinary/selected record-time curve. Selected capture moves
        // this owner to its immutable presentation snapshot.
        std::unique_ptr<report_sink::ScratchCurveWriter> equity_scratch;
        bool equity_tail_stored = false; // scratch includes the held tail
        pf_report_sink_receipt_v1 receipt{};
        pf_report_sink_summary_v1 summary{}; // report output, shares the sink hash waiver
        // Derived report-tail prefix, in max/min/drawdown/runup order. The
        // resulting extrema already have their broker-state folds; this
        // reconstructible prefix shares report_sink_state_'s output waiver.
        double equity_prefix[4]{};
        // Report cursor only, covered by report_sink_state_'s existing
        // broker-hash waiver. No execution decision reads it; copies reset it.
        std::int64_t output_base = 0;
        // Selected report validation only, under report_sink_state_'s output
        // waiver. Released FINAL points are latched here, never broker inputs.
        std::unique_ptr<report::SelectedReportStream> selected_equity_stream;
        // Independent full-run reference for selected tail refolds, including
        // observations outside [T, E) that the selected scratch must omit.
        // Always present so test/module and library NDEBUG settings agree on
        // the C++ layout; only Debug updates/reads these report-only values.
        double selected_released_extremes[4]{};
        ReportSinkState();
        ~ReportSinkState();
        ReportSinkState(const ReportSinkState& other);
        ReportSinkState& operator=(const ReportSinkState& other);
        ReportSinkState(ReportSinkState&&) noexcept;
        ReportSinkState& operator=(ReportSinkState&&) noexcept;
    };
    // @broker-state begin
    mutable ReportSinkState report_sink_state_;
    // @broker-state end
    // O1 capture policy for reports built after it is set. Deliberately
    // outside the broker-state region: it changes no fill, fold, hash leaf or
    // continuation digest (two runs over the same input with different report
    // modes must hash identically), and reset_run_state leaves it in place
    // like the sink descriptor.
    ReportMode report_mode_ = ReportMode::FULL;
 
    class ReportSinkCallScope {
        ReportSinkState& state;
        bool stream;
    public:
        explicit ReportSinkCallScope(const BacktestEngine& engine, bool is_stream = false)
            : state(engine.report_sink_state_), stream(is_stream) {
            ++state.active_calls;
            if (stream) ++state.stream_calls;
        }
        ~ReportSinkCallScope() {
            if (stream) --state.stream_calls;
            --state.active_calls;
        }
        ReportSinkCallScope(const ReportSinkCallScope&) = delete;
        ReportSinkCallScope& operator=(const ReportSinkCallScope&) = delete;
    };
    int report_sink_setter_status() const;
    void begin_report_sink();
    void finish_report_sink(ReportC* out) const;
    void stage_report_sink_equity_point(const pf_equity_point_t& point) const;
    void stage_report_sink_equity_tail(const ReportC* out) const;
    void compute_report_sink_metrics(ReportC* out, std::int64_t equity_count,
                                     CacheCapacity equity_capacity) const;
    void compute_report_sink_trade_metrics(ReportC* out,
                                           const TradeC* open_rows, int count) const;
    void write_report_sink_trades(const TradeC* open_rows, int count) const;
    void fill_report_sink_metrics_section(ReportC* out) const;
    template<class Write> void report_sink_record(Write write) const;
    bool stream_report_sink_trace(const std::string& name, const TraceEntryC& entry);
    void reset_report_sink_outputs();
    std::int64_t report_sink_output_row() const;
    void write_report_sink_output_row() const;
    void write_report_sink_events() const;
    void retire_report_sink_output_row();
    void write_report_sink_hashes() const;
    void retire_report_sink_hashes();
    void begin_report_replay();
    void finish_report_replay(const ReportC* out) const;
    void record_report_replay_close(std::size_t global);
    void record_report_replay_point(const pf_equity_point_t& point);
    void write_report_replay_equity(const pf_equity_point_t& point) const;
    void write_report_replay_trade(std::size_t global, bool terminal) const;
    void retire_report_replay_trades(std::size_t global_end);
 
public:
    // The C descriptor is copied only after the lifecycle/shape checks. The
    // existing idle barrier covers begin callbacks even when the sink is OFF.
    int set_scratch_tables_v1(const pf_scratch_tables_v1* descriptor) {
        if (descriptor && (descriptor->struct_size != sizeof(*descriptor)
            || descriptor->version != 1 || descriptor->reserved != 0
            || descriptor->backend > static_cast<std::uint32_t>(
                detail::ScratchTableBackend::bounded_memory)
            || descriptor->V > 27)) return -1;
        const int status = report_sink_setter_status();
        if (status != 0) return status;
        detail::ScratchTableConfig next;
        if (descriptor) {
            next.backend = static_cast<detail::ScratchTableBackend>(descriptor->backend);
            next.manifest = {descriptor->K_q, descriptor->B_q,
                             descriptor->K_e, descriptor->B_e,
                             descriptor->K_c, descriptor->B_c,
                             descriptor->U, descriptor->B_U,
                             descriptor->V, descriptor->B_V, descriptor->R};
        }
        scratch_table_config_ = next;
        return 0;
    }
    const detail::ScratchTableConfig& scratch_table_config() const noexcept {
        return scratch_table_config_;
    }
 
    // Physical policy lives behind the opaque consumer, so these additive
    // methods do not change the engine's layout or virtual interface.
    int set_cache_policy_v1(const pf_cache_policy_v1* descriptor);
    void set_cache_policy(const CacheDefaults& policy);
    const CacheDefaults& cache_policy_config() const;
    const CacheDefaults& cache_policy_for_run() const;
    void set_scratch_io_policy(const ScratchIoPolicy& policy);
    int set_scratch_io_policy_v1(const pf_scratch_io_policy_v1* descriptor);
    const ScratchIoPolicy& scratch_io_policy_config() const;
    const ScratchIoPolicy& scratch_io_policy_for_run() const;
 
    // The additive C ABI delegates here; receipt queries never bind a consumer.
    int set_report_sink_v1(const pf_report_sink_v1* sink);
    int set_report_sink_fd_v1(const pf_report_sink_fd_v1* sink);
    int report_sink_receipt_v1(pf_report_sink_receipt_v1* out) const noexcept;
    int report_sink_summary_v1(pf_report_sink_summary_v1* out) const noexcept;
    int report_sink_diagnostics_v1(pf_report_sink_diagnostics_v1* out) const noexcept;
    int set_report_replay_v1(const char* path, const char* run_id);
    double raw_net_profit_sum() const noexcept { return net_profit_sum_; }
    double report_pointvalue() const noexcept;
    // Codegen opts in only for modules that do not read closedtrades.*.
    // L6B1 still retains every row; L8c consumes this policy at sealing.
    void set_trade_history_streamable(bool streamable);
    bool trade_history_streamable() const { return report_sink_state_.trade_history_streamable; }
 
protected:
    // A private configuration tag uses the existing pending scalar, never
    // object padding or a public recorder mode. The setter admits only the
    // three public values; begin strips the tag before activating the mode.
    // OFF hooks perform no registry lookup, lock, allocation or replay call.
    static constexpr std::uint32_t report_replay_flag = UINT32_C(0x80000000);
    ReportMode pending_equity_report_mode() const noexcept {
        return static_cast<ReportMode>(
            static_cast<std::uint32_t>(pending_equity_report_mode_) & ~report_replay_flag);
    }
    ReportMode with_report_replay_flag(ReportMode mode) const noexcept {
        return static_cast<ReportMode>(static_cast<std::uint32_t>(mode)
            | (static_cast<std::uint32_t>(pending_equity_report_mode_) & report_replay_flag));
    }
    report::ReportReplay* report_replay_state() const noexcept {
        if (!(static_cast<std::uint32_t>(pending_equity_report_mode_) & report_replay_flag))
            return nullptr;
        return find_report_replay();
    }
    report::ReportReplay* find_report_replay() const noexcept;
    void amend_report_replay_point(std::int64_t time, report::EquityBasis basis,
                                  double term) const;
    // Begin-only source binder input. Backends copy the owner, not this
    // reference; no byte pointer is exposed to a strategy or a hot callback.
    const std::shared_ptr<detail::ScratchSlab>& scratch_tables_for_run() const noexcept {
        return scratch_table_run_.slab;
    }
 
    // In-place closed-trade text comparisons (see TradeLedger::*_matches): an
    // invalid index compares as the empty string, as the owning getters return.
    bool closed_trade_entry_id_equals(int idx, std::string_view rhs) const {
        return trades_.entry_id_matches(idx, rhs);
 
    }
    bool closed_trade_exit_id_equals(int idx, std::string_view rhs) const {
        return trades_.exit_id_matches(idx, rhs);
 
    }
    bool closed_trade_entry_comment_equals(int idx, std::string_view rhs) const {
        return trades_.entry_comment_matches(idx, rhs);
 
    }
    bool closed_trade_exit_comment_equals(int idx, std::string_view rhs) const {
        return trades_.exit_comment_matches(idx, rhs);
 
    }
 
    // The last point stays editable until its successor is recorded. Sinks
    // using the kernel recorder keep only this tail; sink OFF keeps the array.
    pf_equity_point_t* last_equity_point() noexcept;
    const pf_equity_point_t* last_equity_point() const noexcept;
    // Sink execution prefix, excluding the editable held point. A selected
    // prefix starts with its anchor and contains only released window points.
    // The returned descriptor is borrowed; observing flushes pending writes.
    metrics::ScratchCurveRegion report_sink_equity_scratch_region() const;
    void store_equity_point(const pf_equity_point_t& point);
    bool prepare_equity_point(); // release the prior point; true for the first
    void fold_report_equity_extreme(double equity);
    void refold_equity_tail();
    void present_report_equity_tail(ReportC* out) const;
    // Sealed closed rows only; range-end report rows never enter these sums.
    // Each accessor continues its own sum one resident row at a time, so a
    // separately accumulated tail cannot change floating-point grouping.
    struct TradePercentPrefix {
        double all_sum = 0.0;
        double win_sum = 0.0;
        double loss_sum = 0.0;
        std::size_t all_count = 0;
        std::size_t win_count = 0;
        std::size_t loss_count = 0;
    };
    // @broker-state begin
    TradePercentPrefix trade_percent_prefix_;
    // @broker-state end
 
    // The sealing caller folds each final row exactly once, in global row
    // order, immediately before retiring it from trades_. This operation
    // does not change storage, logical indices or the win/loss guards.
    void fold_trade_percent_prefix(const Trade& trade);
    // The streaming owner clears this prefix with the run's closed rows.
    void reset_trade_percent_prefix();
    // A sink hook receives only range-end rows. Re-summing an edited tail
    // starts with this closed-row left fold, never a separately summed tail.
    double report_closed_net_profit() const;
 
    // Optional sequence retention. The default is
    // the historical owning-array path, byte-identical to before. SummaryOnly
    // keeps one fixed ordered witness per sequence instead, so trial memory
    // does not grow with the bar, trace, row or event population. A report
    // sink streams the complete sequence externally in either mode.
public:
    int set_optional_report_mode(report_sequence::ReportMode mode);
    report_sequence::OptionalSequenceSummary optional_sequence_summary() const;
 
private:
    void reset_optional_sequence_witness();
    void fold_pending_hashes_into_witness() const;
    void fold_current_output_row_witness() const;
    void finalize_summary_output_row();
    static void fold_hash_leaf(report_sequence::SequenceWitness& witness,
                               std::uint64_t hash);
    static void fold_trace_leaf(report_sequence::SequenceWitness& witness,
                                std::int64_t timestamp, std::int32_t bar_index,
                                const std::string& name, double value);
    static void fold_row_leaf(report_sequence::SequenceWitness& witness,
                              std::int64_t row, std::int64_t open_ms,
                              std::int64_t close_ms, const double* values,
                              std::int64_t count);
    static void fold_event_leaf(report_sequence::SequenceWitness& witness,
                                const OutputEvent& event);
    report_sequence::ReportMode optional_report_mode_ =
        report_sequence::ReportMode::LegacyArrays;
    // The sink writers and fill_report are const; the witness is the only
    // state they add, and no reader observes it as part of the run's report.
    mutable report_sequence::OptionalSequenceSummary sequence_witness_;
    mutable std::size_t sequence_hash_folded_ = 0;
    mutable std::uint64_t sequence_hash_folded_leaf_ = 0;
    mutable bool sequence_row_folded_ = false;
    report_sequence::SequenceWitness output_row_witness_base_;
    report_sequence::SequenceWitness output_event_row_witness_;
 
public:
    // Configure this thread's next hosts BEFORE their constructors declare
    // outputs. nullptr means unlimited; a negative value is a checked refusal.
    static int set_output_series_limit_checked(const std::int64_t* maximum,
                                               char* error, std::size_t capacity) noexcept;
    // 1: a declaration exceeded its operator limit since the last successful
    // setter; write that maximum. 0: none; -1: null destination. No allocation.
    static int output_series_limit_failure(std::int64_t* maximum) noexcept;
 
    // Independent of legacy security_eval_states_: registering a context from
    // an evaluator never invalidates the registry a native pump is visiting.
    RuntimeContextService& runtime_contexts() noexcept { return runtime_contexts_; }
    const RuntimeContextService& runtime_contexts() const noexcept { return runtime_contexts_; }
    bool runtime_context_early_close_completes() const;
 
private:
    static std::optional<std::int64_t> default_output_series_limit() noexcept;
    // Recorder admission only, outside execution state and its hashes, like
    // the output shape and recording switch. Existing hosts keep their setting.
    std::optional<std::int64_t> max_output_series_ = default_output_series_limit();
    RuntimeContextService runtime_contexts_;
};
 
inline constexpr std::size_t kReportSinkHeldEquityPoints = 1;
 
} // inline namespace engine_script_run_v20
} // namespace pineforge
 
// Optional metrics C entry points, implemented in engine_report.cpp and
// declared here independently of pineforge.h's static-runtime inventory.
// Native modules advertise their certified execution adapter separately via
// strategy_metrics_only_capability_v1 (native_module.hpp).
// mode: 0=OFF, 1=ON (default);
// metrics_needed is the OR of kMetricsNeed*V1. The getter is an additive
// diagnostic transport; it does not extend pf_report_t.
extern "C" PF_API std::int32_t strategy_set_metrics_streaming_v1(
    void* strategy, std::uint32_t streaming_sharpe,
    std::uint64_t metrics_needed) noexcept;
extern "C" PF_API std::int32_t strategy_metrics_extent_receipt_v1(
    const void* strategy, pineforge::metrics::MetricsExtentReceiptV1* out) noexcept;