Skip to content

Commit ad0804f

Browse files
luisleo526claude
andcommitted
report: fail with report_result_invalid when a report metric overflows; sub-day span is a defined absence for cagr and calmar (CR-202)
Squash of cx/metrics-overflow (head d1cf661) merged with engine main da9403f: the tree is that merge. Its single parent is engine main, as the GitHub squash writes it. Report metrics that overflow (buy_hold_return, cagr and every other report metric) fail with the typed run failure report_result_invalid instead of writing null; cagr and calmar over a span under one day are a defined absence (null) with the reason in diagnostics.annualization.<field> (revision 3.1). See docs/design/selected-window-wire-v1.3-revision-3.1.md and docs/pages/report-schema.md. Documentation sentences the 38-commit history of this branch introduced and later reworded or removed, named so scripts/check_doc_reverts.py can read them (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, CR-202 fix 4) 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]>
1 parent da9403f commit ad0804f

35 files changed

Lines changed: 1810 additions & 140 deletions

‎docker/report_annualization.def‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
// Revision 3.1 policy, shared by the kernel and the public report writer.
2+
// Ship beside run_json.py, like its other companion resources.
3+
PF_ANNUALIZATION_SPAN_MS(86400000)
4+
PF_SHORT_SPAN_ANNUALIZED_FIELD(cagr)
5+
PF_SHORT_SPAN_ANNUALIZED_FIELD(calmar)

‎docker/run_json.py‎

Lines changed: 89 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@
5454
"longs": { ...pf_trade_stats_t... }, # long trades only
5555
"shorts": { ...pf_trade_stats_t... }, # short trades only
5656
"equity": { ...pf_equity_stats_t... } # sharpe/sortino/cagr/calmar/...
57-
}, # any NaN statistic -> null (see _num)
57+
}, # defined metric absence -> null (see _num)
5858
"equity_curve": [ # ABI v2: one point per script bar
5959
{ "time_ms": int, "equity": float, "open_profit": float },
6060
...
@@ -129,7 +129,8 @@
129129
130130
NaN convention: any metric with an empty/zero denominator is null (JSON has no
131131
NaN); a real computed 0 stays 0. See the report-schema + metrics reference docs
132-
for the per-field meaning of every metrics.* key.
132+
for the per-field meaning of every metrics.* key. Overflow and other computed
133+
nonfinite report values fail as report_result_invalid, reason nonfinite.
133134
134135
Selected-window mode (selected-window wire v1.3, full/v1 report, no digest). Opt in
135136
with --report-policy selected-window/v1, --window-start-ms T, --window-end-ms E,
@@ -2210,6 +2211,13 @@ def failure_line(text, code=None, code_args=None) -> str:
22102211
(_cut_utf8(_no_surrogates(value), ERROR_ARG_TEXT_MAX)
22112212
if isinstance(value, str) else value)
22122213
for name, value in (code_args or {}).items()}
2214+
if code == "report_result_invalid":
2215+
# Translate native metric fields at the public wire boundary.
2216+
field = doc["args"].get("field")
2217+
if isinstance(field, str):
2218+
prefix, separator, name = field.rpartition(".")
2219+
if prefix == "metrics.equity":
2220+
doc["args"]["field"] = prefix + separator + EQUITY_REPORT_KEYS.get(name, name)
22132221
line = _dump_line(doc)
22142222
if len(line) > ERROR_LINE_MAX:
22152223
if code is not None and len(_dump_line({**doc, "error": ""})) > ERROR_LINE_MAX:
@@ -3543,12 +3551,13 @@ def fmt_utc(ms: int) -> str:
35433551
ms / 1000, tz=timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
35443552

35453553

3546-
def _num(x):
3547-
"""JSON-safe float. The engine's metric NaN convention (empty / zero
3548-
denominator -> NaN, never 0) cannot survive JSON: json.dump emits a bare
3549-
`NaN` token that a strict downstream JSON.parse (the MCP layer) rejects.
3550-
Collapse every non-finite double to null so the report stays valid JSON."""
3554+
def _num(x, *, report_metric=False):
3555+
"""Native metric NaN is the producer's explicit defined-absence sentinel.
3556+
Preserve infinity until _validate_report_result can raise the typed R.
3557+
Recorded script outputs have their separate nonfinite-to-null convention."""
35513558
f = float(x)
3559+
if report_metric:
3560+
return None if math.isnan(f) else f
35523561
return f if math.isfinite(f) else None
35533562

35543563

@@ -3559,16 +3568,54 @@ def _num(x):
35593568
EQUITY_REPORT_KEYS = {"sharpe_monthly": "sharpe_tv", "sortino_monthly": "sortino_tv"}
35603569

35613570

3571+
# Revision 3.1 policy. docker/report_annualization.def holds the same two
3572+
# facts for the C++ metric walk; run_json.py ships as a single file, so it
3573+
# keeps its own copy and tests/test_run_json_nonfinite_report.py pins the two.
3574+
MIN_ANNUALIZATION_SPAN_MS = 86_400_000
3575+
SHORT_SPAN_ANNUALIZED_FIELDS = ("cagr", "calmar")
3576+
3577+
3578+
def _annualization_diagnostics(curve, metrics):
3579+
"""Explain only the revision 3.1 absence, from native report observations.
3580+
3581+
net_profit_pct's existing domain witnesses positive initial capital even
3582+
when the first equity mark differs from it or provenance is unresolved.
3583+
Python's integer subtraction is exact across the full int64 timestamp
3584+
domain; convert the difference to double just as the kernel does.
3585+
"""
3586+
if (not curve or metrics["all"]["net_profit_pct"] is None
3587+
or not math.isfinite(metrics["all"]["net_profit_pct"])
3588+
or not math.isfinite(curve[-1]["equity"]) or curve[-1]["equity"] <= 0):
3589+
return {}
3590+
first, last = curve[0]["time_ms"], curve[-1]["time_ms"]
3591+
span_ms = float(last - first) if last >= first else -float(first - last)
3592+
if not 0 < span_ms < MIN_ANNUALIZATION_SPAN_MS:
3593+
return {}
3594+
return {
3595+
EQUITY_REPORT_KEYS.get(field, field): "span_too_short_to_annualize"
3596+
for field in SHORT_SPAN_ANNUALIZED_FIELDS
3597+
if metrics["equity"][EQUITY_REPORT_KEYS.get(field, field)] is None
3598+
}
3599+
3600+
3601+
def _annualization_block(curve, metrics) -> dict:
3602+
"""The diagnostics entry for revision 3.1: present only when the rule fired."""
3603+
reasons = _annualization_diagnostics(curve, metrics)
3604+
return {"annualization": reasons} if reasons else {}
3605+
3606+
35623607
def _stats_dict(s) -> dict:
35633608
"""Serialize a pf_trade_stats_t / pf_equity_stats_t ctypes struct to a dict,
35643609
keying off each field's ctype: integer counters stay ints, every double is
3565-
sanitized through _num. Driven by _fields_ so it tracks the struct verbatim;
3610+
normalized through _num's metric mode. Computed nonfinite values must
3611+
already have failed native M checks; infinities also fail the C backstop.
3612+
Driven by _fields_ so it tracks the struct verbatim;
35663613
an equity struct's two monthly ratios take their EQUITY_REPORT_KEYS."""
35673614
keys = EQUITY_REPORT_KEYS if isinstance(s, EquityStatsC) else {}
35683615
out = {}
35693616
for name, ctype in s._fields_:
35703617
v = getattr(s, name)
3571-
out[keys.get(name, name)] = _num(v) if ctype is ctypes.c_double else int(v)
3618+
out[keys.get(name, name)] = _num(v, report_metric=True) if ctype is ctypes.c_double else int(v)
35723619
return out
35733620

35743621

@@ -3613,9 +3660,18 @@ def build_report_dict(report: ReportC, ohlcv_path: Path,
36133660

36143661
cum, peak, max_dd = 0.0, 0.0, 0.0
36153662
for p in pnls:
3663+
if not math.isfinite(p):
3664+
raise RunFailure("the report result trades.pnl is not finite",
3665+
"report_result_invalid",
3666+
{"field": "trades.pnl", "reason": "nonfinite"})
36163667
cum += p
36173668
peak = max(peak, cum)
3618-
max_dd = min(max_dd, cum - peak)
3669+
drawdown = cum - peak
3670+
if not math.isfinite(cum) or not math.isfinite(drawdown):
3671+
raise RunFailure("the report result summary.max_drawdown is not finite",
3672+
"report_result_invalid",
3673+
{"field": "summary.max_drawdown", "reason": "nonfinite"})
3674+
max_dd = min(max_dd, drawdown)
36193675

36203676
# Computed trading metrics (ABI v2): all/longs/shorts trade stats + the
36213677
# equity-curve-derived block (sharpe/sortino/cagr/calmar/...). See the
@@ -3636,8 +3692,8 @@ def build_report_dict(report: ReportC, ohlcv_path: Path,
36363692
p = report.equity_curve[i]
36373693
equity_curve.append({
36383694
"time_ms": int(p.time_ms),
3639-
"equity": _num(p.equity),
3640-
"open_profit": _num(p.open_profit),
3695+
"equity": float(p.equity),
3696+
"open_profit": float(p.open_profit),
36413697
})
36423698

36433699
return {
@@ -3674,6 +3730,7 @@ def build_report_dict(report: ReportC, ohlcv_path: Path,
36743730
"magnifier_sub_bars_total": int(report.magnifier_sub_bars_total),
36753731
"magnifier_sample_ticks_total": int(report.magnifier_sample_ticks_total),
36763732
"bar_magnifier_enabled": bool(report.bar_magnifier_enabled),
3733+
**_annualization_block(equity_curve, metrics),
36773734
},
36783735
"trades": trades,
36793736
"metrics": metrics,
@@ -3682,9 +3739,9 @@ def build_report_dict(report: ReportC, ohlcv_path: Path,
36823739

36833740

36843741
def _validate_report_result(out: dict) -> None:
3685-
"""Canonical trade and summary doubles have no defined non-finite absence.
3686-
Keep the failure fields as engine-owned literals; metrics, equity and
3687-
recorded outputs retain their existing _num-to-null convention."""
3742+
"""Required results are finite; only native metric absence is nullable.
3743+
Metric keys come from the producer's ctypes descriptors and alias map,
3744+
after native computation has distinguished absence from computed NaN."""
36883745
for trade in out["trades"]:
36893746
for key, field in (
36903747
("entry_price", "trades.entry_price"),
@@ -3701,6 +3758,7 @@ def _validate_report_result(out: dict) -> None:
37013758
"report_result_invalid",
37023759
{"field": field, "reason": "nonfinite"})
37033760
for key, field in (
3761+
("win_rate_pct", "summary.win_rate_pct"),
37043762
("net_pnl", "summary.net_pnl"),
37053763
("avg_trade", "summary.avg_trade"),
37063764
("best_trade", "summary.best_trade"),
@@ -3711,6 +3769,22 @@ def _validate_report_result(out: dict) -> None:
37113769
raise RunFailure(f"the report result {field} is not finite",
37123770
"report_result_invalid",
37133771
{"field": field, "reason": "nonfinite"})
3772+
for block in ("all", "longs", "shorts", "equity"):
3773+
for name, value in out["metrics"][block].items():
3774+
if value is not None and not math.isfinite(value):
3775+
metric_field = f"metrics.{block}.{name}"
3776+
raise RunFailure(f"the report result {metric_field} is not finite",
3777+
"report_result_invalid",
3778+
{"field": metric_field, "reason": "nonfinite"})
3779+
for point in out["equity_curve"]:
3780+
for key, field in (
3781+
("equity", "equity_curve.equity"),
3782+
("open_profit", "equity_curve.open_profit"),
3783+
):
3784+
if not math.isfinite(point[key]):
3785+
raise RunFailure(f"the report result {field} is not finite",
3786+
"report_result_invalid",
3787+
{"field": field, "reason": "nonfinite"})
37143788

37153789

37163790
def _request_invalid(text: str, option: str, exit_status: int = 1) -> RunFailure:

‎docs/adr/0001-kernel-adapter-boundary.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ summary of it.
8686
`NativeCoordinate::interval_index` (`market_driver.hpp:74`) is the sequential
8787
SCRIPT-bar index even when `input_tf` is finer than `script_tf`. The same
8888
script coordinate books `PyramidEntry::entry_bar_index`, trade-row indices and
89-
the inclusive bar metrics (`engine_orders.cpp:113-114`, `engine_metrics.cpp:140`).
89+
the inclusive bar metrics (`engine_orders.cpp:113-114`, `engine_metrics.cpp:164`).
9090
`NativeCoordinate::input_interval_index` (`market_driver.hpp:79`) names the
9191
input slot that supplied the point for a host that needs input cadence. Both
9292
coordinate values are folded by `hash_coordinate`
@@ -172,7 +172,7 @@ summary of it.
172172
(`guard_native_mutation` `engine_aux_security.cpp:83`).
173173
Indicators are `ta_*.cpp`, session/calendar `session_time.cpp` / `native_calendar.cpp`, FX
174174
`configure_native_fx_curve` (`native_host.hpp:1202`).
175-
- **Reporting.** `fill_report` (`engine.hpp:1859`, `src/engine_report.cpp:56`) gives a bare host
175+
- **Reporting.** `fill_report` (`engine.hpp:1859`, `src/engine_report.cpp:58`) gives a bare host
176176
trade stats, and the equity curve is a run-spec choice rather than a host chore.
177177
`NativeReportPolicy::HostRecorded` (the default) leaves the series to the host, whose
178178
`record_equity_point` / `update_equity_extremes` remain protected
@@ -181,8 +181,8 @@ summary of it.
181181
`KernelRecordedAtHostMarks` records the same series at the host's own marks.
182182
`report_open_position_at_end` books the still-open position as a mark-to-market row under
183183
`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 (`src/engine_metrics.cpp:228`,
185+
consumed by `fill_metrics_section`, `src/engine_report.cpp:203`) — which is why the policy exists.
186186
- **Reproducibility.** Two digests, one wrapping the other. `native_continuation_hash()`
187187
(`native_host.hpp:1376`) returns the consumer's event/continuation hash. **A digest names
188188
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.
761761
| `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. |
762762
| `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`. |
763763
| 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:4091`) | **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. |
765765
| `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. |
766766
| `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. |
768768
| `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`. |
769769
| `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. |
770770

0 commit comments

Comments
 (0)