You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e963e5e
Browse filesBrowse the repository at this point in the historyBrowse files
report: fail with report_result_invalid when a report metric overflows; short-span annualised metrics are a defined absence with a named reason (CR-202)
Squash of cx/metrics-overflow-v3 on engine main 0212cab (merged with it without conflict; the one file both touch is docs/pages/native-engine.md, in disjoint hunks). Its single parent is engine main, as the GitHub squash writes it.
What changes
- A report metric whose computed value overflows (buy_hold_return, every other report metric) fails the run with the typed failure report_result_invalid, reason nonfinite, instead of writing null.
- Revision 3.1 (docs/design/selected-window-wire-v1.3-revision-3.1.md, docs/pages/report-schema.md): cagr, calmar, sharpe_bar and sortino_bar are annualised from the measured span. Under one day (0 < span_ms < 86 400 000, span from the equity-curve point times, UTC epoch milliseconds, script-bar open clock) each is a defined absence: null on the public report with the reason span_too_short_to_annualize at diagnostics.annualization.<field>, outside the 135 digest leaves. At or above one day an overflow stays the typed failure. The policy list is docker/report_annualization.def, read by the kernel, and a copy in docker/run_json.py held equal by a test.
- C host (src/native_c_host.cpp): a report failure after a completed run is recorded and returns E_STATE, a report failure after an earlier latched failure returns E_RUN_FAILED with that failure; in both the caller's report struct is defined (zeroed local report freed on a throw) instead of half written.
- The native runner keeps its own report format: undefined metrics stay the string "NaN" (runner/README.md); only an infinite value is the typed failure there.
- Disclosed behaviour: an infinite first-open or last-close price and a non-finite selected anchor are now report_result_invalid (feed admission makes the first unreachable).
- kNeutralReportDigest in tests/test_native_anchored_legs.cpp is 8139101939074791901 (was 17583267501122239024): the lab harvest of the neutral 15 one-minute bar run, whose cagr, sharpe_bar and sortino_bar become absent on its 14-minute span. Source: lab job rj-20261020t003449-511ce1 (label cr202-v4b-harvest-22b20449), release step log line 2527 "neutral report digest 8139101939074791901, pinned 17583267501122239024"; fixture authority for exactly that printed value was given by CORE-TOP on 2026-10-20 08:20. That test was the only failure of that release run (99% tests passed, 1 tests failed out of 962).
Documentation sentences reworded or replaced by this change, each named for scripts/check_doc_reverts.py (the sentence's introducing commit, then its first words):
- 1bd075c (Trading metrics + equity curve in backtest report, #31): "See the per-field doxygen in `<pineforge/pineforge.h>` for the exact rule on every field." in docs/pages/report-schema.md, now "in `<pineforge/pineforge.h>` for the existing field domains; the rule below is authoritative for the sub-day case".
- 1b08c61 (EN-133, #384): "net_pnl, avg_trade, best_trade, worst_trade and max_drawdown, must be finite or the run fails with report_result_invalid, field naming the corresponding trades.<leaf> or summary.<leaf> and reason equal to nonfinite." in docs/pages/report-schema.md, extended with win_rate_pct and the equity-curve equity and open_profit leaves.
- 5691220 (ADR-0001 rewritten against HEAD): "compute_equity_stats answers its all-NaN value with no error" in docs/adr/0001-kernel-adapter-boundary.md, now "answers its defined empty-curve metrics with no error".
- 375795a (shard the ownership manifest-controls test, CR-196): "(9, 9, 9 and 8 for shards 1 to 4 of 4: 8, 8, 8 and 7 cases plus the guard)" and "The separate cheap test_shards_partition_every_case_exactly_once guard runs in every shard" in tests/ownership/README.md, now "(10, 10, 10 and 10 for shards 1 to 4 of 4: 9 cases plus the guard in each)" and "Each shard also runs the cheap test_shards_partition_every_case_exactly_once guard".
- file:line citation digits only, wording kept: ADR-0001 (the "inclusive bar metrics" bullet, the "Reporting." bullet, the strategy_configure_native_v1 row, the magnifier_sub_bars_total row), native-feature-parity rows RP2, RP4, S1b and "A zoned chart-day memo", native-refactor-progress (the quiet-bar cost check and the every_gate_is_taken_both_ways citation), native-engine ("MUST mirror" citation of compute_equity_stats).
Documentation sentences the history of this branch introduced and later reworded or removed (none of them is deleted by this squash against main):
- c9ba507 introduced "Report arithmetic that produces a nonfinite value, including overflow, fails with `report_result_invalid` and reason `nonfinite`." in docs/pages/report-schema.md.
- c9ba507 introduced "The engine checks computed values before they can become a metric absence." in docs/pages/report-schema.md.
- eba8561 (revision 3.1) introduced "The constant policy list is in `docker/report_annualization.def`, shared by the native metric walk and public report writer." in docs/design/selected-window-wire-v1.3-revision-3.1.md.
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
`KernelRecordedAtHostMarks` records the same series at the host's own marks.
182
182
`report_open_position_at_end` books the still-open position as a mark-to-market row under
183
183
`KernelRecorded`. Under `HostRecorded` an unrecorded curve still degenerates —
184
-
`compute_equity_stats` answers its all-NaN value with no error (`src/engine_metrics.cpp:203`,
185
-
consumed by `fill_metrics_section`, `src/engine_report.cpp:138-145`) — which is why the policy exists.
184
+
`compute_equity_stats` answers its defined empty-curve metrics with no error (`src/engine_metrics.cpp:228`,
185
+
consumed by `fill_metrics_section`, `src/engine_report.cpp:205`) — which is why the policy exists.
186
186
-**Reproducibility.** Two digests, one wrapping the other. `native_continuation_hash()`
187
187
(`native_host.hpp:1376`) returns the consumer's event/continuation hash. **A digest names
188
188
the run's inputs** (rule 2): the timezone identity enters it as the zone's *content* —
@@ -761,10 +761,10 @@ number names its symbol on this tree.
761
761
|`NativeReportPolicy::KernelRecordedAtHostMarks` (`native_run_spec.hpp:64`) |**C++-only** (lane E22's ruling, restated) | Under it the host names each report point from inside its own callbacks, and the C table has no call that marks one: a C host could only declare a series nobody records. `pf_native_report_policy_e` (`native_c_api.h:661`) leaves its value unnamed, and the enum guard holds that exclusion. A C++ host now reaches the same kernel producer through `NativeStrategyHost::mark_native_report_point`; a mark outside a running HostMarks run returns false. |
762
762
|`strategy_set_path_order` (`pineforge.h:948`) clamps an out-of-range mode to AUTO |**retained**| A `void` ABI v4 setter cannot answer a refusal. Its values are now documented as `pf_native_path_order_e`'s (`native_c_api.h:904`); a C host that wants an unknown word refused declares `path_order` in `pf_native_run_spec_ext_v1`, which answers `PF_NATIVE_E_TAG`. |
763
763
| the enumerated `int32` fields of `pf_pending_order_v1_t` (`strategy_pending_order_get``pineforge.h:1096`) |**no C names in the header; generator-owned**| The mirror is generated from the Pine source host's resting-order record by `scripts/gen_pending_order_mirror.py` (held by its `--check` source guard) and self-described at run time by `strategy_pending_order_layout`. Its enumerated fields are the source layer's order vocabulary, not a kernel enumeration. A C name for them belongs in that generator, which owns the struct, so that it cannot drift from the mirror — never hand-written beside it. |
764
-
|`strategy_configure_native_v1` (`c_abi.cpp:980`) versus `strategy_configure_native_ext_result_v1` (`native_c_host.cpp:4066`) |**retained legacy base plus typed additive route**| A base specification the kernel rejects still returns `-1` and latches `Failed`, preserving its frozen caller contract; a Ready misuse retains that Contract latch. The C boundary refuses arguments, a Running phase and a Completed hash hook without entering kernel configure, so a read cannot reconfigure its host. The extended result call validates before its first configure, writes `pf_native_spec_error_t` / `pf_native_spec_field_t`, and names reused-host session-key and run-number refusals; no old signature or layout moved. |
764
+
|`strategy_configure_native_v1` (`c_abi.cpp:980`) versus `strategy_configure_native_ext_result_v1` (`native_c_host.cpp:4107`) |**retained legacy base plus typed additive route**| A base specification the kernel rejects still returns `-1` and latches `Failed`, preserving its frozen caller contract; a Ready misuse retains that Contract latch. The C boundary refuses arguments, a Running phase and a Completed hash hook without entering kernel configure, so a read cannot reconfigure its host. The extended result call validates before its first configure, writes `pf_native_spec_error_t` / `pf_native_spec_field_t`, and names reused-host session-key and run-number refusals; no old signature or layout moved. |
765
765
|`strategy_configure_native_fx_curve_v1` (`pineforge.h:546`) |**typed additive route**|`strategy_configure_native_fx_curve_ext_v1` writes the C twin of `NativeFxCurveValidation` and its offending index. The old `-1` route remains unchanged, while a C caller can now distinguish a decreasing timestamp, non-positive rate, allocation failure or wrong phase. |
766
766
|`on_native_timeframe_bar` (`native_host.hpp:885`) and `NativeTimeframeBarContext::interval` (`native_host.hpp:809`) |**query routed**| The callback signature stays frozen. `strategy_native_timeframe_bar_interval_v1` is valid only during that callback and copies the kernel calendar interval without deriving it from the delivered bar or delivery timestamp. |
767
-
|`magnifier_sub_bars_total` / `magnifier_sample_ticks_total` (`engine_report.cpp:75-76`) |**kernel-owned report facts**| The generic intrabar driver already increments `NativeDriverStatistics::sub_bars_processed` / `sample_ticks_processed` for every retained path (`native_execution_consumer.cpp:8681-8693`); the kernel now publishes those same counters for bare hosts. They are report fields, not new durable state: the existing `native_continuation_hash` fold of `NativeDriverStatistics` (`native_execution_consumer.cpp:1125-1130`) sees the same values, so no hash contract moves. |
767
+
|`magnifier_sub_bars_total` / `magnifier_sample_ticks_total` (`engine_report.cpp:77-78`) |**kernel-owned report facts**| The generic intrabar driver already increments `NativeDriverStatistics::sub_bars_processed` / `sample_ticks_processed` for every retained path (`native_execution_consumer.cpp:8681-8693`); the kernel now publishes those same counters for bare hosts. They are report fields, not new durable state: the existing `native_continuation_hash` fold of `NativeDriverStatistics` (`native_execution_consumer.cpp:1125-1130`) sees the same values, so no hash contract moves. |
768
768
|`pf_native_lot_excursion_v1` (`native_c_api.h:1912`) |**additive fee tail**|`entry_commission` carries the C++ `ClosedLotExcursionFacts::entry_commission` in account currency. The callback table publishes a trailing layout marker so F4 callers still receive the base facts length; current callers receive the fee tail without changing `PF_NATIVE_API_VERSION`. |
769
769
|`strategy_outputs_set_enabled` and the eight `strategy_outputs_*` readers (`pineforge.h`, group `pf_outputs`) |**additive runtime exports**| Recording is off by default, and nothing a run computes reads the record. The event copy is size-prefixed like `strategy_pending_order_get`, and `PF_ABI_VERSION` stays 4. The writers are C++ only in this version (the BASE-CLASS SEAMS rows of `native_c_api.h`): a C host declares no outputs, so its handle answers every reader as empty. |
0 commit comments