|
| 1 | +# Selected-window wire v1.3 — revision 3.1 clarification |
| 2 | + |
| 3 | +Revision 3 Appendix A's equity-metric row (line 83) permits a finite double or |
| 4 | +a defined null, with metric-domain checks and otherwise |
| 5 | +`report_result_invalid`. Its closing paragraph (line 93) permits typed null |
| 6 | +only for a defined absence, never as a catch-all for infinity or arithmetic |
| 7 | +overflow. This clarification defines one additional absence and keeps the |
| 8 | +exhaustive 135 scalar leaf paths and every other ownership rule unchanged. |
| 9 | + |
| 10 | +## Annualization domain |
| 11 | + |
| 12 | +The short-span absence applies to **cagr and calmar only**. The complete |
| 13 | +annualized-field inventory of `compute_equity_stats` |
| 14 | +(`src/engine_metrics.cpp:228`) is: |
| 15 | + |
| 16 | +| Native field | Published field | Construction and short-span treatment | |
| 17 | +| --- | --- | --- | |
| 18 | +| cagr | cagr | Compound annual growth, using the measured span in years; null under one day. | |
| 19 | +| calmar | calmar | CAGR divided by maximum equity drawdown percent; null with the short-span CAGR. | |
| 20 | +| sharpe_bar | sharpe_bar | Observed bar density `(n-1)/span_years`, scaled by its square root; existing behavior on every span, with strict overflow checks. | |
| 21 | +| sortino_bar | sortino_bar | The same density scaling with downside deviation; existing behavior on every span, with strict overflow checks. | |
| 22 | +| sharpe_monthly | sharpe_tv | Calendar-month returns in chart timezone, scaled by fixed sqrt(12); existing behavior and overflow checks. | |
| 23 | +| sortino_monthly | sortino_tv | Calendar-month downside construction with fixed sqrt(12); existing behavior and overflow checks. | |
| 24 | + |
| 25 | +Recovery factor, both buy/hold fields, time in market, open profit, all equity |
| 26 | +extrema and all trade metrics are not annualized. They gain no new absence. |
| 27 | +The constant policy list is in `docker/report_annualization.def`, shared by |
| 28 | +the native metric walk and public report writer. Extending the decision to |
| 29 | +both bar ratios requires adding their two field rows there. |
| 30 | + |
| 31 | +The measured span is `span_ms` (`src/engine_metrics.cpp:289`): the last |
| 32 | +equity-curve point's time minus the first point's time. These are UTC epoch |
| 33 | +milliseconds on the bar-time clock, including the selected anchor when |
| 34 | +present. This uses the existing unsigned integer difference, converted to |
| 35 | +double after subtraction, with its existing signed reverse-span branch. |
| 36 | +It does not use elapsed wall time, requested window bounds, bar count, or |
| 37 | +the timezone-adjusted month calendar. |
| 38 | + |
| 39 | +A span **strictly less than 86,400,000 ms** leaves CAGR and Calmar as NaN, |
| 40 | +serialized as null, before evaluating the CAGR ratio or power. Exactly one |
| 41 | +day annualizes. Existing empty-curve, nonpositive-span, nonpositive-capital |
| 42 | +and nonpositive-final-equity absences remain. At a span of one day or more, |
| 43 | +overflow still raises `report_result_invalid` with reason `nonfinite` and |
| 44 | +the exact metric field. Any overflow outside the two-field set stays strict |
| 45 | +on every span. |
| 46 | + |
| 47 | +## Reason on the public wire |
| 48 | + |
| 49 | +The public JSON writer emits this optional object: |
| 50 | + |
| 51 | +```json |
| 52 | +{"diagnostics":{"annualization":{"cagr":"span_too_short_to_annualize","calmar":"span_too_short_to_annualize"}}} |
| 53 | +``` |
| 54 | + |
| 55 | +The object is present only for a positive sub-day curve with positive initial |
| 56 | +capital and positive final equity, and includes only the policy fields whose |
| 57 | +values are null. No reason is attached to the existing absence cases. |
| 58 | +Calmar carries the short-span reason with CAGR even when the curve also has |
| 59 | +zero drawdown. |
| 60 | + |
| 61 | +`_annualization_diagnostics` (`docker/run_json.py:3596`) derives the span from |
| 62 | +the same first and last curve times. The existing `metrics.all.net_profit_pct` |
| 63 | +domain witnesses positive initial capital without assuming the first equity |
| 64 | +mark equals that capital or requiring resolved provenance. No kernel state, |
| 65 | +public POD member, header ABI, or runtime export is added. |
| 66 | + |
| 67 | +Revision 3 explicitly places diagnostics/timings outside the digest. The |
| 68 | +reason stays there; metrics, summary, trade and curve keys remain unchanged. |
| 69 | +The public writer's canonical-result validation and selected-window placement |
| 70 | +checks retain their existing scopes; `report_shape` is unchanged. The native |
| 71 | +runner's `native_report_json` (`runner/report.hpp:104`) exposes the separate |
| 72 | +native report format and has no existing diagnostics object designated |
| 73 | +outside this digest. It continues to write the metric nulls; the named reason |
| 74 | +is emitted where the public JSON wire is built. |
| 75 | + |
| 76 | +## Examples |
| 77 | + |
| 78 | +| Measured curve | Result | |
| 79 | +| --- | --- | |
| 80 | +| Seven minutes, equity 10,000 to 10,800 | Completes; cagr and calmar are null with the reason above. Other fields retain their definitions, including monthly ratios that are undefined with too few months. | |
| 81 | +| One day or several days, equity ratio 1e300 | Fails with `report_result_invalid`, field `metrics.equity.cagr`, reason `nonfinite`. | |
| 82 | +| 86,399,999 ms, equity ratio 1e300 | Completes when all other results are valid; cagr and calmar are null with the short-span reason. | |
| 83 | +| Exactly one day with an ordinary gain | Annualizes with the existing formula and arithmetic order. | |
| 84 | +| c18_3 buy/hold product overflow, including on a sub-day span | Fails with `report_result_invalid`, field `metrics.equity.buy_hold_return`, reason `nonfinite`. | |
0 commit comments