Skip to content

Commit 329e021

Browse files
luisleo526claude
andcommitted
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]>
1 parent 9316f93 commit 329e021

12 files changed

Lines changed: 119 additions & 12 deletions

File tree

‎benchmarks/throughput/grid_search_repro.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ class pf_equity_stats_t(ctypes.Structure):
5959
("max_equity_drawdown", ctypes.c_double), ("max_equity_drawdown_pct", ctypes.c_double),
6060
("max_equity_runup", ctypes.c_double), ("max_equity_runup_pct", ctypes.c_double),
6161
("buy_hold_return", ctypes.c_double), ("buy_hold_return_pct", ctypes.c_double),
62+
# Historical member names of the C fields sharpe_monthly /
63+
# sortino_monthly. ctypes matches by offset, never by the C field's
64+
# name, and these strings are the serialized report keys, so the mirror
65+
# keeps them (ADR-0001, "Deprecated public spellings").
6266
("sharpe_tv", ctypes.c_double), ("sortino_tv", ctypes.c_double),
6367
("sharpe_bar", ctypes.c_double), ("sortino_bar", ctypes.c_double),
6468
("cagr", ctypes.c_double), ("calmar", ctypes.c_double),

‎docker/run_json.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -611,6 +611,10 @@ class EquityStatsC(ctypes.Structure):
611611
("max_equity_drawdown", ctypes.c_double), ("max_equity_drawdown_pct", ctypes.c_double),
612612
("max_equity_runup", ctypes.c_double), ("max_equity_runup_pct", ctypes.c_double),
613613
("buy_hold_return", ctypes.c_double), ("buy_hold_return_pct", ctypes.c_double),
614+
# Historical member names of the C fields sharpe_monthly /
615+
# sortino_monthly. ctypes matches by offset, never by the C field's
616+
# name, and these strings are the serialized report keys, so the mirror
617+
# keeps them (ADR-0001, "Deprecated public spellings").
614618
("sharpe_tv", ctypes.c_double), ("sortino_tv", ctypes.c_double),
615619
("sharpe_bar", ctypes.c_double), ("sortino_bar", ctypes.c_double),
616620
("cagr", ctypes.c_double), ("calmar", ctypes.c_double),

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -317,6 +317,48 @@ structurally blind to the eighty-nine pending-row names whose spelling contains
317317
sets; the families are ruled above by name, the global by mechanism, and
318318
`scripts/check_kernel_residuals.py` holds the tables.
319319

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
350+
`scripts/run_strategy.py`, `docker/run_json.py`, `tutorial/run.py`,
351+
`benchmarks/throughput/grid_search_repro.py` and `docs/pages/ffi-python.md` therefore keep the
352+
historical member name (ctypes matches by offset, never by the C field's name); each carries a
353+
comment saying it is the historical spelling of `sharpe_monthly` / `sortino_monthly`.
354+
355+
**Portability note for the C alias.** An anonymous union is C11. This project already compiles C at
356+
C11 (`CMAKE_C_STANDARD 11`, and the native C examples document `cc -std=c11`), and C++ has had
357+
anonymous unions since C++98, so every consumer in this repository is covered. A consumer compiling
358+
the public header as strict C99 gets a warning (`-Wc11-extensions`), not an error. The rejected
359+
alternative was `#define sharpe_tv sharpe_monthly`: a macro leaks into every translation unit that
360+
includes the header and would rewrite an unrelated consumer's own `sharpe_tv`.
361+
320362
## Kernel capabilities the Pine adapter does not declare (R5 lane P6 rulings)
321363

322364
Rule 3 below makes every bare-host capability opt-in, so that adapter runs stay byte-identical by

‎docs/pages/abi-stability.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,26 @@ For the 0.14.x line, this is an internal C++ epoch transition rather than a
168168
public C ABI break: `PF_ABI_VERSION` remains 4 and the append-only C ABI
169169
guarantee remains in force.
170170

171+
R5 gap lane P2c gives two TradingView-named public surfaces a generic primary
172+
spelling without an epoch, because an alias needs none.
173+
`pf_equity_stats_t::sharpe_tv` / `sortino_tv` are now
174+
`sharpe_monthly` / `sortino_monthly`: each pair is one `double` behind a C11
175+
anonymous union of two same-typed members, so `sizeof(pf_equity_stats_t)`
176+
(120), the field offsets (48, 56) and `offsetof(pf_metrics_t, equity)` (648)
177+
are unchanged, `static_assert`s in `src/c_abi.cpp` pin them, and a consumer
178+
compiled against either spelling reads the same storage. The standalone
179+
`pineforge::exit_legs::lifecycle_v1` enumerators `Domain::Coof` /
180+
`MagnifierCoof` are now `Domain::FillRecalc` / `MagnifierFillRecalc`, with the
181+
old names kept as value-identical aliases (`== 1` and `== 3`, underlying type
182+
still `uint8_t`, `RawTicks` still 4). Both old spellings are DEPRECATED: the C
183+
fields are removed at the next `PF_ABI_VERSION`, the enumerators at
184+
`lifecycle_v2`. Serialized report keys are unaffected — a report dictionary
185+
still carries `sharpe_tv` / `sortino_tv`. Compile the public C header as C11 or
186+
later (the project's own `CMAKE_C_STANDARD` is 11 and the native C examples
187+
document `cc -std=c11`); strict C99 accepts the anonymous union with a
188+
`-Wc11-extensions` warning. Rulings of record: ADR-0001, "Deprecated public
189+
spellings".
190+
171191
The relocation manifest remains a reviewed description of the v16→v18 source
172192
and host transition; it is not proof by itself. The proof is the authenticated
173193
archive/header input plus the acceptance/rejection links above. The frozen

‎docs/pages/examples-rust.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ struct PfEquityStats {
9494
max_equity_drawdown: f64, max_equity_drawdown_pct: f64,
9595
max_equity_runup: f64, max_equity_runup_pct: f64,
9696
buy_hold_return: f64, buy_hold_return_pct: f64,
97-
sharpe_tv: f64, sortino_tv: f64,
97+
sharpe_monthly: f64, sortino_monthly: f64, // shipped as sharpe_tv / sortino_tv
9898
sharpe_bar: f64, sortino_bar: f64,
9999
cagr: f64, calmar: f64,
100100
recovery_factor: f64, time_in_market_pct: f64,

‎docs/pages/exit-leg-lifecycle.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,11 @@ It is the sole mutable window, not a duplicate mirror book. Hold/replacement
4646
barriers retain their requesting event/domain; completion identifies that exact
4747
barrier and an actual after-margin hook. Completion cannot follow the action's
4848
processing receipt; separate events caused by an owner bind retain that hook's
49-
phase. Ordinary, COOF and both magnifier hooks
50-
remain explicit. Raw-tick bar advancement supplies no such completion.
49+
phase. Ordinary, fill-recalculation (`Domain::FillRecalc`, the host's
50+
re-entry pass after a fill — shipped as the deprecated `Domain::Coof`, for
51+
TradingView's `calc_on_order_fills`) and both magnifier hooks
52+
(`Domain::Magnifier`, `Domain::MagnifierFillRecalc`, the latter shipped as
53+
`Domain::MagnifierCoof`) remain explicit. Raw-tick bar advancement supplies no such completion.
5154

5255
## Bounded replay contract
5356

‎docs/pages/ffi-python.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,10 @@ class pf_equity_stats_t(ctypes.Structure):
8080
("max_equity_drawdown", ctypes.c_double), ("max_equity_drawdown_pct", ctypes.c_double),
8181
("max_equity_runup", ctypes.c_double), ("max_equity_runup_pct", ctypes.c_double),
8282
("buy_hold_return", ctypes.c_double), ("buy_hold_return_pct", ctypes.c_double),
83+
# Historical member names of sharpe_monthly / sortino_monthly. ctypes
84+
# matches by offset, never by the C field's name, and these strings are
85+
# also the serialized report keys, so the mirror keeps them (ADR-0001,
86+
# "Deprecated public spellings").
8387
("sharpe_tv", ctypes.c_double), ("sortino_tv", ctypes.c_double),
8488
("sharpe_bar", ctypes.c_double), ("sortino_bar", ctypes.c_double),
8589
("cagr", ctypes.c_double), ("calmar", ctypes.c_double),

‎docs/pages/metrics.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ every **script-bar close**, timestamped with the script-bar **open** time
7373
| `max_equity_drawdown` (+`_pct`) | Peak-to-trough equity drop, positive currency; pct vs the peak in effect | — (0 when flat) |
7474
| `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 | — |
7575
| `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 |
7777
| `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 |
7878
| `cagr` | `100 · ((final_equity/initial_capital)^(1/years) − 1)`, calendar span | span ≤ 0, or either side ≤ 0 |
7979
| `calmar` | `cagr / max_equity_drawdown_pct` (both percent → dimensionless) | zero drawdown |
@@ -92,7 +92,7 @@ truncated curve and metrics over the truncated prefix.
9292
| 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) |
9393
| 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. |
9494
| 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 |
9696
| Closed-form unit oracles | `tests/test_metrics.cpp` (e.g. monthly Sharpe 19/20, Sortino 114/61 exact rationals) | Bit-level |
9797

9898
### TV risk-panel definition deltas (arbitrated 2026-06-12, all reproduced)
@@ -103,8 +103,8 @@ exactly from the engine curve:
103103

104104
| TV panel row | TV's actual construction | Engine field & difference |
105105
| --- | --- | --- |
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) |
106+
| Sharpe ratio | Monthly returns of **realized** equity (open profit excluded), account-currency, UTC months, rf 2 %/12, **population** stddev, **not annualized** | `sharpe_monthly` (historical spelling `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_monthly` (historical spelling `sortino_tv`) = TV × √12 (same convention otherwise — matches to 4 decimals after de-annualizing) |
108108
| 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 |
109109
| 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 |
110110
| 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
118118

119119
```python
120120
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
122+
# member name of equity.sharpe_monthly;
123+
# it is also the serialized JSON key
122124
curve = report.equity_curve[:report.equity_curve_len]
123125
```
124126

‎docs/pages/native-engine.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3228,6 +3228,18 @@ surface"); the short version:
32283228
layer alone, and a bare host's `strategy_pending_orders_len` is 0. The
32293229
neutral view is `native_working_requests()`. Each family has its ADR row,
32303230
listing every name, and the gate above holds the list.
3231+
- **Deprecated public spellings** (`docs/adr/0001-kernel-adapter-boundary.md`,
3232+
"Deprecated public spellings" — a separate table, deliberately outside the
3233+
residual section the gate parses, because none of these names is a symbol or
3234+
a literal in the archive). The C ABI's `pf_equity_stats_t::sharpe_tv` /
3235+
`sortino_tv` are now `sharpe_monthly` / `sortino_monthly` — the same `double`
3236+
at the same offset behind a C11 anonymous union, so nothing an FFI consumer
3237+
links or reads moves; the old spelling is deprecated and removed at the next
3238+
`PF_ABI_VERSION`, and the serialized report key stays `sharpe_tv`. The
3239+
standalone `lifecycle_v1` enumerators `exit_legs::Domain::Coof` /
3240+
`MagnifierCoof` are now `FillRecalc` / `MagnifierFillRecalc` (the
3241+
fill-recalculation re-entry pass), with the old names kept as
3242+
value-identical aliases until `lifecycle_v2`.
32313243
- **The ambient EMA seeding default.** `ta::EMA` seeds from its first finite
32323244
input (`EmaSeeding::FirstValue`, the default) or from the simple average
32333245
of its first `length` inputs (`EmaSeeding::SimpleAverage`, na for the

0 commit comments

Comments
 (0)