Skip to content

Commit eba8561

Browse files
luisleo526claude
andcommitted
report: revision 3.1, a sub-day span is a defined absence for cagr and calmar (CR-202 fix 4)
L6 ruled option (b): the annualised metrics cagr and calmar are a DEFINED absence (null with the named reason span_too_short_to_annualize) when the measured span is under one day; an overflow on a span of one day or more, and every non-annualised overflow, stays the typed report_result_invalid fault. - Measured span: last minus first equity-curve point time_ms (UTC epoch milliseconds, the bar clock), unsigned difference; under one day means strictly less than 86,400,000 ms. The test runs before the ratio and pow. - One policy list, docker/report_annualization.def, included by the C++ metric walk (src/metrics_annualization.hpp) and read by run_json.py, so the span and the field list exist in one place. - The reason is written outside the revision-3 digest: diagnostics.annualization in the public report, only when the rule fired and the metric is null. - docs/design/selected-window-wire-v1.3-revision-3.1.md and docs/pages/report-schema.md state the clarification. - Tests: the short-span fixtures of fix 2/3 go back to completing with null; new cases cover 7 minutes, 86,399,999 ms, exactly one day, an overflow at one day and at several days, and the non-annualised buy_hold_return overflow on a sub-day span; the wire test shows the reason only when the rule fired. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent 4ff37b8 commit eba8561

25 files changed

Lines changed: 614 additions & 578 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: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3568,6 +3568,54 @@ def _num(x, *, report_metric=False):
35683568
EQUITY_REPORT_KEYS = {"sharpe_monthly": "sharpe_tv", "sortino_monthly": "sortino_tv"}
35693569

35703570

3571+
def _read_annualization_policy():
3572+
"""The same closed policy list the C++ metric walk includes."""
3573+
minimum = None
3574+
fields = []
3575+
for raw in Path(__file__).with_name("report_annualization.def").read_text(
3576+
encoding="utf-8").splitlines():
3577+
line = raw.strip()
3578+
if not line or line.startswith("//"):
3579+
continue
3580+
span = re.fullmatch(r"PF_ANNUALIZATION_SPAN_MS\(([0-9]+)\)", line)
3581+
field = re.fullmatch(r"PF_SHORT_SPAN_ANNUALIZED_FIELD\(([a-z_]+)\)", line)
3582+
if span and minimum is None:
3583+
minimum = int(span[1])
3584+
elif field and field[1] not in fields:
3585+
fields.append(field[1])
3586+
else:
3587+
raise ValueError("invalid report annualization policy")
3588+
if minimum is None or minimum <= 0 or not fields:
3589+
raise ValueError("incomplete report annualization policy")
3590+
return minimum, tuple(fields)
3591+
3592+
3593+
MIN_ANNUALIZATION_SPAN_MS, SHORT_SPAN_ANNUALIZED_FIELDS = _read_annualization_policy()
3594+
3595+
3596+
def _annualization_diagnostics(curve, metrics):
3597+
"""Explain only the revision 3.1 absence, from native report observations.
3598+
3599+
net_profit_pct's existing domain witnesses positive initial capital even
3600+
when the first equity mark differs from it or provenance is unresolved.
3601+
Python's integer subtraction is exact across the full int64 timestamp
3602+
domain; convert the difference to double just as the kernel does.
3603+
"""
3604+
if (not curve or metrics["all"]["net_profit_pct"] is None
3605+
or not math.isfinite(metrics["all"]["net_profit_pct"])
3606+
or not math.isfinite(curve[-1]["equity"]) or curve[-1]["equity"] <= 0):
3607+
return {}
3608+
first, last = curve[0]["time_ms"], curve[-1]["time_ms"]
3609+
span_ms = float(last - first) if last >= first else -float(first - last)
3610+
if not 0 < span_ms < MIN_ANNUALIZATION_SPAN_MS:
3611+
return {}
3612+
return {
3613+
EQUITY_REPORT_KEYS.get(field, field): "span_too_short_to_annualize"
3614+
for field in SHORT_SPAN_ANNUALIZED_FIELDS
3615+
if metrics["equity"][EQUITY_REPORT_KEYS.get(field, field)] is None
3616+
}
3617+
3618+
35713619
def _stats_dict(s) -> dict:
35723620
"""Serialize a pf_trade_stats_t / pf_equity_stats_t ctypes struct to a dict,
35733621
keying off each field's ctype: integer counters stay ints, every double is
@@ -3660,7 +3708,7 @@ def build_report_dict(report: ReportC, ohlcv_path: Path,
36603708
"open_profit": float(p.open_profit),
36613709
})
36623710

3663-
return {
3711+
out = {
36643712
"engine": "pineforge",
36653713
"input": {
36663714
"ohlcv": str(ohlcv_path),
@@ -3699,6 +3747,10 @@ def build_report_dict(report: ReportC, ohlcv_path: Path,
36993747
"metrics": metrics,
37003748
"equity_curve": equity_curve,
37013749
}
3750+
annualization = _annualization_diagnostics(equity_curve, metrics)
3751+
if annualization:
3752+
out["diagnostics"]["annualization"] = annualization
3753+
return out
37023754

37033755

37043756
def _validate_report_result(out: dict) -> None:

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

Lines changed: 2 additions & 2 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:157`).
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`
@@ -181,7 +181,7 @@ 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 defined empty-curve metrics (`src/engine_metrics.cpp:221`,
184+
`compute_equity_stats` answers its defined empty-curve metrics (`src/engine_metrics.cpp:228`,
185185
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

‎docs/design/native-feature-parity.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -156,9 +156,9 @@ Columns: **Feature** (adapter mechanism, cited) · **Native today** (`yes` / `pa
156156
| ID | Feature (adapter mechanism) | Native today | Class | Lane | Sources | Notes |
157157
|---|---|---|---|---|---|---|
158158
| RP1 | Per-lot MFE / MAE, kernel-sampled or host-owned | **yes** — sampler `apply_excursion` native_execution_consumer.cpp:3280, closing-row fold `max_runup` engine_orders.cpp:157-171; `owns_lot_excursions` native_host.hpp:1021-1025 | K+A | — | F:H1 O:I1 O:I2 S:X1 | **Disagree:** S partial + its P8 excursion-mode enum (single-source, not adopted, Appendix A.9). **Lowered by R5 lane H-THIN:** the Pine host keeps the kernel's `owns_lot_excursions()` default, so the sampler is the Pine excursion; the host model, its entry-bar masks and its caches are deleted, and the source layer's fold no longer carries them. **Measured against TradingView first (R5 lane H-MEASURE, `tests/test_e19_excursion_tape.cpp`):** the host-owned model was `ab9714be`'s, not TradingView's — where it and the kernel sampler differ the kernel's number is TradingView's (entry-bar over-mask, exit-bar over-fold after an at-open exit, a `calc_on_order_fills` scratch TradingView reports as 0 / 0); both miss a bar's open print ahead of a same-bar stop fill. On the corpus the two models differ on 341 of 431 390 trades, and of the 326 of those a TradingView export identifies, the kernel's number is TradingView's on 315 and the host's on none. The lowering moved the cells of 335 trades in 19 corpus probes: 324 now equal TradingView's, 11 moved closer, none farther; the all-in residual's own entry-bar call is the tape of the private fixture set `e19_allin_trim`. |
159-
| RP2 | Closed-trade list, trade statistics, report struct | **yes** — `fill_report` engine_report.cpp:58-105, `get_trade` engine.hpp:1792-1829, `compute_trade_stats` engine_metrics.cpp:132 | K | — | F:H2 O:I3 S:X2 | — |
159+
| RP2 | Closed-trade list, trade statistics, report struct | **yes** — `fill_report` engine_report.cpp:58-105, `get_trade` engine.hpp:1792-1829, `compute_trade_stats` engine_metrics.cpp:139 | K | — | F:H2 O:I3 S:X2 | — |
160160
| RP3 | Equity curve | **no** — `update_equity_extremes` engine.hpp:1362 / `record_equity_point` engine.hpp:1380 are protected and were called only by the adapter **Closed:** `NativeReportPolicy::KernelRecorded` native_run_spec.hpp:63 has the consumer fold the extremes and append one point per script calculation, labelled with the script interval's open; `KernelRecordedAtHostMarks` records the same series at the host's own marks (`tests/test_native_report_truth.cpp`). | K | L2 | F:H3 O:I4 S:X2 | S's "partial" folds RP2 in |
161-
| RP4 | Equity metrics (drawdown, run-up, Sharpe / Sortino, CAGR, time in market) | **no** — `compute_equity_stats` exits early on an empty curve engine_metrics.cpp:221; `fill_metrics_section` engine_report.cpp:203 **Closed:** with a recorded curve the drawdown / run-up walk is finite and every equity metric is computed over a real series; `report_open_position_at_end` adds the still-open position as a mark-to-market row (`tests/test_native_report_truth.cpp`). | K | L2 | F:H3 O:I5 | silent degenerate metrics, no error (O) |
161+
| RP4 | Equity metrics (drawdown, run-up, Sharpe / Sortino, CAGR, time in market) | **no** — `compute_equity_stats` exits early on an empty curve engine_metrics.cpp:228; `fill_metrics_section` engine_report.cpp:203 **Closed:** with a recorded curve the drawdown / run-up walk is finite and every equity metric is computed over a real series; `report_open_position_at_end` adds the still-open position as a mark-to-market row (`tests/test_native_report_truth.cpp`). | K | L2 | F:H3 O:I5 | silent degenerate metrics, no error (O) |
162162
| RP5 | Range-end row for a position still open at the end (`scheduler_record_range_end` pine_strategy_host.cpp:1982) | **yes, shared** — one generic producer `NativeExecutionConsumer::append_open_position_report_rows`, called by the kernel's run-end `record_open_position_report_rows` (`KernelRecorded` + `report_open_position_at_end`) and by the adapter at TradingView's mark; `report_trade_count()` engine.hpp:1831 includes the rows | K + A report shape | L2, Q6 | F:H4 O:I6 S:X2 | **Disagree:** S says kernel range-end rows exist (storage only). The ROWS are now the kernel's (§3.7 part 1); TV report shape — the equity re-mark, the extreme re-fold, the same-bar re-sort, three marks — stays A, measured in §3.7 part 2. The short-seed swaps (`project_short_seed_report_rows` pine_strategy_host.cpp:1444) stay A as well: a projection of two rows' `entry_incarnation` onto `ab9714be`'s numbering, which TradingView does not export; measured against the kernel's own lot identities by `tests/test_short_seed_report_swap.cpp` (R5 lane H-MEASURE), and pinned by `test_native_oracle_short_seed_percent_full_l2`, whose two incarnation checks fail when the swap is skipped. The swap runs only when a later close of the seed id closes a remnant; a flat collision keeps the kernel's numbering. |
163163
| RP6 | Per-trade accessors | **partial** — `get_trade` is public; the `closed_trade_*` family is protected engine.hpp:1391 **Closed:** `closed_trade_count()` / `closed_trade(i)` and `report_trade_count()` / `get_report_trade(i)` are public, and `closed_trade_close_cause(i)` engine.hpp:1849 answers the typed `execution::CloseCause` the closer recorded (`tests/test_native_report_truth.cpp`). | K | L2 | F:H6 | (single-source) |
164164
| RP7 | Live order-action stream (runner ledger / webhook) | **yes** — `stream_observe_actions_` engine_execution.cpp:1383, enabled `stream_observe_actions_` native_execution_consumer.cpp:10589, C ABI `strategy_stream_order_actions_len` c_abi.cpp:737-754 | K | — | F:H5 | (single-source) |
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
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

Comments
 (0)