|
PineForge v0.13.1-379-g9b50973
Deterministic PineScript v6 backtest runtime — C ABI reference
|
Data Structures | |
| struct | IntrabarPath |
| An owned lower-timeframe execution path. More... | |
| struct | NativeAuxiliaryFeed |
| An auxiliary feed of the run's OWN symbol at a timeframe strictly finer than the input: the bars the input feed does not have. More... | |
| struct | NativeLossLimit |
| One risk threshold (L9). More... | |
| struct | NativeMarginModel |
| A generic per-side broker margin model (L4). More... | |
| struct | NativeRiskLimits |
Generic account risk limits (L9), entirely opt-in: a spec that leaves NativeRunSpec::risk unset evaluates nothing, appends no event and folds nothing into the continuation digest. More... | |
| struct | NativeRunSpec |
| One complete setup value, staged/copied by NativeStrategyHost before it is applied at begin. More... | |
| struct | NativeRunSpecValidation |
| Allocation-free facts suitable for the host's durable failure variant. More... | |
| struct | NativeTimeframeSubscription |
Typedefs | |
| using | NativeLegacyTolerance = NativeFeedTolerance |
| Deprecated spelling of the tolerance type. | |
Functions | |
| constexpr bool | native_feed_tolerance_enabled (NativeFeedTolerance enabled, NativeFeedTolerance requested) noexcept |
| Whether one NativeFeedTolerance bit is set in a run's mask. | |
| constexpr bool | native_legacy_tolerance_enabled (NativeFeedTolerance enabled, NativeFeedTolerance requested) noexcept |
| Deprecated spelling of native_feed_tolerance_enabled. | |
| NativeRunSpecValidation | validate_native_run_spec (const NativeRunSpec &spec) noexcept |
| Complete validation, with deterministic first-error field order. | |
| NativeRunSpecValidation | normalize_native_run_spec (NativeRunSpec &spec) noexcept |
| Validate the WHOLE value first, then canonicalize its admitted numeric negative zero (fee_value) to positive zero. | |
| NativeRunSpecValidation | validate_native_timeframe_subscriptions (const std::vector< NativeTimeframeSubscription > &subscriptions, const std::string &input_tf, bool timeframe_undetected) noexcept |
| Exactly the part of validate_native_run_spec that judges declared higher-timeframe series, against a stated input timeframe: the pairing rule (as script_tf pairs, never strictly finer), the literals, the order of any authoritative bars, the one conflicting-feed refusal, and the undetected-timeframe rule. | |
| NativeRunSpecValidation | validate_native_timeframe_subscriptions (const std::vector< NativeTimeframeSubscription > &subscriptions, const std::string &input_tf, bool timeframe_undetected, const std::optional< NativeAuxiliaryFeed > &auxiliary_feed) noexcept |
| The same judgement for a run that declares an auxiliary feed: the feed is judged first (validate_native_auxiliary_feed), then every series, a series built from the feed pairing with the FEED's timeframe. | |
| NativeRunSpecValidation | validate_native_auxiliary_feed (const std::optional< NativeAuxiliaryFeed > &auxiliary_feed, const std::string &input_tf, bool timeframe_undetected) noexcept |
| Exactly the part of validate_native_run_spec that judges the auxiliary feed, against a stated input timeframe: the literal, the strictly-finer pairing under the input, the order and structure of its bars, and the undetected-timeframe rule. | |
| std::uint64_t | native_intrabar_path_digest (const IntrabarPath &path) noexcept |
| Exact FNV-1a content digest for a retained intrabar path. | |
| std::uint64_t | native_timeframe_subscriptions_digest (const std::vector< NativeTimeframeSubscription > &subscriptions) noexcept |
| Exact FNV-1a content digest for the declared higher-timeframe series. | |
| std::uint64_t | native_auxiliary_feed_digest (const NativeAuxiliaryFeed &feed) noexcept |
| Exact FNV-1a content digest for the declared auxiliary feed: its timeframe literal and every bar in caller order, so a continuation cannot silently reuse another begin's feed. | |
| std::uint64_t | native_run_spec_digest (const NativeRunSpec &spec) noexcept |
| Machine-independent digest of a run spec: exactly the fields the consumer folds into the continuation identity for the spec, and nothing else — no timezone resources, no session identity beyond the spec's own. | |
| std::uint64_t | native_margin_model_digest (const NativeMarginModel &margin) noexcept |
| Exact FNV-1a content digest for the generic margin model. | |
| std::uint64_t | native_risk_limits_digest (const NativeRiskLimits &risk) noexcept |
| Exact FNV-1a content digest for the generic risk limits. | |
Deprecated spelling of the tolerance type.
Same type, same values, same hash; kept so existing hosts and the source adapter compile unchanged.
Definition at line 356 of file native_run_spec.hpp.
|
strong |
Encodings coincide with the versioned native-v1 C transport.
These values describe native execution; they do not configure source strategy policies.
| Enumerator | |
|---|---|
| Percent | |
| CashPerUnit | |
| CashPerExecution | |
Definition at line 19 of file native_run_spec.hpp.
|
strong |
When a request born at a script calculation may first match.
NextEligiblePoint (the default) waits for a later eligible matching point — the next modeled opening, an observed print, or a carried open — and never fills on the bar's already presented open/high/low/close. AfterCalculation additionally offers a modeled close point after that calculation, still obeying the birth ordinal and floor; it is not a replay of observed prints. The Pine adapter projects process_orders_on_close onto AfterCalculation. Pinned by tests/test_native_resting_driver_contract.cpp.
| Enumerator | |
|---|---|
| NextEligiblePoint | |
| AfterCalculation | |
Definition at line 33 of file native_run_spec.hpp.
|
strong |
Abort presentation is a run-level policy rather than an exception-path convention.
Generic hosts retain an error diagnostic by default; a host that models cooperative cancellation can opt into a quiet status result.
| Enumerator | |
|---|---|
| Error | |
| Quiet | |
Definition at line 41 of file native_run_spec.hpp.
|
strong |
Who records the per-script-bar report series.
HostRecorded leaves the equity curve, its metrics and any range-end row entirely to the host, which is what every host that drives its own recording already does. KernelRecorded asks the consumer to mark one equity point per script calculation, so a bare host gets a truthful curve, finite drawdown/run-up metrics and a report whose walk is not degenerate. Recording is reporting: it books no cash and places no order. KernelRecordedAtHostMarks records the very same series, at the points the host marks: a host whose report cadence is not one point per calculation — a source adapter that re-enters its script on a fill, or publishes a bar its script never calculates — keeps that cadence and still stops owning what a report point is. The consumer never records on its own initiative under it, so it leaves the continuation identity exactly where HostRecorded leaves it (see hash_spec in native_execution_consumer.cpp).
| Enumerator | |
|---|---|
| HostRecorded | |
| KernelRecorded | |
| KernelRecordedAtHostMarks | |
Definition at line 60 of file native_run_spec.hpp.
|
strong |
Which opening directions the run admits at all.
Both is the default and the whole established surface; a refused opening is MatchRejectReason::OpeningDirection, and it rejects the ENTIRE transaction, including a proposed close remainder. Closing-only reductions stay legal under None. Pinned by tests/test_native_resting_matching_contract.cpp.
| Enumerator | |
|---|---|
| None | |
| Long | |
| Short | |
| Both | |
Definition at line 71 of file native_run_spec.hpp.
|
strong |
When the kernel asks the host to calculate.
BarClose is the whole default surface: exactly one calculation per script bar, at its close, which is what every host that drives its own cadence already gets. The other two are a strict superset of the one before them, so a host never loses the close calculation by opting in.
BarCloseAndFills additionally recalculates once at the cursor of each applied execution, from the existing applied-notification drain and bounded by max_recalculations_per_point. EveryModeledPoint additionally recalculates at every modeled point of the delivered path (each confirmed OHLC waypoint, each intrabar sample) and at every observed print.
This is a generic cadence, not a source-language policy: TradingView's waypoint-only COOF refill, its two-fills-at-open rule and its script-state rollback stay in the source layer, which never sets this field.
| Enumerator | |
|---|---|
| BarClose | |
| BarCloseAndFills | |
| EveryModeledPoint | |
Definition at line 93 of file native_run_spec.hpp.
|
strong |
What a bar-open callback is handed.
Complete keeps the established view: on_native_bar_open receives the whole script bar, which is what a host that schedules against the bar's own high/low needs. OpenOnly masks that lookahead for hosts that must decide at the open with open-only information: H = L = C = open and volume 0. It changes no matching, no fill and no other callback; mid-bar callbacks answer current_partial_bar() for the lookahead-free bar so far.
| Enumerator | |
|---|---|
| Complete | |
| OpenOnly | |
Definition at line 106 of file native_run_spec.hpp.
|
strong |
A generic instrument price grid.
The kernel otherwise treats price_tick as the slippage multiplier only, so an unset grid leaves every booked price exactly as the path presented it. QuantizeFills books the fill on the tick ladder; QuantizeFillsAndTriggers additionally tests a resting trigger against the tick-quantized path. Source-language tick quirks are not spelled here: they remain source-layer policy on top of None.
| Enumerator | |
|---|---|
| None | |
| QuantizeFills | |
| QuantizeFillsAndTriggers | |
Definition at line 117 of file native_run_spec.hpp.
|
strong |
HalfUp is the nearest tick with ties away from zero.
Directional rounds toward the price region the resting order needs: a buy limit rounds down and a sell limit up, a stop the other way, which is also the adverse side of a market fill.
| Enumerator | |
|---|---|
| HalfUp | |
| Directional | |
Definition at line 127 of file native_run_spec.hpp.
|
strong |
Which units a kernel-issued liquidation reduces (L4).
RestoreMinimum is the fewest units that restore the marked equity to the maintenance requirement at the sizing mark; ShortfallMultiple books that same restore scaled by shortfall_multiple (never 4.0 by default: a broker wanting a multiple declares it); Flatten closes the whole position. A host whose slice rule is not one of these answers it through resolve_margin_call_units and declares none of them (the Pine adapter does).
| Enumerator | |
|---|---|
| RestoreMinimum | |
| ShortfallMultiple | |
| Flatten | |
Definition at line 139 of file native_run_spec.hpp.
|
strong |
When the kernel tests the maintenance requirement.
PathAdverseExtreme evaluates it against the most adverse price the remaining modeled script path still reaches and rests the reduction at the liquidation level, so the fill lands where the account actually runs out of margin. CalculationOnly tests the mark only at a script calculation point and rests nothing. PathAdverseExtremeMark is the period-mark broker: it measures the breach at that same adverse mark and rests the reduction AT THAT MARK, so the fill lands on the adverse waypoint the breach was measured at instead of on a solved level. It never solves a level, which is also what makes it the one mode that still checks where no level exists (a LONG at full maintenance — see NativeMarginModel). The resting price is the default resolved price of that fill, so resolve_execution_terms still has the last word on it.
| Enumerator | |
|---|---|
| PathAdverseExtreme | |
| CalculationOnly | |
| PathAdverseExtremeMark | |
Definition at line 157 of file native_run_spec.hpp.
|
strong |
Which equity the maintenance requirement is tested against.
MarkedEquity is the account's marked equity exactly as marked_equity() computes it: the open entries' commissions have already reduced it. MarkedEquityBeforeOpenCommission is the same mark-to-market equity taken before that reduction (initial capital + realized net profit + open profit), i.e. a broker whose margin equity does not charge the still-open entries' commission against the account. Nothing else about the account model changes: this is one term of one comparison, never a second accounting truth.
| Enumerator | |
|---|---|
| MarkedEquity | |
| MarkedEquityBeforeOpenCommission | |
Definition at line 171 of file native_run_spec.hpp.
|
strong |
Which base the liquidation level is solved from.
MarkedEquity is the intercept of marked_equity(): initial capital + realized net profit minus the open entries' commissions. RealizedOnly drops that last term, so the level is solved from initial capital + realized net profit alone. The two agree whenever no open entry has paid a commission.
| Enumerator | |
|---|---|
| MarkedEquity | |
| RealizedOnly | |
Definition at line 181 of file native_run_spec.hpp.
|
strong |
Which day a risk limit's "day" is.
SessionDay is the run's own session calendar: the trading date of the session that contains the instant (native_calendar::session_day_ordinal), so an overnight session is one day. CalendarDayInTimezone is the plain civil date in the spec's scheduling timezone, which is what a host that reports by wall-clock date wants. The two differ exactly where a session crosses midnight.
| Enumerator | |
|---|---|
| SessionDay | |
| CalendarDayInTimezone | |
Definition at line 269 of file native_run_spec.hpp.
|
strong |
What a breach does.
BlockOpenings refuses every opening while the block lasts and leaves the live book alone. FlattenAndBlock first closes the book with one kernel-originated Flatten and then blocks.
| Enumerator | |
|---|---|
| BlockOpenings | |
| FlattenAndBlock | |
Definition at line 277 of file native_run_spec.hpp.
|
strong |
Native hosts normally require every confirmed bar to name a canonical input slot.
A host whose feed carries provider labels can retain the caller's strictly-increasing timestamps as its decision labels instead. This is a feed-shape policy, not a source-language one, and it remains a run-spec value so the two modes never share a continuation.
| Enumerator | |
|---|---|
| Canonical | |
| FeedTolerant | |
| LegacyTolerant | Deprecated spelling of FeedTolerant; identical value, kept so existing hosts and the source adapter compile unchanged. |
Definition at line 323 of file native_run_spec.hpp.
|
strong |
Generic ordering for a modeled OHLC path.
Auto retains the open-proximity rule; the forced modes make the first excursion explicit for replay/live hosts without relying on process-global or source-language state.
| Enumerator | |
|---|---|
| Auto | |
| HighFirst | |
| LowFirst | |
Definition at line 334 of file native_run_spec.hpp.
|
strong |
Explicit, opt-in admission exceptions for a tolerated input-feed shape.
They are separate from slot labels because a host may need the tolerant price / unavailable-volume admission while retaining canonical calendar labels. This is a feed-shape policy, not a source-language one.
Definition at line 344 of file native_run_spec.hpp.
|
strong |
One declared higher-timeframe series of the run's own symbol, the native equivalent of request.security(syminfo.tickerid, tf, ...).
The kernel aggregates the accepted input into tf buckets and delivers each completed bucket to the host; nothing here configures a source language.
A subscription is a series INSTANCE, not a period: several may declare the same tf, each gets its own evaluator and bucket state, and each is identified — in NativeTimeframeBarContext::subscription and in native_series_bar() — by its own index in NativeRunSpec::subscriptions. The one thing same-period instances cannot each own is a different authoritative_bars feed; see DuplicateSubscriptionTimeframe.
tf must pair with NativeRunSpec::input_tf exactly as script_tf does (native_calendar::compatibility) and may not be strictly finer than the input: a lower-timeframe array is a different contract.
authoritative_bars are the exchange's own bars of that timeframe, at most one per completed bucket. When present, a completed bucket takes its OHLCV from the bar keyed to the same period, and those stamps become the period partition: the feed store is TradingView-calibrated, so "W"/"M" buckets are built from installed DAILY bars and a session with no stamp of its own folds into the next trade date's bar. A host that supplies them inherits those rules (docs/pages/native-engine.md).
lookahead is Pine's barmerge.lookahead_off (false, the default: the bucket is delivered when its last contributing input bar is accepted) or lookahead_on (true: the completed bucket's final values are delivered at its FIRST contributing input bar).
gaps is Pine's barmerge.gaps_off (false, the default: a delivered bucket stands until the next delivery replaces it) or gaps_on (true: the series is CLEARED on every accepted input that delivers no bucket of its own, so native_series_bar() answers nullopt — the empty that stands for na — on exactly the bars the series does not publish on). It changes nothing about which buckets complete, when they are delivered, or what they contain.
source names the bars the series is built from. Input (the default, and the whole surface described above) aggregates the accepted input. AuxiliaryFeed aggregates NativeRunSpec::auxiliary_feed instead — the finer bars the input does not have — so tf then pairs with the FEED's timeframe exactly as script_tf pairs with input_tf, and may be finer than the input, equal to it or coarser. See NativeAuxiliaryFeed for the routing rule.
| Enumerator | |
|---|---|
| Input | |
| AuxiliaryFeed | |
Definition at line 476 of file native_run_spec.hpp.
|
strong |
Which field a validation refused, in deterministic first-error order.
It is what lets a host report "which field" instead of "invalid"; every enumerator names a NativeRunSpec member or one of its nested blocks.
Definition at line 611 of file native_run_spec.hpp.
|
strong |
Why a field was refused.
Read it beside NativeRunSpecValidation::field: the error says what is wrong and the field says where. Each feature's own suite pins the refusals of the fields it owns — the subscription and auxiliary-feed rows in tests/test_native_auxiliary_feed.cpp, the margin rows in tests/test_native_margin_model.cpp, the risk rows in tests/test_native_risk_limits.cpp.
Definition at line 642 of file native_run_spec.hpp.
|
constexprnoexcept |
Whether one NativeFeedTolerance bit is set in a run's mask.
Prefer it to testing the bits by hand; enabled is the run's own value and requested the single bit being asked about.
Definition at line 361 of file native_run_spec.hpp.
|
constexprnoexcept |
Deprecated spelling of native_feed_tolerance_enabled.
Definition at line 368 of file native_run_spec.hpp.
|
noexcept |
Complete validation, with deterministic first-error field order.
Every string is semantic UTF-8 without embedded NUL (all cross C-string v1). Required: identity key, tickerid, scheduling timezone, and both timeframe literals unless timeframe_undetected is explicitly set. Empty chart timezone is preserved as optional observation metadata. Calendar parsing/compatibility remain in native_calendar. Batch monthly pairings are accepted here; stream-only restrictions belong to begin. Calendar parsing may allocate. Allocation/other dependency exceptions are converted into typed failure facts; the supplied spec is never changed.
|
noexcept |
Validate the WHOLE value first, then canonicalize its admitted numeric negative zero (fee_value) to positive zero.
Failure preserves every input bit/string/optional. Positive-only fields cannot admit either zero sign; price_tick admits and preserves both zero signs, and absent optionals have no payload. Literal strings/numbers are never otherwise rewritten. There is no second validated/live configuration wrapper. Host usage: copy input into a candidate, normalize candidate, then stage that same spec atomically; own copy-allocation/lifecycle failure handling.
|
noexcept |
Exactly the part of validate_native_run_spec that judges declared higher-timeframe series, against a stated input timeframe: the pairing rule (as script_tf pairs, never strictly finer), the literals, the order of any authoritative bars, the one conflicting-feed refusal, and the undetected-timeframe rule.
A host that declares its series at begin (NativeStrategyHost::declare_timeframe_subscriptions) is judged by this same function, so a list accepted there is one configure_native would also have accepted. Calendar parsing may allocate; failures are converted into typed facts and nothing is changed.
|
noexcept |
The same judgement for a run that declares an auxiliary feed: the feed is judged first (validate_native_auxiliary_feed), then every series, a series built from the feed pairing with the FEED's timeframe.
The three-argument form above is this one with no feed, where such a series is refused as SubscriptionWithoutAuxiliaryFeed.
|
noexcept |
Exactly the part of validate_native_run_spec that judges the auxiliary feed, against a stated input timeframe: the literal, the strictly-finer pairing under the input, the order and structure of its bars, and the undetected-timeframe rule.
An absent feed is always valid. A host that declares its feed at begin (NativeStrategyHost::declare_auxiliary_feed) is judged by this same function.
|
noexcept |
Exact FNV-1a content digest for a retained intrabar path.
It includes the mode, lower bars in caller order when present, and every sampling parameter, so continuation identity cannot silently reuse a path from another begin.
|
noexcept |
Exact FNV-1a content digest for the declared higher-timeframe series.
It includes each subscription's timeframe literal, publication modes and authoritative bars in caller order, so a continuation cannot silently reuse another begin's series. Callers fold it only when subscriptions is non-empty, keeping the default spec's continuation identity unchanged, and gaps folds only where a series set it, keeping every series declared before that field existed at the digest it already had. source folds the same way: only where a series left the input.
|
noexcept |
Exact FNV-1a content digest for the declared auxiliary feed: its timeframe literal and every bar in caller order, so a continuation cannot silently reuse another begin's feed.
Callers fold it only when auxiliary_feed is present, keeping the default spec's continuation identity unchanged.
|
noexcept |
Machine-independent digest of a run spec: exactly the fields the consumer folds into the continuation identity for the spec, and nothing else — no timezone resources, no session identity beyond the spec's own.
Two specs with equal digests drive identical continuation identities on every machine with the same tz resources.
It is the consumer's own spec fold (hash_spec) over a freshly seeded accumulator: the same FNV-1a offset basis continuation_hash() starts from, with nothing folded before the spec (no semantic-version markers, no state) and the relative-generation base set to spec.identity.run_number, exactly as the consumer seeds it for the run this spec describes. The folded generation distance is therefore zero and the digest is a property of the spec value alone. It is NOT a continuation hash and never comparable with one: a raw continuation hash also folds the resolved timezone resources (zoneinfo root and zone file paths), which differ per machine, so only this digest is portable enough to pin as a constant.
|
noexcept |
Exact FNV-1a content digest for the generic margin model.
It includes every per-side fraction, the liquidation policy and its parameters, so two runs that differ only in their margin model cannot share a continuation identity. Callers fold it only when margin is present, keeping the default spec's continuation identity unchanged.
|
noexcept |
Exact FNV-1a content digest for the generic risk limits.
It includes every threshold, its percent flag, the day basis and the breach action, so two runs that differ only in their risk limits cannot share a continuation identity. Callers fold it only when risk is present, keeping the default spec's continuation identity unchanged.