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 329e021
Browse filesBrowse the repository at this point in the historyBrowse files
A deprecated spelling is a ruling with a removal epoch, not a comment (R5 gap lane P2c, item 3)
ADR-0001 gains a table "Deprecated public spellings": the four names, their
generic spelling, the ABI that carries each, the epoch that removes it
(`PF_ABI_VERSION` 5 for the C fields, `lifecycle_v2` for the enumerators) and
why the old spelling is retained.
It is deliberately its OWN section, outside "Residual TradingView-named surface
in the kernel-only archive". `scripts/check_kernel_residuals.py` rules by
presence: it reads the first column of every table in that one section and
fails on a ruled name the archive no longer carries. A struct field name and an
enumerator exist only at compile time and neither is written into a
`last_error` text, so `sharpe_tv` and `Coof` are in no archive — a row inside
that section would be a stale row. The gate reads the same 119 identifiers and
11 texts as before this commit.
The serialized report keys do NOT change. `sharpe_tv` / `sortino_tv` stay the
JSON keys of every report dictionary (docker/run_json.py's `_stats_dict` and
crossvalidate_metrics.py's engine dict are both driven off the ctypes
`_fields_` names), and they are ruled report-schema names — the historical
spelling of `sharpe_monthly` / `sortino_monthly`. The ctypes mirrors therefore
keep the historical member name and say so: ctypes matches by offset, never by
the C field's name, so nothing there reads the renamed field.
Docs: the generic name is primary in metrics.md, report-schema.md,
examples-rust.md and exit-leg-lifecycle.md; ffi-python.md and the four ctypes
harnesses show the unchanged key; abi-stability.md and native-engine.md state
the deprecation, the removal epochs and the C11 requirement the anonymous union
puts on a consumer of the public header.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Copy file name to clipboardExpand all lines: docs/adr/0001-kernel-adapter-boundary.md
+42Lines changed: 42 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -317,6 +317,48 @@ structurally blind to the eighty-nine pending-row names whose spelling contains
317
317
sets; the families are ruled above by name, the global by mechanism, and
318
318
`scripts/check_kernel_residuals.py` holds the tables.
319
319
320
+
## Deprecated public spellings (R5 gap lane P2c rulings)
321
+
322
+
Two public surfaces still spelled a TradingView name, and both are load-bearing: a public C ABI
323
+
field a compiled consumer reads by offset, and an enumerator of a shipped standalone C++ ABI. The
324
+
lane's decision is **alias and deprecate, never break**. The generic name is the primary spelling
325
+
in code and in the documentation; the old name stays a valid, value-identical alias, and its
326
+
removal is scheduled for the next epoch of the ABI that carries it. Nothing here changes a value,
327
+
an offset, a size, a serialized key or a behaviour: `PF_ABI_VERSION` stays 4 and `lifecycle_v1`
328
+
stays `lifecycle_v1`, because an alias needs no epoch.
329
+
330
+
This table is deliberately OUTSIDE the residual-vocabulary section above.
331
+
`scripts/check_kernel_residuals.py` rules by presence: it reads the first column of every table in
332
+
the section "Residual TradingView-named surface in the kernel-only archive" and fails on a ruled
333
+
name that is no longer in the archive. None of the four names below is a symbol or a string literal
334
+
in `libpineforge_kernel.a` — a struct field name and an enumerator exist only at compile time, and
335
+
neither is written into any `last_error` text — so a row here would be a stale row there. Verified
336
+
on a Release and on a Debug archive: `0 findings`, both profiles, with these aliases in the tree.
337
+
338
+
| name | generic spelling | ABI that carries it | removal epoch | why retained |
339
+
|---|---|---|---|---|
340
+
|`pf_equity_stats_t::sharpe_tv`|`sharpe_monthly`| public C ABI (`include/pineforge/pineforge.h`, `PF_ABI_VERSION` 4) | the next `PF_ABI_VERSION` (5) | The field is month-end-resampled equity simple returns (chart timezone, open-time bucketing), risk-free 2 %/yr, annualized ×√12, sample (N−1) stddev — a construction whose name is its resampling period, not its calibration source. The published header is the contract of every compiled FFI consumer, so both names are one `double` behind a C11 anonymous union of two same-typed members: identical offset (48), identical `sizeof(pf_equity_stats_t)` (120), identical `offsetof(pf_metrics_t, equity)` (648), pinned by `static_assert` in `src/c_abi.cpp` and exercised from C by `tests/test_c_abi.c`. |
341
+
|`pf_equity_stats_t::sortino_tv`|`sortino_monthly`| public C ABI (as above) | the next `PF_ABI_VERSION` (5) | Same resampling as `sharpe_monthly`, population downside deviation vs the monthly risk-free. Aliased on the same terms; offset 56. |
342
+
|`exit_legs::Domain::Coof`|`FillRecalc`| standalone C++ ABI `pineforge::exit_legs::lifecycle_v1` (`include/pineforge/exit_leg_lifecycle.hpp`) |`lifecycle_v2`| The domain is the fill-recalculation re-entry pass: the host re-runs its script after a fill and observes the rest of the same bar. `coof` abbreviates `calc_on_order_fills`, the Pine adapter's name for it (the same abbreviation the `coof_*` reflection rows carry, ruled above). An enumerator alias adds a name and no value: `Coof == FillRecalc == 1`, the underlying type stays `uint8_t`, `Domain::RawTicks` stays 4 (so `valid_frame`'s range check is unchanged), and no `switch` gains a case. Twin-parity-frozen TUs keep compiling their old spelling unchanged. |
343
+
|`exit_legs::Domain::MagnifierCoof`|`MagnifierFillRecalc`| standalone C++ ABI `lifecycle_v1` (as above) |`lifecycle_v2`| The same re-entry pass on a magnified sub-bar. `MagnifierCoof == MagnifierFillRecalc == 3`. |
344
+
345
+
**The serialized report keys do not change.**`sharpe_tv` and `sortino_tv` remain the JSON keys of
346
+
the report dictionaries built by `docker/run_json.py` (`_stats_dict`, driven off the ctypes
347
+
`_fields_` list) and of the engine dict `scripts/crossvalidate_metrics.py` builds the same way. They
348
+
are ruled **report-schema names**: a schema key is a wire format, not an identifier, and renaming it
349
+
would break every Python/FFI consumer for no mechanical gain. The ctypes mirrors in
Copy file name to clipboardExpand all lines: docs/pages/metrics.md
+7-5Lines changed: 7 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -73,7 +73,7 @@ every **script-bar close**, timestamped with the script-bar **open** time
73
73
|`max_equity_drawdown` (+`_pct`) | Peak-to-trough equity drop, positive currency; pct vs the peak in effect | — (0 when flat) |
74
74
|`max_equity_runup` (+`_pct`) | Trough-to-peak rise, **trough resets on each new equity peak** (mirrors the engine's intra-run extremes); pct vs that trough | — |
75
75
|`buy_hold_return` (+`_pct`) |`initial_capital · (last_close/first_open − 1)`| first open non-finite or ≤ 0 |
76
-
|`sharpe_tv` / `sortino_tv`| Month-end-resampled equity simple returns (chart tz, open-time bucketing), risk-free 2 %/yr (2/12 per month), annualized ×√12. Sharpe: sample (N−1) stddev. Sortino: population downside deviation vs the monthly risk-free | < 2 monthly returns, or zero deviation |
76
+
|`sharpe_monthly` / `sortino_monthly`| Month-end-resampled equity simple returns (chart tz, open-time bucketing), risk-free 2 %/yr (2/12 per month), annualized ×√12. Sharpe: sample (N−1) stddev. Sortino: population downside deviation vs the monthly risk-free. Deprecated alias: `sharpe_tv` / `sortino_tv` — the same `double` at the same offset, removed at the next `PF_ABI_VERSION`; the **serialized report key stays `sharpe_tv` / `sortino_tv`** (see @ref report_schema)| < 2 monthly returns, or zero deviation |
77
77
|`sharpe_bar` / `sortino_bar`| Same construction over per-script-bar returns, annualized by **observed bar density** (`bars/yr = (len−1)/calendar span`) — not a fixed calendar formula | < 2 returns, or zero deviation |
78
78
|`cagr`|`100 · ((final_equity/initial_capital)^(1/years) − 1)`, calendar span | span ≤ 0, or either side ≤ 0 |
@@ -92,7 +92,7 @@ truncated curve and metrics over the truncated prefix.
92
92
| Trade statistics (counts, PF, percent bases, averages, largest-%, bars) | Real TradingView Strategy Tester export (`composite-4emarsi-integration-01`, 336 trades, All/Long/Short panels) | Match within TV 2-dp rounding; three TV conventions arbitrated and adopted (net return-on-cost `pnl_pct`, independent largest-%, inclusive bar counts) |
93
93
| Commission + slippage economics | Historical TradingView exports: 0.1% commission + 2 ticks via `strategy_set_override` ([archived inputs](https://github.com/pineforge-4pass/pineforge-engine/blob/a03ac6d3fb42df5af1db9e39727daf450b2fb71f/validation-adhoc/4emarsi-commission-slippage-ethusdt/inputs.json)) | Historical fixed-export validation only: 672 fill prices bit-exact and 335/336 commission rows reproduced to the cent after the documented USDT→USD conversion. A separate historical bracket export reproduced 396/396 trades and pinned limit/stop slippage rules. These archived receipts do not claim current dynamic-FX native settlement parity; current native settlement preserves paid entry costs and allocates one execution's costs across physical effects. |
94
94
| TV risk panel (Sharpe, Sortino, drawdown/run-up rows, CAGR) | TV xlsx export (Performance + Risk-adjusted performance sheets) | Every panel value reproduced from the engine curve once TV's conventions are applied — see the definition-delta table below |
95
-
| Equity statistics (max DD ±%, Sharpe/Sortino both variants, CAGR, Calmar, recovery) | quantstats 0.0.81 + empyrical-reloaded 0.5.12 (`scripts/crossvalidate_metrics.py --all`) | All 246 corpus strategies ran, 0 skipped, 0 mismatches; worst engine-convention \|rel Δ\| = 1.886e-11 (`pyramid-cash-fractional-commission-01`, sharpe/sortino_bar vs empyrical); 3 degenerate NaN fields (sharpe_tv, zero monthly variance) agree on degeneracy across engine/numpy/empyrical/quantstats; known library-convention deltas labelled in single-strategy mode |
95
+
| Equity statistics (max DD ±%, Sharpe/Sortino both variants, CAGR, Calmar, recovery) | quantstats 0.0.81 + empyrical-reloaded 0.5.12 (`scripts/crossvalidate_metrics.py --all`) | All 246 corpus strategies ran, 0 skipped, 0 mismatches; worst engine-convention \|rel Δ\| = 1.886e-11 (`pyramid-cash-fractional-commission-01`, sharpe/sortino_bar vs empyrical); 3 degenerate NaN fields (`sharpe_monthly`, zero monthly variance) agree on degeneracy across engine/numpy/empyrical/quantstats; known library-convention deltas labelled in single-strategy mode |
### TV risk-panel definition deltas (arbitrated 2026-06-12, all reproduced)
@@ -103,8 +103,8 @@ exactly from the engine curve:
103
103
104
104
| TV panel row | TV's actual construction | Engine field & difference |
105
105
| --- | --- | --- |
106
-
| Sharpe ratio | Monthly returns of **realized** equity (open profit excluded), account-currency, UTC months, rf 2 %/12, **population** stddev, **not annualized**|`sharpe_tv`: mark-to-market equity, chart-tz months, sample stddev, ×√12 |
107
-
| Sortino ratio | Same series, population downside dev vs rf, not annualized |`sortino_tv` = TV × √12 (same convention otherwise — matches to 4 decimals after de-annualizing) |
| Sortino ratio | Same series, population downside dev vs rf, not annualized |`sortino_monthly` (historical spelling `sortino_tv`) = TV × √12 (same convention otherwise — matches to 4 decimals after de-annualizing) |
108
108
| Max/avg drawdown & run-up "(close-to-close)" | Realized equity sampled at **trade exits only**, split into alternating phases at the global max/min; phase value = endpoint-to-endpoint change (durations in days corroborate) |`max_equity_drawdown/runup`: per-script-bar curve with trough-reset walk |
109
109
| Max DD / run-up "(intrabar)" | Settled realized curve (with entry-commission dips) vs per-trade excursion extremes | closest to the engine's per-bar walk; reproduced exactly from trade MFE/MAE |
110
110
| CAGR | Net over the **configured backtesting range** day count, 365-day year |`cagr`: traded calendar span, 365.25 |
@@ -118,7 +118,9 @@ durations, intrabar excursion variants, account-size/margin rows. The retired re
118
118
119
119
```python
120
120
report.metrics.all.profit_factor # ctypes mirror, see FFI page
121
-
report.metrics.equity.sharpe_tv
121
+
report.metrics.equity.sharpe_tv # the ctypes mirror keeps the historical
0 commit comments