Skip to content

Commit 9507d8f

Browse files
refactor(corpus): pull equity-mirror into corpus/parity-anomalies/
Companion to the corpus submodule bump (8d1aefe..50813bc). The former validation/parity-probe-03-equity-mirror probe documents TV-side non-determinism at the 1x equity margin boundary, not an engine bug. Keeping it inside --all only masked it as a regression. This commit moves the runtime-side support for the new parity-anomalies/ category. scripts/verify_corpus.py: - --all defaults to the 167 reference strategies in basic/, community/, validation/. parity-anomalies/ is excluded so the headline tier counts stay clean. - new --include-anomalies flag folds parity-anomalies/ back into --all for the full 168-strategy sweep. - parity-anomalies added as --category choice for explicit inspection. - --all prints a one-line note pointing at parity-anomalies/README.md when probes are skipped, so users know there is more on demand. docs/coverage.md: - canonical-report figure updated: excellent=165, strong=2 across the 167 reference strategies; the anomaly probe is described in its own paragraph with pointers to the local index and the utils write-up. src/engine_strategy_commands.cpp: - margin-check comment refs updated to parity-anomalies/equity-mirror. No behaviour change. Co-authored-by: Cursor <[email protected]>
1 parent 7f9bce9 commit 9507d8f

4 files changed

Lines changed: 120 additions & 32 deletions

File tree

‎corpus‎

‎docs/coverage.md‎

Lines changed: 68 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ via `StrategyOverrides`; they must be set by the generated subclass.
235235
`strategy.closedtrades.*` accessors are wired (defined inline on `BacktestEngine`):
236236
237237
```
238-
profit, profit_percent, commission, direction,
238+
profit, profit_percent, commission,
239239
entry_bar_index, exit_bar_index,
240240
entry_comment, exit_comment, entry_id, exit_id,
241241
entry_price, exit_price, entry_time, exit_time,
@@ -246,11 +246,16 @@ size, max_runup, max_runup_percent, max_drawdown, max_drawdown_percent
246246
`exit_*` fields (exits do not exist for an open trade):
247247
248248
```
249-
profit, profit_percent, commission, direction,
249+
profit, profit_percent, commission,
250250
entry_bar_index, entry_comment, entry_id, entry_price, entry_time,
251251
size, max_runup, max_runup_percent, max_drawdown, max_drawdown_percent
252252
```
253253
254+
Pine v6 has no `strategy.closedtrades.direction(...)` /
255+
`strategy.opentrades.direction(...)` accessor — direction is encoded in
256+
the sign of `size` (positive = long, negative = short), and the support
257+
checker rejects any user code that calls a `direction(...)` accessor.
258+
254259
Aggregate strategy state methods are also defined on the engine:
255260
`net_profit / gross_profit / gross_loss` (and `_percent` variants),
256261
`avg_trade / avg_winning_trade / avg_losing_trade` (and `_percent`),
@@ -277,8 +282,27 @@ variables must be reconstructed from `tf_to_seconds(...)` (which
277282
- `is_last_tick_` — last sample within the script bar.
278283
- `barstate_islast_` — last script bar in the run.
279284
280-
`barstate.isrealtime`, `barstate.ishistory`, and live-tick semantics
281-
have no runtime backing.
285+
Pine v6 exposes seven `barstate.*` flags. PineForge runs in batch mode
286+
with no live data feed, so the runtime cannot honour their realtime
287+
semantics. The consumer compiler maps them onto the three engine flags
288+
above with the following batch-mode approximations:
289+
290+
291+
| Pine v6 flag | PineForge batch-mode value |
292+
| --------------------------------- | -------------------------------------------------------- |
293+
| `barstate.isfirst` | `bar_index == 0` (handled by the consumer compiler). |
294+
| `barstate.islast` | always `false` (no live "current" bar in batch mode). |
295+
| `barstate.ishistory` | always `true` (every bar is historical in batch mode). |
296+
| `barstate.isrealtime` | always `false`. |
297+
| `barstate.isnew` | follows `is_first_tick_` (first sample of a script bar). |
298+
| `barstate.isconfirmed` | follows `is_last_tick_` (last sample of a script bar). |
299+
| `barstate.islastconfirmedhistory` | always `false`. |
300+
301+
302+
Live-tick semantics (`calc_on_every_tick`, `calc_on_order_fills`,
303+
`barstate.isnew` flipping mid-bar on a live feed) have no runtime
304+
backing — they are intentionally not modelled, see
305+
"`varip` and realtime tick semantics" below.
282306
283307
## Technical Analysis (`namespace ta`)
284308
@@ -323,18 +347,25 @@ Trend / pivots (`src/ta_volatility_trend.cpp`): `Supertrend(factor, atr_period)`
323347
324348
Cross / state machines (`src/ta_misc.cpp`): `Crossover`, `Crossunder`,
325349
`Cross`, `Rising(length)`, `Falling(length)`, `BarsSince`,
326-
`ValueWhen(max_occurrence=1)`, `Change(max_length=1)`.
350+
`ValueWhen(max_occurrence=1)`, `Change(max_length=1)`. `Change::compute`
351+
takes a `double src`; Pine v6's `ta.change` also accepts a bool source
352+
(returns true on flip). The consumer compiler is responsible for
353+
casting bool → 0.0 / 1.0 before feeding the runtime, since the runtime
354+
class itself is numeric only.
327355
328356
Statistical / windowed (`src/ta_misc.cpp`): `StdDev`, `Variance`,
329357
`Median`, `Mode`, `Range`, `Dev` (mean absolute deviation), `Highest`,
330358
`Lowest`, `HighestBars`, `LowestBars`, `PercentRank`,
331359
`PercentileNearestRank`, `PercentileLinearInterpolation`, `Correlation`.
332360
333361
Volume indicators (`src/ta_extremes_volume.cpp`): official `ta.vwap(...)`
334-
is a function backed by `VWAP`; official `ta.obv`, `ta.accdist`,
335-
`ta.nvi`, `ta.pvi`, `ta.pvt`, `ta.wad`, `ta.wvad`, and `ta.iii` are
336-
series variables backed by `OBV`, `AccDist`, `NVI`, `PVI`, `PVT`,
337-
`WAD`, `WVAD`, and `III`. Parenthesized call forms such as
362+
is a function backed by `VWAP` — single-value form only. Pine v6's
363+
3-tuple form `[vwap, upper_band, lower_band] = ta.vwap(source, anchor, stdev_mult)`
364+
when `stdev_mult` is specified is not implemented at the runtime layer;
365+
the consumer compiler must reject or emit it inline. Official `ta.obv`,
366+
`ta.accdist`, `ta.nvi`, `ta.pvi`, `ta.pvt`, `ta.wad`, `ta.wvad`, and
367+
`ta.iii` are series variables backed by `OBV`, `AccDist`, `NVI`, `PVI`,
368+
`PVT`, `WAD`, `WVAD`, and `III`. Parenthesized call forms such as
338369
`ta.obv()` are rejected by PineForge's support checker because they are
339370
not Pine v6 functions.
340371
@@ -735,14 +766,21 @@ declaration.
735766
736767
`request.financial(symbol, field, period)`, `request.dividends`,
737768
`request.earnings`, `request.splits`, `request.currency_rate`,
769+
`request.economic(country_code, field, ...)`,
738770
`request.seed(source, symbol, expression)`, `request.quandl`.
739771
772+
These are the eight `request.`* calls Pine v6 exposes outside the two
773+
that PineForge does support (`request.security` and
774+
`request.security_lower_tf`). The support checker rejects all eight
775+
loudly via a generic `request.`* catch-all, so user code never silently
776+
falls through to broken codegen.
777+
740778
- **Feasibility:**
741-
- `request.financial / dividends / earnings / splits / currency_rate`: *Feasible — needs aux data*. Would need a parallel data-ingestion path so the user can supply a CSV / Parquet of fundamentals or corporate actions; the runtime would then look up the right slice by `bar.timestamp`.
779+
- `request.financial / dividends / earnings / splits / currency_rate / economic`: *Feasible — needs aux data*. Would need a parallel data-ingestion path so the user can supply a CSV / Parquet of fundamentals, corporate actions, or macroeconomic series; the runtime would then look up the right slice by `bar.timestamp`.
742780
- `request.seed`: *Out of scope structurally*. TradingView seeds are user-published time series hosted on TV's infrastructure; PineForge has no equivalent registry.
743781
- `request.quandl`: *Out of scope by design*. Deprecated upstream; not worth implementing.
744-
- **Future story:** Fundamentals would land as a generic "auxiliary timeline" feature: pass `aux_data={"earnings": df}` to the runner, exposed to Pine via `request.financial`-shaped accessors that read from the aux table.
745-
- **Why not done yet:** Most strategy logic in our test corpus relies on the chart symbol's bars + indicators. Fundamentals-driven strategies are a meaningful but smaller user segment; we have not built the aux-data ingestion contract.
782+
- **Future story:** Fundamentals and economic indicators would land as a generic "auxiliary timeline" feature: pass `aux_data={"earnings": df, "us_gdp": df}` to the runner, exposed to Pine via `request.financial` / `request.economic`-shaped accessors that read from the aux table.
783+
- **Why not done yet:** Most strategy logic in our test corpus relies on the chart symbol's bars + indicators. Fundamentals- and macro-driven strategies are a meaningful but smaller user segment; we have not built the aux-data ingestion contract.
746784
747785
#### `barmerge.lookahead_on` for lower-TF emulation
748786
@@ -772,15 +810,26 @@ is the backing store.
772810
773811
## Verifying the surface yourself
774812
775-
The 162-strategy validation corpus under `[corpus/](../corpus/)` is the
776-
canonical proof that this runtime delivers the surface listed above.
777-
Run `bash scripts/run_corpus.sh` to compile every `generated.cpp`
813+
The 168-strategy validation corpus under `[corpus/](../corpus/)` (162
814+
reference strategies + 6 parity probes) is the canonical proof that
815+
this runtime delivers the surface listed above. Run
816+
`bash scripts/run_corpus.sh` to compile every `generated.cpp`
778817
against `libpineforge.a` and diff the per-strategy `engine_trades.csv`
779818
against the TradingView export shipped alongside it — the current
780-
canonical report is **excellent=160, strong=2** across 162 strategies.
781-
The strict profile checks count + entry-price + exit-price + P&L within
782-
`1.0% / 0.01% / 0.01% / 1.0%`; the production profile is reserved for
783-
path-dependent trailing-stop strategies.
819+
canonical report is **excellent=165, strong=2** across the 167 reference
820+
strategies in `basic/`, `community/`, and `validation/`. The strict
821+
profile is the only profile and is applied to every strategy: count +
822+
entry-price + exit-price + P&L within `1.0% / 0.01% / 0.01% / 1.0%`.
823+
824+
One additional probe — `corpus/parity-anomalies/equity-mirror/` (the
825+
former `parity-probe-03-equity-mirror`) — lives in a dedicated
826+
`parity-anomalies/` directory and is excluded from the headline count
827+
by default. It exercises the 1× equity margin boundary specifically to
828+
surface TV-side non-determinism we cannot match deterministically (see
829+
`parity-anomalies/tv-margin-boundary.md` in the dev-utils repo for the
830+
full write-up, and `corpus/parity-anomalies/README.md` for the local
831+
index). Run `python scripts/verify_corpus.py --all --include-anomalies`
832+
to fold it into the sweep.
784833
785834
The three-way benchmark under `[benchmarks/](../benchmarks/)` extends
786835
this comparison to include [PyneCore](https://github.com/PyneSys/pynecore)

‎scripts/verify_corpus.py‎

Lines changed: 43 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,21 @@
1010
it applies common-window edge trimming, honours per-strategy metadata,
1111
and reports the five parity labels used in the corpus README.
1212
13+
`--all` covers the three reference-tier categories — `basic/`, `community/`,
14+
`validation/` — i.e. 167 strategies after the equity-mirror anomaly probe
15+
moved to `parity-anomalies/`. The `parity-anomalies/` category is a home
16+
for probes that *deliberately* surface TV-side non-determinism (engine is
17+
correct, divergence is documented in `pineforge-utils/parity-anomalies/`);
18+
it is excluded from `--all` by default so it doesn't mask as a regression.
19+
Use `--include-anomalies` to fold it into the same sweep, or run it
20+
explicitly with `--category parity-anomalies`.
21+
1322
Usage:
1423
scripts/verify_corpus.py corpus/basic/greedy # one strategy
15-
scripts/verify_corpus.py --all # entire corpus
24+
scripts/verify_corpus.py --all # 167 reference strategies
25+
scripts/verify_corpus.py --all --include-anomalies # + parity-anomalies/
1626
scripts/verify_corpus.py --category validation # one category
27+
scripts/verify_corpus.py --category parity-anomalies # anomaly probes only
1728
scripts/verify_corpus.py corpus/... --show-diffs 5 # show first 5 diffs
1829
"""
1930
from __future__ import annotations
@@ -208,7 +219,7 @@ def percentile(xs: list[float], p: float) -> float:
208219

209220
def verify_one(strategy_dir: Path, *, verbose: bool = True, show_diffs: int = 0) -> str:
210221
rel = strategy_dir.name
211-
if strategy_dir.parent.name in {"basic", "community", "validation"}:
222+
if strategy_dir.parent.name in {"basic", "community", "validation", "parity-anomalies"}:
212223
rel = f"{strategy_dir.parent.name}/{strategy_dir.name}"
213224
meta = load_strategy_metadata(strategy_dir)
214225
tv_path = strategy_dir / str(meta.get("tv_trades_csv", "tv_trades.csv"))
@@ -301,9 +312,16 @@ def verify_one(strategy_dir: Path, *, verbose: bool = True, show_diffs: int = 0)
301312
def main() -> int:
302313
ap = argparse.ArgumentParser(description=__doc__)
303314
ap.add_argument("strategy_dir", nargs="?", help="Single strategy folder, e.g. corpus/basic/greedy")
304-
ap.add_argument("--all", action="store_true", help="Verify every strategy in corpus/")
305-
ap.add_argument("--category", choices=["basic", "community", "validation"],
315+
ap.add_argument("--all", action="store_true",
316+
help="Verify all reference-tier strategies (basic/, community/, validation/). "
317+
"parity-anomalies/ is excluded unless --include-anomalies is given.")
318+
ap.add_argument("--category", choices=["basic", "community", "validation", "parity-anomalies"],
306319
help="Verify all strategies in one category")
320+
ap.add_argument("--include-anomalies", action="store_true",
321+
help="With --all, also include parity-anomalies/ probes. These deliberately "
322+
"surface TV-side non-determinism and are documented in "
323+
"pineforge-utils/parity-anomalies/. Folding them in degrades the headline "
324+
"tier counts, so off by default.")
307325
ap.add_argument("--show-diffs", type=int, default=0,
308326
help="With single-strategy mode, show this many worst-deviation matched trades")
309327
ap.add_argument("--quiet", action="store_true", help="Print only summary")
@@ -318,12 +336,20 @@ def main() -> int:
318336
return 0 if label in {"excellent", "strong"} else 1
319337

320338
if args.all or args.category:
321-
cats = [args.category] if args.category else ["basic", "community", "validation"]
339+
if args.category:
340+
cats = [args.category]
341+
else:
342+
cats = ["basic", "community", "validation"]
343+
if args.include_anomalies:
344+
cats.append("parity-anomalies")
322345
n_total = 0
323346
counts = {k: 0 for k in ("excellent", "strong", "moderate", "weak", "minimal", "missing")}
324347
n_fail: list[str] = []
325348
for cat in cats:
326-
for strat in sorted((corpus_root / cat).iterdir()):
349+
cat_root = corpus_root / cat
350+
if not cat_root.is_dir():
351+
continue
352+
for strat in sorted(cat_root.iterdir()):
327353
if not strat.is_dir():
328354
continue
329355
label = verify_one(strat, verbose=not args.quiet)
@@ -341,6 +367,17 @@ def main() -> int:
341367
f"moderate={counts['moderate']}, weak={counts['weak']}, "
342368
f"minimal={counts['minimal']}, missing={counts['missing']}"
343369
)
370+
# Emit a one-liner about parity-anomalies/ when --all skipped them, so
371+
# the user knows there's more to inspect on demand.
372+
anomaly_dir = corpus_root / "parity-anomalies"
373+
if args.all and not args.include_anomalies and anomaly_dir.is_dir():
374+
n_anomaly = sum(1 for d in anomaly_dir.iterdir() if d.is_dir())
375+
if n_anomaly:
376+
print(
377+
f"(skipped {n_anomaly} probe(s) in parity-anomalies/ — these surface "
378+
"TV-side non-determinism, see corpus/parity-anomalies/README.md; "
379+
"rerun with --include-anomalies to fold them in)"
380+
)
344381
if n_fail:
345382
print()
346383
print("Below strong tier:")

‎src/engine_strategy_commands.cpp‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,15 +47,17 @@ void BacktestEngine::strategy_entry(const std::string& id, bool is_long,
4747
// — the close of the bar where ``strategy.entry`` was just called),
4848
// NOT later in apply_market_order_fill where fill_price is the
4949
// NEXT bar's open. For ``qty = strategy.equity / close`` sizing
50-
// patterns (parity-probe-03, community/IES) this distinction is
51-
// load-bearing: the close-vs-open slippage routinely inflates
52-
// overshoot from ~zero (at signal) to ~$20 (at fill), and
50+
// patterns (parity-anomalies/equity-mirror, community/IES) this
51+
// distinction is load-bearing: the close-vs-open slippage routinely
52+
// inflates overshoot from ~zero (at signal) to ~$20 (at fill), and
5353
// pre-fix engine rejected those at fill time while TV accepted
5454
// them at signal time — accumulating into community/IES's PnL
5555
// drift. Verified empirically by parity-probe-04..06 (all 57/57
56-
// matched) and parity-probe-03 (full-equity sizing right at the
57-
// 1× boundary). Only applied to MARKET entries (limit/stop entries
58-
// have their own price baked into the order itself).
56+
// matched) and parity-anomalies/equity-mirror (full-equity sizing
57+
// right at the 1× boundary, where TV's behaviour is itself
58+
// non-deterministic — see corpus/parity-anomalies/README.md).
59+
// Only applied to MARKET entries (limit/stop entries have their
60+
// own price baked into the order itself).
5961
if (!std::isnan(qty) && std::isnan(limit_price) && std::isnan(stop_price)) {
6062
double margin_pct = is_long ? margin_long_ : margin_short_;
6163
if (margin_pct > 0.0 && !std::isnan(current_bar_.close)) {

0 commit comments

Comments
 (0)