@@ -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
143147Optional, absent unless set:
144148
@@ -578,6 +582,128 @@ its 4× shortfall default, its one-contract long money call and its
578582adverse-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
583709There is one engine lot/account book. Native matching inspects settlement,
@@ -767,7 +893,9 @@ auxiliary-symbol feed and no chart-slice mapping.
767893Two driver models only: confirmed OHLCV and observed ticks. Mixing them on
768894one 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
772900Confirmed OHLC retains the modeled **Opening**, high/low in the existing
773901AUTO 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
0 commit comments