CR-202: proportional annualisation for sub-day runs, never null (W-73) by luisleo526 · Pull Request #456 · pineforge-4pass/pineforge-engine

luisleo526 · 2026-10-20T03:32:06Z

CR-202 v6: annualised metrics on short runs are proportional, never null (owner ruling W-73). Replaces #453.

Span under one day (span_ms < 86,400,000): cagr = (E/E0 - 1) × (1/span_years) × 100, the simple proportional annualisation, flagged diagnostics.annualization.cagr = "simple_proportional_subday"; calmar = cagr / max_equity_drawdown_pct and carries the same flag.
Span of one day or more: main's compounded formula unchanged. Only if it is not finite, the simple form with flag "simple_proportional_overflow" (the possible ranking inversion is named in the docs).
sharpe_bar / sortino_bar: main's formulas on every span, never null. sharpe_monthly / sortino_monthly unchanged.
No null for these four on a valid run. Any other non-finite value is the typed report_result_invalid; the runner report keeps "NaN".
Known residual (documented): when the starting equity can't be proven from the wire (span of a day or more, compounded overflow, a trade at bar 0), the value is still the simple form but the overflow flag is absent. The exact fix (a C ABI export) is carded for 1.8.0.
Tests red-first: 7-min +8% (simple + flag), a monotonic pair on one sub-day span, the 1-day boundary on both sides, sharpe/sortino_bar on a sub-day span equal to 1.6.1's.
The neutral report digest is re-harvested from the lab in a follow-up commit on this branch.

One squash on main 0212cab; the commit message names every reworded doc sentence with the commit that introduced it.

🤖 Generated with Claude Code

…s; annualise cagr proportionally under one day, with a named form flag (CR-202, owner W-73) Squash of the CR-202 work on engine main 0212cab. 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. - Proportional annualisation (owner ruling W-73; docs/design/selected-window-wire-v1.3-revision-3.1.md, docs/pages/report-schema.md). span_years = (last bar time - first bar time) / (365.25 * 86400 * 1000 ms), as before. Under one day (span_ms < 86 400 000) cagr = (E/E0 - 1) * (1/span_years) * 100, the simple proportional form, always, and calmar = cagr / max_equity_drawdown_pct follows. From one day on cagr is the compounded form, unchanged; only if that value is not finite the simple form is used instead (a rare ranking inversion across the one-day boundary, documented). sharpe_bar and sortino_bar use the same formulas on every span and are never absent by span; sharpe_tv and sortino_tv are unchanged. No null for these four on a valid run; every other non-finite value is the typed report_result_invalid. - The public report names the form under diagnostics.annualization (outside the 135 digest leaves): cagr = "simple_proportional_subday" or "simple_proportional_overflow", and calmar carries the same string when it is not null. The writer derives it from the curve it holds; for a run of one day or more whose compounded form is not finite and whose first mark is not proven to be the initial capital the cagr is still the simple value and only the overflow flag is absent (documented; a runtime export of the capital is carded for a later release). The frozen report structures gain no member. - 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 a lab harvest of the neutral 15 one-minute bar run (its cagr is the simple proportional value on a 14-minute span); the value is taken from the lab log under the fixture authority of CORE-TOP. 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 cagr on a span under one day and when its compounded form overflows. - 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`." and "The engine checks computed values before they can become a metric absence." in docs/pages/report-schema.md, both kept. - 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; e963e5e728 (the earlier squash of this work) introduced the revision 3.1 note's null-rule sentences ("The short-span absence applies to cagr, calmar, sharpe_bar and sortino_bar", "Calmar carries the short-span reason with CAGR even when the curve also has zero drawdown", "span_too_short_to_annualize") and the report-schema.md ones; the owner ruling W-73 withdrew that null rule and they are reworded or replaced in this change. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…rics_l4d (twin parity) scripts/check_twin_parity.py requires every assertion literal of the base test_metrics to survive in its switched-route twin test_metrics_l4d.cpp. The proportional-annualisation rewrite of test_equity_stats_drawdown_walk dropped `CHECK(!std::isnan(e.cagr));`, so the source-guard-twin-parity stage failed and the verifier-tests stage of preflight read `not-started` for every later stage. The literal is back, unchanged and still true (cagr is defined on every valid run); the reference comparison below it stays. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…onal-annualisation report The neutral run (15 one-minute bars, a 14-minute span, KernelRecorded) now reports a finite simple proportional cagr (10000 to about 10005, no drawdown) and main's formulas for sharpe_bar and sortino_bar, so nothing is absent and its report digest moves again from the value pinned for the earlier null rule. Value harvested from lab job rj-20261020t035042-1a9c33 (label cr202-v6c-pre-rel, release step, test_native_anchored_legs:262), log line 2525: "neutral report digest 6216030702059937357, pinned 8139101939074791901". Fixture authority for exactly that printed value: CORE-TOP (2026-10-20 12:29). That test was the only failure of that release run (961 of 962 tests passed). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

luisleo526 mentioned this pull request Oct 20, 2026

metrics: typed report_result_invalid for overflow; annualised metrics under one day are null with a reason (rev 3.1, CR-202) #453

Closed

luisleo526 and others added 2 commits October 20, 2026 11:47

luisleo526 merged commit 34f9b3a into main Oct 20, 2026
33 of 35 checks passed

Navigation Menu

Repository navigation

CR-202: proportional annualisation for sub-day runs, never null (W-73) - #456

CR-202: proportional annualisation for sub-day runs, never null (W-73)#456
luisleo526 merged 3 commits into
mainfrom
cx/metrics-overflow-v6

luisleo526 commented Oct 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

luisleo526 commented Oct 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant