Skip to content

Commit 44bb687

Browse files
luisleo526claude
andcommitted
Native calculation timing: recalculate on fills and at every modeled point, partial-bar view, open-only bar view (R5 lane L5)
native_run_spec_v3: NativeCalculationTrigger { BarClose (default), BarCloseAndFills, EveryModeledPoint }, max_recalculations_per_point, and NativeOpenBarView { Complete (default), OpenOnly } — folded into the continuation hash only when not default. engine_script_run_v18: every calculation is routed through on_native_recalculate(bar, ctx, reason, cause), whose default forwards to on_native_bar; on_native_sub_bar fires after each lower-timeframe sub-bar's path; current_partial_bar() gives the O/H/L/C/volume up to the cursor. Chronology contract: match and settle -> on_native_applied FIFO -> (BarCloseAndFills) one recalculation at the fill cursor from the existing notification drain under its re-entrancy guard, bounded per point; requests born in callbacks follow the existing birth rule (born_on_remaining_path untouched); EveryModeledPoint recalculates at each magnifier sample / observed print in batch and stream. Recalculations add no report points. Pine's COOF scheduler and language-state rollback stay in the adapter, which is untouched. Tests: tests/test_native_calc_timing.cpp (BarClose default pinned, fill cascade with the bound, every-modeled-point in batch/intrabar/stream, sub-bar hook, OpenOnly view, no extra report points, twin against the adapter's calc_on_order_fills path). ci_verify release PASS (499). Design: docs/design/native-feature-parity.md A.4. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01CSmYixVAp4NqWpBZxkrLPT (cherry picked from commit dc59f8639a0610f713a18add011a01d1a2588fbf)
1 parent 9ae173d commit 44bb687

12 files changed

Lines changed: 1583 additions & 22 deletions

‎docs/pages/abi-stability.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -121,17 +121,22 @@ private consumer to `engine_script_run_v17`; R5 L6 advances the same three to
121121
`engine_script_run_v18` for the native higher-timeframe host surface
122122
(`on_native_timeframe_bar`, `native_series_bar`), joined by R5 L4's margin
123123
surface (`resolve_margin_call_units`, `on_native_margin_call`,
124-
`native_liquidation_price`), and the host capability macro
124+
`native_liquidation_price`) and R5 L5's calculation-timing surface
125+
(`on_native_recalculate`, `on_native_sub_bar`, `current_partial_bar`), and the
126+
host capability macro
125127
is `PINEFORGE_HAS_NATIVE_STRATEGY_HOST_V18`. L3b removes the source compatibility
126128
order type; `pineforge-source-adapter/v2` hashes adapter and scheduler state
127129
instead. Native request/core/event values are `native_order_v6`, the private
128130
consumer identity is
129131
`native-consumer/v7`, driver types are `native_driver_v5`, and run specs are
130-
`native_run_spec_v3` (R5 L6 adds `NativeRunSpec::subscriptions` and R5 L4 adds
131-
`NativeRunSpec::margin`, each folded into the continuation hash only when it is
132-
set). R5 L4 also adds `RequestDefinition::origin` and the `MarginCallEvent`
133-
alternative to `native_order_v6`; `RequestOrigin::Host` — every host request —
134-
folds nothing, so no established continuation hash moves.
132+
`native_run_spec_v3` (R5 L6 adds `NativeRunSpec::subscriptions`, folded into
133+
the continuation hash only when it is non-empty; R5 L4 adds
134+
`NativeRunSpec::margin`, folded only when it is set; R5 L5 adds `calculation`,
135+
`max_recalculations_per_point` and `open_bar_view`, folded only once the
136+
trigger or the open-bar view is non-default). R5 L4 also adds
137+
`RequestDefinition::origin` and the `MarginCallEvent` alternative to
138+
`native_order_v6`; `RequestOrigin::Host` — every host request — folds nothing,
139+
so no established continuation hash moves.
135140

136141
| Matrix role | Internal identity |
137142
| --- | --- |

‎docs/pages/native-engine.md‎

Lines changed: 133 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,10 @@ Always set, with documented defaults in the header:
139139
- `report_policy`: `HostRecorded` (default) or `KernelRecorded`;
140140
`report_open_position_at_end`: `false` (default). See *Reporting for native
141141
hosts* below.
142+
- `calculation`: `BarClose` (default), `BarCloseAndFills` or
143+
`EveryModeledPoint`; `max_recalculations_per_point`: `8` (default, any
144+
value including 0 is legal); `open_bar_view`: `Complete` (default) or
145+
`OpenOnly`. See *Calculation timing* below.
142146

143147
Optional, absent unless set:
144148

@@ -578,6 +582,128 @@ its 4× shortfall default, its one-contract long money call and its
578582
adverse-extreme fill pricing stay in the Pine adapter, which never sets
579583
`margin`.
580584

585+
## Calculation timing
586+
587+
`NativeRunSpec::calculation` decides when the kernel asks the host to
588+
calculate. It is `NativeCalculationTrigger::BarClose` by default, which is the
589+
established surface exactly: one calculation per script bar, at its close. The
590+
source layer never sets this field, so Pine-compatible runs are unchanged, and
591+
the spec folds the block into the continuation hash only once the trigger or
592+
the open-bar view is non-default.
593+
594+
Every calculation — including the script bar's own — is delivered through
595+
596+
```cpp
597+
virtual void on_native_recalculate(const Bar& bar, const NativeDecisionContext& ctx,
598+
NativeCalculationReason reason,
599+
const native_order::ExecutionAppliedEvent* cause);
600+
```
601+
602+
whose default forwards to `on_native_bar(bar, ctx)`. A host that implements
603+
only `on_native_bar` therefore sees precisely what it saw before this field
604+
existed. `NativeCalculationReason` is `BarClose` (the script bar's own
605+
calculation, `cause == nullptr`), `OrderFill` (one recalculation at an applied
606+
execution's cursor, `cause` being that event, valid only for the call),
607+
`Tick` (one recalculation at a modeled point or an observed print) and
608+
`SubBar`, which is reserved: a lower-timeframe sub-bar has its own hook and is
609+
never delivered through `on_native_recalculate`.
610+
611+
The triggers are a strict superset chain, so opting in never removes a
612+
calculation:
613+
614+
- `BarClose` (default): the script bar's calculation only.
615+
- `BarCloseAndFills`: additionally one `OrderFill` recalculation per applied
616+
execution (Pine's `calc_on_order_fills`, without its TradingView specifics).
617+
- `EveryModeledPoint`: additionally one `Tick` recalculation at every modeled
618+
point of the delivered path — each confirmed OHLC waypoint, each intrabar
619+
sample — and at every observed print, in batch and in a stream alike
620+
(Pine's `calc_on_every_tick`, generically).
621+
622+
### Chronology contract
623+
624+
At **one** point, in this order and no other:
625+
626+
1. Match and settle.
627+
2. `on_native_applied` for each applied event, FIFO, through the existing
628+
notification drain under its re-entrancy guard.
629+
3. With `BarCloseAndFills` or `EveryModeledPoint`, one `OrderFill`
630+
recalculation at that event's own cursor, immediately after its
631+
`on_native_applied`, driven from the same drain. It is bounded by
632+
`max_recalculations_per_point` (default 8) **per matching point**:
633+
executions a callback drives through `execute_current` land at the same
634+
cursor and spend the same budget, so a host that refills on its own fill
635+
cannot cascade without end. Beyond the bound the execution is still
636+
applied and still delivered to `on_native_applied`; only the calculation
637+
it would have driven is dropped. `native_recalculation_count()` and
638+
`native_recalculations_skipped()` report both totals.
639+
4. With `EveryModeledPoint`, one `Tick` recalculation after the point's
640+
matching is finished. `on_native_tick` stays the observation hook and
641+
still runs **before** the print is matched.
642+
643+
A request born in any of these callbacks follows the existing birth rule
644+
unchanged: it is eligible on the unconsumed rest of the bar, which for a
645+
market request means the next discrete matching point. Nothing about the
646+
drain order, the birth rule or language-state rollback moves — the kernel
647+
never attempts rollback; that stays a source-layer concern.
648+
649+
A recalculation records **no** report point. Under
650+
`NativeReportPolicy::KernelRecorded` the equity curve still has exactly one
651+
point per script bar whatever the trigger is.
652+
653+
### Sub-bars
654+
655+
```cpp
656+
virtual void on_native_sub_bar(const Bar& sub, const NativeDecisionContext& ctx);
657+
```
658+
659+
fires once after each retained lower-timeframe sub-bar's whole matching path,
660+
before the next sub-bar's. It is not a cadence: it fires whatever
661+
`calculation` is. It requires a real lower feed
662+
(`IntrabarPath::lower_tf`) — a synthesized path and a plain confirmed bar have
663+
no sub-bars of their own, so it never fires for them. The decision point is
664+
the sub-bar's last modeled point, so commands and `execute_current` are legal
665+
and a request born there follows the ordinary birth rule.
666+
667+
### The bar so far, and the open-bar view
668+
669+
```cpp
670+
std::optional<Bar> current_partial_bar() const; // non-virtual
671+
```
672+
673+
answers the lookahead-free bar so far at the current cursor: the open of this
674+
script bar's first modeled point, the running high/low, and the close at the
675+
cursor. `volume` accrues only activity actually consumed — the completed
676+
lower-timeframe sub-bars of an intrabar path, or the observed prints of a
677+
stream — and stays 0 for a modeled path that carries no intrabar volume of its
678+
own. It is valid in the bar-open, applied, tick, sub-bar and recalculation
679+
callbacks, and is `nullopt` outside a path walk, including in the bar's own
680+
close calculation, where the host already holds the complete bar.
681+
682+
This matters because the mid-bar callbacks are handed the **complete** script
683+
bar: `on_native_bar_open` receives the whole bar by default, and so does every
684+
`OrderFill` / batch `Tick` recalculation. That is deliberate — a host that
685+
schedules against the bar's own high/low needs it, and the adapter relies on
686+
it — but it is lookahead. `current_partial_bar()` is the answer for a host
687+
that must not see it.
688+
689+
`NativeRunSpec::open_bar_view` masks exactly one callback:
690+
`NativeOpenBarView::OpenOnly` hands `on_native_bar_open` (and `current_bar_`
691+
while it runs) `H = L = C = open` and volume 0. `Complete` (default) is
692+
unchanged. The mask is presentation only: the complete bar is restored before
693+
the open match, so matching, fills, excursions and every later callback are
694+
byte-for-byte what `Complete` books.
695+
696+
### What stays in the source layer
697+
698+
TradingView's COOF specifics are **not** reproduced here (design ruling R5-5):
699+
the waypoint-only refill, the two-fills-at-open rule, the script-state
700+
snapshot/restore and the adapter's own cascade guard and deferral queue all
701+
remain in `src/source`. A native `BarCloseAndFills` host running the adapter's
702+
refill rule reaches the same book with the same order ids in the same order,
703+
but the coordinates a request born in a recalculation fills at differ: the
704+
adapter re-presents it at the chart bar's next waypoint, the kernel at the
705+
next discrete matching point of the delivered path.
706+
581707
## One physical book
582708

583709
There is one engine lot/account book. Native matching inspects settlement,
@@ -767,7 +893,9 @@ auxiliary-symbol feed and no chart-slice mapping.
767893
Two driver models only: confirmed OHLCV and observed ticks. Mixing them on
768894
one stream is refused. The script-bar **calculation** callback is
769895
`on_native_bar`, one per completed script bucket; the opening, tick and
770-
post-fill hooks fire in addition to it, not instead of it.
896+
post-fill hooks fire in addition to it, not instead of it. Calculation is
897+
**close-only** unless the spec asks otherwise; see *Calculation timing* above
898+
for `BarCloseAndFills` and `EveryModeledPoint`.
771899
772900
Confirmed OHLC retains the modeled **Opening**, high/low in the existing
773901
AUTO order, close, calculation and optional AfterCalculation close sequence.
@@ -809,8 +937,10 @@ These are existing refusals, not implied future features:
809937
- Source `calc_on_every_tick` / `calc_on_order_fills` enabled (the runner
810938
rejects an explicit true override, and the Pine host refuses a stream begin
811939
with `calc_on_order_fills`, `pine_strategy_host.cpp:266-269`). This is a
812-
limit on the *source* calculation policies, not on the native hooks:
813-
`on_native_tick` and `on_native_applied` are delivered on a stream.
940+
**source-route** refusal, not a limit on the native hooks: `on_native_tick`
941+
and `on_native_applied` are delivered on a stream, and a native host's own
942+
`NativeRunSpec::calculation` is accepted there, where `EveryModeledPoint`
943+
recalculates per observed print
814944
- A nonempty staged native FX curve on `stream_begin`; batch runs may use one.
815945
- Auxiliary/native security feeds, source magnifier/tail/probe/hash/trace
816946
setters, `set_input`, and Pine

‎include/pineforge/native_host.hpp‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -460,6 +460,24 @@ struct NativeTimeframeBarContext {
460460
std::int64_t delivered_at_ms = 0;
461461
};
462462

463+
// Why the kernel is asking the host to calculate. BarClose is the script
464+
// bar's own calculation and is delivered for every run, whatever the spec's
465+
// NativeCalculationTrigger is: every calculation is routed through
466+
// on_native_recalculate, whose default forwards to on_native_bar, so a host
467+
// that only implements on_native_bar sees exactly what it saw before.
468+
// OrderFill is one recalculation at the cursor of an applied execution
469+
// (NativeCalculationTrigger::BarCloseAndFills and above) and carries that
470+
// event as its cause. Tick is one recalculation at a modeled path point or
471+
// an observed print (NativeCalculationTrigger::EveryModeledPoint). SubBar is
472+
// reserved: a lower-timeframe sub-bar has its own hook, on_native_sub_bar,
473+
// and is never delivered through on_native_recalculate.
474+
enum class NativeCalculationReason : std::uint8_t {
475+
BarClose = 0,
476+
OrderFill = 1,
477+
Tick = 2,
478+
SubBar = 3,
479+
};
480+
463481
// Most-derived native strategy host. Binds NativeExecutionConsumer in the
464482
// protected engine constructor. Noncopyable and nonmovable. Lives in the
465483
// same inline engine epoch as BacktestEngine so old-header/new-library
@@ -498,6 +516,43 @@ class NativeStrategyHost : public BacktestEngine {
498516
// returns, before the consumer advances beyond this calculation point.
499517
virtual void on_native_bar(const Bar& bar, const NativeDecisionContext& context) = 0;
500518

519+
// EVERY calculation of the run arrives here first, including the script
520+
// bar's own close calculation (reason BarClose, cause nullptr), whose
521+
// default forwarding keeps on_native_bar the complete contract for a host
522+
// that never opts into another cadence.
523+
//
524+
// reason OrderFill: one recalculation at an applied execution's cursor,
525+
// driven from the applied-notification drain after that event's
526+
// on_native_applied and bounded by
527+
// NativeRunSpec::max_recalculations_per_point. `cause` is that event and
528+
// is valid only for this call. reason Tick: one recalculation at a
529+
// modeled path point or an observed print, with a null cause.
530+
//
531+
// `bar` is the bar the calculation is about: the script bar under
532+
// delivery in batch, the print's value bar for a stream Tick. It is the
533+
// COMPLETE script bar even mid-path; current_partial_bar() is the
534+
// lookahead-free bar so far at this cursor. Commands and
535+
// execute_current are legal here exactly as in on_native_applied.
536+
virtual void on_native_recalculate(const Bar& bar, const NativeDecisionContext& ctx,
537+
NativeCalculationReason reason,
538+
const native_order::ExecutionAppliedEvent* cause) {
539+
(void)reason;
540+
(void)cause;
541+
on_native_bar(bar, ctx);
542+
}
543+
544+
// One completed lower-timeframe sub-bar of an IntrabarPath::lower_tf
545+
// path, delivered after that sub-bar's whole matching path and before the
546+
// next sub-bar's. Never called for a run without a retained lower feed:
547+
// a synthesized path and a plain confirmed bar have no sub-bars of their
548+
// own. The decision point is the sub-bar's last modeled point, so
549+
// commands and execute_current are legal and a request born here follows
550+
// the ordinary birth rule.
551+
virtual void on_native_sub_bar(const Bar& sub, const NativeDecisionContext& ctx) {
552+
(void)sub;
553+
(void)ctx;
554+
}
555+
501556
virtual void on_native_applied(const native_order::ExecutionAppliedEvent&,
502557
const NativeDecisionContext&) {}
503558

@@ -534,6 +589,22 @@ class NativeStrategyHost : public BacktestEngine {
534589
return {};
535590
}
536591

592+
// The bar so far at the current cursor, folded from the modeled points
593+
// this script bar has already presented: open of its first point,
594+
// running high/low, close at the cursor. Volume is the activity actually
595+
// consumed so far — the completed lower-timeframe sub-bars of an
596+
// intrabar path, or the prints of an observed stream — and stays 0 for a
597+
// modeled path with no intrabar volume of its own. Valid in the bar-open,
598+
// applied, tick, sub-bar and recalculation callbacks; nullopt outside a
599+
// path walk, including in the bar's own close calculation, where the host
600+
// already holds the complete bar.
601+
std::optional<Bar> current_partial_bar() const;
602+
// How many recalculations the kernel has driven this run, and how many it
603+
// suppressed because a point had already spent its
604+
// max_recalculations_per_point budget. Observation only.
605+
std::uint64_t native_recalculation_count() const;
606+
std::uint64_t native_recalculations_skipped() const;
607+
537608
std::optional<NativeCurrentPointView> current_execution_point() const;
538609
std::optional<NativeTrailState> trail_state(
539610
const native_order::RequestHandle& target) const;

‎include/pineforge/native_run_spec.hpp‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,39 @@ enum class NativeOpenDirections : std::uint32_t {
5454
Both = 3,
5555
};
5656

57+
// When the kernel asks the host to calculate. BarClose is the whole default
58+
// surface: exactly one calculation per script bar, at its close, which is
59+
// what every host that drives its own cadence already gets. The other two
60+
// are a strict superset of the one before them, so a host never loses the
61+
// close calculation by opting in.
62+
//
63+
// BarCloseAndFills additionally recalculates once at the cursor of each
64+
// applied execution, from the existing applied-notification drain and
65+
// bounded by max_recalculations_per_point. EveryModeledPoint additionally
66+
// recalculates at every modeled point of the delivered path (each confirmed
67+
// OHLC waypoint, each intrabar sample) and at every observed print.
68+
//
69+
// This is a generic cadence, not a source-language policy: TradingView's
70+
// waypoint-only COOF refill, its two-fills-at-open rule and its script-state
71+
// rollback stay in the source layer, which never sets this field.
72+
enum class NativeCalculationTrigger : std::uint32_t {
73+
BarClose = 0,
74+
BarCloseAndFills = 1,
75+
EveryModeledPoint = 2,
76+
};
77+
78+
// What a bar-open callback is handed. Complete keeps the established view:
79+
// on_native_bar_open receives the whole script bar, which is what a host that
80+
// schedules against the bar's own high/low needs. OpenOnly masks that
81+
// lookahead for hosts that must decide at the open with open-only
82+
// information: H = L = C = open and volume 0. It changes no matching, no
83+
// fill and no other callback; mid-bar callbacks answer current_partial_bar()
84+
// for the lookahead-free bar so far.
85+
enum class NativeOpenBarView : std::uint32_t {
86+
Complete = 0,
87+
OpenOnly = 1,
88+
};
89+
5790
// A generic instrument price grid. The kernel otherwise treats price_tick as
5891
// the slippage multiplier only, so an unset grid leaves every booked price
5992
// exactly as the path presented it. QuantizeFills books the fill on the tick
@@ -299,6 +332,19 @@ struct NativeRunSpec {
299332
// book, the realized sums and every hash are left exactly as the run left
300333
// them. Inert under HostRecorded, whose host owns the whole report series.
301334
bool report_open_position_at_end = false;
335+
// Calculation timing. BarClose is the established cadence and the whole
336+
// default surface; the other triggers only add calculations, never move
337+
// or remove one. max_recalculations_per_point bounds the fill cascade at
338+
// one matching point: further executions at that point are still applied
339+
// and still delivered to on_native_applied, they just stop driving a new
340+
// calculation. Zero is a legal bound and means "deliver, never
341+
// recalculate". All three fold into the continuation hash only once the
342+
// trigger or the open-bar view is non-default, so a spec that leaves the
343+
// cadence alone keeps the continuation identity it had before these
344+
// fields existed.
345+
NativeCalculationTrigger calculation = NativeCalculationTrigger::BarClose;
346+
std::uint32_t max_recalculations_per_point = 8;
347+
NativeOpenBarView open_bar_view = NativeOpenBarView::Complete;
302348
IntrabarPath intrabar{};
303349
// Declared higher-timeframe series. Empty is the whole default surface:
304350
// no evaluator is registered, no feed is prepared, and the run spec's
@@ -324,6 +370,7 @@ enum class NativeRunSpecField : std::uint8_t {
324370
SubscriptionTimeframe, SubscriptionBars,
325371
MarginModel, MarginInitial, MarginMaintenance, MarginSizing,
326372
MarginShortfallMultiple, MarginMinUnits, MarginCheck,
373+
Calculation, OpenBarView,
327374
};
328375

329376
enum class NativeRunSpecError : std::uint8_t {
@@ -374,6 +421,9 @@ enum class NativeRunSpecError : std::uint8_t {
374421
MarginModelConflict,
375422
UnknownLiquidationSizing,
376423
UnknownLiquidationCheck,
424+
// A calculation trigger / open-bar view outside its enumeration.
425+
UnknownCalculationTrigger,
426+
UnknownOpenBarView,
377427
};
378428

379429
// Allocation-free facts suitable for the host's durable failure variant.

0 commit comments

Comments
 (0)