pineforge.h

Go to the documentation of this file.

/*
 * SPDX-License-Identifier: Apache-2.0
 *
 * pineforge.h — public C ABI for the PineForge runtime.
 *
 * This header is the single source of truth for the harness ↔ compiled-
 * strategy boundary. Every PineForge-generated .so exports a fixed set
 * of C symbols declared below; the Python harness (validate_detailed_
 * report.py) and any C/C++/FFI consumer of compiled strategies links
 * against this contract.
 *
 * STABILITY GUARANTEE
 * ───────────────────
 * Within the same PINEFORGE_VERSION_MAJOR, this header's POD struct
 * layouts and `extern "C"` symbol signatures are append-only. Fields
 * are never reordered, removed, or retyped; new fields may only be
 * appended at the end of structs. New functions may be added; existing
 * functions are not removed or signature-changed.
 *
 * Across major versions all bets are off. Bump
 * PINEFORGE_VERSION_MAJOR when breaking the ABI.
 *
 * SCOPE — WHAT THIS HEADER COVERS
 * ───────────────────────────────
 * ✓ Lifecycle of a compiled strategy (create / destroy)
 * ✓ Running a backtest (auto-detect or fully configured)
 * ✓ Per-strategy configuration (inputs, overrides, magnifier, trace)
 * ✓ The shape of the report returned to the harness
 *
 * SCOPE — WHAT THIS HEADER DOES NOT COVER (BY DESIGN)
 * ───────────────────────────────────────────────────
 * ✗ The contract between codegen-emitted strategy code and the runtime
 *   internals (TA classes, math, series, strategy commands). That
 *   contract stays C++ — codegen and runtime ship together and are
 *   versioned in lockstep within the closed transpiler.
 * ✗ Source-compiling strategies. Use the closed transpiler binary.
 *
 * The C++ headers under `<pineforge/engine.hpp>` etc. are *internal*
 * implementation surface — not part of this stability guarantee.
 */
 
#ifndef PINEFORGE_H
#define PINEFORGE_H
 
#include <stdint.h>
#include <stddef.h>
 
/* Public C words with enum types must retain their published width even when
 * a consumer enables -fshort-enums. The C99 fallback keeps the strict-C99
 * header build valid; the two newer languages get a native static assertion. */
#if defined(__cplusplus)
#define PF_STATIC_ASSERT(condition) static_assert((condition), #condition)
#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
#define PF_STATIC_ASSERT(condition) _Static_assert((condition), #condition)
#else
#define PF_STATIC_ASSERT_JOIN_(a, b) a##b
#define PF_STATIC_ASSERT_JOIN(a, b) PF_STATIC_ASSERT_JOIN_(a, b)
#define PF_STATIC_ASSERT(condition) \
    typedef char PF_STATIC_ASSERT_JOIN(pf_static_assertion_, __LINE__)[(condition) ? 1 : -1]
#endif
 
/* ── Version ─────────────────────────────────────────────────────── */
/* Macros (PINEFORGE_VERSION_MAJOR / _MINOR / _PATCH / _STRING / _FULL,
 * PINEFORGE_GIT_SHA) live in the generated <pineforge/version.h>. */
#include <pineforge/version.h>
 
/* pf_pending_order_v1_t / pf_field_desc_t -- the generated, C-compatible POD
 * mirror of the engine's resting-order record (ABI v4, task 7). Regenerate
 * with scripts/gen_pending_order_mirror.py; never edit by hand. */
#include <pineforge/pending_order_mirror.hpp>
 
/* ── Visibility ──────────────────────────────────────────────────── */
 
#if defined(_WIN32) || defined(__CYGWIN__)
  #if defined(PINEFORGE_BUILD_SHARED)
    #define PF_API __declspec(dllexport)
  #else
    #define PF_API __declspec(dllimport)
  #endif
#elif defined(__GNUC__) || defined(__clang__)
  #define PF_API __attribute__((visibility("default")))
#else
  #define PF_API
#endif
 
/** Monotonic strategy-module compatibility version. Bumped for layout growth
 *  or a required module rebuild. Consumers MUST verify
 *  pf_abi_version() == PF_ABI_VERSION before calling run_backtest.
 *  pf_report_t is caller-allocated: growth silently corrupts an undersized buffer.
 *  pf_trade_t is runtime-allocated: growth changes the array stride.
 *  Value 2 introduced metrics and the equity curve. Modules predating this
 *  macro have no pf_abi_version symbol; treat dlsym failure as version 1.
 *  Value 3 appended pf_trade_t::open_at_end (the range-end close
 *  flag); a v2 reader would misindex every row after the first.
 *  Value 4 appended live-runtime accessors and the per-bar broker-state
 *  hash array to pf_report_t.
 *  Value 5 requires a 1.8.0 module rebuild for the native order layouts,
 *  without growing the caller-allocated C report/trade layouts. */
#define PF_ABI_VERSION 5
 
/** Feature probe for the opt-in split chart/request.security feed boundary.
 *  When defined, #strategy_set_aux_security_feed is available. */
#define PINEFORGE_HAS_AUX_SECURITY_FEED_V1 1
 
/** Feature probe for native higher-timeframe request.security feeds.
 *  When defined, #strategy_set_native_security_feed is available. */
#define PINEFORGE_HAS_NATIVE_SECURITY_FEED_V1 1
 
/** Feature probe for immutable native-run account-currency FX curves.
 *  When defined, #strategy_configure_native_fx_curve_v1 is available. */
#define PINEFORGE_HAS_NATIVE_FX_CURVE_V1 1
 
#ifdef __cplusplus
extern "C" {
#endif
 
/** @defgroup pf_types Types
 *  @brief POD types and enums passed across the C ABI.
 *  @{
 */
 
/** Bar-magnifier sub-bar sampling distribution.
 *
 *  Selects how intra-bar synthetic ticks are placed when the bar
 *  magnifier is enabled in #run_backtest_full. Layout-compatible with the
 *  internal C++ `pineforge::MagnifierDistribution` enum class — a
 *  `static_assert` in `c_abi.cpp` guarantees the integer values match. */
typedef enum pf_magnifier_distribution_e {
    PF_MAGNIFIER_UNIFORM       = 0, /**< Uniform spacing across the parent bar. */
    PF_MAGNIFIER_COSINE        = 1, /**< Cosine-tapered density. */
    PF_MAGNIFIER_TRIANGLE      = 2, /**< Triangle-tapered density. */
    PF_MAGNIFIER_ENDPOINTS     = 3, /**< Default — exact O,H,L,C points plus uniform fill between. */
    PF_MAGNIFIER_FRONT_LOADED  = 4, /**< Sample density biased toward bar open. */
    PF_MAGNIFIER_BACK_LOADED   = 5  /**< Sample density biased toward bar close. */
} pf_magnifier_distribution_t;
 
/** Single OHLCV bar pushed into the engine.
 *
 *  Layout-compatible with the internal C++ `pineforge::Bar` struct. */
typedef struct pf_bar_s {
    double  open;       /**< Open price.   */
    double  high;       /**< High price.   */
    double  low;        /**< Low price.    */
    double  close;      /**< Close price.  */
    double  volume;     /**< Bar volume.   */
    int64_t timestamp;  /**< Bar open time, Unix milliseconds. */
} pf_bar_t;
 
/** One provider-neutral realtime executed-trade update.
 *
 *  `sequence` is optional: pass 0 when the normalized source has no stable
 *  ordering key. Non-zero values must increase strictly within a stream.
 *  `quantity` is expressed in the configured symbol's volume units and is
 *  accumulated into the input bar's volume. The source adapter owns all
 *  provider-specific fields and normalization. */
typedef struct pf_trade_tick_s {
    int64_t  timestamp;  /**< Source event time, Unix milliseconds. */
    uint64_t sequence;   /**< Normalized per-stream sequence, or 0. */
    double   price;      /**< Executed trade price (> 0). */
    double   quantity;   /**< Traded quantity in symbol volume units (>= 0). */
} pf_trade_tick_t;
 
/** Closed-trade record returned in pf_report_t::trades.
 *
 *  Layout-compatible with internal `pineforge::TradeC`. */
typedef struct pf_trade_s {
    int64_t entry_time;     /**< Entry fill time (Unix ms). */
    int64_t exit_time;      /**< Exit  fill time (Unix ms). */
    double  entry_price;    /**< Entry fill price (incl. slippage). */
    double  exit_price;     /**< Exit  fill price (incl. slippage). */
    double  pnl;            /**< Net realized PnL in account currency (commission-inclusive). */
    double  pnl_pct;        /**< Net return-on-cost in percent: pnl (NET of commission) /
                             *   entry cost (entry_price * qty * pointvalue) * 100. This is
                             *   TradingView's "Net P&L %" convention (synthetic one-unit
                             *   short: 90.00 net PnL on a 2000.00 entry cost =>
                             *   4.50%). Degenerates to the old gross
                             *   (exit/entry-1)*100 form for longs with zero commission;
                             *   the previous short form (entry/exit-1)*100 was wrong on
                             *   large moves. Sign always matches pnl. */
    int     is_long;        /**< 1 if long, 0 if short. */
    double  max_runup;      /**< Peak favorable whole-trade excursion, account currency, net of entry fees. */
    double  max_drawdown;   /**< Peak adverse whole-trade excursion, account currency, net of entry fees. */
    double  qty;            /**< Filled quantity. */
    double  commission;     /**< Entry+exit commission actually deducted from pnl
                             *   (account currency). pnl is already net of this. */
    int32_t entry_bar_index;/**< Script-bar index of the entry fill (0-based). */
    int32_t exit_bar_index; /**< Script-bar index of the exit fill (0-based). */
    int32_t open_at_end;    /**< 1 when this row is the RANGE-END close of a position
                             *   that was still open after the final bar; 0 for an
                             *   exit the script or a bracket produced. TradingView's
                             *   deep-backtest report does not leave the last position
                             *   open: it reports it as a closed trade whose exit leg is
                             *   the range's last bar at that bar's CLOSE, with an
                             *   empty exit Signal, and counts it in closedTrades
                             *   (synthetic NYSE:F daily example: Entry short @ 25.00,
                             *   Exit @ 26.00 on the final daily bar = the last close,
                             *   closedTrades:1). The engine emulates that row
                             *   (operator decision 2026-09-02): exit_time is the last
                             *   script bar's label, exit_price its mintick-rounded
                             *   close with no slippage, commission per the strategy's
                             *   rules, pnl/pnl_pct/excursions as for any close.
                             *   Appended in ABI v3. */
} pf_trade_t;
 
/** Trade-level statistics block — computed once each for all / long / short.
 *
 *  Loss-side fields (`gross_loss`, `avg_loss`, `largest_loss`) are
 *  **positive magnitudes** (absolute values of the underlying negative PnL). */
typedef struct pf_trade_stats_s {
    int32_t num_trades;                /**< Closed trades in this block (all / long-only / short-only). */
    int32_t num_wins;                  /**< Trades with pnl > 0. */
    int32_t num_losses;                /**< Trades with pnl < 0. */
    int32_t num_even;                  /**< Trades with pnl == 0.0 exactly; breaks both win and loss
                                        *   streaks; excluded from win/loss averages.
                                        *   Invariant: num_trades == num_wins + num_losses + num_even. */
    double  percent_profitable;        /**< 100 * num_wins / num_trades, in PERCENT (0-100).
                                        *   NaN when num_trades == 0. */
    double  net_profit;                /**< Sum of pnl (account currency, net of commission). */
    double  net_profit_pct;            /**< net_profit as a percent of initial capital (0-100 scale).
                                        *   NaN when initial capital <= 0. */
    double  gross_profit;              /**< Sum of winning pnl. */
    double  gross_profit_pct;          /**< gross_profit as a percent of initial capital (0-100 scale).
                                        *   NaN when initial capital <= 0. */
    double  gross_loss;                /**< Sum of |losing pnl| — POSITIVE magnitude (TV display convention). */
    double  gross_loss_pct;            /**< gross_loss as a percent of initial capital (0-100 scale).
                                        *   NaN when initial capital <= 0. */
    double  profit_factor;             /**< gross_profit / gross_loss. NaN when gross_loss == 0. */
    double  avg_trade;                 /**< net_profit / num_trades. NaN when num_trades == 0. */
    double  avg_trade_pct;             /**< Mean of per-trade pnl_pct over all trades.
                                        *   NaN when num_trades == 0. */
    double  avg_win;                   /**< gross_profit / num_wins. NaN when num_wins == 0. */
    double  avg_win_pct;               /**< Mean of per-trade pnl_pct over winning trades.
                                        *   NaN when num_wins == 0. */
    double  avg_loss;                  /**< gross_loss / num_losses (positive magnitude).
                                        *   NaN when num_losses == 0. */
    double  avg_loss_pct;              /**< Mean of the NEGATED pnl_pct of the losing trades. Since
                                        *   pnl_pct is net return-on-cost (sign matches pnl), this is
                                        *   a genuinely POSITIVE magnitude. Basis = pf_trade_t::pnl_pct.
                                        *   NaN when num_losses == 0. */
    double  ratio_avg_win_avg_loss;    /**< avg_win / avg_loss. NaN unless both sides non-empty. */
    double  largest_win;               /**< Single largest pnl among winning trades.
                                        *   NaN when num_wins == 0. */
    double  largest_win_pct;           /**< Maximum pnl_pct over winning trades — an INDEPENDENT
                                        *   maximum, not the pct of the largest-USD win (TV convention,
                                        *   validated 2026-06-12 vs TV export).
                                        *   NaN when num_wins == 0. */
    double  largest_loss;              /**< Single largest |pnl| among losing trades (positive magnitude).
                                        *   NaN when num_losses == 0. */
    double  largest_loss_pct;          /**< Maximum of -pnl_pct over losing trades (positive magnitude) —
                                        *   an INDEPENDENT maximum, not the pct of the largest-USD loss
                                        *   (TV convention, validated 2026-06-12 vs TV export: All
                                        *   "Largest loss %" came from a different trade than the
                                        *   largest USD loss). NaN when num_losses == 0. */
    double  commission_paid;           /**< Sum of pf_trade_t::commission in the block. */
    double  expectancy;                /**< (num_wins/num_trades)*avg_win - (num_losses/num_trades)*avg_loss,
                                        *   account currency per trade. NaN when num_trades == 0. */
    int32_t max_consecutive_wins;      /**< Longest winning run; even trades reset both streaks. */
    int32_t max_consecutive_losses;    /**< Longest losing run; even trades reset both streaks. */
    double  avg_bars_in_trade;         /**< Mean of (exit_bar_index - entry_bar_index + 1) in SCRIPT
                                        *   bars, over all trades — inclusive of the entry bar (TV
                                        *   convention, validated 2026-06-12).
                                        *   NaN when num_trades == 0. */
    double  avg_bars_in_wins;          /**< Mean bar duration of winning trades, inclusive of the entry
                                        *   bar (TV convention, validated 2026-06-12).
                                        *   NaN when num_wins == 0. */
    double  avg_bars_in_losses;        /**< Mean bar duration of losing trades, inclusive of the entry
                                        *   bar (TV convention, validated 2026-06-12).
                                        *   NaN when num_losses == 0. */
} pf_trade_stats_t;
 
/** Equity-curve-derived statistics (all-trades only, like TV). */
typedef struct pf_equity_stats_s {
    double max_equity_drawdown;        /**< Peak-to-trough equity drop, positive currency magnitude. */
    double max_equity_drawdown_pct;    /**< max_equity_drawdown relative to the peak in effect
                                        *   (PERCENT 0-100). */
    double max_equity_runup;           /**< Trough-to-peak rise where the trough resets on each new
                                        *   equity peak (mirrors the engine's intra-run extremes). */
    double max_equity_runup_pct;       /**< max_equity_runup relative to that trough (PERCENT 0-100). */
    double buy_hold_return;            /**< initial_capital * (last_close/first_open - 1), currency.
                                        *   NaN when first chart open is non-finite or <= 0. */
    double buy_hold_return_pct;        /**< buy_hold_return as PERCENT.
                                        *   NaN when first chart open is non-finite or <= 0. */
    /** Month-end-resampled equity simple returns (chart timezone, open-time
     *  bucketing), risk-free 2%/yr (2/12 per month), annualized by sqrt(12).
     *  Uses sample (N-1) stddev. NaN with <2 monthly returns or zero deviation.
     *
     *  Its pre-1.0 spelling `sharpe_tv` named this same double at this same
     *  offset (48) and was removed for 1.0; the serialized report key is still
     *  `sharpe_tv` (report-schema name). */
    double sharpe_monthly;
    /** Same resampling as sharpe_monthly; uses population downside deviation
     *  vs the monthly risk-free. NaN with <2 monthly returns or zero deviation.
     *
     *  Its pre-1.0 spelling `sortino_tv` (offset 56) was removed the same way;
     *  the serialized report key is still `sortino_tv`. */
    double sortino_monthly;
    double sharpe_bar;                 /**< Per-script-bar returns, annualized by observed bar density
                                        *   (bars per year = (len-1)/calendar span), NOT a fixed
                                        *   calendar formula. Uses sample (N-1) stddev.
                                        *   NaN with <2 returns or zero deviation. */
    double sortino_bar;                /**< Same construction as sharpe_bar over per-bar returns;
                                        *   uses population downside deviation.
                                        *   NaN with <2 returns or zero deviation. */
    double cagr;                       /**< PERCENT per year: 100*((final_equity/initial_capital)^(1/years)-1).
                                        *   NaN when span <= 0 or either side <= 0. */
    double calmar;                     /**< cagr / max_equity_drawdown_pct — BOTH IN PERCENT, so the
                                        *   ratio is dimensionless. NaN when drawdown is 0. */
    double recovery_factor;            /**< net_profit / max_equity_drawdown (currency / currency).
                                        *   NaN when drawdown is 0. */
    double time_in_market_pct;         /**< PERCENT (0-100) of script bars with an open position
                                        *   at bar close. */
    double open_pl;                    /**< Mark-to-market open profit at the final bar. */
} pf_equity_stats_t;
 
/** Composite metrics container: trade stats (all / long / short) +
 *  equity-curve stats. */
typedef struct pf_metrics_s {
    pf_trade_stats_t  all, longs, shorts;
    pf_equity_stats_t equity;
} pf_metrics_t;
 
/** Single per-script-bar equity point.
 *
 *  `time_ms` is the script-bar **open** timestamp (Unix ms).
 *  `equity` = `initial_capital` + `net_profit` + `open_profit` at bar close. */
typedef struct pf_equity_point_s {
    int64_t time_ms;       /**< Script-bar OPEN timestamp (Unix ms). */
    double  equity;        /**< initial_capital + net_profit + open_profit. */
    double  open_profit;   /**< Mark-to-market open P&L at bar close. */
} pf_equity_point_t;
 
/** Per-`request.security()` site diagnostic counters.
 *
 *  Layout-compatible with internal `pineforge::SecurityDiagC`. */
typedef struct pf_security_diag_s {
    int     sec_id;          /**< Stable id for the request.security site. */
    int64_t feed_count;      /**< Higher-TF feed bars consumed. */
    int64_t complete_count;  /**< Evaluations on completed parent bars. */
    int64_t partial_count;   /**< Evaluations on still-forming parent bars. */
} pf_security_diag_t;
 
/** Single per-bar trace entry.
 *
 *  Emitted when the source script contains `// @pf-trace name=expr`
 *  pragmas and tracing is enabled via #strategy_set_trace_enabled.
 *  Layout-compatible with internal `pineforge::TraceEntryC`. */
typedef struct pf_trace_entry_s {
    int64_t timestamp;  /**< Bar timestamp (Unix ms). */
    int32_t bar_index;  /**< Zero-based bar index. */
    int32_t name_id;    /**< Index into pf_report_t::trace_names. */
    double  value;      /**< Traced expression value on this bar. */
} pf_trace_entry_t;
 
/** Backtest report filled by #run_backtest / #run_backtest_full.
 *
 *  Layout-compatible with internal `pineforge::ReportC`.
 *
 *  ### Ownership and lifetime
 *  The struct itself is caller-owned (typically stack). The embedded
 *  arrays (`trades`, `security_diag`, `trace`, `trace_names`,
 *  `equity_curve`, `broker_state_hash`) are heap-allocated by the
 *  runtime; the caller frees each filled report exactly once, with #report_free
 *  or, on the kernel archive, #strategy_native_report_free_v1. `trace_names`
 *  strings stay owned by the strategy handle until #strategy_free. */
 
typedef struct pf_report_s {
    /* Trades */
    int             total_trades;       /**< Logical closed-trade count, including
                                         *   the range-end close of a position still open
                                         *   after the final bar. Equals trades_len on the
                                         *   owning-array route; with a sink trades_len is 0.
                                         *   The opt-in report envelope declares capture
                                         *   separately in <pineforge/report_mode.h>. */
    pf_trade_t*     trades;             /**< Heap array of closed trades; script-driven exits
                                         *   first, then the range-end rows (open_at_end=1). */
    int             trades_len;         /**< Resident length of #trades, not the logical total. */
    double          net_profit;         /**< Sum of all closed-trade PnL. */
 
    /* Bar processing counts */
    int64_t         input_bars_processed;   /**< Source-feed bars consumed. */
    int64_t         script_bars_processed;  /**< Script-timeframe bars evaluated. */
 
    /* Security diagnostics */
    int64_t         security_feeds_total;     /**< Total higher-TF feed bars across all security sites. */
    int64_t         security_complete_total;  /**< Total complete-bar evals across all security sites. */
    int64_t         security_partial_total;   /**< Total partial-bar evals across all security sites. */
 
    /* Bar magnifier diagnostics */
    int64_t         magnifier_sub_bars_total;     /**< Sub-bars synthesized by the magnifier. */
    int64_t         magnifier_sample_ticks_total; /**< Sample ticks visited by the magnifier. */
 
    /* Timeframe metadata */
    int             input_tf_seconds;       /**< Detected/configured input timeframe (seconds). */
    int             script_tf_seconds;      /**< Script timeframe (seconds). */
    int             script_tf_ratio;        /**< script_tf_seconds / input_tf_seconds. */
    int             needs_aggregation;      /**< 1 if input → script TF aggregation was performed. */
    int             bar_magnifier_enabled;  /**< 1 if magnifier was active for this run. */
 
    /* Per-security feed/eval counters */
    pf_security_diag_t* security_diag;      /**< One entry per request.security site. */
    int                 security_diag_len;  /**< Length of #security_diag. */
 
    /* Per-bar trace records */
    pf_trace_entry_t*   trace;              /**< Per-bar trace records (empty unless tracing enabled). */
    int                 trace_len;          /**< Length of #trace. */
    const char**        trace_names;        /**< Names indexed by pf_trace_entry_t::name_id. */
    int                 trace_names_len;    /**< Length of #trace_names. */
 
    /* Computed trading metrics. Trade-based blocks reported for all /
     * long-only / short-only; equity-based stats are all-trades only.
     * Loss-side fields are positive magnitudes. Undefined values are NaN
     * (see per-field docs). */
    pf_metrics_t        metrics;
    /* Per-script-bar equity curve (bare host: KernelRecorded); time_ms is the script-bar OPEN
     * timestamp; equity = initial_capital + net_profit + open_profit at
     * bar close. Free via #report_free or #strategy_native_report_free_v1.
     * On a completed KernelRecorded run len == script_bars_processed; a
     * Failed or Aborted run can expose a shorter prefix (check
     * strategy_get_last_error), and metrics describe that prefix. NOTE int64_t
     * length (ctypes: c_int64). With a report sink: NULL / 0 length.
     * The opt-in <pineforge/report_mode.h> envelope exposes logical point
     * count and capture flags separately; this field is resident length. */
    pf_equity_point_t*  equity_curve;
    int64_t             equity_curve_len;
    /* Per-script-bar broker-state hash when recording is on and report
     * points exist (KernelRecorded for a bare native host); freed by
     * #report_free or #strategy_native_report_free_v1. NULL / 0-length when off or no points were recorded.
     * On a completed run, len == script_bars_processed and the last row
     * equals #strategy_broker_state_hash after the run for Pine and bare
     * native hosts alike: each point latches the continuation, and the
     * scalar folds the last latch. A Failed or Aborted run can have a
     * shorter recorded prefix; its last row need not equal the scalar.
     * ABI v4. With a report sink: NULL / 0 length. */
    uint64_t*           broker_state_hash;
    int64_t             broker_state_hash_len;
} pf_report_t;
 
/** @} */ /* end of pf_types */
 
/** Opaque handle to a compiled strategy instance. */
typedef void* pf_strategy_t;
 
/** @defgroup pf_lifecycle Strategy lifecycle
 *  @brief Create, run, and destroy a compiled strategy instance.
 *  @{
 *
 *  NOTE: Per-strategy symbols (strategy_create, run_backtest, etc.) are
 *  emitted by the codegen with internal C++ types (ReportC, Bar) that are
 *  layout-compatible but type-distinct from the public C PODs below.
 *  Guard with PINEFORGE_NO_STRATEGY_DECLS so engine.hpp can include this
 *  header for its POD types without conflicting with per-strategy TU
 *  definitions.
 */
 
/** What #strategy_execution_contract answers for a valid handle. */
typedef enum pf_execution_contract_e {
    PF_EXECUTION_CONTRACT_LEGACY           = 1, /**< The retired legacy execution path. */
    PF_EXECUTION_CONTRACT_NATIVE_MARKET_V1 = 2  /**< The native market kernel; every
                                                 *   handle this runtime creates. */
} pf_execution_contract_t;
 
/** Native execution contract query: a #pf_execution_contract_t, or -1 for a
 *  NULL handle. Absence of this symbol on a known ABI4/stream-v1 library
 *  means legacy. */
PF_API int strategy_execution_contract(pf_strategy_t s);
 
/** The bits of #pf_native_run_spec_v1::optional_mask: each names the one
 *  optional field it makes meaningful. A bit outside this set is refused. */
typedef enum pf_native_spec_optional_e {
    PF_NATIVE_SPEC_OPTIONAL_QUANTITY_GRID           = 1u << 0, /**< `quantity_grid`. */
    PF_NATIVE_SPEC_OPTIONAL_MAX_ABS_UNITS           = 1u << 1, /**< `max_abs_units`. */
    PF_NATIVE_SPEC_OPTIONAL_INITIAL_MARGIN_FRACTION = 1u << 2, /**< `initial_margin_fraction`. */
    PF_NATIVE_SPEC_OPTIONAL_MAX_OPEN_LOTS           = 1u << 3  /**< `max_open_lots`. */
} pf_native_spec_optional_t;
 
/** Versioned native run specification. All string pointers are non-null.
 *  session may be empty (all-day literal). session_key, timeframes, timezone
 *  and tickerid are nonempty. `optional_mask` carries
 *  #pf_native_spec_optional_t bits.
 *
 *  Its three enum-valued words are named in <pineforge/native_c_api.h>:
 *  `fee_kind` is a #pf_native_fee_kind_t, `close_execution` a
 *  #pf_native_close_execution_t and `allowed_open_directions` a
 *  #pf_native_open_directions_t (zero-filled, that word admits no opening at
 *  all). #strategy_configure_native_v1 hands the whole value to the kernel,
 *  which answers an invalid spec with -1 and a Failed native handle
 *  (PF_NATIVE_FAILURE_INVALID_SPECIFICATION). A Ready handle still fails by
 *  the kernel's Contract rule. A Running handle is refused at the C boundary
 *  without changing its native state, including from a callback. A Completed
 *  handle or one Failed by a cooperative abort may be configured for another
 *  run outside callbacks; the kernel judges reuse constraints (an aborted
 *  handle is reused with the same session key and a higher run number), and a
 *  handle whose configure call failed remains Failed. A Completed
 *  host's `on_hash_extension` callback cannot reconfigure it during a read-only hash query.
 *  This call has no typed out-parameters. The
 *  extended path validates before configuring: #strategy_configure_native_ext_v1
 *  keeps the handle Unconfigured on a validation refusal, and
 *  #strategy_configure_native_ext_result_v1 additionally writes the exact
 *  #pf_native_spec_error_t / #pf_native_spec_field_t pair. */
typedef struct pf_native_run_spec_v1 {
    uint32_t struct_size;
    const char *session_key; uint64_t run_number;
    const char *input_tf, *script_tf;
    const char *ticker, *tickerid, *type, *currency, *basecurrency, *description, *volumetype;
    const char *timezone, *session, *chart_timezone;
    double initial_capital, point_value, account_fx, price_tick;
    uint32_t slippage_ticks, fee_kind; double fee_value;
    uint32_t optional_mask, close_execution, allowed_open_directions;
    double quantity_grid, max_abs_units, initial_margin_fraction;
    uint64_t max_open_lots;
} pf_native_run_spec_v1;
 
/** Apply a native v1 specification. Returns 0 on success, -1 on failure.
 *  Legacy handles refuse without native state mutation. */
PF_API int strategy_configure_native_v1(pf_strategy_t s, const pf_native_run_spec_v1* spec);
 
/** Immutable timestamped account-currency FX curve for a native run.
 *  The two arrays have exactly @c n elements and are copied by the runtime. */
typedef struct pf_native_fx_curve_v1 {
    uint32_t struct_size;
    uint32_t n;
    const int64_t* effective_from_ms;
    const double* account_per_quote;
} pf_native_fx_curve_v1;
 
/** Why a native FX curve was refused — the C twin of
 *  `pineforge::NativeFxCurveError`. The typed additive route writes this word
 *  beside the offending array index. */
typedef enum pf_native_fx_curve_error_e {
    PF_NATIVE_FX_CURVE_ERROR_NONE                    = 0,
    PF_NATIVE_FX_CURVE_ERROR_LENGTH_MISMATCH        = 1,
    PF_NATIVE_FX_CURVE_ERROR_NOT_STRICTLY_INCREASING = 2,
    PF_NATIVE_FX_CURVE_ERROR_NOT_FINITE_POSITIVE    = 3,
    PF_NATIVE_FX_CURVE_ERROR_ALLOCATION_FAILURE     = 4,
    PF_NATIVE_FX_CURVE_ERROR_WRONG_PHASE            = 5
} pf_native_fx_curve_error_t;
PF_STATIC_ASSERT(sizeof(pf_native_fx_curve_error_t) == 4);
 
/** Stage an immutable account-currency FX curve on a Ready native handle.
 *
 *  Timestamps must be strictly increasing and rates finite and positive.
 *  Pass @c n == 0 to clear the staged curve; the scalar @c account_fx remains
 *  the pre-first fallback. Curves are applied when the native run begins.
 *  Legacy handles and non-Ready native handles refuse without mutation.
 *
 *  @return 0 only when staging is applied; -1 for invalid input, an invalid
 *  handle, a non-native or non-host native handle, or a non-Ready host. The
 *  typed additive #strategy_configure_native_fx_curve_ext_v1 writes the
 *  #pf_native_fx_curve_error_t and offending index when the kernel judged the
 *  curve. */
PF_API int strategy_configure_native_fx_curve_v1(
    pf_strategy_t s, const pf_native_fx_curve_v1* curve);
 
/** Typed additive spelling of #strategy_configure_native_fx_curve_v1. On a
 *  kernel validation refusal, writes the #pf_native_fx_curve_error_t and the
 *  offending element index (length mismatch uses index 0). C-layer argument,
 *  handle and layout refusals leave the out-parameters untouched. */
PF_API int strategy_configure_native_fx_curve_ext_v1(
    pf_strategy_t s, const pf_native_fx_curve_v1* curve,
    pf_native_fx_curve_error_t* error, uint64_t* index);
 
/* ───────────────────────────────────────────────────────────────────
 * STRATEGY .SO EXPORTS — implemented per compiled strategy
 * ───────────────────────────────────────────────────────────────────
 *
 * Each .so emitted by the codegen exports the following symbols. The
 * runtime library itself does NOT define them — they are per-strategy
 * implementations generated by the transpiler.
 *
 * Note on naming: these are the legacy unprefixed names retained for
 * backward compatibility with the existing harness. Future major
 * versions may introduce `pf_`-prefixed equivalents and deprecate the
 * unprefixed forms.
 */
#ifndef PINEFORGE_NO_STRATEGY_DECLS
 
/** Allocate a new strategy instance.
 *
 *  @param params_json  Currently ignored; pass `NULL`.
 *  @return Strategy handle, or `NULL` on allocation failure.
 *
 *  Caller owns the returned handle and must release it via #strategy_free. */
PF_API pf_strategy_t strategy_create(const char* params_json);
 
/** Release a strategy handle previously returned by #strategy_create.
 *
 *  Safe to call with `NULL`. Invalidates any `pf_report_t::trace_names`
 *  pointers obtained from this strategy. */
PF_API void strategy_free(pf_strategy_t s);
 
/** Run a backtest with auto-detected timeframe and no bar magnifier.
 *
 *  @param s     Strategy handle from #strategy_create.
 *  @param bars  Non-NULL pointer to OHLCV bars (length @p n).
 *  @param n     Bar count (>= 0).
 *  @param out   Non-NULL output report. Fields are populated with heap
 *               allocations the caller must release via #report_free. */
PF_API void run_backtest(pf_strategy_t s,
                         pf_bar_t* bars,
                         int n,
                         pf_report_t* out);
 
/** Run a backtest with explicit timeframe and magnifier configuration.
 *
 *  @param s                  Strategy handle.
 *  @param bars               Bar feed.
 *  @param n                  Bar count.
 *  @param input_tf           Input timeframe ("1", "5", "15", "60", "1D", ...).
 *                            Empty string → auto-detect from bar timestamps.
 *  @param script_tf          Script timeframe. Empty string → defaults to @p input_tf.
 *  @param bar_magnifier      Boolean (0 / non-zero) — enable bar magnifier.
 *  @param magnifier_samples  Sub-bar samples per parent bar (typical: 4).
 *  @param magnifier_dist     Sampling distribution (see #pf_magnifier_distribution_t).
 *  @param out                Output report. Free with #report_free. */
PF_API void run_backtest_full(pf_strategy_t s,
                              pf_bar_t* bars,
                              int n,
                              const char* input_tf,
                              const char* script_tf,
                              int bar_magnifier,
                              int magnifier_samples,
                              pf_magnifier_distribution_t magnifier_dist,
                              pf_report_t* out);
 
/** Free heap arrays attached to a filled report.
 *
 *  Idempotent. Safe to call with `NULL` or an already-freed report.
 *  The `pf_report_t` struct itself is caller-owned. */
PF_API void report_free(pf_report_t* report);
 
/** @} */ /* end of pf_lifecycle */
 
/** @defgroup pf_config Per-strategy configuration
 *  @brief Override @c input.*() values, `strategy(...)` params, and runtime knobs.
 *  @{
 */
 
/** Override a Pine @c input.*() value before the next run.
 *
 *  @param s      Strategy handle.
 *  @param key    The input's title (or fallback identifier).
 *  @param value  Serialized value — numbers as decimal strings,
 *                booleans as `"true"` / `"false"`.
 *
 *  Calls after #run_backtest are accepted but only take effect on
 *  subsequent runs. */
PF_API void strategy_set_input(pf_strategy_t s,
                               const char* key,
                               const char* value);
 
/** Override a `strategy(...)` declaration parameter.
 *
 *  Recognised @p key values: `initial_capital`, `commission_value`,
 *  `default_qty_value`, `pyramiding`, `slippage`,
 *  `process_orders_on_close`, `close_entries_rule`, `default_qty_type`,
 *  `commission_type`. */
PF_API void strategy_set_override(pf_strategy_t s,
                                  const char* key,
                                  const char* value);
 
/** Toggle volume-weighted bar-magnifier sampling.
 *
 *  Has no effect unless the bar magnifier is enabled in
 *  #run_backtest_full. */
PF_API void strategy_set_magnifier_volume_weighted(pf_strategy_t s,
                                                   int on);
 
/** Report the script's `strategy(..., use_bar_magnifier = true)` declaration.
 *
 *  Exported only by a strategy whose declaration is that literal; every
 *  other `.so` lacks the symbol. TradingView backtests such a script on its
 *  bar magnifier, so a host runs it on a finer input with the magnifier on
 *  (#run_backtest_full).
 *
 *  @return 1. */
PF_API int strategy_declares_bar_magnifier(void);
 
#endif /* PINEFORGE_NO_STRATEGY_DECLS */
 
/* ───────────────────────────────────────────────────────────────────
 * RUNTIME LIBRARY EXPORTS — implemented in libpineforge
 * ─────────────────────────────────────────────────────────────────── */
/** Toggle per-bar trace recording. Default off (zero-cost when off).
 *
 *  Enables capture for `// @pf-trace name=expr` pragmas already compiled
 *  into the strategy `.so`. Trace records appear in pf_report_t::trace. */
PF_API void strategy_set_trace_enabled(pf_strategy_t s, int on);
 
/** Set the earliest Unix-ms timestamp at which strategy order commands
 *  may fire.
 *
 *  Earlier bars still execute user code and warm TA/series state, but
 *  `strategy.entry/order/exit/close` commands are ignored. */
PF_API void strategy_set_trade_start_time(pf_strategy_t s, int64_t timestamp_ms);
 
/** @} */ /* end of pf_config */
 
/** @addtogroup pf_lifecycle
 *  @{
 */
 
/** Read process-wide scratch-arena diagnostics, outside canonical report bytes.
 *  Writes the peak bytes of simultaneously claimed chunks since attachment
 *  and the exact supplied backing size (including any unallocatable tail).
 *  Returns 0; with no arena attached both values are 0. Returns -1 with both
 *  outputs unchanged if either pointer is NULL, the pointers alias, or the
 *  snapshot cannot be read. Never throws or changes a strategy's last error.
 *  Query after report finalization and before arena detach. The counters
 *  belong to the attachment, not a strategy or repeat; detach resets them.
 *  No pf_report_t, sink receipt, trailer or broker-state hash layout changes. */
PF_API int pf_report_scratch_arena_stats(uint64_t* high_water_bytes,
                                       uint64_t* arena_bytes);
 
/** Read the handle's admitted-run command-cache and trade-ledger diagnostics.
 *  resident_bytes is the current sum of live command-cache control/slabs and
 *  the ledger's fixed workspace, allocated directory and decoded-entry pages.
 *  Each allocation owner contributes once; borrowed shared-cache storage does
 *  not add another charge. Arena chunks and backing-file extents are separate.
 *  allocation_bypass_count counts optional command-slab and ledger-directory/
 *  page allocation failures, once per sticky bypass, including released owners.
 *  Both outputs are 0 before the first admitted run; admission resets them.
 *  Returns 0, or -1 with both outputs unchanged for a NULL handle/output or
 *  aliased outputs. Never allocates, throws or changes last_error.
 *  Query on the invoking thread after report finalization and before freeing
 *  the strategy. No existing report, receipt or diagnostics layout changes. */
PF_API int pf_report_cache_stats(pf_strategy_t s, uint64_t* resident_bytes,
                                 uint64_t* allocation_bypass_count);
 
/** Admit a jailed handle only with an attached scratch arena.
 *  Attach the inherited environment arena, if configured (fixed fd 5:
 *  PF_SCRATCH_ARENA_FD=5, positive PF_SCRATCH_ARENA_BYTES);
 *  validate its backing and mapping configuration before execution.
 *  On Linux, require a sealed memfd whose seal mask contains
 *  F_SEAL_GROW | F_SEAL_SHRINK | F_SEAL_SEAL. F_SEAL_EXEC and other non-write
 *  seals may be added (e.g. MFD_NOEXEC_SEAL). F_SEAL_WRITE or
 *  F_SEAL_FUTURE_WRITE is refused at attachment with
 *  report_sink_failed/arena_backing. These requirements hold regardless of
 *  PF_SCRATCH_ARENA_JAILED; off Linux, admit any attached arena.
 *  Returns 0 accepted; -1 for a NULL handle or an unavailable/invalid arena.
 *  Arena failures set the handle's typed report_sink_failed/arena_backing
 *  failure. Never creates a backing file or falls back to TMPDIR.
 *  Existing unjailed callers do not need to call this opt-in admission.
 *  The first successful attach sets SIGXFSZ to SIG_IGN process-wide; the prior disposition is not restored.
 *  Same fd/size reattaches are no-ops. Hosts relying on their SIGXFSZ handler
 *  or default termination must account for this before attaching an arena. */
PF_API int strategy_require_report_scratch_arena_v1(pf_strategy_t s);
 
struct pf_report_sink_diagnostics_v1;
/** Read bounded sink provenance without reading the sink or replaying rows.
 *  Include report_sink.h for the descriptor; initialize struct_size and
 *  version=1. Returns 0 filled; -1 with *out unchanged for a bad handle,
 *  size, version or NULL output. Completion follows the sink trailer.
 *  Queries never execute callbacks, advance a cursor or change last_error. */
PF_API int strategy_report_sink_diagnostics_v1(
    pf_strategy_t s, struct pf_report_sink_diagnostics_v1* out);
 
/** Install the invocation's cooperative SIGTERM handler. The handler only
 *  stores a volatile sig_atomic_t flag; batch runs observe it at completed
 *  input-bar boundaries, independently of #strategy_request_abort.
 *  Opt-in, process-wide, for one serialized child invocation. Call on the
 *  invoking thread with SIGTERM blocked, then unblock it; pending SIGTERM is
 *  preserved. Returns 0, or -1 on signal-setup failure. Repeated installation
 *  preserves an already requested stop. This opt-in installs only the abort
 *  handler for SIGTERM; it does not change any ABI layout. */
PF_API int pf_run_abort_install_sigterm_v1(void);
 
/** Read the invocation stop flag: 0 or 1. No allocation or state mutation. */
PF_API int pf_run_abort_requested_v1(void);
 
/** Restore the disposition saved by #pf_run_abort_install_sigterm_v1.
 *  Call with SIGTERM blocked, after native cleanup and failure publication.
 *  Returns 0 (also when uninstalled), or -1 on signal-setup failure. */
PF_API int pf_run_abort_restore_sigterm_v1(void);
 
/** Return the physical entry incarnation for one closed-trade row.
 *
 *  Partial-close/FIFO fragments emitted from the same physical entry share
 *  this value. Distinct broker entry objects receive distinct monotonically
 *  increasing values even when Pine reuses the same user-visible entry ID.
 *  The value is scoped to one strategy run and is intended as report
 *  provenance, not as a stable cross-run identifier.
 *
 *  @param s            Strategy handle whose most recent run filled a report.
 *  @param trade_index  Zero-based row index into that report's `trades`
 *                      array — the script's closed trades followed by the
 *                      range-end rows (`open_at_end`, ABI v3), which carry
 *                      the incarnation of the lot they mark like any other
 *                      close.
 *  @return Non-zero physical-entry identity, or 0 for an invalid index or a
 *          legacy/synthetic trade without request record provenance. */
PF_API uint64_t strategy_closed_trade_entry_incarnation(
    pf_strategy_t s, int trade_index);
 
/** @} */ /* end of pf_lifecycle */
 
/** @defgroup pf_streaming Historical to realtime streaming
 *  @brief Warm on confirmed OHLCV and continue the same strategy instance on
 *         normalized ordered trades from any data source.
 *  @{
 */
 
/** Warm a strategy with confirmed OHLCV, then switch the same instance to a
 *  realtime trade stream without resetting position, equity, pending orders,
 *  Pine variables, TA state, request.security state, or timeframe aggregation.
 *
 *  The warmup must contain at least one complete fixed-duration input bar.
 *  Normalized ticks start at or after the next input bar's open. This
 *  lifecycle uses close-only strategy calculation (the Pine strategy default)
 *  while resting broker orders are evaluated on every normalized trade.
 *
 *  A generated Pine strategy using this entry point rejects calc_on_order_fills,
 *  historical probe/tail overrides, timestamped FX and auxiliary/native
 *  security feeds. A C native host can also use this entry point and accepts
 *  the native FX curve, auxiliary feeds and calculation trigger where its
 *  run specification permits them.
 *  @return 0 on success, -1 on failure. Inspect #strategy_get_last_error. */
PF_API int strategy_stream_begin(pf_strategy_t s,
                                 const pf_bar_t* warmup_bars,
                                 int n_warmup,
                                 const char* input_tf,
                                 const char* script_tf);
 
/** Native live extension version (1). Additive to ABI v4; callers must probe
 *  this symbol before using the confirmed-bar/action API in older modules. */
PF_API int strategy_stream_api_version(void);
 
/** One physical emulator lot action. is_long describes the position side:
 *  buy = is_entry == is_long. A reversal is exits followed by an entry.
 *  price/time are emulator reference values, not external broker fills.
 *  Strings are borrowed until the next stream mutation or queue clear. */
typedef struct pf_stream_order_action {
    uint64_t sequence;
    int64_t timestamp_ms;
    int32_t bar_index;
    int32_t is_entry;
    int32_t is_long;
    double quantity;
    double price;
    const char* order_id;
    const char* comment;
    uint64_t entry_incarnation;
} pf_stream_order_action_t;
 
/** Consume one confirmed input-timeframe bar. Its script-timeframe aggregate
 *  uses the existing batch OHLC fill kernel when complete. Close-only strategy
 *  calculation; no bar magnifier or synthetic trade ticks. The first tick/bar
 *  locks the feed mode. Off-grid/out-of-order data, invalid OHLCV and missing
 *  in-session bars fail. Calendar-closed intervals may be skipped. No padding.
 *  Returns 0/-1. On ANY input-processing failure discard/recover the instance:
 *  the operation is not transactional and can have advanced native state. */
PF_API int strategy_stream_push_bar(pf_strategy_t s, const pf_bar_t* bar);
 
/** Queued physical fills since the last clear, in execution order. Historical
 *  warmup and report-only range-end rows never enqueue. Sequence starts at 1
 *  after warmup and is not reset by clear. Returns -1 on a null handle. */
PF_API int strategy_stream_order_actions_len(pf_strategy_t s);
/** Copy one action; return 0 on success, -1 on invalid handle/index/output. */
PF_API int strategy_stream_order_action_get(pf_strategy_t s, int index,
                                            pf_stream_order_action_t* out);
/** Clear observed events after the caller durably journals them. */
PF_API void strategy_stream_order_actions_clear(pf_strategy_t s);
/** Versioned deterministic fingerprint of observable broker/stream state.
 *  Excludes the consumable queue and arbitrary private strategy members.
 *  This is a replay check, not a complete state snapshot or cryptographic hash.
 *  Fresh replay must use deterministic strategy code, the same pinned engine
 *  build and configuration. The fingerprint's recipe belongs to the script
 *  ABI epoch: from 1.0.0 it is fixed for every 1.x engine
 *  (engine_script_run_v19 to 1.10, then v20), and a new recipe is a new epoch; a value from a
 *  build before 1.0.0 is not comparable. Returns 0 for NULL.
 *
 *  A refused read also returns 0, so a 0 alone does not tell it from an
 *  answer: a handle that carries selected-window provenance refuses this
 *  query once its run has sealed, and #strategy_state_query_status_v1 names
 *  that refusal. The recorded broker-state rows
 *  (#strategy_set_broker_state_hash_recording) are not values of this token:
 *  it has no recorded counterpart, so a refused read leaves no witness. */
PF_API uint64_t strategy_stream_state_hash(pf_strategy_t s);
 
/** Push one normalized realtime trade. Returns 0 on success, -1 on failure. */
PF_API int strategy_stream_push_tick(pf_strategy_t s,
                                     const pf_trade_tick_t* tick);
 
/** Push an ordered batch of realtime trades. Semantically identical to
 *  repeated #strategy_stream_push_tick calls, with lower FFI overhead. */
PF_API int strategy_stream_push_ticks(pf_strategy_t s,
                                      const pf_trade_tick_t* ticks,
                                      int n);
 
/** Advance the stream clock and close every input bar whose end is <= the
 *  supplied time. Quiet in-session intervals become zero-volume carry-forward
 *  bars; intervals outside the configured syminfo session are skipped. */
PF_API int strategy_stream_advance_time(pf_strategy_t s, int64_t timestamp_ms);
 
/** End a realtime stream. When @p finalize_partial_input_bar is non-zero, the
 *  currently forming input bar is dispatched before ending; normally callers
 *  should first advance to a confirmed boundary and pass zero here. */
PF_API int strategy_stream_end(pf_strategy_t s, int finalize_partial_input_bar);
 
/** Snapshot the cumulative warmup + realtime report. The embedded arrays are
 *  caller-owned after return and must be released with #report_free, or with
 *  #strategy_native_report_free_v1 by a host that links the kernel archive,
 *  which has no #report_free. */
PF_API int strategy_stream_fill_report(pf_strategy_t s, pf_report_t* out);
 
/** @} */ /* end of pf_streaming */
 
/** @defgroup pf_live Live-runtime surface (ABI v4)
 *  Default-off flags and read-only accessors used by pineforge-live. None of
 *  them changes a historical run unless enabled. @{ */
 
#define PINEFORGE_HAS_SCRATCH_TABLES_V1 1
 
#define PINEFORGE_HAS_CACHE_POLICY_V1 1
 
/** Append-only cache-kind vocabulary. Zero is reserved and is rejected as
 *  an unknown kind. Values are contiguous, starting at one; new kinds take
 *  the next unused value and existing values are never renumbered.
 *  A kind whose cache a later release deletes remains accepted as a
 *  documented retired no-op, never an unknown-kind error. */
typedef uint32_t pf_cache_kind_t;
#define PF_CACHE_KIND_LEDGER_CACHE             1u
#define PF_CACHE_KIND_TRADE_PAGES              2u
#define PF_CACHE_KIND_DEPENDENCY_PAGES         3u
#define PF_CACHE_KIND_EXIT_PAGES               4u
#define PF_CACHE_KIND_BOOK_PAGES               5u
#define PF_CACHE_KIND_RETAINED_SEQUENCE_PAGES  6u
#define PF_CACHE_KIND_COHORT_ID_PAGES          7u
#define PF_CACHE_KIND_EXIT_RANK_PAGES          8u
#define PF_CACHE_KIND_ERASED_MINIMA_PAGES      9u
#define PF_CACHE_KIND_CONSUMED_CYCLE_PAGES    10u
#define PF_CACHE_KIND_POSITION_TAIL_PAGES     11u
#define PF_CACHE_KIND_SUCCESSOR_ROOT_PAGES    12u
#define PF_CACHE_KIND_RECEIPT_TAIL_PAGES       13u
#define PF_CACHE_KIND_CHAIN_SEGMENT_PAGES     14u
#define PF_CACHE_KIND_EQUITY_CURVE_PAGES       15u
#define PF_CACHE_KIND_TA_HISTORY_PAGES         16u
#define PF_CACHE_KIND_FEED_CALENDAR_PAGES      17u
#define PF_CACHE_KIND_RECORDED_SERIES_PAGES    18u
#define PF_CACHE_KIND_PROJECTION_EXIT_PAGES   19u
 
/** One optional resident cache size. Ordinary C alignment applies: kind is
 *  uint32_t and capacity_bytes is uint64_t, with no packed wire layout.
 *  Every capacity is in bytes. For PF_CACHE_KIND_LEDGER_CACHE, the engine
 *  selects the largest row count R with
 *  R * TradeLedger::kLedgerEntryBytes + ceil(R / 256) * sizeof(void*) <= capacity_bytes
 *  (312 bytes per decoded entry and 8 bytes per page pointer on LP64).
 *  Omitting this entry selects the provisional default of 67,108,864 bytes
 *  (64 MiB), which holds 215,070 entries on LP64 and never grows with the
 *  retained history; a failed optional allocation retries only after the
 *  retained population has doubled since the failed attempt, and the first
 *  failure remains observable until clear. Retirement and a rewind release
 *  every optional page. Every present ledger entry selects an explicit finite
 *  row policy, including an allowance equal to the default or to 65,536 rows
 *  (20,449,280 bytes on LP64).
 *  Zero selects the existing zero-row
 *  bypass minimum. A nonzero capacity converting to fewer than one row fails
 *  with setting_rejected, input="cache_policy", reason="value_below_minimum";
 *  above the existing 1,048,576-row ceiling it fails with the same input and
 *  reason="value_above_maximum". No clamping or sub-row bypass occurs.
 *  The ledger keeps private pages; its allowance includes their page directory.
 *  Allocated pointers and pages are reported once in cache resident bytes.
 *  A finite policy's optional directory/page allocation failure permanently
 *  bypasses further allocation for that ledger, preserving backing reads and
 *  writes. The omitted default keeps its old hits on a failed allocation and
 *  retries as described above; its first allocation failure remains
 *  observable until clear. Required backing I/O failures still propagate.
 *  Other kinds include optional line metadata in their byte allowances and
 *  bypass when below one line. Reads still use backing at zero capacity.
 *  reserved must be zero; a nonzero word is a typed setting_rejected error. */
typedef struct pf_cache_policy_entry_v1 {
    uint32_t kind;
    uint32_t reserved;
    uint64_t capacity_bytes;
} pf_cache_policy_entry_v1;
 
/** Versioned resident cache policy. Set struct_size = sizeof(pf_cache_policy_v1)
 *  and version = 1; both reserved words and every entry's reserved word must
 *  be zero. Nonzero reserved words fail with setting_rejected,
 *  input="cache_policy", reason="unparseable_value".
 *  The caller owns this descriptor and its entries; the setter copies their
 *  values before returning and retains neither pointer.
 *  entry_count is a uint64_t count; entries may be NULL only when it is zero.
 *  Each successful replacement starts from internal defaults, then applies
 *  the entries. Omitted kinds use defaults (the 64 MiB ledger default); duplicate
 *  and unknown kinds fail. NULL/empty descriptors restore the ledger default.
 *  No entry limits logical records, retained history or backing extent. */
typedef struct pf_cache_policy_v1 {
    uint32_t struct_size;
    uint32_t version;
    uint64_t entry_count;
    const pf_cache_policy_entry_v1* entries;
    uint32_t reserved[2];
} pf_cache_policy_v1;
 
/** Copy cache settings before run admission; NULL restores internal defaults.
 *  A run freezes its settings before its first store begin/append. Calls in
 *  begin callbacks, during execution or during an active stream fail without
 *  changing either configuration or the admitted run. An idle call between
 *  runs affects the next run, including stream warmup, and never resizes the
 *  preceding run's retained stores or borrowed views.
 *  Returns 0 on success and -1 on invalid descriptor, nonzero reserved word,
 *  duplicate/unknown kind, ledger capacity outside its setting range,
 *  unrepresentable size or busy/frozen handle. A valid handle records the
 *  typed setting_rejected configuration error through
 *  #strategy_get_last_error_code and #strategy_get_last_error_args.
 *  Optional cache allocation failure bypasses caching; it is not admission
 *  failure. This policy does not change scratch-table maxima or arena shares. */
PF_API int strategy_set_cache_policy_v1(pf_strategy_t s,
                                        const pf_cache_policy_v1* policy);
 
/** Disk scratch write batching, independent of resident cache policy.
 *  Set struct_size = sizeof(pf_scratch_io_policy_v1), version = 1 and both
 *  reserved words to zero. write_batch_bytes is successful write traffic in
 *  bytes: default 65536; every uint64_t value is valid. Positive values retain
 *  the before-next-batch sync/discard order. Zero syncs/discards each positive
 *  transfer before write/write_some returns success, including short writes.
 *  This is not a logical history limit or a physical-memory guarantee.
 *  The fixed clean-read and userspace sequence windows remain unchanged. */
typedef struct pf_scratch_io_policy_v1 {
    uint32_t struct_size;
    uint32_t version;
    uint64_t write_batch_bytes;
    uint64_t reserved[2];
} pf_scratch_io_policy_v1;
 
/** Copy settings before admission; NULL restores the 65536-byte default.
 *  The descriptor is copied and no pointer is retained. Active begin,
 *  callback, execution and stream calls reject atomically. Idle replacement
 *  affects the next run and does not retune retained stores.
 *  Returns 0 on success, -1 for a null handle, invalid descriptor or frozen
 *  settings. Valid handles report setting_rejected, input="scratch_io_policy":
 *  size/reserved errors use reason="unparseable_value", unsupported version
 *  uses "invalid_enum_option", and active handles use "frozen".
 *  A loader must resolve this symbol and fail if it is missing/incompatible,
 *  including when requesting a NULL reset. */
PF_API int strategy_set_scratch_io_policy_v1(pf_strategy_t s,
                                             const pf_scratch_io_policy_v1* policy);
 
/** Storage policy for the nine historical scratch-table regions. */
typedef enum pf_scratch_table_backend_e {
    PF_SCRATCH_TABLE_DISK_SCRATCH = 0,
    PF_SCRATCH_TABLE_BOUNDED_MEMORY = 1
} pf_scratch_table_backend_t;
 
/** Version 1 scratch-table admission maxima, in keys/rows and key bytes.
 *  Set struct_size = sizeof(pf_scratch_tables_v1), version = 1, reserved = 0.
 *  K_q/B_q are reserved zero; q's two region descriptors remain empty.
 *  Each other K/B pair includes all distinct ever-stored keys, including erased
 *  keys. U/B_U cover all cohort IDs, V/B_V all exit-rank IDs (V <= 27), and R
 *  all rooted successors, including internally generated replacements.
 *  Counts and UTF-8/binary key-byte totals are admitted maxima supplied by
 *  the host, not estimates inferred from the number of bars.
 *  Bounded mode reserves one fixed slab before run preparation; exceeding
 *  the manifest fails the run with scratch_capacity_exceeded. The layout
 *  and every offset must fit uint64_t, size_t and off_t. Allocation failure
 *  remains out_of_memory. This policy is independent of the report sink.
 *  In bounded mode, all eleven maxima zero select the P0 policy at each
 *  begin: finite batches use that run's input-bar count, and streams without
 *  a declared lifetime use the fixed stream tier (warmup is not lifetime).
 *  Any nonzero maximum makes the entire manifest explicit, zeros included.
 *  The default is an admission policy, not a measured workload bound. */
typedef struct pf_scratch_tables_v1 {
    uint32_t struct_size;
    uint32_t version;
    uint32_t backend;
    uint32_t reserved;
    uint64_t K_q;
    uint64_t B_q;
    uint64_t K_e;
    uint64_t B_e;
    uint64_t K_c;
    uint64_t B_c;
    uint64_t U;
    uint64_t B_U;
    uint64_t V;
    uint64_t B_V;
    uint64_t R;
} pf_scratch_tables_v1;
 
/** Copy scratch-table configuration while idle; NULL restores disk defaults.
 *  Never retains a pointer into the caller's descriptor. Returns 0 on
 *  success, -1 for a null handle or invalid size/version/backend/reserved/V,
 *  -2 during a stream, and -3 during a batch run (including begin callbacks).
 *  A refusal preserves the installed configuration and active run ownership.
 *  Finite streams must supply maxima for their complete admitted lifetime.
 *  The embedding host sets RLIMIT_FSIZE and owns disk-scratch SIGXFSZ policy.
 *  This setter does not attach an arena; see #strategy_require_report_scratch_arena_v1 for the SIGXFSZ side effect of arena attachment. */
PF_API int strategy_set_scratch_tables_v1(pf_strategy_t s,
                                         const pf_scratch_tables_v1* config);
 
/** Request cooperative abort of the run in progress (see c_abi.cpp). */
PF_API void strategy_request_abort(pf_strategy_t s);
/** 0 = completed, 1 = NOT_COMPLETED (aborted), -1 = @p s is NULL. */
PF_API int  strategy_last_run_status(pf_strategy_t s);
/** Live-runtime tail semantics (spec §3.1): the LAST bar of the array fed to
 *  every subsequent run() is a still-forming bar, not the chart's rightmost
 *  historical bar. This is persistent configuration, not a one-shot flag --
 *  it stays in effect until a caller passes @p on == 0, so a handle reused
 *  for a later plain historical replay must be explicitly turned back off.
 *  Effects when @p on is non-zero:
 *    1. `barstate.islast` is false for that bar.
 *    2. `session.islastbar` is computed from the bucket calendar (no next
 *       bar to peek at, so it evaluates whether the next bucket -- this
 *       bar's timestamp plus one script-TF step -- falls out of session).
 *    3. `bar_index` stays put; `last_bar_index` is frozen at the horizon
 *       bar (`horizon_bars - 1`), when @p horizon_bars > 0. `last_bar_time`
 *       is exact when the horizon bar is in the script-bar array, one
 *       script-TF step per missing bar past the array's last bar
 *       otherwise; under aggregation (input_tf < script_tf) it is
 *       extrapolated from the first bar instead, and the aggregation-path
 *       caveat below applies.
 *    4. The range-end synthetic close row/trade is skipped (no
 *       `open_at_end` row); the final equity point keeps `open_profit`.
 *    5. Interior bars (every bar before the last) are unaffected, except
 *       effect 2 under aggregation (below).
 *  Scope: the Pine source host's scheduler applies these where it publishes
 *  a script bar to the generated script. Effects 1, 3 and 4 hold on every
 *  path. Effect 2 is its session-predicate step, which runs for every script
 *  bar of a run whose timeframe is known -- a timeframe-aware overload, or
 *  `run(bars, n)` with at least two bars, whose timeframe it detects from
 *  them; with fewer, `session.ismarket`/`session.islastbar` keep their
 *  reset-state `false` whatever this flag says. The bucket-calendar
 *  lookahead stands in for the next bar wherever the scheduler holds none:
 *  with input_tf == script_tf that is the array's last bar alone, but under
 *  aggregation (input_tf < script_tf) the scheduler holds no next script
 *  bar at all, so the lookahead decides `session.islastbar` on every bar of
 *  the run. Callers must feed an input_tf == script_tf array, matching
 *  #strategy_set_probe_suppress_tail_logic's scope note.
 *  `strategy_stream_begin` refuses a handle with this flag set.
 *  Default off (@p on == 0): every historical run stays byte-identical to
 *  before this flag existed. The mode belongs to the Pine source host; on
 *  a host that models no still-forming tail bar (a bare kernel host) the
 *  call is accepted and inert, as it always was there. */
PF_API void strategy_set_realtime_tail(pf_strategy_t s, int on, int horizon_bars);
/** Live probe tail suppression (spec §3.2): the LAST script bar of the array
 *  fed to every subsequent run() is matched but not calculated. The kernel
 *  matches that bar like any other, so resting stop/limit orders settle
 *  against it; the Pine source host's scheduler then publishes it through
 *  its suppressed-tail step instead of the generated script -- source
 *  history and `bar_index` advance, the fills already matched on the bar
 *  are settled, the report point is marked, `on_bar` is not invoked and no
 *  range-end row is written. The host's own bar-close policy is not the
 *  script and still runs on that bar -- its risk-state update and its
 *  TradingView margin-call checkpoint -- so a margin call due against the
 *  forming bar is booked against it.
 *  Apart from what that policy books, the run's last-bar fills are exactly
 *  the settled book's fills against the forming bar, and the post-run
 *  pending-order book is the book in force during that bar. This is
 *  persistent configuration, like #strategy_set_realtime_tail, and
 *  independent of it -- do not assume the two flags are coupled; set each
 *  explicitly.
 *  Scope (ABI v4 / live v1): honoured on every batch path -- the
 *  single-timeframe and the timeframe-aware overloads, with or without the
 *  bar magnifier. Under aggregation (input_tf < script_tf) the suppressed
 *  bar is the run's last COMPLETED script bar, and a trailing partial
 *  bucket is never calculated at all. Under `calc_on_order_fills` only the
 *  bar's close calculation is suppressed: a fill on the forming bar still
 *  triggers the fill recalculation, which runs the script on it.
 *  `calc_on_order_fills` and the bar magnifier stay gated in live v1 and a
 *  probe must not enable them; callers must feed an input_tf == script_tf
 *  array.
 *  `strategy_stream_begin` refuses a handle with this flag set: clear it
 *  (on = 0) first.
 *  Default off (@p on == 0): every historical run stays byte-identical to
 *  before this flag existed. Like #strategy_set_realtime_tail the mode
 *  belongs to the Pine source host; on a host that models no still-forming
 *  tail bar the call is accepted and inert, as it always was there. */
PF_API void strategy_set_probe_suppress_tail_logic(pf_strategy_t s, int on);
/** Force this run's intrabar path order (ABI v4 live-runtime surface): the
 *  leg order every modeled OHLC path the engine walks uses -- stop/limit
 *  fill priority, exit trail walking, dual-entry-stop arbitration,
 *  bar-magnifier sub-bar sampling, and the excursion columns a source host
 *  reports on a closed row. Values:
 *    - `0` AUTO (default): the unchanged TV-emulator rule -- the leg nearer
 *      `open` (by `|high-open|` vs `|open-low|`) goes first.
 *    - `1` HIGH_FIRST: force `O -> H -> L -> C` regardless of the bar's own
 *      shape.
 *    - `2` LOW_FIRST: force `O -> L -> H -> C` regardless of the bar's own
 *      shape.
 *  The values are #pf_native_path_order_t's (<pineforge/native_c_api.h>):
 *  #PF_NATIVE_PATH_ORDER_AUTO, #PF_NATIVE_PATH_ORDER_HIGH_FIRST and
 *  #PF_NATIVE_PATH_ORDER_LOW_FIRST. Any other @p mode is clamped to AUTO:
 *  this setter answers nothing, so it cannot refuse one.
 *  A live probe runs the SAME forming bar under BOTH forced orders and emits
 *  only the fills that agree between the two -- a fill that depends on which
 *  leg TradingView's own (unobservable, still-forming) bar will resolve to
 *  is path-dependent and must be suppressed rather than guessed.
 *  This is persistent configuration, like #strategy_set_realtime_tail -- it
 *  stays in effect until a caller passes @p mode == 0, so a handle reused
 *  for a later plain historical replay must be explicitly set back to AUTO.
 *  Scope: the mode is carried by the RUN, in `NativeRunSpec::path_order`. A
 *  native-bound source host projects this setting into that field at begin
 *  -- at run() and at #strategy_stream_begin alike -- and a bare native host
 *  declares the field itself; every modeled path the native driver walks
 *  then resolves its leg order from that field. So the setting takes effect
 *  at the next begin rather than mid-run, and a stream is NOT exempt: a
 *  confirmed bar pushed with #strategy_stream_push_bar is sealed on the same
 *  forced waypoint sequence a run() walks (measured on a 99/101 bracket and
 *  an AUTO-low-first touch bar: both routes exit at 99.00 under AUTO and at
 *  101.00 under HIGH_FIRST). What a forced order cannot reach is an OBSERVED
 *  TICK (#strategy_stream_push_tick): one price is not a modeled path and
 *  has no legs to order, so the same tape fills identically under all three
 *  modes; the forming bar those ticks build is ordered only when it seals,
 *  on the waypoint sequence above.
 *  Default AUTO (@p mode == 0): every historical run stays byte-identical to
 *  before this flag existed. */
PF_API void strategy_set_path_order(pf_strategy_t s, int mode);
/** The dual-entry-stop arbitration decided on the LAST bar the most recent
 *  run() dispatched: a flat position resting exactly one long stop-only
 *  ENTRY and one short stop-only ENTRY, both touched on that bar.
 *  Values mirror
 *  `internal::DualEntryStopPathWinner`'s enumerator order:
 *    - `0` None -- no such pair was arbitrated on that bar (not flat, no
 *      matching pair, or neither/only one side touched).
 *    - `1` LongFirst -- the long stop's first-touch position on the intrabar
 *      path came first (or the two tied, which the engine always resolves
 *      in the long leg's favour).
 *    - `2` ShortFirst -- the short stop's first-touch position came first.
 *    - `-1` -- @p s is NULL.
 *  This is a per-BAR snapshot, not a live read of the engine's per-pass
 *  working state: it is written once, at the arbitration itself, and then
 *  holds for the rest of that bar even though the working state goes back
 *  to None the moment the winning side fills (position no longer flat) or
 *  its stop-entry admission is declined -- neither of which undoes the fact
 *  that TradingView's broker emulator arbitrated a real pair that bar. A
 *  caller therefore gets the right answer whether it reads this after a
 *  `strategy_set_probe_suppress_tail_logic` forming-bar probe (a single
 *  native request-matching pass) or after an ordinary
 *  `process_orders_on_close` run with no tail suppression (two passes, the
 *  winner already filled by the second).
 *  A live probe reads this after a forming-bar run to see which side the
 *  engine's own broker-emulator tie-break picked, without having to re-run
 *  and infer it from which of the two possible fills came back.
 *  Only the standard (non-`calc_on_order_fills`) dispatch path updates this
 *  value; it is a silent no-op under the COOF scheduler, mirroring
 *  #strategy_set_probe_suppress_tail_logic's dispatch-path-scope caveat. */
PF_API int strategy_last_bar_dual_entry_path(pf_strategy_t s);
/** Toggle per-report-point broker-state hash recording (spec §3.4, ABI v4).
 *
 *  When @p on is non-zero, every subsequent run() appends
 *  #strategy_broker_state_hash's value to pf_report_t::broker_state_hash
 *  after each report point (KernelRecorded for bare hosts); completed runs
 *  match pf_report_t::script_bars_processed, failed ones may not. Cleared (recorded array
 *  emptied, not the flag itself) at the start of every run(); the flag is
 *  persistent configuration, like #strategy_set_realtime_tail, and stays
 *  set until a caller passes @p on == 0.
 *  Also covers #strategy_stream_begin's warmup run() and every script bar
 *  dispatched afterward by the realtime tick stream, so
 *  #strategy_stream_fill_report's cumulative report satisfies the same
 *  len == script_bars_processed invariant. Set this BEFORE
 *  #strategy_stream_begin to also record the warmup leg -- reset_run_state()
 *  (which stream_begin's internal run() invokes) empties the recorded
 *  array, not the flag, but a flag flipped on only after stream_begin
 *  returns misses the warmup bars already dispatched.
 *  Default off (@p on == 0): pf_report_t::broker_state_hash is NULL /
 *  0-length and every historical run stays byte-identical to before this
 *  flag existed.
 *
 *  What a row is, and what it is for. A row is the run's CONTINUATION
 *  IDENTITY at that bar, not its trade outcome: it folds the broker state and,
 *  ahead of it, the state a resume would continue from -- the driving mode
 *  (batch run, stream warmup, stream realtime) included, on purpose. So the
 *  array is a replay check WITHIN one driving mode and deliberately not across
 *  modes: two runs driven the same way over the same bars record the same
 *  rows, and a run driven the same way that ended at bar k recorded, as its
 *  last row, the row the longer run recorded after bar k; but a run(), a
 *  #strategy_stream_begin with one warmup bar and one with every bar as warmup
 *  record DIFFERENT rows from index 0 over the same bars booking the same
 *  trades. Only the len == script_bars_processed identity above holds across
 *  drivings. What pins that a stream books what a batch books is the outcome
 *  itself -- the trades, the position and the equity -- and not this array. */
PF_API void strategy_set_broker_state_hash_recording(pf_strategy_t s, int on);
/** Return the broker-state hash of the FINAL state after the most recent
 *  run() (see #strategy_set_broker_state_hash_recording's doc and
 *  pf_report_t::broker_state_hash for the per-bar recording; this accessor
 *  works whether or not recording was enabled). Compare runs of one
 *  configuration: the recipe belongs to the script ABI epoch, fixed from 1.0.0
 *  for every 1.x engine (engine_script_run_v19 to 1.10, then v20), so two values differ only
 *  when the states they fold differ. This is not a serialized checkpoint.
 *  Returns 0 when @p s is NULL.
 *
 *  A refused read also returns 0, so a 0 alone does not tell it from an
 *  answer: once a handle that carries selected-window provenance has sealed
 *  its run, this query is refused and #strategy_state_query_status_v1 names
 *  it (#PF_STATE_QUERY_SELECTED_WINDOW_AFTER_SEAL_V1). A caller that needs
 *  that run's terminal witness enables
 *  #strategy_set_broker_state_hash_recording BEFORE the run and reads the last
 *  pf_report_t::broker_state_hash row; no row means no witness. */
PF_API uint64_t strategy_broker_state_hash(pf_strategy_t s);
 
/** What #strategy_state_query_status_v1 answers: whether the two state queries,
 *  #strategy_broker_state_hash and #strategy_stream_state_hash, may answer a
 *  handle now, and whether the report-only terminal-quote writers may still
 *  store. A fixed-width word rather than an enum, so its width does not
 *  depend on the consumer's compiler flags. */
typedef int32_t pf_state_query_status_v1_t;
#define PF_STATE_QUERY_ALLOWED_V1                    0 /**< Both queries may answer, and the quote writers store. */
#define PF_STATE_QUERY_SELECTED_WINDOW_AFTER_SEAL_V1 1 /**< Both are refused, and so are the quote writers: a selected window's run has sealed. */
#define PF_STATE_QUERY_INVALID_HANDLE_V1             2 /**< The handle is NULL. */
 
/** The current eligibility of BOTH #strategy_broker_state_hash and
 *  #strategy_stream_state_hash on @p s, as a #pf_state_query_status_v1_t:
 *  #PF_STATE_QUERY_ALLOWED_V1 when either may answer,
 *  #PF_STATE_QUERY_SELECTED_WINDOW_AFTER_SEAL_V1 when the handle carries
 *  selected-window provenance and its run has sealed (a refused query returns
 *  0, which is also a legal hash value: this tells the two apart), and
 *  #PF_STATE_QUERY_INVALID_HANDLE_V1 for a NULL @p s. A handle answers
 *  #PF_STATE_QUERY_ALLOWED_V1 unless it was admitted as a selected-window run,
 *  which only a separately documented export can do. This is the state of the
 *  handle at the call, not a last-error slot: it allocates nothing, changes
 *  nothing, runs no host code and never records, replaces or clears
 *  #strategy_get_last_error or its code, so a run's first cause stays what the
 *  run made it. To keep a selected run's terminal witness, enable
 *  #strategy_set_broker_state_hash_recording BEFORE the run and read the last
 *  pf_report_t::broker_state_hash row. A broker-state row is not a value of
 *  the #strategy_stream_state_hash token, and no row means no witness.
 *
 *  The same status is the observable refusal of the report-only terminal-quote
 *  writers (docs/report-terminal-quote.md), under the same condition: once a
 *  selected-window run has sealed (completed, failed or aborted), the Pine
 *  host stores neither reserved syminfo metadata key,
 *  report_terminal_quote_time_ms and report_terminal_quote_close, whatever the
 *  value, nor a clear of the quote. In C++ the host throws
 *  pineforge::SelectedWindowQueryAfterSeal before any store; the C export
 *  #strategy_set_syminfo_metadata keeps its void signature and swallows every
 *  exception, so a caller learns of the refusal from this status:
 *  #PF_STATE_QUERY_SELECTED_WINDOW_AFTER_SEAL_V1 means a quote-key write stored
 *  nothing. Like the state queries, the refusal records, replaces and clears no
 *  #strategy_get_last_error or its code, latches no run failure and leaves the
 *  captured report as it was. A handle without selected-window provenance, and
 *  a selected handle before its first admitted begin, accept the writes as
 *  before. Proof: tests/test_selected_quote_seal.cpp. */
PF_API pf_state_query_status_v1_t strategy_state_query_status_v1(pf_strategy_t s);
 
/** Number of orders resting in the engine's pending-order book after the
 *  most recent run() (ABI v4 live-runtime surface, task 7, spec 3.6): the
 *  book in force for the NEXT bar. 0 when @p s is NULL. Read-only; a
 *  historical run is byte-identical whether or not a caller reads it. */
PF_API int strategy_pending_orders_len(pf_strategy_t s);
/** Copy the @p index-th resting order (0-based, the engine's own book
 *  order -- insertion order; broker fill priority is decided at fill time
 *  from `created_seq`, not from this index) into @p out as a
 *  pf_pending_order_v1_t value snapshot. Copies
 *  min(@p size_in, sizeof(pf_pending_order_v1_t)) bytes: an older reader
 *  with a smaller struct receives a prefix (struct_version and size first),
 *  a newer reader with a larger one receives the whole v1 and must not
 *  read past pf_pending_order_v1_t::size. Strings are NUL-terminated
 *  char[64] copies with a `_truncated` flag and a `_hash64` (FNV-1a 64 of
 *  the full string); enums are int32 values; NaN sentinels are copied
 *  verbatim. Returns 0 on success, -1 -- with nothing written -- when
 *  @p s or @p out is NULL, @p index is out of range, or @p size_in < 8
 *  (too small to hold even the `struct_version` + `size` header; every
 *  larger @p size_in is honoured as a prefix copy). The layout is
 *  self-described by #strategy_pending_order_layout. */
PF_API int strategy_pending_order_get(pf_strategy_t s, int index, void* out, size_t size_in);
/** The field table of pf_pending_order_v1_t as THIS runtime compiled it --
 *  one pf_field_desc_t {name, type, offset, size} per field, in struct
 *  order, starting with `struct_version` and `size`. Static storage: the
 *  pointer stays valid for the life of the process and needs no handle.
 *  @p count (may be NULL) receives the row count. An FFI consumer builds
 *  its struct from this table rather than from a hand-typed copy, so the
 *  mirror can grow (append-only) without breaking it. */
PF_API const pf_field_desc_t* strategy_pending_order_layout(int* count);
/** Which sizing rule #strategy_pending_order_fill_qty's quantity came from,
 *  written to its `partition` out-parameter; each value is documented there.
 *  The value set is the Pine source host's pending-order sizing, the only
 *  host that answers a probe. */
typedef enum pf_fill_qty_partition_e {
    PF_FILL_QTY_PARTITION_EXIT                   = -1, /**< An exit: no partition. */
    PF_FILL_QTY_PARTITION_EXPLICIT               = 0,
    PF_FILL_QTY_PARTITION_FROZEN_PLACEMENT       = 1,
    PF_FILL_QTY_PARTITION_DEFAULT_STOP_PLACEMENT = 2,
    PF_FILL_QTY_PARTITION_AT_FILL                = 3
} pf_fill_qty_partition_t;
 
/** Engine-computed fill quantity of the @p index-th resting order (ABI v4
 *  live-runtime surface, task 8, spec 3.6): the contracts the entry kernel
 *  would OPEN if that order filled at @p fill_price, sized by the engine's
 *  own rules so a live runtime never re-implements them. @p fill_price is
 *  slipped the way the kernel slips it (`native_matching::apply_slippage`
 *  then the directional grid snap; an entry with a
 *  limit leg takes the unslipped limit-or-better route). @p partition
 *  receives which sizing rule produced the value, a #pf_fill_qty_partition_t:
 *    - `0` EXPLICIT -- a script-supplied qty: for `strategy.entry` the
 *      lot-floored contracts (`apply_qty_step`) of a fixed qty, or the
 *      explicit percent/cash budget sized at the fill for a per-call
 *      qty_type override; a `strategy.order` explicit qty is dispatched
 *      verbatim (no lot step).
 *    - `1` FROZEN_PLACEMENT -- a quantity fixed before the fill, never
 *      re-derived from the fill price: the default percent_of_equity /
 *      cash MARKET (or strategy.order) size frozen at the signal close
 *      (`frozen_default_qty`); a MARKET's frozen broker transaction (a
 *      finalized flat pair's `paired_flat_market_transaction_qty`; a
 *      same-bar-market member's `sbmt_tx_qty` from flat or as a kept
 *      over-cap add); or what one of the two MARKET reversal kernels
 *      opens -- a same-bar-market member against an opposite live position
 *      opens the remainder `sbmt_tx_qty - min(sbmt_tx_qty, live qty)`
 *      (the same-bar market reversal path), and the exact SHORT-seed
 *      collision's final short re-opens the residual
 *      `pyramid_entries[0].qty - pyramid_entries[1].qty` after closing both
 *      lots (the short-seed collision path). Both kernels are
 *      modelled; each reports `close_only` 1 when it opens nothing.
 *    - `2` DEFAULT_STOP_PLACEMENT -- the DEFAULT percent_of_equity pure
 *      STOP entry's placement size, at any percentage
 *      (`default_stop_placement_qty`, round-7 family K), when the
 *      placement-size rule says the fill consumes it: created flat, filling
 *      from flat, positive fill.
 *    - `3` AT_FILL -- default sizing at the slipped fill.
 *  @p close_only receives 1 when the kernel's close-only predicate fires
 *  -- the fill closes against the live opposite position and that
 *  predicate opens no leg of its own: the order's
 *  `affordability_close_only` (entry leg declined at placement), the
 *  priced-entry `prior_cycle_close_only` rule (opposite live position whose
 *  cycle the order was not placed in -- `created_position_side !=` the
 *  live side -- and not a `reverses_same_bar_market_from_flat`), the
 *  same-cycle frozen explicit-FIXED transaction the close consumes exactly,
 *  a finalized flat MARKET pair against an opposite position, or one of the
 *  two reversal kernels above opening nothing. Where the order was created
 *  FLAT the engine's close-only branch can open a remainder: a
 *  transaction larger than the live position still opens the remainder, so
 *  a consumer compares @p qty with the live position. A replaced
 *  default-percent short is dispatched
 *  with its `frozen_default_qty`:
 *  @p qty is that transaction, @p close_only 0. The probe answers for the
 *  order filling against the CURRENT book and position; fills that an
 *  earlier order in the same pass would make first are not simulated.
 *  NOT folded into @p qty: the deferred-flip
 *  carry (`tv_carry_qty`, added on a priced entry from FLAT whose
 *  placement side is the opposite of the
 *  requested side) -- read `tv_carry_qty` / `created_position_side` from
 *  the mirror. Returns 0 on success; 1 -- with @p qty NaN, @p close_only 0,
 *  @p partition -1 (#PF_FILL_QTY_PARTITION_EXIT) -- when the order is an EXIT (its fill quantity is
 *  decided against the live position at the fill, not by a partition); -1
 *  with nothing written when @p s is NULL, @p index is out of range, or any
 *  out-pointer is NULL. Read-only: no historical run changes because a
 *  caller probed it. */
PF_API int strategy_pending_order_fill_qty(pf_strategy_t s, int index, double fill_price,
                                           double* qty, int* close_only, int* partition);
/** 1 when the @p index-th resting order's entry-relative offsets
 *  (`profit_ticks` / `loss_ticks` / `trail_points`) resolve now (ABI v4,
 *  task 8): entries, plain orders and exits with an empty `from_entry`
 *  always; an exit bound to a `from_entry` only once that id has filled in
 *  the CURRENT position cycle -- the same condition the level-resolution
 *  and eligibility passes use.
 *  0 otherwise; -1 when @p s is NULL or
 *  @p index is out of range. */
PF_API int strategy_pending_order_level_resolved(pf_strategy_t s, int index);
/** The price levels the @p index-th resting order would fire at, as the
 *  engine's fill path resolves them (ABI v4, task 8). A leg the order
 *  carries as a price (`stop_price`, `limit_price`, `trail_price`) is
 *  reported verbatim -- it is already on the price grid. A leg carried as
 *  a tick offset is resolved against the live position's average entry
 *  price only when #strategy_pending_order_level_resolved is 1 AND a
 *  position is live, with the POSITION side's sign exactly as the fill
 *  path: `limit = entry + dir * profit_ticks * mintick`, `stop = entry -
 *  dir * loss_ticks * mintick` (dir = +1 long, -1 short; both
 *  `level_on_price_grid`), and `trail_activation = entry +/- ceil(
 *  trail_points - 8e-3 * mintick) * mintick` snapped to the tick grid
 *  (`trail_points` wins over `trail_price` when both are set, as in
 *  the trail activation rule). NaN for a leg that is unset or not yet
 *  resolvable. Returns 0; -1 with nothing written when @p s is NULL,
 *  @p index is out of range, or any out-pointer is NULL. */
PF_API int strategy_pending_order_effective_levels(pf_strategy_t s, int index, double* stop,
                                                   double* limit, double* trail_activation);
/** The trail extreme the exit trail legs ride (`trail_best_price_`: the
 *  running high of a long / low of a short since the position filled,
 *  bar extremes folded in as the fill path folds them). NaN when @p s is
 *  NULL and NaN until a position has filled. */
PF_API double strategy_trail_best_price(pf_strategy_t s);
/** The live position's volume-weighted average entry price
 *  (`position_entry_price_`). NaN when @p s is NULL and NaN when the
 *  position is flat (the engine keeps 0 there; a live reader must not
 *  mistake it for a price). */
PF_API double strategy_position_avg_price(pf_strategy_t s);
/** The live position's cycle id (`position_cycle_seq_`): 0 when flat, a
 *  fresh nonzero id per open or reversal, unchanged across same-direction
 *  adds -- the id `created_position_cycle_seq` on a mirrored order refers
 *  to. -1 when @p s is NULL. */
PF_API int64_t strategy_position_cycle_seq(pf_strategy_t s);
/** Task 9: closed-trade id / exit-comment string accessors, indexing the
 *  same REPORT row space as #strategy_closed_trade_entry_incarnation
 *  (`trades_` then the range-end rows, `open_at_end`). The returned pointer
 *  is valid until the next run() (or stream call) on this handle, like
 *  #strategy_get_last_error. NULL on NULL @p s, out-of-range @p trade_index
 *  or policy-erased rows; retained sealed rows are readable. This legacy API
 *  materializes rows until the next run; full-history reads use growing RAM. */
PF_API const char* strategy_closed_trade_entry_id(pf_strategy_t s, int trade_index);
/** See #strategy_closed_trade_entry_id for the row-space/lifetime/NULL
 *  contract. The returned string is the engine's own INTERNAL exit id, not
 *  always the script's `strategy.exit`/`strategy.close` id verbatim:
 *    - a real `strategy.exit` bracket leg -- the user's own id, unchanged.
 *    - a `strategy.close(id, ...)` close -- `"__close__" + id`.
 *    - `strategy.close_all()` / a bare-id `strategy.close()` -- the literal
 *      `"__close__"` (empty target id appended).
 *    - a margin-call forced liquidation -- the sentinel `"__margin_call__"`.
 *    - an intraday-cap close (`risk.max_intraday_loss`, or the
 *      max-filled-orders cap) -- empty (`""`).
 *  A caller matching exit ids back to its own `strategy.close` calls should
 *  strip the `"__close__"` prefix rather than compare verbatim. */
PF_API const char* strategy_closed_trade_exit_id(pf_strategy_t s, int trade_index);
/** See #strategy_closed_trade_entry_id. */
PF_API const char* strategy_closed_trade_exit_comment(pf_strategy_t s, int trade_index);
/** Why a closed report row exited — `execution::CloseCause`, the value
 *  #strategy_closed_trade_close_cause answers for a valid row. The names are
 *  the kernel's; the descriptive labels in that function's documentation are
 *  the same numbers. */
typedef enum pf_close_cause_e {
    PF_CLOSE_CAUSE_UNSPECIFIED = 0, /**< No cause recorded (UNKNOWN). */
    PF_CLOSE_CAUSE_SCRIPT      = 1, /**< A market close or a reversal. */
    PF_CLOSE_CAUSE_BRACKET     = 2, /**< A bracket leg. */
    PF_CLOSE_CAUSE_LIQUIDATION = 3, /**< A margin-call liquidation slice (MARGIN_CALL). */
    PF_CLOSE_CAUSE_RISK_LIMIT  = 4, /**< A risk-limit flatten (INTRADAY_LOSS_CAP). */
    PF_CLOSE_CAUSE_FILL_CAP    = 5, /**< A filled-order cap (INTRADAY_FILL_CAP). */
    PF_CLOSE_CAUSE_RANGE_END   = 6  /**< The range-end close of a position still open. */
} pf_close_cause_t;
 
/** Task 9: why the @p trade_index-th REPORT-row closed trade exited, a
 *  #pf_close_cause_t.
 *  Values:
 *    - `0` UNKNOWN -- reserved for the documented "no cause" value on a
 *      VALID trade. Every in-range row currently falls through the
 *      derivation below to at worst `1` SCRIPT, so no live derivation
 *      today actually returns `0`; it is not used for a bad index (see
 *      `-1` below, final review F7).
 *    - `1` SCRIPT -- a `strategy.close` / `strategy.close_all` market close,
 *      or a reversal-driven close.
 *    - `2` BRACKET -- a `strategy.exit` stop/limit/trail/profit/loss leg,
 *      or a native host's close its owner's fill armed.
 *    - `3` MARGIN_CALL -- a forced liquidation slice.
 *    - `4` INTRADAY_LOSS_CAP -- `risk.max_intraday_loss`.
 *    - `5` INTRADAY_FILL_CAP -- the max-filled-orders intraday cap.
 *    - `6` RANGE_END -- the still-open position closed at the end of a
 *      flag-off run (`open_at_end`, ABI v3) -- this always wins over every
 *      other cause below it.
 *  Derivation order (see `BacktestEngine::closed_trade_close_cause`,
 *  engine_trade_accessors.cpp): `open_at_end` -> 6; then the cause the
 *  CLOSER recorded on the row (`execution::CloseCause`, whose numbers are
 *  exactly these values) -- a kernel-originated liquidation or risk flatten
 *  states it through the settling fill, and so does a host request its
 *  owner's fill armed (a `WaitForApplied` owner relation, as
 *  `native_toolkit::submit_bracket` builds, with an intent that only closes:
 *  `Reduce`, `Flatten` or a host-sized close), which records `2` BRACKET; a
 *  host running its own forced-close policy states it on the row it
 *  produced, which is where the Pine adapter's margin-call (3),
 *  max-intraday-loss (4) and filled-order-cap (5) rows get their value (the
 *  adapter classifies its own bracket rows by order family, so it clears the
 *  kernel's `2` on them first); then the row's `exit_from_bracket` flag -- true
 *  only for a REAL `strategy.exit` leg, either an exit-order fill
 *  whose id does NOT carry the internal `"__close__"` prefix that a deferred
 *  `strategy.close`/`close_all` order is also given (that path reuses the
 *  same exit fill machinery), or a whole-position bracket
 *  revived and fired at the margin-call event price
 *  (through the margin-call bracket revival) -- -> 2;
 *  otherwise 1.
 *  A Pine/source run's values are unchanged. A bare native host that declares
 *  a kernel margin model now reads `3` for its own liquidation rows (and `4`
 *  for a kernel risk flatten) where the retired string derivation, which only
 *  recognised the adapter's sentinels, answered `1`, and it reads `2` for a
 *  bracket leg its parent request armed, where it read `1` before the host excursion and bracket-cause integration.
 *  `-1` when @p s is NULL, or when @p trade_index is out of range (final
 *  review F7: matches every sibling indexed live accessor's -1-on-bad-index
 *  convention -- #strategy_pending_order_fill_qty,
 *  #strategy_pending_order_level_resolved,
 *  #strategy_pending_order_effective_levels). `0` therefore never
 *  ambiguously means "bad index"; a caller can tell "row exists but reads
 *  UNKNOWN" apart from "bad index" without a separate
 *  #strategy_closed_trade_entry_incarnation `report_trade_count` bounds
 *  check first, though doing that check is still good practice. */
PF_API int strategy_closed_trade_close_cause(pf_strategy_t s, int trade_index);
/** Task 9: the script-facing signed position size (`strategy.position_size`;
 *  Freeze-aware -- while a same-bar `process_orders_on_close` close is
 *  frozen for the current bar, this reads the PRE-close position, matching
 *  what the script itself observes). NaN when @p s is NULL. */
PF_API double strategy_position_size(pf_strategy_t s);
/** Task 9: initial capital plus realized net profit
 *  (`strategy.initial_capital + strategy.netprofit`). NOT Pine's
 *  `strategy.equity`, which adds open profit on top of this (unlike the
 *  last point of `pf_report_t::equity_curve`, which does). NaN when @p s is
 *  NULL. */
PF_API double strategy_current_equity(pf_strategy_t s);
/** ABI v4 live-runtime surface (1.8.0): the configured run's initial capital,
 *  before realized or open profit. Includes staged native specs before begin,
 *  and generated defaults or overrides once the source host configures the run.
 *  NaN when @p s is NULL or the read raises, matching
 *  #strategy_current_equity's invalid-handle sentinel so a failed query is
 *  not mistaken for a capital value. */
PF_API double strategy_initial_capital(pf_strategy_t s);
/** Raw whole-lot realized P&L, excluding initial capital and report-only
 *  terminal rows. Reads the engine accumulator directly, including before
 *  report retrieval; independent of report sorting and global-exit recuts.
 *  Nonvirtual, additive accessor; ABI version unchanged. NaN when @p s is NULL. */
PF_API double strategy_net_profit_sum(pf_strategy_t s);
/** Effective symbol pointvalue used by the engine report. NaN on NULL. */
PF_API double strategy_report_pointvalue(pf_strategy_t s);
/** Opt in to the separate pf-report-replay/v1 companion before a run.
 *  Copies @p path and @p run_id (at most 64 KiB each; NULL run ID means empty).
 *  NULL path disables.
 *  Does not modify primary sink descriptors or existing C layouts.
 *  Returns 0 on success, -1 for invalid arguments, -2 during streaming,
 *  -3 during an active call or after ledger retirement. Check the result. */
PF_API int strategy_set_report_replay_v1(pf_strategy_t s, const char* path, const char* run_id);
/** Task 9: total SCRIPT bars dispatched by the most recent run() (mirrors
 *  `pf_report_t::script_bars_processed`, engine_report.cpp) -- includes a
 *  stream's warmup leg and every realtime tick-driven bar dispatched
 *  afterward by #strategy_stream_push_tick / #strategy_stream_push_ticks.
 *  `-1` when @p s is NULL. */
PF_API int64_t strategy_script_bars_processed(pf_strategy_t s);
/** @} */
 
/** @addtogroup pf_config
 *  @{
 */
 
/** Set the strategy's chart timezone (IANA / POSIX TZ string).
 *
 *  Pine builtins ``hour``, ``minute``, ``second``, ``dayofmonth``,
 *  ``dayofweek``, ``month``, ``year`` and ``weekofyear`` return the
 *  wall-clock for the chart's timezone — TV exports trade rows in chart
 *  TZ too. Engine bars are stored as Unix-ms (UTC), so without this
 *  override these builtins return UTC and silently diverge from TV by N
 *  hours when the chart is on a non-UTC zone (Asia/Hong_Kong = UTC+8 is the
 *  validator default).
 *
 *  Pass `NULL`, `""`, `"UTC"` or `"Etc/UTC"` for the legacy UTC
 *  behaviour (cheap, mutex-free). Any other value names a TZ resolved by
 *  the system tzdata; uncached decomposition uses the engine image's mutex
 *  and checks the process's actual TZ. Sequential switches between engine
 *  images are coherent. Independent images do not share that mutex;
 *  concurrent conversions across images are not serialized by it.
 *
 *  Should be called before #run_backtest / #run_backtest_full. Persists
 *  across runs on the same strategy handle until overridden. */
PF_API void strategy_set_chart_timezone(pf_strategy_t s, const char* tz);
 
/** Plumb the symbol's exchange timezone (IANA string) into syminfo. Feeds
 *  ``session.ismarket`` / ``time(session)`` predicates. Defaults to "UTC"
 *  (crypto). Distinct from #strategy_set_chart_timezone — the chart TZ
 *  drives wall-clock builtins and intraday-cap day rollover; this drives
 *  session membership. `NULL` is ignored. Call before #run_backtest / #run_backtest_full. */
PF_API void strategy_set_syminfo_timezone(pf_strategy_t s, const char* tz);
 
/** Set the symbol's session string (e.g. "0930-1600:23456", default
 *  "24x7"). Feeds ``session.ismarket`` / ``time(session)``. `NULL`
 *  ignored. Call before #run_backtest / #run_backtest_full. */
PF_API void strategy_set_syminfo_session(pf_strategy_t s, const char* session);
 
/** Set the instrument class (``syminfo.type``: "forex", "stock", "crypto",
 *  "futures", "index", "fund", "cfd", ...; default "crypto"). Scripts branch
 *  on it for instrument conventions (e.g. the forex pip size). `NULL` /
 *  empty ignored. Call before #run_backtest / #run_backtest_full. */
PF_API void strategy_set_syminfo_type(pf_strategy_t s, const char* type);
 
/** Set one of the remaining string members of ``syminfo`` by Pine member
 *  name: "ticker", "tickerid", "currency", "basecurrency", "description",
 *  "volumetype" (and "type"). Returns 0 when set, -1 for an unknown key,
 *  empty value or NULL. Call before #run_backtest / #run_backtest_full. */
PF_API int strategy_set_syminfo_string(pf_strategy_t s, const char* key,
                                       const char* value);
 
/** Set the instrument tick size (``syminfo.mintick``, default 0.01). Drives the
 *  directional stop-entry snap and ``slippage = N*mintick`` economics. Set
 *  per-instrument (e.g. 0.25 for ES, 0.00001 for FX). Non-positive ignored.
 *  Call before #run_backtest / #run_backtest_full. */
PF_API void strategy_set_syminfo_mintick(pf_strategy_t s, double mintick);
 
/** Set the instrument point value (``syminfo.pointvalue``, default 1.0) — the
 *  $-per-point-per-contract multiplier applied to every money path: realized
 *  PnL and MFE/MAE, open profit / mark-to-market equity (and the drawdown /
 *  runup extremes), percent-of-equity and cash position sizing, percent
 *  commission notionals, and the margin admission check. Set per-instrument
 *  (e.g. 50 for ES). Non-positive ignored. Call before #run_backtest / #run_backtest_full. */
PF_API void strategy_set_syminfo_pointvalue(pf_strategy_t s, double pointvalue);
 
/** Inject a fundamental/exchange metadata value by Pine member name (e.g.
 *  "shares_outstanding_total"); un-injected reads return na. Quantity step: a
 *  declared "qty_step", or a finite "mincontract" > 0 while no "qty_step" is
 *  declared, sets the order quantity grid. Call before #run_backtest[_full].
 *  series_origin_ms declares the reference series' first bar open
 *  in epoch ms and enables chart EMA SMA seeding plus request.security warmup
 *  from the first whole bucket opening at/after that origin. */
PF_API void strategy_set_syminfo_metadata(pf_strategy_t s, const char* key,
                                          double value);
 
/** Install a timestamped quote-to-account currency conversion curve.
 *
 *  Each value is account-currency units per one unit of the symbol's quote
 *  currency and becomes active, inclusively, at the corresponding Unix-ms
 *  timestamp. The latest active value carries forward; broker events before
 *  the first point use the scalar `account_currency_fx` metadata fallback.
 *  Installing a curve also selects the converted account-currency broker
 *  ledger, including during that pre-first fallback interval; it is not
 *  equivalent to a same-currency run merely because a rate happens to be 1.
 *  Arrays are copied. Timestamps must be strictly increasing and rates
 *  positive and finite. Pass `n == 0` to clear the curve and restore scalar
 *  behavior. Timestamped curves currently support ordinary historical runs.
 *  Broker-open rate changes: carried 1× longs and 1× shorts are supported;
 *  leveraged positions fail closed at the crossing. Streaming,
 *  calc-on-order-fills, and bar-magnifier runs
 *  also fail closed.
 *
 *  @return 0 on success, -1 for a null strategy or invalid arrays. */
PF_API int strategy_set_account_currency_fx_series(
    pf_strategy_t s, const int64_t* effective_from_ms,
    const double* account_per_quote, int n);
 
#ifdef PINEFORGE_HAS_AUX_SECURITY_FEED_V1
/** Copy a finer feed used exclusively by same-symbol request.security calls.
 *
 *  The next ordinary #run_backtest_full call must receive native chart bars
 *  with @c input_tf equal to @c script_tf and bar magnifier disabled. Chart
 *  OHLCV, broker fills, and @c bar_index continue to advance only from that
 *  native chart feed; @p bars advance only request.security evaluators.
 *  Every auxiliary bar must map to exactly one native chart bar and every
 *  native chart bar must have at least one auxiliary bar, otherwise the run
 *  fails closed via #strategy_get_last_error. Arrays are copied. Pass
 *  @p n == 0 to clear the auxiliary feed.
 *
 *  @return 0 on success, -1 for a null strategy or invalid input. */
PF_API int strategy_set_aux_security_feed(pf_strategy_t s,
                                          const pf_bar_t* bars,
                                          int n,
                                          const char* input_tf);
#endif
 
#ifdef PINEFORGE_HAS_NATIVE_SECURITY_FEED_V1
/** Copy the exchange's OWN bars of one higher timeframe for same-symbol
 *  request.security calls that request exactly that timeframe.
 *
 *  On intraday charts of CME futures and US/Indian equities TradingView's
 *  request.security(syminfo.tickerid, "D", close) returns the exchange's
 *  daily bar -- the 15:00 CT settlement on ES1!/NQ1!, the official closing
 *  print on NASDAQ/NYSE/NSE -- which no aggregation of the intraday feed can
 *  reproduce. With a native feed installed for @p timeframe ("D", "1D", "W",
 *  ...), every completed request.security bucket of that timeframe carries
 *  the native bar's OHLCV (matched by the bucket's own label: the session-day
 *  stamp for D/W/M, the grid open for intraday) instead of the aggregate;
 *  bucket TIMING -- when the bar completes relative to the chart -- and every
 *  other timeframe's request are unchanged, and so are chart OHLCV, broker
 *  fills and bar_index. A "W" / "M" request with no feed of its own reads
 *  the daily feed's bars aggregated per week / month (TradingView builds its
 *  W/M bars from the native daily bars, never from intraday prints), keyed by
 *  the period's first session-day. A completed bucket with no native bar
 *  keeps its aggregate (counted, not fatal). Bars must be strictly
 *  increasing; arrays are copied; pass @p n == 0 to clear the feed for
 *  @p timeframe. Historical runs only: stream_begin() fails closed while a
 *  native feed is installed.
 *
 *  @return 0 on success, -1 for a null strategy or invalid input. */
PF_API int strategy_set_native_security_feed(pf_strategy_t s,
                                             const char* timeframe,
                                             const pf_bar_t* bars,
                                             int n);
#endif
 
/** Feature probe for #strategy_set_symbol_feed: the first of four opt-in
 *  setters of another symbol's data for request.security (lane XSYM-D),
 *  each behind its own feature probe. They are the Pine source host's
 *  doors: a strategy that registers a request site for another symbol reads
 *  its bars, its facts and its recorded request values from what these
 *  installed before the run; during a run each answers -1, as a host with
 *  no source layer does. Every array is copied; a later call replaces what
 *  an earlier one installed under the same key. Historical runs only:
 *  stream_begin() fails closed while a symbol feed or a recorded series is
 *  installed. */
#define PINEFORGE_HAS_SYMBOL_FEED_V1 1
/** Feature probe for #strategy_set_symbol_feed_column. */
#define PINEFORGE_HAS_SYMBOL_FEED_COLUMN_V1 1
/** Feature probe for #strategy_set_symbol_facts. */
#define PINEFORGE_HAS_SYMBOL_FACTS_V1 1
/** Feature probe for #strategy_set_recorded_series. */
#define PINEFORGE_HAS_RECORDED_SERIES_V1 1
 
#ifdef PINEFORGE_HAS_SYMBOL_FEED_V1
/** Copy another symbol's own bars of one timeframe, keyed by the exact
 *  symbol string a request site passes at run time (@p key) and by
 *  @p timeframe ("15", "60", "1D", ...; "D" and "1D" are one key).
 *
 *  Each bar carries its own close, @p close_ms[i]: after its open
 *  (@c bars[i].timestamp) and at or before the next bar's open. No calendar
 *  is guessed for the symbol. Bars must be strictly increasing with finite
 *  prices; a volume the symbol does not publish is NaN. The feed reaches
 *  the kernel as a NativeRunSpec instrument feed: on each chart bar, a site
 *  with lookahead off reads the last bar that has closed by the chart bar's
 *  close, one with lookahead on the last bar that opened by its open, and the
 *  site's expression runs over every bar of the feed, in order. Installing a
 *  feed drops the columns of the feed it replaces; @p n == 0 installs a feed
 *  without bars, whose sites read na. Historical runs only: stream_begin()
 *  fails closed while a symbol feed is installed.
 *
 *  @return 0 on success, -1 for a null strategy, invalid input (the reason in
 *          #strategy_get_last_error) or a host with no source layer. */
PF_API int strategy_set_symbol_feed(pf_strategy_t s, const char* key, const char* timeframe,
                                    const pf_bar_t* bars, const int64_t* close_ms, int n);
#endif
 
#ifdef PINEFORGE_HAS_SYMBOL_FEED_COLUMN_V1
/** Copy one named column of an installed symbol feed: @p n values, one per
 *  bar of the feed of (@p key, @p timeframe), in bar order (a footprint
 *  delta, @c "fp_delta_100_70"). NaN is an absent value. A column of the same
 *  name is replaced. Historical runs only: stream_begin() fails closed while
 *  a symbol feed is installed.
 *
 *  @return 0 on success, -1 for a null strategy, a feed that is not
 *          installed, a length that is not the feed's, a name the kernel
 *          refuses, or a host with no source layer. */
PF_API int strategy_set_symbol_feed_column(pf_strategy_t s, const char* key,
                                           const char* timeframe, const char* name,
                                           const double* values, int n);
#endif
 
#ifdef PINEFORGE_HAS_SYMBOL_FACTS_V1
/** Set one fact of the symbol a request site names by @p key: @p field is
 *  one of @c "canonical", @c "valid" (@c "true" / @c "false"), @c "type",
 *  @c "timezone", @c "session", @c "currency" or @c "mintick" (a positive
 *  decimal). Inside that site's expression @c syminfo.* reads these facts
 *  (@c syminfo.tickerid reads @p key itself). A symbol whose @c valid is
 *  @c "false" makes a site with @c ignore_invalid_symbol read na and fails
 *  any other site's run closed. Facts only describe an installed feed, so
 *  historical runs only: stream_begin() fails closed while a symbol feed is
 *  installed.
 *
 *  @return 0 on success, -1 for a null strategy, an unknown field, a value
 *          the field refuses, or a host with no source layer. */
PF_API int strategy_set_symbol_facts(pf_strategy_t s, const char* key, const char* field,
                                     const char* value);
#endif
 
#ifdef PINEFORGE_HAS_RECORDED_SERIES_V1
/** Copy a recorded request series: the values a request returned on the
 *  chart bars that opened at @p chart_open_ms (strictly increasing), keyed
 *  by the request key a generated strategy reads it under. On a chart bar
 *  with no row the series reads na, and on every bar when @p n == 0.
 *  Historical runs only: stream_begin() fails closed while a recorded series
 *  is installed.
 *
 *  @return 0 on success, -1 for a null strategy, invalid input or a host
 *          with no source layer. */
PF_API int strategy_set_recorded_series(pf_strategy_t s, const char* key,
                                        const int64_t* chart_open_ms, const double* values,
                                        int n);
#endif
 
/** Returns the error message captured by the most recent #run_backtest /
 *  #run_backtest_full call on this strategy.
 *
 *  Returns an empty string when the run completed normally, or `NULL`
 *  only when `s` itself is `NULL`. The pointer is owned by the engine
 *  and remains valid until the next #run_backtest / #run_backtest_full call (which clears
 *  the captured error before it begins).
 *
 *  The runtime catches every `std::exception` derivative inside the
 *  engine's run loop so the C ABI never unwinds a C++ exception across
 *  the `extern "C"` boundary. Consumers must check this after every
 *  run to surface engine-rejected configurations such as a script
 *  timeframe finer than the input timeframe, a `request.security`
 *  timeframe below the chart timeframe without a supported lower-TF
 *  emulation, or a missing input timeframe when securities are
 *  registered. */
PF_API const char* strategy_get_last_error(pf_strategy_t s);
 
/** Compile-time probe for the two run-failure code getters below (and the
 *  generated-code helpers of `<pineforge/run_failure.hpp>`). A runtime library
 *  without them lacks the symbols: look them up with `dlsym`. */
#define PINEFORGE_HAS_RUN_FAILURE_CODES_V1 1
 
/** Stable code of the most recent failure on @p s: lower snake_case ASCII
 *  matching `^[a-z][a-z0-9_]{2,47}$`, from the closed vocabulary published as
 *  `run_failure_codes.json` (schema `pineforge-run-failure-catalog/v1`); a
 *  code is never reused for another meaning.
 *
 *  Returns `""` exactly when the most recent run (or setter) on @p s recorded
 *  no failure, and `NULL` only when @p s is `NULL`. It is not keyed on the
 *  text: a script that stops with an empty `runtime.error()` message fails
 *  with #strategy_get_last_error `""` and the code `strategy_runtime_error`,
 *  and a non-empty error that no coded site wrote reads
 *  `engine_unclassified_error`, never `""`. A text a script writes never
 *  selects a code. The pointer has the lifetime of #strategy_get_last_error's
 *  (until the next run or setter on @p s). */
PF_API const char* strategy_get_last_error_code(pf_strategy_t s);
 
/** The typed arguments of the failure #strategy_get_last_error_code names, as
 *  one canonical JSON object: UTF-8, keys sorted, no whitespace; an integer
 *  is a JSON integer, a number the shortest round-trip double, every other
 *  kind a JSON string. `"{}"` when the code has no arguments, `""` when there
 *  is no failure, `NULL` only when @p s is `NULL`. An argument is never a
 *  value the script computed while it ran. Same lifetime as
 *  #strategy_get_last_error_code. */
PF_API const char* strategy_get_last_error_args(pf_strategy_t s);
 
/** @} */ /* end of pf_config */
 
/** @defgroup pf_version Version query
 *  @brief Runtime version metadata.
 *  @{
 */
 
/** Runtime version descriptor returned by #pf_version_get. */
typedef struct pf_version_s {
    int         major;       /**< Major version. */
    int         minor;       /**< Minor version. */
    int         patch;       /**< Patch version. */
    const char* commit_sha;  /**< Short git commit SHA, or `""` if unknown. */
} pf_version_t;
 
/** @return Linked runtime version. */
PF_API pf_version_t pf_version_get(void);
 
/** @return Monotonic ABI version (see #PF_ABI_VERSION). */
PF_API int pf_abi_version(void);
 
/** Full version descriptor, the `PINEFORGE_VERSION_FULL` of the generated
 *  `pineforge/version.h`.
 *
 *  Returns `"MAJOR.MINOR.PATCH[-rc.N][-N-gSHA[-dirty]]"` for a tagged git
 *  checkout, or exactly the `VERSION` file (`"MAJOR.MINOR.PATCH"`, or
 *  `"MAJOR.MINOR.PATCH-rc.N"` for a release candidate) for a tarball build
 *  or one configured with `PINEFORGE_VERSION_SOURCE=FILE`. #pf_version_get
 *  carries only the numeric MAJOR.MINOR.PATCH. The pointer is to a static
 *  string with program lifetime; do not free. */
PF_API const char* pf_version_string(void);
 
/** @} */ /* end of pf_version */
 
/** @defgroup pf_settings Generated Strategy Settings
 *  Additive, opt-in validation and effective-settings receipts.
 *  @{ */
 
/** Current generated-strategy settings extension version. */
#define PF_SETTINGS_API_VERSION 1u
 
/** Current compiled-strategy execution-capabilities extension version. */
#define PF_CAPABILITIES_API_VERSION 1u
 
/** Status codes for the opt-in generated-strategy settings extension. */
typedef enum pf_settings_status_t {
    PF_SETTINGS_OK = 0,
    PF_SETTINGS_INVALID_ARGUMENT = 1,
    PF_SETTINGS_UNSUPPORTED = 2,
    PF_SETTINGS_EXCEPTION = 3,
    PF_SETTINGS_BUFFER_TOO_SMALL = 4,
    PF_SETTINGS_RUN_FAILED = 5
} pf_settings_status_t;
 
/** @} */ /* end of pf_settings */
 
#ifndef PINEFORGE_NO_STRATEGY_DECLS
 
/** Generated-strategy settings extension version (currently 1).
 *  Older compiled strategies lack this symbol. This is independent of
 *  #pf_abi_version and does not change the legacy entry points. */
PF_API uint32_t strategy_settings_api_version(void);
 
/** Compiled execution-capabilities extension version (currently 1).
 *  Older strategies lack this symbol. Independent of #PF_ABI_VERSION and
 *  #PF_SETTINGS_API_VERSION; implemented by the generated strategy, not runtime. */
PF_API uint32_t strategy_capabilities_api_version(void);
 
/** Read immutable canonical JSON describing compiled execution declarations
 *  and analyzed request/data requirements, never inferred from runtime state.
 *  Uses #pf_settings_status_t and the buffer/error protocol of
 *  #strategy_get_effective_settings: @p required includes the NUL, NULL/0
 *  queries return #PF_SETTINGS_BUFFER_TOO_SMALL, and no partial JSON is returned.
 *  @p s and @p required must be non-NULL. Receipt bytes remain identical across
 *  settings changes, batch runs, stream runs and fresh/reused handles.
 *  A consumer must separately validate effective settings and staged run data. */
PF_API int strategy_capabilities_receipt(pf_strategy_t s, char* json,
                                         size_t capacity, size_t* required,
                                         char* error, size_t error_capacity);
 
/** Allocate a strategy without allowing any exception across the C boundary.
 *  @p params_json is reserved: pass NULL or an empty string. Nonempty values
 *  are refused, unlike the legacy factory which ignores them.
 *  @p out is required and is set to NULL before allocation.
 *  All checked calls return #pf_settings_status_t; an optional caller-owned
 *  error buffer receives a NUL-terminated, possibly truncated message.
 *  A successful call clears that buffer. No error buffer allocation is needed. */
PF_API int strategy_create_checked(const char* params_json, pf_strategy_t* out,
                                   char* error, size_t error_capacity);
 
/** Validate and install a declared input before execution.
 *  Rejects unknown or ambiguous keys, invalid options/booleans, non-finite
 *  numbers, trailing bytes, range violations and unsupported input forms.
 *  Invalid values leave the existing setting unchanged. Pine's numeric step
 *  is UI metadata, not a restriction on programmatically supplied values.
 *  Calls after execution starts are refused; use the legacy setter for its
 *  historical subsequent-run behavior. */
PF_API int strategy_set_input_checked(pf_strategy_t s, const char* key,
                                      const char* value, char* error,
                                      size_t error_capacity);
 
/** Validate and install a supported strategy override before execution.
 *  Accepts the legacy documented enum aliases, but never silently defaults
 *  an unknown key, invalid enum, invalid boolean or invalid numeric value. */
PF_API int strategy_set_override_checked(pf_strategy_t s, const char* key,
                                         const char* value, char* error,
                                         size_t error_capacity);
 
/** Read a deterministic UTF-8 JSON receipt of effective settings.
 *  Lists every declared input and supported override, including type,
 *  options, min/max/step constraints, default and effective value. Values
 *  use canonical serialized strings. No new execution state is retained.
 *  @p required is required and receives the byte count INCLUDING the NUL.
 *  Pass NULL/0 for @p json/capacity to query that count; this returns
 *  #PF_SETTINGS_BUFFER_TOO_SMALL. No partial JSON is returned.
 *  The receipt describes source settings, not a native run-spec capability. */
PF_API int strategy_get_effective_settings(pf_strategy_t s, char* json,
                                           size_t capacity, size_t* required,
                                           char* error, size_t error_capacity);
 
/** Exception-contained counterpart of #run_backtest_full.
 *  Validates pointers and bar count, then uses the identical batch dispatch.
 *  Returns #PF_SETTINGS_RUN_FAILED for a runtime-reported failure and
 *  #PF_SETTINGS_EXCEPTION for an escaping C++ exception. Initialize @p out
 *  to zero and release any populated arrays with #report_free, including
 *  after a failed call. */
PF_API int run_backtest_full_checked(pf_strategy_t s, pf_bar_t* bars, int n,
                                     const char* input_tf, const char* script_tf,
                                     int bar_magnifier, int magnifier_samples,
                                     pf_magnifier_distribution_t magnifier_dist,
                                     pf_report_t* out, char* error,
                                     size_t error_capacity);
 
#endif
 
/** @defgroup pf_outputs Recorded outputs
 *  What a module records besides trades, read after a run or between the
 *  inputs of a stream (docs/outputs.md). A module that records declares named
 *  series slots, outputs and run constants, and per run writes one row per
 *  bar it publishes: a double per slot (NaN = na), events with an optional
 *  message, and one value per run constant. Nothing is recorded until
 *  #strategy_outputs_set_enabled turns recording on, and nothing a run
 *  computes depends on it: trades, the report, #PF_ABI_VERSION and every
 *  hash are what they are with recording off. What a slot, an output or a
 *  constant means is in the manifest the module exports
 *  (#strategy_outputs_manifest).
 *
 *  Part B, the readers, is implemented by the runtime and present in every
 *  module built on it; a module that declares nothing answers them as empty.
 *  Part A is generated per module and present only in one that records:
 *  detect recording with dlsym("strategy_outputs_api_version").
 *
 *  Threading: every strategy_outputs_* call runs on the thread that drives
 *  the handle, never during one of its run or stream calls. A NULL handle
 *  answers -1 (nothing for a void function).
 *  @{ */
 
/** Present in a pineforge.h that declares the group. */
#define PINEFORGE_HAS_OUTPUTS_V1 1
/** What #strategy_outputs_api_version answers. */
#define PF_OUTPUTS_API_VERSION 1u
 
/** The run phase an event was recorded in. */
typedef enum pf_output_phase_e {
    PF_OUTPUT_PHASE_BATCH = 0,   /**< a batch run */
    PF_OUTPUT_PHASE_WARMUP = 1,  /**< a stream's warm-up, inside strategy_stream_begin */
    PF_OUTPUT_PHASE_REALTIME = 2 /**< a stream after its warm-up */
} pf_output_phase_t;
PF_STATIC_ASSERT(sizeof(pf_output_phase_t) == 4);
 
/** One recorded event, copied by #strategy_outputs_event_get. Every 8-byte
 *  field sits at a multiple of 8, so the 72 bytes before `message` are laid
 *  out alike on every target. */
typedef struct pf_output_event_v1_s {
    uint32_t struct_version;  /**< 1 */
    uint32_t size;            /**< sizeof(pf_output_event_v1_t) as the runtime compiled it */
    uint64_t sequence;        /**< 1-based per run; once cleared, never issued again */
    int32_t  output_index;    /**< the output, as the manifest's `outputs[].index` */
    int32_t  bar_index;       /**< the row, 0-based */
    int64_t  bar_open_ms;     /**< the row's open, Unix ms */
    int64_t  bar_close_ms;    /**< the row's close, Unix ms; INT64_MIN when unknown */
    uint32_t ordinal_in_bar;  /**< per output, from 0 within the row */
    uint32_t phase;           /**< a #pf_output_phase_t */
    uint32_t confirmed;       /**< 0 when recorded on a partially finalized bar */
    uint32_t reserved0;       /**< 0 */
    double   value;           /**< the event's value; NaN = na */
    uint64_t message_hash64;  /**< FNV-1a 64 of every byte the module recorded as the
                                   message; 0 without one */
    const char* message;      /**< NUL-terminated, or NULL without one: a message holding a
                                   NUL byte reads to its first NUL, while message_hash64
                                   covers every recorded byte. Borrowed until the next call
                                   that runs, streams or clears on the handle */
} pf_output_event_v1_t;
 
/** Turn recording on (@p on nonzero) or off. A change clears the record; a
 *  call that changes nothing changes nothing, even while a run is in progress.
 *  Returns 0, or -1 with nothing changed and the refusal recorded as code
 *  `outputs_rejected`: reason `not_declared`, "outputs: this module declares
 *  no outputs" (turning on a module that records nothing; turning it off
 *  answers 0), or reason `run_in_progress`, "outputs: recording cannot
 *  change during a run" (a change while a batch or a stream, from
 *  #strategy_stream_begin to #strategy_stream_end, is running). As with
 *  #strategy_set_trace_enabled, a success leaves #strategy_get_last_error
 *  and its code as they were; a refusal keeps a failed run's own. */
PF_API int strategy_outputs_set_enabled(pf_strategy_t s, int on);
/** Series slots per row; 0 while recording is off. */
PF_API int strategy_outputs_series_count(pf_strategy_t s);
/** Rows recorded: one per bar the module published this run. A module that
 *  opens at most one row per calculation, as a generated one does, never
 *  records more than #strategy_script_bars_processed. */
PF_API int64_t strategy_outputs_bars_len(pf_strategy_t s);
/** Copy the open and close times (Unix ms) of rows from @p from_bar on.
 *  Requires 0 <= @p from_bar <= rows, @p capacity >= 0 and @p written; either
 *  array may be NULL. Writes min(capacity, rows - from_bar) items, sets
 *  *written to that count and returns 0; otherwise -1 and nothing written. */
PF_API int strategy_outputs_bar_times_copy(pf_strategy_t s, int64_t from_bar,
                                           int64_t* open_ms, int64_t* close_ms,
                                           int64_t capacity, int64_t* written);
/** Copy one slot's values (NaN = na) of rows from @p from_bar on, as
 *  #strategy_outputs_bar_times_copy does; @p out is required when
 *  @p capacity > 0, and @p series must be below the series count. */
PF_API int strategy_outputs_series_copy(pf_strategy_t s, int series, int64_t from_bar,
                                        double* out, int64_t capacity, int64_t* written);
/** Events queued since the run began or since the last clear. */
PF_API int strategy_outputs_events_len(pf_strategy_t s);
/** Copy event @p index into @p out: min(@p size_in, sizeof(pf_output_event_v1_t))
 *  bytes, so an older or newer caller's struct works. Returns 0, or -1 with
 *  nothing written for an index out of range, a NULL @p out, or a @p size_in
 *  below the 8 bytes of struct_version and size. */
PF_API int strategy_outputs_event_get(pf_strategy_t s, int index, void* out, size_t size_in);
/** Drop the queued events, in every mode; rows and the sequence are kept. A
 *  streaming caller clears after #strategy_stream_begin and after each input
 *  it has read; a batch caller need not clear. */
PF_API void strategy_outputs_events_clear(pf_strategy_t s);
/** Copy the run constants (NaN = na, or not written this run) into @p out:
 *  the first min(@p capacity, n) of them. Returns n, the declared count (0
 *  while recording is off), or -1 for @p capacity < 0 or a NULL @p out with
 *  @p capacity > 0. */
PF_API int strategy_outputs_constants_copy(pf_strategy_t s, double* out, int capacity);
 
#ifndef PINEFORGE_NO_STRATEGY_DECLS
/** Part A: #PF_OUTPUTS_API_VERSION. Present only in a module that records. */
PF_API uint32_t strategy_outputs_api_version(void);
/** Part A: the module's outputs manifest, canonical JSON
 *  (`pineforge-outputs-manifest/v1`): what every output, slot and constant
 *  means. The buffer and status protocol of #strategy_capabilities_receipt. */
PF_API int strategy_outputs_manifest(pf_strategy_t s, char* json, size_t capacity,
                                     size_t* required, char* error,
                                     size_t error_capacity);
/** Part A: the module's signal-safety receipt, canonical JSON
 *  (`pineforge-signal-safety/v1`), per output. The protocol of
 *  #strategy_capabilities_receipt. */
PF_API int strategy_signal_safety_receipt(pf_strategy_t s, char* json, size_t capacity,
                                          size_t* required, char* error,
                                          size_t error_capacity);
#endif
 
/** @} */ /* end of pf_outputs */
 
/** Feature probe for the borrowed symbol-feed setter. */
#define PINEFORGE_HAS_SYMBOL_FEED_BORROWED_V1 1
/** Install another symbol's bars without copying them. The caller keeps both
 *  arrays alive until the feed is replaced or cleared, or #strategy_free.
 *  Validation and return values match #strategy_set_symbol_feed. Historical
 *  runs only: stream_begin() fails closed while a symbol feed is installed. */
PF_API int strategy_set_symbol_feed_borrowed_v1(
    pf_strategy_t s, const char* key, const char* timeframe,
    const pf_bar_t* bars, const int64_t* close_ms, int n);
 
/** Exact C++ engine layout accepted by the live report accumulator.
 *  Bump whenever that layout changes, independently of #PF_ABI_VERSION. */
#define PF_STREAM_ENGINE_LAYOUT_VERSION 4u
 
/** Optional module declaration that its strategy handles point directly to
 *  a BacktestEngine with the returned #PF_STREAM_ENGINE_LAYOUT_VERSION.
 *  The engine runtime exports this with its streaming implementation.
 *  Modules with opaque or wrapped handles must omit it or return 0.
 *  Absence or 0 requires using #strategy_stream_fill_report. A nonzero
 *  different version is refused by the native runner before strategy creation;
 *  rebuild the module with the exact paired engine. Stream ABI and
 *  execution-capabilities versions alone do not prove layout.
 *  This query reads no strategy state and changes no report or hash. */
PF_API uint32_t strategy_stream_engine_layout_version(void);
 
/** Set this module's creation-time recorded-series limit on the calling thread.
 *  Call before strategy_create/strategy_create_checked (or C++ construction):
 *  the base engine snapshots it before the derived constructor declares.
 *  NULL or 0 means unlimited, the default. A non-NULL positive int64 is the
 *  operator's maximum.
 *  Returns a pf_settings_status_t; negative values return
 *  #PF_SETTINGS_INVALID_ARGUMENT without changing the previous setting.
 *  Errors follow the checked-settings buffer protocol. Success also clears
 *  the typed declaration refusal read by #pf_output_series_limit_failure.
 *  The host must restore NULL after its factory call; existing hosts retain
 *  their snapshot. Different threads have independent defaults and refusals. */
PF_API int pf_output_series_limit_set_checked(const int64_t* maximum,
                                             char* error, size_t error_capacity);
/** Read an outputs_limit / too_many_series declaration refusal even when a
 *  factory returned NULL. Returns 1 and writes the positive operator maximum
 *  from the refused setting (NULL or 0 selects unlimited), 0 when no refusal
 *  has occurred since the last successful setter (leaving the destination
 *  unchanged), or -1 for NULL. Query on the creation thread before restoring
 *  the default. No exception or allocation crosses the ABI. */
PF_API int pf_output_series_limit_failure(int64_t* maximum);
 
/** Set this module's map-pair creation policy on the calling thread.
 *  Call before strategy_create/strategy_create_checked (or C++ construction).
 *  NULL or 0 means unlimited, the default. A positive value is the maximum
 *  number of distinct pairs in EACH map; replacement never consumes a pair.
 *  Each host captures the policy and installs it during script preparation
 *  and callbacks, including maps first created on a later bar. Each map then
 *  retains its own limit through copy, clear and rollback.
 *  Restore NULL after the factory call; existing hosts keep their policy.
 *  Returns a pf_settings_status_t and follows the checked-settings buffer
 *  protocol. A negative maximum returns #PF_SETTINGS_INVALID_ARGUMENT
 *  atomically. A refused put raises RE10070 with maxSize/currSize/bar_index
 *  through the pine_map_capacity_exceeded run-failure catalog entry. */
PF_API int pf_map_pairs_limit_set_checked(const int64_t* maximum,
                                         char* error, size_t error_capacity);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
/* The C-level native host API (the versioned C host API). Included last, after the PODs
 * it builds on (pf_bar_t, pf_report_t, pf_strategy_t) and outside this
 * header's `extern "C"` block, which it opens for itself. Both headers guard
 * their own include, so either include order resolves. Its PF_API symbols are
 * pinned separately by scripts/check_c_abi_runtime.py, which is why they do
 * not move this header's own declaration count. */
#include <pineforge/native_c_api.h>
 
/** Feature probe: include <pineforge/report_sink.h> for the additive sink ABI. */
#define PINEFORGE_HAS_REPORT_SINK_V1 1
 
#endif /* PINEFORGE_H */