#include <stdint.h>
#include <stddef.h>
#include <pineforge/version.h>
#include <pineforge/pending_order_mirror.hpp>
#include <pineforge/native_c_api.h>

Include dependency graph for pineforge.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	pf_bar_t
	Single OHLCV bar pushed into the engine. More...

struct	pf_trade_tick_t
	One provider-neutral realtime executed-trade update. More...

struct	pf_trade_t
	Closed-trade record returned in pf_report_t::trades. More...

struct	pf_trade_stats_t
	Trade-level statistics block — computed once each for all / long / short. More...

struct	pf_equity_stats_t
	Equity-curve-derived statistics (all-trades only, like TV). More...

struct	pf_metrics_t
	Composite metrics container: trade stats (all / long / short) + equity-curve stats. More...

struct	pf_equity_point_t
	Single per-script-bar equity point. More...

struct	pf_security_diag_t
	Per-`request.security()` site diagnostic counters. More...

struct	pf_trace_entry_t
	Single per-bar trace entry. More...

struct	pf_report_t
	Backtest report filled by run_backtest / run_backtest_full. More...

struct	pf_native_run_spec_v1
	Versioned native run specification. More...

struct	pf_native_fx_curve_v1
	Immutable timestamped account-currency FX curve for a native run. More...

struct	pf_stream_order_action_t
	One physical emulator lot action. More...

struct	pf_cache_policy_entry_v1
	One optional resident cache size. More...

struct	pf_cache_policy_v1
	Versioned resident cache policy. More...

struct	pf_scratch_tables_v1
	Version 1 scratch-table admission maxima, in keys/rows and key bytes. More...

struct	pf_version_t
	Runtime version descriptor returned by pf_version_get. More...

struct	pf_output_event_v1_t
	One recorded event, copied by strategy_outputs_event_get. More...

Macros
#define	PF_STATIC_ASSERT(condition)

#define	PF_API

#define	PF_ABI_VERSION 5
	Monotonic strategy-module compatibility version.

#define	PINEFORGE_HAS_AUX_SECURITY_FEED_V1 1
	Feature probe for the opt-in split chart/request.security feed boundary.

#define	PINEFORGE_HAS_NATIVE_SECURITY_FEED_V1 1
	Feature probe for native higher-timeframe request.security feeds.

#define	PINEFORGE_HAS_NATIVE_FX_CURVE_V1 1
	Feature probe for immutable native-run account-currency FX curves.

#define	PINEFORGE_HAS_SCRATCH_TABLES_V1 1

#define	PINEFORGE_HAS_CACHE_POLICY_V1 1

#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

#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.

#define	PINEFORGE_HAS_SYMBOL_FEED_V1 1
	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.

#define	PINEFORGE_HAS_SYMBOL_FEED_COLUMN_V1 1
	Feature probe for strategy_set_symbol_feed_column.

#define	PINEFORGE_HAS_SYMBOL_FACTS_V1 1
	Feature probe for strategy_set_symbol_facts.

#define	PINEFORGE_HAS_RECORDED_SERIES_V1 1
	Feature probe for strategy_set_recorded_series.

#define	PINEFORGE_HAS_RUN_FAILURE_CODES_V1 1
	Compile-time probe for the two run-failure code getters below (and the generated-code helpers of `<pineforge/run_failure.hpp>`).

#define	PF_SETTINGS_API_VERSION 1u
	Current generated-strategy settings extension version.

#define	PF_CAPABILITIES_API_VERSION 1u
	Current compiled-strategy execution-capabilities extension version.

#define	PINEFORGE_HAS_OUTPUTS_V1 1
	Present in a pineforge.h that declares the group.

#define	PF_OUTPUTS_API_VERSION 1u
	What strategy_outputs_api_version answers.

#define	PINEFORGE_HAS_SYMBOL_FEED_BORROWED_V1 1
	Feature probe for the borrowed symbol-feed setter.

#define	PF_STREAM_ENGINE_LAYOUT_VERSION 2u
	Exact C++ engine layout accepted by the live report accumulator.

#define	PINEFORGE_HAS_REPORT_SINK_V1 1
	Feature probe: include <pineforge/report_sink.h> for the additive sink ABI.

Typedefs
typedef void *	pf_strategy_t
	Opaque handle to a compiled strategy instance.

typedef uint32_t	pf_cache_kind_t
	Append-only cache-kind vocabulary.

typedef int32_t	pf_state_query_status_v1_t
	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.

Enumerations
enum	pf_magnifier_distribution_t { PF_MAGNIFIER_UNIFORM = 0 , PF_MAGNIFIER_COSINE = 1 , PF_MAGNIFIER_TRIANGLE = 2 , PF_MAGNIFIER_ENDPOINTS = 3 , PF_MAGNIFIER_FRONT_LOADED = 4 , PF_MAGNIFIER_BACK_LOADED = 5 }
	Bar-magnifier sub-bar sampling distribution. More...

enum	pf_execution_contract_t { PF_EXECUTION_CONTRACT_LEGACY = 1 , PF_EXECUTION_CONTRACT_NATIVE_MARKET_V1 = 2 }
	What strategy_execution_contract answers for a valid handle. More...

enum	pf_native_spec_optional_t { PF_NATIVE_SPEC_OPTIONAL_QUANTITY_GRID = 1u << 0 , PF_NATIVE_SPEC_OPTIONAL_MAX_ABS_UNITS = 1u << 1 , PF_NATIVE_SPEC_OPTIONAL_INITIAL_MARGIN_FRACTION = 1u << 2 , PF_NATIVE_SPEC_OPTIONAL_MAX_OPEN_LOTS = 1u << 3 }
	The bits of pf_native_run_spec_v1::optional_mask: each names the one optional field it makes meaningful. More...

enum	pf_native_fx_curve_error_t { 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 }
	Why a native FX curve was refused — the C twin of `pineforge::NativeFxCurveError`. More...

enum	pf_scratch_table_backend_t { PF_SCRATCH_TABLE_DISK_SCRATCH = 0 , PF_SCRATCH_TABLE_BOUNDED_MEMORY = 1 }
	Storage policy for the nine historical scratch-table regions. More...

enum	pf_fill_qty_partition_t { PF_FILL_QTY_PARTITION_EXIT = -1 , 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 }
	Which sizing rule strategy_pending_order_fill_qty's quantity came from, written to its `partition` out-parameter; each value is documented there. More...

enum	pf_close_cause_t { PF_CLOSE_CAUSE_UNSPECIFIED = 0 , PF_CLOSE_CAUSE_SCRIPT = 1 , PF_CLOSE_CAUSE_BRACKET = 2 , PF_CLOSE_CAUSE_LIQUIDATION = 3 , PF_CLOSE_CAUSE_RISK_LIMIT = 4 , PF_CLOSE_CAUSE_FILL_CAP = 5 , PF_CLOSE_CAUSE_RANGE_END = 6 }
	Why a closed report row exited — `execution::CloseCause`, the value strategy_closed_trade_close_cause answers for a valid row. More...

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 }
	Status codes for the opt-in generated-strategy settings extension. More...

enum	pf_output_phase_t { PF_OUTPUT_PHASE_BATCH = 0 , PF_OUTPUT_PHASE_WARMUP = 1 , PF_OUTPUT_PHASE_REALTIME = 2 }
	The run phase an event was recorded in. More...

Functions
int	strategy_execution_contract (pf_strategy_t s)
	Native execution contract query: a pf_execution_contract_t, or -1 for a NULL handle.

int	strategy_configure_native_v1 (pf_strategy_t s, const pf_native_run_spec_v1 *spec)
	Apply a native v1 specification.

	PF_STATIC_ASSERT (sizeof(pf_native_fx_curve_error_t)==4)

int	strategy_configure_native_fx_curve_v1 (pf_strategy_t s, const pf_native_fx_curve_v1 *curve)
	Stage an immutable account-currency FX curve on a Ready native handle.

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)
	Typed additive spelling of strategy_configure_native_fx_curve_v1.

pf_strategy_t	strategy_create (const char *params_json)
	Allocate a new strategy instance.

void	strategy_free (pf_strategy_t s)
	Release a strategy handle previously returned by strategy_create.

void	run_backtest (pf_strategy_t s, pf_bar_t bars, int n, pf_report_t out)
	Run a backtest with auto-detected timeframe and no bar magnifier.

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)
	Run a backtest with explicit timeframe and magnifier configuration.

void	report_free (pf_report_t *report)
	Free heap arrays attached to a filled report.

void	strategy_set_input (pf_strategy_t s, const char key, const char value)
	Override a Pine `input`.

void	strategy_set_override (pf_strategy_t s, const char key, const char value)
	Override a `strategy(...)` declaration parameter.

void	strategy_set_magnifier_volume_weighted (pf_strategy_t s, int on)
	Toggle volume-weighted bar-magnifier sampling.

int	strategy_declares_bar_magnifier (void)
	Report the script's `strategy(..., use_bar_magnifier = true)` declaration.

void	strategy_set_trace_enabled (pf_strategy_t s, int on)
	Toggle per-bar trace recording.

void	strategy_set_trade_start_time (pf_strategy_t s, int64_t timestamp_ms)
	Set the earliest Unix-ms timestamp at which strategy order commands may fire.

int	pf_report_scratch_arena_stats (uint64_t high_water_bytes, uint64_t arena_bytes)
	Read process-wide scratch-arena diagnostics, outside canonical report bytes.

int	pf_report_cache_stats (pf_strategy_t s, uint64_t resident_bytes, uint64_t allocation_bypass_count)
	Read the handle's admitted-run command-cache and trade-ledger diagnostics.

int	strategy_require_report_scratch_arena_v1 (pf_strategy_t s)
	Admit a jailed handle only with an attached scratch arena.

int	strategy_report_sink_diagnostics_v1 (pf_strategy_t s, struct pf_report_sink_diagnostics_v1 *out)
	Read bounded sink provenance without reading the sink or replaying rows.

int	pf_run_abort_install_sigterm_v1 (void)
	Install the invocation's cooperative SIGTERM handler.

int	pf_run_abort_requested_v1 (void)
	Read the invocation stop flag: 0 or 1.

int	pf_run_abort_restore_sigterm_v1 (void)
	Restore the disposition saved by pf_run_abort_install_sigterm_v1.

uint64_t	strategy_closed_trade_entry_incarnation (pf_strategy_t s, int trade_index)
	Return the physical entry incarnation for one closed-trade row.

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)
	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.

int	strategy_stream_api_version (void)
	Native live extension version (1).

int	strategy_stream_push_bar (pf_strategy_t s, const pf_bar_t *bar)
	Consume one confirmed input-timeframe bar.

int	strategy_stream_order_actions_len (pf_strategy_t s)
	Queued physical fills since the last clear, in execution order.

int	strategy_stream_order_action_get (pf_strategy_t s, int index, pf_stream_order_action_t *out)
	Copy one action; return 0 on success, -1 on invalid handle/index/output.

void	strategy_stream_order_actions_clear (pf_strategy_t s)
	Clear observed events after the caller durably journals them.

uint64_t	strategy_stream_state_hash (pf_strategy_t s)
	Versioned deterministic fingerprint of observable broker/stream state.

int	strategy_stream_push_tick (pf_strategy_t s, const pf_trade_tick_t *tick)
	Push one normalized realtime trade.

int	strategy_stream_push_ticks (pf_strategy_t s, const pf_trade_tick_t *ticks, int n)
	Push an ordered batch of realtime trades.

int	strategy_stream_advance_time (pf_strategy_t s, int64_t timestamp_ms)
	Advance the stream clock and close every input bar whose end is <= the supplied time.

int	strategy_stream_end (pf_strategy_t s, int finalize_partial_input_bar)
	End a realtime stream.

int	strategy_stream_fill_report (pf_strategy_t s, pf_report_t *out)
	Snapshot the cumulative warmup + realtime report.

int	strategy_set_cache_policy_v1 (pf_strategy_t s, const pf_cache_policy_v1 *policy)
	Copy cache settings before run admission; NULL restores internal defaults.

int	strategy_set_scratch_tables_v1 (pf_strategy_t s, const pf_scratch_tables_v1 *config)
	Copy scratch-table configuration while idle; NULL restores disk defaults.

void	strategy_request_abort (pf_strategy_t s)
	Request cooperative abort of the run in progress (see c_abi.cpp).

int	strategy_last_run_status (pf_strategy_t s)
	0 = completed, 1 = NOT_COMPLETED (aborted), -1 = `s` is NULL.

void	strategy_set_realtime_tail (pf_strategy_t s, int on, int horizon_bars)
	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.

void	strategy_set_probe_suppress_tail_logic (pf_strategy_t s, int on)
	Live probe tail suppression (spec §3.2): the LAST script bar of the array fed to every subsequent run() is matched but not calculated.

void	strategy_set_path_order (pf_strategy_t s, int mode)
	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.

int	strategy_last_bar_dual_entry_path (pf_strategy_t s)
	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.

void	strategy_set_broker_state_hash_recording (pf_strategy_t s, int on)
	Toggle per-report-point broker-state hash recording (spec §3.4, ABI v4).

uint64_t	strategy_broker_state_hash (pf_strategy_t s)
	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).

pf_state_query_status_v1_t	strategy_state_query_status_v1 (pf_strategy_t s)
	The current eligibility of BOTH strategy_broker_state_hash and strategy_stream_state_hash on `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 `s`.

int	strategy_pending_orders_len (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.

int	strategy_pending_order_get (pf_strategy_t s, int index, void *out, size_t size_in)
	Copy the `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 `out` as a pf_pending_order_v1_t value snapshot.

const pf_field_desc_t *	strategy_pending_order_layout (int *count)
	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`.

int	strategy_pending_order_fill_qty (pf_strategy_t s, int index, double fill_price, double qty, int close_only, int *partition)
	Engine-computed fill quantity of the `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 `fill_price`, sized by the engine's own rules so a live runtime never re-implements them.

int	strategy_pending_order_level_resolved (pf_strategy_t s, int index)
	1 when the `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.

int	strategy_pending_order_effective_levels (pf_strategy_t s, int index, double stop, double limit, double *trail_activation)
	The price levels the `index-th` resting order would fire at, as the engine's fill path resolves them (ABI v4, task 8).

double	strategy_trail_best_price (pf_strategy_t s)
	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).

double	strategy_position_avg_price (pf_strategy_t s)
	The live position's volume-weighted average entry price (`position_entry_price_`).

int64_t	strategy_position_cycle_seq (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.

const char *	strategy_closed_trade_entry_id (pf_strategy_t s, int trade_index)
	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`).

const char *	strategy_closed_trade_exit_id (pf_strategy_t s, int trade_index)
	See strategy_closed_trade_entry_id for the row-space/lifetime/NULL contract.

const char *	strategy_closed_trade_exit_comment (pf_strategy_t s, int trade_index)
	See strategy_closed_trade_entry_id.

int	strategy_closed_trade_close_cause (pf_strategy_t s, int trade_index)
	Task 9: why the `trade_index-th` REPORT-row closed trade exited, a pf_close_cause_t.

double	strategy_position_size (pf_strategy_t s)
	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).

double	strategy_current_equity (pf_strategy_t s)
	Task 9: initial capital plus realized net profit (`strategy.initial_capital + strategy.netprofit`).

double	strategy_initial_capital (pf_strategy_t s)
	ABI v4 live-runtime surface (1.8.0): the configured run's initial capital, before realized or open profit.

double	strategy_net_profit_sum (pf_strategy_t s)
	Raw whole-lot realized P&L, excluding initial capital and report-only terminal rows.

double	strategy_report_pointvalue (pf_strategy_t s)
	Effective symbol pointvalue used by the engine report.

int	strategy_set_report_replay_v1 (pf_strategy_t s, const char path, const char run_id)
	Opt in to the separate pf-report-replay/v1 companion before a run.

int64_t	strategy_script_bars_processed (pf_strategy_t s)
	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.

void	strategy_set_chart_timezone (pf_strategy_t s, const char *tz)
	Set the strategy's chart timezone (IANA / POSIX TZ string).

void	strategy_set_syminfo_timezone (pf_strategy_t s, const char *tz)
	Plumb the symbol's exchange timezone (IANA string) into syminfo.

void	strategy_set_syminfo_session (pf_strategy_t s, const char *session)
	Set the symbol's session string (e.g.

void	strategy_set_syminfo_type (pf_strategy_t s, const char *type)
	Set the instrument class (`syminfo.type`: "forex", "stock", "crypto", "futures", "index", "fund", "cfd", ...; default "crypto").

int	strategy_set_syminfo_string (pf_strategy_t s, const char key, const char value)
	Set one of the remaining string members of `syminfo` by Pine member name: "ticker", "tickerid", "currency", "basecurrency", "description", "volumetype" (and "type").

void	strategy_set_syminfo_mintick (pf_strategy_t s, double mintick)
	Set the instrument tick size (`syminfo.mintick`, default 0.01).

void	strategy_set_syminfo_pointvalue (pf_strategy_t s, double pointvalue)
	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.

void	strategy_set_syminfo_metadata (pf_strategy_t s, const char *key, double value)
	Inject a fundamental/exchange metadata value by Pine member name (e.g.

int	strategy_set_account_currency_fx_series (pf_strategy_t s, const int64_t effective_from_ms, const double account_per_quote, int n)
	Install a timestamped quote-to-account currency conversion curve.

int	strategy_set_aux_security_feed (pf_strategy_t s, const pf_bar_t bars, int n, const char input_tf)
	Copy a finer feed used exclusively by same-symbol request.security calls.

int	strategy_set_native_security_feed (pf_strategy_t s, const char timeframe, const pf_bar_t bars, int n)
	Copy the exchange's OWN bars of one higher timeframe for same-symbol request.security calls that request exactly that timeframe.

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)
	Copy another symbol's own bars of one timeframe, keyed by the exact symbol string a request site passes at run time (`key`) and by `timeframe` ("15", "60", "1D", ...; "D" and "1D" are one key).

int	strategy_set_symbol_feed_column (pf_strategy_t s, const char key, const char timeframe, const char name, const double values, int n)
	Copy one named column of an installed symbol feed: `n` values, one per bar of the feed of (`key`, `timeframe`), in bar order (a footprint delta, `"fp_delta_100_70"`).

int	strategy_set_symbol_facts (pf_strategy_t s, const char key, const char field, const char *value)
	Set one fact of the symbol a request site names by `key:` `field` is one of `"canonical"`, `"valid"` (`"true"` / `"false"`), `"type"`, `"timezone"`, `"session"`, `"currency"` or `"mintick"` (a positive decimal).

int	strategy_set_recorded_series (pf_strategy_t s, const char key, const int64_t chart_open_ms, const double *values, int n)
	Copy a recorded request series: the values a request returned on the chart bars that opened at `chart_open_ms` (strictly increasing), keyed by the request key a generated strategy reads it under.

const char *	strategy_get_last_error (pf_strategy_t s)
	Returns the error message captured by the most recent run_backtest / run_backtest_full call on this strategy.

const char *	strategy_get_last_error_code (pf_strategy_t s)
	Stable code of the most recent failure on `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.

const char *	strategy_get_last_error_args (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.

pf_version_t	pf_version_get (void)

int	pf_abi_version (void)

const char *	pf_version_string (void)
	Full version descriptor, the `PINEFORGE_VERSION_FULL` of the generated `pineforge/version.h`.

uint32_t	strategy_settings_api_version (void)
	Generated-strategy settings extension version (currently 1).

uint32_t	strategy_capabilities_api_version (void)
	Compiled execution-capabilities extension version (currently 1).

int	strategy_capabilities_receipt (pf_strategy_t s, char json, size_t capacity, size_t required, char *error, size_t error_capacity)
	Read immutable canonical JSON describing compiled execution declarations and analyzed request/data requirements, never inferred from runtime state.

int	strategy_create_checked (const char params_json, pf_strategy_t out, char *error, size_t error_capacity)
	Allocate a strategy without allowing any exception across the C boundary.

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 declared input before execution.

int	strategy_set_override_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.

int	strategy_get_effective_settings (pf_strategy_t s, char json, size_t capacity, size_t required, char *error, size_t error_capacity)
	Read a deterministic UTF-8 JSON receipt of effective settings.

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)
	Exception-contained counterpart of run_backtest_full.

	PF_STATIC_ASSERT (sizeof(pf_output_phase_t)==4)

int	strategy_outputs_set_enabled (pf_strategy_t s, int on)
	Turn recording on (`on` nonzero) or off.

int	strategy_outputs_series_count (pf_strategy_t s)
	Series slots per row; 0 while recording is off.

int64_t	strategy_outputs_bars_len (pf_strategy_t s)
	Rows recorded: one per bar the module published this run.

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 the open and close times (Unix ms) of rows from `from_bar` on.

int	strategy_outputs_series_copy (pf_strategy_t s, int series, int64_t from_bar, double out, int64_t capacity, int64_t written)
	Copy one slot's values (NaN = na) of rows from `from_bar` on, as strategy_outputs_bar_times_copy does; `out` is required when `capacity` > 0, and `series` must be below the series count.

int	strategy_outputs_events_len (pf_strategy_t s)
	Events queued since the run began or since the last clear.

int	strategy_outputs_event_get (pf_strategy_t s, int index, void *out, size_t size_in)
	Copy event `index` into `out:` min(`size_in`, sizeof(pf_output_event_v1_t)) bytes, so an older or newer caller's struct works.

void	strategy_outputs_events_clear (pf_strategy_t s)
	Drop the queued events, in every mode; rows and the sequence are kept.

int	strategy_outputs_constants_copy (pf_strategy_t s, double *out, int capacity)
	Copy the run constants (NaN = na, or not written this run) into `out:` the first min(`capacity`, n) of them.

uint32_t	strategy_outputs_api_version (void)
	Part A: PF_OUTPUTS_API_VERSION.

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 outputs manifest, canonical JSON (`pineforge-outputs-manifest/v1`): what every output, slot and constant means.

int	strategy_signal_safety_receipt (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.

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)
	Install another symbol's bars without copying them.

uint32_t	strategy_stream_engine_layout_version (void)
	Optional module declaration that its strategy handles point directly to a BacktestEngine with the returned PF_STREAM_ENGINE_LAYOUT_VERSION.

int	pf_output_series_limit_set_checked (const int64_t maximum, char error, size_t error_capacity)
	Set this module's creation-time recorded-series limit on the calling thread.

int	pf_output_series_limit_failure (int64_t *maximum)
	Read an outputs_limit / too_many_series declaration refusal even when a factory returned NULL.

Macro Definition Documentation

◆ PF_STATIC_ASSERT

#define PF_STATIC_ASSERT ( condition )

Value:

static_assert((condition), #condition)

Definition at line 52 of file pineforge.h.

◆ PF_API

#define PF_API

Definition at line 83 of file pineforge.h.

◆ PF_ABI_VERSION

#define PF_ABI_VERSION 5

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.

Definition at line 99 of file pineforge.h.

◆ PINEFORGE_HAS_AUX_SECURITY_FEED_V1

#define PINEFORGE_HAS_AUX_SECURITY_FEED_V1 1

Feature probe for the opt-in split chart/request.security feed boundary.

When defined, strategy_set_aux_security_feed is available.

Definition at line 103 of file pineforge.h.

◆ PINEFORGE_HAS_NATIVE_SECURITY_FEED_V1

#define PINEFORGE_HAS_NATIVE_SECURITY_FEED_V1 1

Feature probe for native higher-timeframe request.security feeds.

When defined, strategy_set_native_security_feed is available.

Definition at line 107 of file pineforge.h.

◆ PINEFORGE_HAS_NATIVE_FX_CURVE_V1

#define PINEFORGE_HAS_NATIVE_FX_CURVE_V1 1

Feature probe for immutable native-run account-currency FX curves.

When defined, strategy_configure_native_fx_curve_v1 is available.

Definition at line 111 of file pineforge.h.

◆ PINEFORGE_HAS_SYMBOL_FEED_BORROWED_V1

#define PINEFORGE_HAS_SYMBOL_FEED_BORROWED_V1 1

Feature probe for the borrowed symbol-feed setter.

Definition at line 2107 of file pineforge.h.

◆ PF_STREAM_ENGINE_LAYOUT_VERSION

#define PF_STREAM_ENGINE_LAYOUT_VERSION 2u

Exact C++ engine layout accepted by the live report accumulator.

Bump whenever that layout changes, independently of PF_ABI_VERSION.

Definition at line 2118 of file pineforge.h.

◆ PINEFORGE_HAS_REPORT_SINK_V1

#define PINEFORGE_HAS_REPORT_SINK_V1 1

Feature probe: include <pineforge/report_sink.h> for the additive sink ABI.

Definition at line 2163 of file pineforge.h.

Typedef Documentation

◆ pf_strategy_t

typedef void* pf_strategy_t

Opaque handle to a compiled strategy instance.

Definition at line 441 of file pineforge.h.

Function Documentation

◆ strategy_settings_api_version()

uint32_t strategy_settings_api_version ( void )

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.

References PF_API.

◆ strategy_capabilities_api_version()

uint32_t strategy_capabilities_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.

References PF_API.

◆ strategy_capabilities_receipt()

int strategy_capabilities_receipt	(	pf_strategy_t	s,
		char *	json,
		size_t	capacity,
		size_t *	required,
		char *	error,
		size_t	error_capacity )

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: required includes the NUL, NULL/0 queries return PF_SETTINGS_BUFFER_TOO_SMALL, and no partial JSON is returned. s and 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.

References PF_API.

◆ strategy_create_checked()

int strategy_create_checked	(	const char *	params_json,
		pf_strategy_t *	out,
		char *	error,
		size_t	error_capacity )

Allocate a strategy without allowing any exception across the C boundary.

params_json is reserved: pass NULL or an empty string. Nonempty values are refused, unlike the legacy factory which ignores them. 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.

References PF_API.

◆ strategy_set_input_checked()

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 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.

References PF_API.

◆ strategy_set_override_checked()

int strategy_set_override_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.

References PF_API.

◆ strategy_get_effective_settings()

int strategy_get_effective_settings	(	pf_strategy_t	s,
		char *	json,
		size_t	capacity,
		size_t *	required,
		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. required is required and receives the byte count INCLUDING the NUL. Pass NULL/0 for 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.

References PF_API.

◆ run_backtest_full_checked()

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 )

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 out to zero and release any populated arrays with report_free, including after a failed call.

References PF_API.

◆ strategy_set_symbol_feed_borrowed_v1()

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 )

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.

References PF_API.

◆ strategy_stream_engine_layout_version()

uint32_t strategy_stream_engine_layout_version ( void )

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 a different version requires using strategy_stream_fill_report; stream ABI and execution-capabilities versions alone do not prove layout. This query reads no strategy state and changes no report or hash.

References PF_API.

◆ pf_output_series_limit_set_checked()

int pf_output_series_limit_set_checked	(	const int64_t *	maximum,
		char *	error,
		size_t	error_capacity )

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.

References PF_API.

◆ pf_output_series_limit_failure()

int pf_output_series_limit_failure ( int64_t * maximum )

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.

References PF_API.

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ PF_STATIC_ASSERT

◆ PF_API

◆ PF_ABI_VERSION

◆ PINEFORGE_HAS_AUX_SECURITY_FEED_V1

◆ PINEFORGE_HAS_NATIVE_SECURITY_FEED_V1

◆ PINEFORGE_HAS_NATIVE_FX_CURVE_V1

◆ PINEFORGE_HAS_SYMBOL_FEED_BORROWED_V1

◆ PF_STREAM_ENGINE_LAYOUT_VERSION

◆ PINEFORGE_HAS_REPORT_SINK_V1

Typedef Documentation

◆ pf_strategy_t

Function Documentation

◆ strategy_settings_api_version()

◆ strategy_capabilities_api_version()

◆ strategy_capabilities_receipt()

◆ strategy_create_checked()

◆ strategy_set_input_checked()

◆ strategy_set_override_checked()

◆ strategy_get_effective_settings()

◆ run_backtest_full_checked()

◆ strategy_set_symbol_feed_borrowed_v1()

◆ strategy_stream_engine_layout_version()

◆ pf_output_series_limit_set_checked()

◆ pf_output_series_limit_failure()